ContainerHelper


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   * ContainerHelper.java
26   *
27   * Created on April 25, 2002
28   */
29  
30  package com.sun.jdo.spi.persistence.support.sqlstore.ejb;
31  
32  import javax.ejb.*;
33  
34  import com.sun.jdo.api.persistence.support.PersistenceManager;
35  import com.sun.jdo.api.persistence.support.PersistenceManagerFactory;
36  
37      /** Provide an implementation that supports CMP integration with information 
38       * required for such support.  This is an interface that a helper class
39       * implements that is specific to an application server.
40       * <P><B>This interface is subject to change without notice.  In particular, 
41       * as additional
42       * experience is gained with specific application servers, this interface
43       * may have methods added and removed, even with patch releases.
44       * Therefore, this interface should be considered very volatile, and
45       * any class that implements it might have to be reimplemented whenever
46       * an upgrade to either the application server or internal code occurs.</B></P>
47       * The class that implements this interface must register itself
48       * by a static method at class initialization time.  For example,
49       * <blockquote><pre>
50       * import com.sun.jdo.spi.persistence.support.sqlstore.ejb.*;
51       * class blackHerringContainerHelper implements ContainerHelper {
52       *    static CMPHelper.register(new blackHerringContainerHelper());
53       *    ...
54       * }
55       * </pre></blockquote>
56       */
57      public interface ContainerHelper {
58  
59      /** Called in a CMP-supported environment to get a Container helper instance that
60       * will be passed unchanged to the required methods.  In a non-managed environment 
61       * should not be called and throws JDOFatalInternalException.
62       * The info argument can be an array of Objects if necessary.
63       *   
64       * @see getEJBObject(Object, Object)
65       * @see getEJBLocalObject(Object, Object)
66       * @see getEJBLocalObject(Object, Object, EJBContext)
67       * @see removeByEJBLocalObject(EJBLocalObject, Object)
68       * @see removeByPK(Object, Object)
69       * @param info Object with the request information that is application server
70       * specific.
71       * @throws JDOFatalInternalException.
72       * @return a Container instance as an Object.
73       */
74      Object   getContainer(Object   info);
75  
76      /** Called in a CMP-supported environment to get an EJBObject reference for this
77       * primary key instance and Container instance. In a non-managed environment
78       * is not called.
79       * The Container instance is acquired via #getContainer(Object).
80       * 
81       * @see getContainerHelper(Object)
82       * @param pk the primary key instance.
83       * @param container a Container instance for the request.
84       * @return a corresponding EJBObject instance (as an Object) to be used by 
85       * the client.
86       */   
87      EJBObject getEJBObject(Object   pk, Object   container);
88  
89      /** Called in a CMP-supported environment to get an EJBLocalObject reference for this 
90       * primary key instance and Container instance. In a non-managed environment 
91       * is not called.
92       * The Container instance is acquired via #getContainer(Object). 
93       * 
94       * @see getContainer(Object)
95       * @param pk the primary key instance. 
96       * @param container a Container instance for the request. 
97       * @return a corresponding EJBLocalObject (as an Object) instance to be used 
98       * by the client. 
99       */    
100     EJBLocalObject getEJBLocalObject(Object   pk, Object   container);
101 
102     /** Called in a CMP-supported environment to get an EJBLocalObject reference for this
103      * primary key instance, Container object, and EJBContext of the calling bean.
104      * Allows the container to check if this method is called during ejbRemove
105      * that is part of a cascade-delete remove.
106      * The Container instance is acquired via #getContainer(Object).
107      *
108      * @see getContainer(Object)
109      * @param pk the primary key instance.
110      * @param container a Container instance for the request.
111      * @param context an EJBContext of the calling bean.
112      * @return a corresponding EJBLocalObject (as an Object) to be used by
113      * the client.
114      */  
115     EJBLocalObject getEJBLocalObject(Object   pk, Object   container,
116         EJBContext context);
117 
118     /** Called in a CMP-supported environment to remove a bean for a given 
119      * EJBLocalObject and Container instance.
120      * The Container instance is acquired via #getContainerHelper(Object).
121      * 
122      * @see getContainer(Object)
123      * @param ejb the EJBLocalObject for the bean to be removed.
124      * @param container a Container instance for the request. 
125      */ 
126     void removeByEJBLocalObject(EJBLocalObject ejb, Object   containerHelper);
127 
128     /** Called in a CMP-supported environment to remove a bean for a given primary key
129      * and Container instance.
130      * The Container instance is acquired via #getContainer(Object).
131      * 
132      * @see getContainer(Object)
133      * @param pk the primary key for the bean to be removed.
134      * @param container a Container instance for the request. 
135      */  
136     void removeByPK(Object   pk, Object   container);
137 
138     /** Called in a CMP-supported environment to verify that the specified object
139      * is of a valid local interface type.
140      * The Container instance is acquired via #getContainer(Object).
141      *
142      * @see getContainer(Object)
143      * @param o the instance to validate.
144      * @param container a Container instance for the request.
145      */
146     void assertValidLocalObject(Object   o, Object   container);
147 
148     /** Called in a CMP-supported environment to verify that the specified object
149      * is of a valid remote interface type.
150      * The Container instance is acquired via #getContainer(Object).
151      *
152      * @see getContainer(Object)
153      * @param o the instance to validate.
154      * @param container a Container instance for the request.
155      */
156     void assertValidRemoteObject(Object   o, Object   container);
157 
158     /** Called in a CMP-supported environment to mark EntityContext as
159      * already removed during cascade-delete operation.
160      * The Container instance is acquired via #getContainer(Object).
161      * Called by the generated ejbRemove method before calling ejbRemove of the 
162      * related beans (via removeByEJBLocalObject) that are to be cascade-deleted.
163      *
164      *   
165      * @param context the EntityContext of the bean beeing removed.
166      */  
167     void setCascadeDeleteAfterSuperEJBRemove(EntityContext context);
168 
169     /** Called in a CMP supported environment. Notifies the container that 
170      * ejbSelect had been called.
171      * The Container instance is acquired via #getContainer(Object).
172      *
173      * @see getContainer(Object)
174      * @param container a Container instance for the request.
175      */
176     void preSelect(Object   container);
177 
178     /** Called in a CMP environment to lookup PersistenceManagerFactory
179      * referenced by this Container instance as the CMP resource.
180      * The Container instance is acquired via #getContainer(Object).
181      *   
182      * @see getContainer(Object)
183      * @param container a Container instance for the request.
184      */  
185     PersistenceManagerFactory getPersistenceManagerFactory(Object   container);
186 
187     /**
188      * Called in CMP environment to get NumericConverter policy referenced
189      * by this Container instance.
190      * @see getContainer(Object)
191      * @param container a Container instance for the request
192      * @return a valid NumericConverter policy type
193      */
194     int getNumericConverterPolicy(Object   container);
195 
196     /** Called in a unspecified transaction context of a managed environment.
197      * According to p.364 of EJB 2.0 spec, CMP may need to manage
198      * its own transaction when its transaction attribute is
199      * NotSupported, Never, Supports.
200      *
201      * @param pm PersistenceManager
202      */
203     void beginInternalTransaction(PersistenceManager pm);
204 
205     /** Called in a unspecified transaction context of a managed environment.
206      * According to p.364 of EJB 2.0 spec, CMP may need to manage
207      * its own transaction when its transaction attribute is
208      * NotSupported, Never, Supports.
209      *
210      * @param pm PersistenceManager
211      */
212     void commitInternalTransaction(PersistenceManager pm);
213 
214     /** Called in a unspecified transaction context of a managed environment.
215      * According to p.364 of EJB 2.0 spec, CMP may need to manage
216      * its own transaction when its transaction attribute is
217      * NotSupported, Never, Supports.
218      *
219      * @param pm PersistenceManager
220      */
221     void rollbackInternalTransaction(PersistenceManager pm);
222 
223     /** Called from read-only beans to suspend current transaction.
224      * This will guarantee that PersistenceManager is not bound to
225      * any transaction.
226      *
227      * @return javax.transaction.Transaction object representing 
228      * the suspended transaction.
229      * Returns null if the calling thread is not associated
230      * with a transaction.
231      */
232     javax.transaction.Transaction   suspendCurrentTransaction();
233 
234     /** Called from read-only beans to resume current transaction.
235      * This will guarantee that the transaction continues to run after
236      * read-only bean accessed its PersistenceManager.
237      *
238      * @param tx - The javax.transaction.Transaction object that 
239      * represents the transaction to be resumed.
240      */
241     void resumeCurrentTransaction(javax.transaction.Transaction   tx);
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags