TransactionHelper


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  /*
25   * TransactionHelper.java
26   *
27   * Created on December 15, 2000, 10:06 AM
28   */
29  
30  package com.sun.jdo.spi.persistence.support.sqlstore.ejb;
31  
32  import javax.transaction.*;
33  
34  import com.sun.jdo.api.persistence.support.PersistenceManagerFactory;
35  
36      /** Provide a Forte for Java implementation with information about the distributed
37       * transaction environment.  This is an interface that a helper class
38       * implements that is specific to a managed environment.
39       * <P><B>This interface is specific to Forte for Java, version 3.0,
40       * and is subject to change without notice.  In particular, as additional
41       * experience is gained with specific application servers, this interface
42       * may have methods added and removed, even with patch releases.
43       * Therefore, this interface should be considered very volatile, and
44       * any class that implements it might have to be reimplemented whenever
45       * an upgrade to either the application server or Forte for Java occurs.</B></P>
46       * The class that implements this interface must register itself
47       * by a static method at class initialization time.  For example,
48       * <blockquote><pre>
49       * import com.sun.jdo.spi.persistence.support.sqlstore.ejb.*;
50       * class blackHerringTransactionHelper implements TransactionHelper {
51       *    static EJBHelper.register(new blackHerringTransactionHelper());
52       *    ...
53       * }
54       * </pre></blockquote>
55       */
56      public interface TransactionHelper {
57  
58      /** Returns the UserTransaction associated with the calling thread.  If there
59       * is no transaction currently in progress, this method returns null.
60       * @return the UserTransaction instance for the calling thread
61       */
62      UserTransaction getUserTransaction();
63  
64      /** Identify the Transaction context for the calling thread, and return a
65       * Transaction instance that can be used to register synchronizations,
66       * and used as the key for HashMaps. The returned Transaction must implement
67       * <code>equals()</code> and <code>hashCode()</code> based on the global transaction id.
68       * <P>All Transaction instances returned by this method called in the same
69       * Transaction context must compare equal and return the same hashCode.
70       * The Transaction instance returned will be held as the key to an
71       * internal HashMap until the Transaction completes. If there is no transaction
72       * associated with the current thread, this method returns null.
73       * @return the Transaction instance for the calling thread
74       */
75      Transaction getTransaction();
76  
77      /** Translate local representation of the Transaction Status to
78       * javax.transaction.Status value if necessary. Otherwise this method
79       * should return the value passed to it as an argument.
80       * <P>This method is used during afterCompletion callbacks to translate
81       * the parameter value passed by the application server to the
82       * afterCompletion method.  The return value must be one of:
83       * <code>javax.transaction.Status.STATUS_COMMITTED</code> or
84       * <code>javax.transaction.Status.STATUS_ROLLED_BACK</code>.
85       * @param   st  local Status value
86       * @return the javax.transaction.Status value of the status
87       */
88      int translateStatus(int st);
89  
90      /** Replace newly created instance of PersistenceManagerFactory
91       * with the hashed one if it exists. The replacement is necessary only if
92       * the JNDI lookup always returns a new instance. Otherwise this method
93       * returns the object passed to it as an argument.
94       *
95       * PersistenceManagerFactory is uniquely identified by
96       * ConnectionFactory.hashCode() if ConnectionFactory is
97       * not null; otherwise by ConnectionFactoryName.hashCode() if
98       * ConnectionFactoryName is not null; otherwise
99       * by the combination of URL.hashCode() + userName.hashCode() +
100      * password.hashCode() + driverName.hashCode();
101      *
102      * @param   pmf     PersistenceManagerFactory instance to be replaced
103      * @return  the PersistenceManagerFactory known to the runtime
104      */
105     PersistenceManagerFactory replaceInternalPersistenceManagerFactory(
106     PersistenceManagerFactory pmf);
107 
108     /** Called at the beginning of the Transaction.beforeCompletion() to
109      * register the component with the app server if necessary.
110      * The component argument is an array of Objects. 
111      * The first element is com.sun.jdo.spi.persistence.support.sqlstore.Transaction 
112      * object responsible for transaction completion.
113      * The second element is com.sun.jdo.api.persistence.support.PersistenceManager 
114      * object that has been associated with the Transaction context for the 
115      * calling thread. 
116      * The third element is javax.transaction.Transaction object that has been 
117      * associated with the given instance of PersistenceManager. 
118      * The return value is passed unchanged to the postInvoke method.
119      *
120      * @param   component   an array of Objects
121      * @return  implementation-specific Object
122      */
123     Object   preInvoke(Object   component);
124 
125     /** Called at the end of the Transaction.beforeCompletion() to
126      * de-register the component with the app server if necessary.
127      * The parameter is the return value from preInvoke, and can be any
128      * Object.
129      *
130      * @param   im  implementation-specific Object
131      */
132     void postInvoke(Object   im);
133 
134    /** Called in a managed environment to register internal Synchronization object
135     * with the Transaction Synchronization. If available, this registration
136     * provides special handling of the registered instance, calling it after
137     * all user defined Synchronization instances.
138     *
139     * @param jta the Transaction instance for the calling thread.
140     * @param sync the internal Synchronization instance to register.
141     * @throws javax.transaction.RollbackException.
142     * @throws javax.transaction.SystemException
143     */
144     void registerSynchronization(Transaction jta, Synchronization sync)
145         throws RollbackException, SystemException;
146 
147     /** Called in a managed environment to get a Connection from the application
148      * server specific resource. In a non-managed environment throws an Exception
149      * as it should not be called. 
150      *
151      * @param resource the application server specific resource. 
152      * @param username the resource username. If null, Connection is requested
153      * without username and password validation. 
154      * @param password the password for the resource username.
155      * @return a Connection. 
156      * @throw java.sql.SQLException.
157      */  
158     java.sql.Connection   getConnection(Object   resource, String   username, String   password)
159         throws java.sql.SQLException  ;
160 
161     /** Called in a managed environment to get a non-transactional Connection
162      * from the application server specific resource. In a non-managed
163      * environment throws an Exception as it should not be called.
164      *
165      * @param resource the application server specific resource.
166      * @param username the resource username. If null, Connection is requested
167      * without username and password validation.
168      * @param password the password for the resource username.
169      * @return a Connection.
170      * @throw java.sql.SQLException.
171      */
172     java.sql.Connection   getNonTransactionalConnection(
173         Object   resource, String   username, String   password)
174         throws java.sql.SQLException  ;
175 
176     /** Called in a managed environment to access a TransactionManager
177      * for managing local transaction boundaries and registering synchronization
178      * for call backs during completion of a local transaction.
179      * 
180      * @return javax.transaction.TransactionManager
181      */
182     TransactionManager getLocalTransactionManager();
183 
184     /** Identifies the managed environment behavior.
185      * @return true if this implementation represents the managed environment.
186      */  
187     boolean isManaged();
188 
189     /**
190      * This method unwrap given Statement and return the Statement from
191      * JDBC driver.
192      */
193     java.sql.Statement   unwrapStatement(java.sql.Statement   stmt);
194 
195 
196     /**
197      * Set environment specific default values for the given PersistenceManagerFactory.
198      * 
199      * @param pmf the PersistenceManagerFactory.
200      */
201     void setPersistenceManagerFactoryDefaults(PersistenceManagerFactory pmf);
202 
203     /** 
204      * Returns name prefix for DDL files extracted from the info instance by the
205      * application server specific code.
206      *   
207      * @param info the instance to use for the name generation.
208      * @return name prefix as String. 
209      */   
210     String   getDDLNamePrefix(Object   info);
211         
212     /**
213      * Called to register a ApplicationLifeCycleEventListener. If
214      * ApplicationLifeCycle management is active (typically in managed
215      * environment), the registered listener will receive a call back
216      * for lifecycle events.
217      *
218      * @param listener An instance of ApplicationLifeCycleEventListener. 
219      */ 
220     void registerApplicationLifeCycleEventListener(
221             ApplicationLifeCycleEventListener listener);
222 
223 }
224 
225
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags