Author: husted Date: Mon Nov 26 08:03:48 2007 New Revision: 598326 URL: http://svn.apache.org/viewvc?rev=598326&view=rev Log: WW-1399 Spruce up some of the JavaDocs. Add exception.jsp to webapp and exception handling to struts.xml.
Added: struts/sandbox/trunk/jpa-mailreader/src/main/webapp/exception.jsp Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/action/Index.java struts/sandbox/trunk/jpa-mailreader/src/main/java/action/user/Login.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityAware.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityHelper.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityInterceptor.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityManagerHelper.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/ExpiredPasswordException.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/UuidEntity.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolHelper.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolTypeConverter.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/Subscription.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionHelper.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionTypeConverter.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/User.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserHelper.java struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserTypeConverter.java struts/sandbox/trunk/jpa-mailreader/src/main/java/struts.xml Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/action/Index.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/action/Index.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/action/Index.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/action/Index.java Mon Nov 26 08:03:48 2007 @@ -29,11 +29,14 @@ /** * <p> - * Provides the Struts-specific Business and Persistance Logic API for the + * The top-level Struts-specific business and persistance logic API for the * MailReader application. * </p> * <p> - * Generic logic should be pushed down to the Entity managers or another facade. + * The application is entity or resource-orientated. Subclasses provide + * additional logic specific to each entity or resource. Persistence system + * logic is delegated to a helper class for each entity. The Action classes + * interact only with the entity helpers, and not the underlying JPA. * </p> */ @Conversion(conversions = { Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/action/user/Login.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/action/user/Login.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/action/user/Login.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/action/user/Login.java Mon Nov 26 08:03:48 2007 @@ -1,3 +1,21 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ package action.user; import org.apache.struts2.config.Result; Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityAware.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityAware.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityAware.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityAware.java Mon Nov 26 08:03:48 2007 @@ -1,7 +1,40 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ package entity; import javax.persistence.EntityManager; +/** + * <p> + * Comparion interface to <code>EntityInterceptor</code> that provides access + * to an <code>EntityManager</code> for this thread. + * </p> + */ public interface EntityAware { + + /** + * <p> + * Capture the <code>EntityManager</code> for this thread. + * </p> + * + * @param value + * EntityManager for this thead + */ void setManager(EntityManager value); } Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityHelper.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityHelper.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityHelper.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityHelper.java Mon Nov 26 08:03:48 2007 @@ -26,12 +26,19 @@ /** * <p> - * Custom CRUD operations involving the <code>User</code> object. + * A set of generic CRUD operations that can operate on any entity in the + * default persistence unit. + * </p> * <p> + * If an application needs only basic CRUD operations, this class (and its + * companion the <code>EntityManagerHelper</code>) may be the only "data + * access object" the applications needs. + * </p> * <p> - * This implementation delegates transaction managemetn and exception handling + * This implementation delegates transaction management and exception handling * to another component, such as an Interceptor or Filter, or the setUp and - * tearDown methods of a TestCase. + * tearDown methods of a TestCase. See <code>EntityInterceptor</code> for an + * example. * </p> * */ Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityInterceptor.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityInterceptor.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityInterceptor.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityInterceptor.java Mon Nov 26 08:03:48 2007 @@ -1,3 +1,21 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ package entity; import javax.persistence.EntityManager; @@ -5,6 +23,23 @@ import com.opensymphony.xwork2.ActionInvocation; import com.opensymphony.xwork2.interceptor.AbstractInterceptor; +/** + * <p> + * A "single transaction per view" Interceptor for a JPA application. + * </p> + * <p> + * This class creates an EntityManager for each thread, and begins a transation. + * Other JPA components can utilize the EntityManager for persistence + * operations, without opening or committing transactions. At the end of the + * Action's lifecyle, this interceptor will commit the transaction, log any + * errors, and attempt a rollback, if needed. + * </p> + * <p> + * Exceptions are logged and rethrown. An application utilizing this + * interceptors should also utilize declarative exception handling, being sure + * to catch PersistenceExceptions. + * </p> + */ public class EntityInterceptor extends AbstractInterceptor { private String entityInvoke(ActionInvocation invocation) throws Exception { Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityManagerHelper.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityManagerHelper.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityManagerHelper.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/EntityManagerHelper.java Mon Nov 26 08:03:48 2007 @@ -28,11 +28,26 @@ /** * <p> - * Provide access to JPA implementation using static methods. + * A generic facade that provides easy access to a JPA persistence unit using + * static methods. + * </p> + * <p> + * This static class is designed so that it can be used with any JPA + * application. * </p> */ public class EntityManagerHelper { + /** + * <p> + * Declare the persistence unit for this EntityManagerHelper ("entity"). + * </p> + * <p> + * This is the only setting that might need to be changed between + * applications. Otherwise, this class can be dropped into any JPA + * application. + * </p> + */ static final String PERSISTENCE_UNIT = "entity"; private static final EntityManagerFactory emf; @@ -45,6 +60,17 @@ logger = LogFactory.getLog(EntityManagerHelper.class); } + /** + * <p> + * Provide a per-thread EntityManager "singleton" instance. + * </p> + * <p> + * This method can be called as many times as needed per thread, and it will + * return the same EntityManager instance, until the manager is closed. + * </p> + * + * @return EntityManager singleton for this thread + */ public static EntityManager getEntityManager() { EntityManager manager = threadLocal.get(); if (manager == null || !manager.isOpen()) { @@ -54,6 +80,11 @@ return manager; } + /** + * <p> + * Close the EntityManager and set the thread's instance to null. + * </p> + */ public static void closeEntityManager() { EntityManager em = threadLocal.get(); threadLocal.set(null); @@ -61,26 +92,64 @@ em.close(); } + /** + * <p> + * Initiate a transaction for the EntityManager on this thread. + * </p> + * <p> + * The Transaction will remain open until commit or closeEntityManager is + * called. + * </p> + */ public static void beginTransaction() { getEntityManager().getTransaction().begin(); } + /** + * <p> + * Submit the changes to the persistance layer. + * </p> + * <p> + * Until commit is called, rollback can be used to undo the transaction. + * </p> + */ public static void commit() { getEntityManager().getTransaction().commit(); } + /** + * <p> + * Create a query for the EntityManager on this thread. + * </p> + */ public static Query createQuery(String query) { return getEntityManager().createQuery(query); } + /** + * <p> + * Flush the EntityManager state on this thread. + * </p> + */ public static void flush() { getEntityManager().flush(); } + /** + * <p> + * Write an error message to the logging system. + * </p> + */ public static void logError(String info, Throwable ex) { logger.error(info, ex); } + /** + * <p> + * Undo an uncommitted transaction, in the event of an error or other + * problem. + * </p> + */ public static void rollback() { getEntityManager().getTransaction().rollback(); } Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/ExpiredPasswordException.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/ExpiredPasswordException.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/ExpiredPasswordException.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/ExpiredPasswordException.java Mon Nov 26 08:03:48 2007 @@ -20,8 +20,8 @@ /** * <p> - * Signal that a password has expired and needs to be changed before principal - * can be authorized for any other operation. + * An application exception to signals that a password has expired and needs to + * be changed before principal can be authorized for any other operation. * </p> */ public class ExpiredPasswordException extends Exception { Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/UuidEntity.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/UuidEntity.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/UuidEntity.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/UuidEntity.java Mon Nov 26 08:03:48 2007 @@ -31,8 +31,8 @@ @MappedSuperclass /** * <p> - * Define a POJO that utilizes an ID property based on a universally unique - * identifier (UUID). + * A POJO base class with helper methods for managing an ID property based on a + * universally unique identifier (UUID). * </p> * <p> * UUIDs are particulary useful in RESTful application designs, since an object Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolHelper.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolHelper.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolHelper.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolHelper.java Mon Nov 26 08:03:48 2007 @@ -25,7 +25,8 @@ /** * <p> - * Custom operations involving the <code>Protocol</code> object. + * Facade providing custom operations involving the <code>Protocol</code> + * object. * <p> */ public interface ProtocolHelper { Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolTypeConverter.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolTypeConverter.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolTypeConverter.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/protocol/ProtocolTypeConverter.java Mon Nov 26 08:03:48 2007 @@ -24,10 +24,8 @@ /** * <p> - * Retrieve a <code>Protocol</code> entity from its String ID, or return the - * String ID for a <code>Protocol</code> entity. + * Type converter for a <code>Protocol</code> entity. * </p> - * */ @SuppressWarnings("unchecked") public class ProtocolTypeConverter extends StrutsTypeConverter { Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/Subscription.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/Subscription.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/Subscription.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/Subscription.java Mon Nov 26 08:03:48 2007 @@ -33,13 +33,13 @@ /** * <p> - * Describes an email account. + * An entity representing an email account. * </p> - * * <p> * JPA entity class for the <code>APP_SUBSCRIPTION</code> table. TThis class * contains sufficient detail to regenerate the database schema (top-down * development). The annotation mode is by field. + * </p> */ @NamedQueries( { @NamedQuery(name = Subscription.COUNT, query = Subscription.COUNT_QUERY), Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionHelper.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionHelper.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionHelper.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionHelper.java Mon Nov 26 08:03:48 2007 @@ -22,8 +22,9 @@ /** * <p> - * Custom operations involving the <code>Subscription</code> object. - * <p> + * Facade providing custom operations involving the <code>Subscription</code> + * object. + * </p> */ public interface SubscriptionHelper { Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionTypeConverter.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionTypeConverter.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionTypeConverter.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/subscription/SubscriptionTypeConverter.java Mon Nov 26 08:03:48 2007 @@ -23,8 +23,7 @@ /** * <p> - * Retrieve a <code>Subscription</code> entity from by its host name, or - * return the host name for a <code>Subscription</code> entity. + * Type converter for a <code>Subscription</code>. * </p> * */ Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/User.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/User.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/User.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/User.java Mon Nov 26 08:03:48 2007 @@ -35,7 +35,8 @@ /** * <p> - * Describes an account that maintains zero or more <code>Subscription</code>s. + * Entity representing an account that maintains zero or more + * <code>Subscription</code>s. * </p> * <p> * JPA entity class for the <code>APP_USER</code> table. This class contains Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserHelper.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserHelper.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserHelper.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserHelper.java Mon Nov 26 08:03:48 2007 @@ -22,7 +22,7 @@ /** * <p> - * Custom operations involving the <code>User</code> object. + * Facade providing custom operations involving the <code>User</code> object. * </p> * */ Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserTypeConverter.java URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserTypeConverter.java?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserTypeConverter.java (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/entity/user/UserTypeConverter.java Mon Nov 26 08:03:48 2007 @@ -23,18 +23,16 @@ /** * <p> - * Retrieve a <code>User</code> entity from its username, or return the - * username for a <code>User</code> entity. + * Type convertion for a <code>User</code> entity. * </p> - * */ @SuppressWarnings("unchecked") public class UserTypeConverter extends StrutsTypeConverter { /** * <p> - * Given a <code>username</code>, retrieve the corresponding - * <code>User</code> entity from the persistence database. + * Retrieve the corresponding <code>User</code> entity from the + * persistence database, given a <code>username</code>. * </p> */ public Object convertFromString(Map context, String[] values, Class toClass) { Modified: struts/sandbox/trunk/jpa-mailreader/src/main/java/struts.xml URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/java/struts.xml?rev=598326&r1=598325&r2=598326&view=diff ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/java/struts.xml (original) +++ struts/sandbox/trunk/jpa-mailreader/src/main/java/struts.xml Mon Nov 26 08:03:48 2007 @@ -7,12 +7,6 @@ <constant name="struts.devMode" value="false" /> <constant name="struts.action.extension" value="" /> - - <!-- Alternative way to support message resources without wrapper classes or annotations. - <constant name="struts.custom.i18n.resources" value="action.package" /> - --> - <!-- include file="" / --> - <!-- Add packages here --> <package name="entity-default" extends="struts-default"> <interceptors> @@ -23,5 +17,17 @@ </interceptor-stack> </interceptors> <default-interceptor-ref name="entityStack"/> + + <global-results> + <result name="error">exception.jsp</result> + <result name="exception">exception.jsp</result> + </global-results> + + <global-exception-mappings> + <exception-mapping exception="java.lang.Exception" result="exception"/> + </global-exception-mappings> </package> + + <!-- include file="" / --> + </struts> Added: struts/sandbox/trunk/jpa-mailreader/src/main/webapp/exception.jsp URL: http://svn.apache.org/viewvc/struts/sandbox/trunk/jpa-mailreader/src/main/webapp/exception.jsp?rev=598326&view=auto ============================================================================== --- struts/sandbox/trunk/jpa-mailreader/src/main/webapp/exception.jsp (added) +++ struts/sandbox/trunk/jpa-mailreader/src/main/webapp/exception.jsp Mon Nov 26 08:03:48 2007 @@ -0,0 +1,28 @@ +<%@ page contentType="text/html; charset=UTF-8" %> +<%@ taglib prefix="s" uri="/struts-tags" %> +<html> + <head> + <title> + An unexpected error has occurred + </title> + </head> + <body> + <h2>An unexpected error has occurred</h2> + <p> + Please report this error to your system administrator + or appropriate technical support personnel. + Thank you for your cooperation. + </p> + <hr/> + <h3>Error Message</h3> + <s:actionerror/> + <p> + <s:property value="%{exception.message}"/> + </p> + <hr/> + <h3>Technical Details</h3> + <p> + <s:property value="%{exceptionStack}"/> + </p> + </body> +</html> \ No newline at end of file