Author: tchemit Date: 2011-07-05 14:01:58 +0200 (Tue, 05 Jul 2011) New Revision: 87 Url: http://nuiton.org/repositories/revision/nuiton-web/87 Log: add final javadoc Modified: trunk/nuiton-struts2/src/main/java/org/nuiton/web/struts2/interceptor/TopiaTransactionInterceptor.java Modified: trunk/nuiton-struts2/src/main/java/org/nuiton/web/struts2/interceptor/TopiaTransactionInterceptor.java =================================================================== --- trunk/nuiton-struts2/src/main/java/org/nuiton/web/struts2/interceptor/TopiaTransactionInterceptor.java 2011-07-05 10:22:53 UTC (rev 86) +++ trunk/nuiton-struts2/src/main/java/org/nuiton/web/struts2/interceptor/TopiaTransactionInterceptor.java 2011-07-05 12:01:58 UTC (rev 87) @@ -5,7 +5,7 @@ * $Id$ * $HeadURL$ * %% - * Copyright (C) 2010 - 2011 CodeLutin + * Copyright (C) 2010 - 2011 CodeLutin, Tony Chemit * %% * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as @@ -41,8 +41,48 @@ import java.util.HashSet; import java.util.Set; + /** - * To deal with topia transaction . + * <!-- START SNIPPET: description --> + * <p/> + * The aim of this Interceptor is to inject a freshly opened {@code transaction} + * in a action which implements {@link TopiaTransactionAware} contract and + * after result of action, to close the transaction. + * <p/> + * The interceptor is abstract and let user to implement the way how to open a + * new transaction via the method {@link #beginTransaction()}. + * <p/> + * Note that the transaction pushed in the action is in fact a proxy of the + * freshly opened transaction to forbid some method to be call on it. The list + * of method to forbid can be customized using the interceptor parameter + * {@link #excludeMethods}. + * <p/> + * Note also that the transaction is closed after all stack of interceptor + * consumed, this means that the transaction will still be opened while + * rendering the result, this is a particular interesting thing to avoid + * pre-loading of entities due to lazy strategy of hibernate for example. + * With this mecanism you can feel free to just obtain the obtain from database + * via a DAO and then really load it in the rendering result. + * <p/> + * <p/> + * This interceptor, as it provides connection to database should be in the + * interceptor stack before any other interceptor requiring access to database. + * For example, it is a common behaviour to do such calls in a prepare method, + * so make sure to place this interceptor before the {@code prepare} interceptor. + * <!-- END SNIPPET: description --> + * <p/> + * <p/> <u>Interceptor parameters:</u> + * <p/> + * <!-- START SNIPPET: parameters --> + * <p/> + * <ul> + * <li>excludeMethods (optional) - Customized method names separated by coma to + * forbid on the proxy of the transaction given to action. By default, if this + * parameter is not filled, then we will use this one : + * {@link #DEFAULT_EXCLUDE_METHODS}.</li> + * </ul> + * <p/> + * <!-- END SNIPPET: parameters --> * * @author tchemit <chemit@codelutin.com> * @since 1.2 @@ -61,6 +101,7 @@ "clear" }; + /** names of methods to forbid access while using proxy. */ protected Set<String> excludeMethods; public Set<String> getExcludeMethods() { @@ -71,6 +112,12 @@ this.excludeMethods = TextParseUtil.commaDelimitedStringToSet(excludeMethods); } + /** + * Method to open a new transaction. + * + * @return the new freshly opened transaction + * @throws TopiaException if any problem while opening a new transaction + */ protected abstract TopiaContext beginTransaction() throws TopiaException; @Override @@ -111,7 +158,7 @@ getClass().getClassLoader(), new Class<?>[]{TopiaContext.class, TopiaContextImplementor.class}, - new TopiaTransactionProxy(transaction) + new TopiaTransactionProxyInvocationHandler(transaction) ); // set the transaction in the action @@ -138,16 +185,16 @@ } /** - * A proxy to used only to forbids usage of some method of the transaction. + * Handler of a proxy on a {@link TopiaContext}. * * @see TopiaTransactionInterceptor#excludeMethods */ - class TopiaTransactionProxy implements InvocationHandler { + class TopiaTransactionProxyInvocationHandler implements InvocationHandler { /** Target to use for the proxy. */ protected final TopiaContext tx; - TopiaTransactionProxy(TopiaContext tx) { + TopiaTransactionProxyInvocationHandler(TopiaContext tx) { this.tx = tx; }