EJBHelper


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   * EJBHelper.java
26   *
27   * Created on December 15, 2000, 10:15 AM
28   */
29  package com.sun.jdo.spi.persistence.support.sqlstore.ejb;
30  
31  import java.util.ResourceBundle  ;
32  
33  import javax.transaction.*;
34  import com.sun.jdo.spi.persistence.utility.I18NHelper;
35  import com.sun.jdo.api.persistence.support.PersistenceManagerFactory;
36  import com.sun.jdo.api.persistence.support.JDOFatalInternalException;
37  import com.sun.jdo.spi.persistence.utility.logging.Logger;
38  import com.sun.jdo.spi.persistence.support.sqlstore.LogHelperPersistenceManager;
39  
40    /** Provides helper methods for a Forte for Java implementation with the
41     * application server specific information in the distributed transaction
42     * environment. Calls corresponding methods on the registered class which
43     * implements TransactionHelper interface.
44     */
45  public class EJBHelper {
46  
47      /** I18N message handler */
48      private final static ResourceBundle   messages = I18NHelper.loadBundle(
49          "com.sun.jdo.spi.persistence.support.sqlstore.Bundle", // NOI18N
50          EJBHelper.class.getClassLoader());
51  
52      /** The logger */
53      private static Logger logger = LogHelperPersistenceManager.getLogger();
54  
55     /** Reference to a class that implements TransactionHelper interface for this
56      * particular application server, or DefaultTransactionHelper for a non-managed
57      * environment.
58      */
59      static TransactionHelper myHelper = DefaultTransactionHelper.getInstance();
60  
61     /** Register class that implements TransactionHelper interface
62      * Should be called by a static method at class initialization time.
63      * If null is passed, sets the reference to the DefaultTransactionHelper.
64      *
65      * @param    h   application server specific implemetation of the TransactionHelper
66      *           interface.
67      */
68      public static void registerTransactionHelper (TransactionHelper h) {
69          myHelper = h;
70          if (myHelper == null) {
71              myHelper = DefaultTransactionHelper.getInstance();
72          }
73      }
74  
75     /** Returns Transaction instance that can be used to register synchronizations.
76      * In a non-managed environment or if there is no transaction associated with
77      * the current thread, this method returns null.
78      *
79      * @see TransactionHelper#getTransaction()
80      * @return the Transaction instance for the calling thread
81      */
82      public static Transaction getTransaction() {
83          return myHelper.getTransaction();
84      }
85  
86     /** Returns the UserTransaction associated with the calling thread.  In a
87      * non-managed environment or if there is no transaction currently in progress,
88      * this method returns null.
89      *
90      * @see TransactionHelper#getUserTransaction()
91      * @return the UserTransaction instance for the calling thread
92      */
93      public static UserTransaction getUserTransaction() {
94          return myHelper.getUserTransaction();
95      }
96  
97      /** Identifies the managed environment behavior.
98       * @return true if this implementation represents the managed environment.
99       */
100     public static boolean isManaged() {
101         return myHelper.isManaged();
102     }
103 
104    /** Translates local representation of the Transaction Status to
105     * javax.transaction.Status value. In a non-managed environment
106     * returns the value passed to it as an argument.
107     *
108     * @see TransactionHelper#translateStatus(int st)
109     * @param    local   Status value
110     * @return   the javax.transaction.Status value of the status
111     */
112     public static int translateStatus(int st) {
113         return myHelper.translateStatus(st);
114     }
115 
116    /** Returns the hashed instance of PersistenceManagerFactory
117     * that compares equal to the newly created instance or the instance
118     * itself if it is not found. In a non-managed environment returns the value
119     * passed to it as an argument.
120     *
121     * @see TransactionHelper#replaceInternalPersistenceManagerFactory(
122     *   PersistenceManagerFactory pmf)
123     * @param    pmf     PersistenceManagerFactory instance to be replaced
124     * @return   the PersistenceManagerFactory known to the runtime
125     */
126     public static PersistenceManagerFactory replaceInternalPersistenceManagerFactory(
127                 PersistenceManagerFactory pmf) {
128         return myHelper.replaceInternalPersistenceManagerFactory(pmf);
129     }
130 
131    /** Called at the beginning of the Transaction.beforeCompletion() to register
132     * the component with the app server if necessary. In a non-managed environment
133     * or if the postInvoke method does not use the value, this method returns null.
134     *
135     * @see TransactionHelper#preInvoke(Object component)
136     * @param    component   an array of Objects
137     * @return implementation-specific Object
138     */
139     public static Object   preInvoke(Object   component) {
140         return myHelper.preInvoke(component);
141     }
142 
143    /** Called in a managed environment at the end of the Transaction.beforeCompletion()
144     * to de-register the component with the app server if necessary.
145     *
146     * @see TransactionHelper#postInvoke(Object im)
147     * @param im implementation-specific Object
148     */
149     public static void postInvoke(Object   im) {
150         myHelper.postInvoke(im);
151     }
152 
153    /** Called in a managed environment to register internal Synchronization object
154     * with the Transaction Synchronization. If available, this registration
155     * provides special handling of the registered instance, calling it after
156     * all user defined Synchronization instances.
157     *
158     * @see Transaction#registerSynchronization(Synchronization sync)
159     * @see TransactionHelper#registerSynchronization(Transaction jta, 
160     * Synchronization sync)
161     * @param jta the Transaction instance for the calling thread.
162     * @param sync the internal Synchronization instance to register.
163     * @throws javax.transaction.RollbackException.
164     * @throws javax.transaction.SystemException.
165     */
166     public static void registerSynchronization(Transaction jta, 
167         Synchronization sync) throws RollbackException, SystemException {
168         myHelper.registerSynchronization(jta, sync);
169     }
170 
171     /** Called in a managed environment to get a Connection from the application
172      * server specific resource. In a non-managed environment throws an Exception 
173      * as it should not be called.
174      *
175      * @param resource the application server specific resource.
176      * @param username the resource username. If null, Connection is requested
177      * without username and password validation.
178      * @param password the password for the resource username.
179      * @return a Connection.
180      * @throw java.sql.SQLException.
181      */
182     public static java.sql.Connection   getConnection(Object   resource, 
183         String   username, String   password) throws java.sql.SQLException   {
184         return myHelper.getConnection(resource, username, password);
185     }
186 
187     /** Called in a managed environment to get a non-transactional Connection
188      * from the application server specific resource. In a non-managed 
189      * environment throws an Exception as it should not be called.
190      *
191      * @param resource the application server specific resource.
192      * @param username the resource username. If null, Connection is requested
193      * without username and password validation.
194      * @param password the password for the resource username.
195      * @return a Connection.
196      * @throw java.sql.SQLException.
197      */
198     public static java.sql.Connection   getNonTransactionalConnection(
199         Object   resource, String   username, String   password)
200         throws java.sql.SQLException   {
201 
202         return myHelper.getNonTransactionalConnection(resource, 
203             username, password);
204     }
205 
206 
207     /** Called in a managed environment to access a TransactionManager
208      * for managing local transaction boundaries and synchronization
209      * for local transaction completion.
210      * 
211      * @return javax.transaction.TransactionManager
212      */
213     public static TransactionManager getLocalTransactionManager() {
214         return myHelper.getLocalTransactionManager();
215     }
216 
217     /**
218      * This method unwraps given Statement and return the Statement from
219      * JDBC driver if possible.
220      */
221     public static java.sql.Statement   unwrapStatement(java.sql.Statement   stmt) {
222         return myHelper.unwrapStatement(stmt);
223     }
224     
225     /**
226      * Set environment specific default values for the given PersistenceManagerFactory.
227      *   
228      * @param pmf the PersistenceManagerFactory.
229      */  
230     public static void setPersistenceManagerFactoryDefaults(PersistenceManagerFactory pmf) {
231         myHelper.setPersistenceManagerFactoryDefaults(pmf);
232     }
233 
234     /**
235      * Returns name prefix for DDL files extracted from the info instance by the
236      * application server specific code.
237      *   
238      * @param info the instance to use for the name generation.
239      * @return name prefix as String.
240      */  
241     public static String   getDDLNamePrefix(Object   info) {
242         return myHelper.getDDLNamePrefix(info);
243     }
244       
245     /**
246      * Called to register a ApplicationLifeCycleEventListener. If
247      * ApplicationLifeCycle management is active (typically in managed
248      * environment), the registered listener will receive a call back
249      * for lifecycle events.
250      *
251      * @param listener An instance of ApplicationLifeCycleEventListener. 
252      */  
253     public static void registerApplicationLifeCycleEventListener(
254             ApplicationLifeCycleEventListener listener) {
255         myHelper.registerApplicationLifeCycleEventListener(listener);        
256     }
257 
258       /**
259      * This is the default implementation of the TransactionHelper interface
260      * for a non-mananged environment execution.
261      * In the managed environment the application server specific implementation
262      * registers itself with the EJBHelper to override this behavior.
263      */
264     private static class DefaultTransactionHelper implements TransactionHelper {
265         
266        private static final DefaultTransactionHelper instance = new DefaultTransactionHelper();
267 
268        /**
269         * Returns instance of this class.
270         */
271        public static DefaultTransactionHelper getInstance() {return instance;}
272 
273        /** 
274         * In a non-managed environment there is no transaction associated with
275         * the current thread, this method returns null.
276         *
277         * @see TransactionHelper#getTransaction()
278         * @return null;
279         */
280         public Transaction getTransaction() { return null; }
281     
282        /** 
283         * In a non-managed environment there is no transaction currently in progress,
284         * this method returns null.
285         *
286         * @see TransactionHelper#getUserTransaction()
287         * @return the null.
288         */
289         public UserTransaction getUserTransaction() { return null; }
290     
291         /** Identifies the non-managed environment behavior.
292          * @return false.
293          */
294         public boolean isManaged() { return false; }
295     
296        /** 
297         * In a non-managed environment returns the value passed to it as an argument.
298         *
299         * @see TransactionHelper#translateStatus(int st)
300         * @param    local   Status value
301         * @return   the status value
302         */
303         public int translateStatus(int st) { return st; }
304     
305        /** 
306         * In a non-managed environment returns the value passed to it as an argument.
307         *
308         * @see TransactionHelper#replaceInternalPersistenceManagerFactory(
309         *   PersistenceManagerFactory pmf)
310         * @param    pmf     PersistenceManagerFactory instance to be replaced
311         * @return   the pmf value.
312         */
313         public PersistenceManagerFactory replaceInternalPersistenceManagerFactory(
314                     PersistenceManagerFactory pmf) { return pmf; }
315     
316        /** Called at the beginning of the Transaction.beforeCompletion() to register
317         * the component with the app server if necessary. 
318         * In a non-managed environment throws JDOFatalInternalException.
319         *
320         * @see TransactionHelper#preInvoke(Object component)
321         * @param    component   an array of Objects
322         * @throw JDOFatalInternalException if called.
323         */
324         public Object   preInvoke(Object   component) { 
325             throw new JDOFatalInternalException(I18NHelper.getMessage(
326                 messages, "ejb.ejbhelper.nonmanaged", "preInvoke")); //NOI18N
327         }
328     
329        /** Called in a managed environment at the end of the Transaction.beforeCompletion()
330         * to de-register the component with the app server if necessary.
331         * In a non-managed environment throws JDOFatalInternalException.
332         *
333         * @see TransactionHelper#postInvoke(Object im)
334         * @param im implementation-specific Object
335         * @throw JDOFatalInternalException if called.
336         */
337         public void postInvoke(Object   im) { 
338             throw new JDOFatalInternalException(I18NHelper.getMessage(
339                 messages, "ejb.ejbhelper.nonmanaged", "postInvoke")); //NOI18N
340         }
341     
342        /** Called in a managed environment to register internal Synchronization object
343         * with the Transaction Synchronization. 
344         * In a non-managed environment it is a no-op.
345         *
346         * @see Transaction#registerSynchronization(Synchronization sync)
347         * @see TransactionHelper#registerSynchronization(Transaction jta, 
348         * Synchronization sync)
349         * @param jta the Transaction instance for the calling thread.
350         * @param sync the internal Synchronization instance to register.
351         * @throws javax.transaction.RollbackException.
352         * @throws javax.transaction.SystemException.
353         */
354         public void registerSynchronization(Transaction jta, 
355             Synchronization sync) throws RollbackException, SystemException { }
356     
357         /** Called in a managed environment to get a Connection from the application
358          * server specific resource. 
359          * In a non-managed environment throws JDOFatalInternalException.
360          *
361          * @param resource the application server specific resource.
362          * @param username the resource username. If null, Connection is requested
363          * without username and password validation.
364          * @param password the password for the resource username.
365          * @throw JDOFatalInternalException if called.
366          * @throw java.sql.SQLException.
367          */
368         public java.sql.Connection   getConnection(Object   resource, 
369             String   username, String   password) throws java.sql.SQLException   {
370             throw new JDOFatalInternalException(I18NHelper.getMessage(
371                 messages, "ejb.ejbhelper.nonmanaged", "getConnection")); //NOI18N
372         }
373     
374         /** Called in a managed environment to get a non-transactional Connection
375          * from the application server specific resource.
376          * In a non-managed environment throws JDOFatalInternalException.
377          *
378          * @param resource the application server specific resource.
379          * @param username the resource username. If null, Connection is requested
380          * without username and password validation.
381          * @param password the password for the resource username.
382          * @throw JDOFatalInternalException if called.
383          * @throw java.sql.SQLException.
384          */
385         public java.sql.Connection   getNonTransactionalConnection(
386             Object   resource, String   username, String   password)
387             throws java.sql.SQLException   {
388 
389             throw new JDOFatalInternalException(I18NHelper.getMessage(
390                 messages, "ejb.ejbhelper.nonmanaged", //NOI18N
391                 "getNonTransactionalConnection")); //NOI18N
392         }
393     
394         /** Called in a managed environment to access a TransactionManager
395          * for managing local transaction boundaries and synchronization
396          * for local transaction completion.
397          * 
398          * @return javax.transaction.TransactionManager
399          */
400         public TransactionManager getLocalTransactionManager() {
401             throw new JDOFatalInternalException(I18NHelper.getMessage(
402                 messages, "ejb.ejbhelper.nonmanaged", "getLocalTransactionManager")); //NOI18N
403         }
404     
405         /**
406          * This method unwraps given Statement and return the Statement from
407          * JDBC driver if possible.
408          */
409         public java.sql.Statement   unwrapStatement(java.sql.Statement   stmt) {
410             if (stmt instanceof com.sun.jdo.spi.persistence.support.sqlstore.connection.StatementImpl) {
411                 return ((com.sun.jdo.spi.persistence.support.sqlstore.connection.StatementImpl)stmt).unwrapStatement();
412             } else {
413                 return stmt;
414             }
415         }
416 
417         /** 
418          * Set environment specific default values for the given PersistenceManagerFactory. 
419          * In a non-managed this is a no-op.
420          *   
421          * @param pmf the PersistenceManagerFactory. 
422          */   
423         public void setPersistenceManagerFactoryDefaults(PersistenceManagerFactory pmf) {}
424 
425         /** 
426          * Returns name prefix for DDL files extracted from the info instance by the 
427          * application server specific code. 
428          * In a non-managed environment throws JDOFatalInternalException.
429          *   
430          * @param info the instance to use for the name generation. 
431          * @return name prefix as String. 
432          */   
433         public String   getDDLNamePrefix(Object   info) { 
434             throw new JDOFatalInternalException(I18NHelper.getMessage(
435                 messages, "ejb.ejbhelper.nonmanaged", "getDDLNamePrefix")); //NOI18N
436         }
437           
438         /**
439          * @inheritDoc
440          */ 
441         public void registerApplicationLifeCycleEventListener(
442                 ApplicationLifeCycleEventListener listener) {
443             // The default implementation is no-op 
444         }
445    }
446 }
447
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags