Container


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  package com.sun.ejb;
24  
25  import java.rmi.Remote  ;
26  import javax.transaction.UserTransaction  ;
27  import javax.ejb.*;
28  import com.sun.enterprise.deployment.EjbDescriptor;
29  import com.sun.enterprise.ComponentInvocation;
30  import com.sun.ejb.containers.EntityContextImpl;
31  
32  /**
33   * A Container stores EJB instances and is responsible for
34   * the lifecycle, state management, concurrency, transactions, security,
35   * naming, resource management, etc.
36   * It does the above by interposing actions before
37   * and after invocations on EJBs.
38   * It uses the ProtocolManager, SecurityManager, TransactionManager,
39   * NamingManager for help with the above responsibilities.
40   * There are four types of Containers:
41   * StatefulSessionContainer, StatelessSessionContainer,
42   * EntityContainer, and MessageBeanContainer.
43   * Note: the term "Container" here refers
44   * to an instance of one of the above container classes.
45   * In the EJB spec "container" refers to a process or JVM which
46   * hosts EJB instances.
47   * <p>
48   * There is one instance of the Container for each EJB type (deployment desc).
49   * When a JAR is deployed on the EJB server, a Container instance is created 
50   * for each EJB declared in the ejb-jar.xml for the EJB JAR.
51   * <p>
52   * The Container interface provides methods called from other parts of
53   * the RI as well as from generated EJBHome/EJBObject implementations.
54   *
55   */
56  public interface Container {
57  
58      // These values are for the transaction attribute of a bean method    
59      public int TX_NOT_INITIALIZED = 0; // default
60      public int TX_NOT_SUPPORTED = 1;
61      public int TX_BEAN_MANAGED = 2;
62      public int TX_REQUIRED = 3;
63      public int TX_SUPPORTS = 4;
64      public int TX_REQUIRES_NEW = 5;
65      public int TX_MANDATORY = 6;
66      public int TX_NEVER = 7;
67  
68      // Must match the values of the tx attributes above.
69      public String  [] txAttrStrings = { "TX_NOT_INITIALIZED",
70                                        "TX_NOT_SUPPORTED",
71                                        "TX_BEAN_MANAGED",
72                                        "TX_REQUIRED",
73                                        "TX_SUPPORTS",
74                                        "TX_REQUIRES_NEW",
75                                        "TX_MANDATORY",
76                                        "TX_NEVER" };
77  
78      // These values are for the security attribute of a bean method    
79      public int SEC_NOT_INITIALIZED = 0; // default
80      public int SEC_UNCHECKED = 1;
81      public int SEC_EXCLUDED = 2;
82      public int SEC_CHECKED = 3;
83  
84      public String  [] secAttrStrings = { "SEC_NOT_INITIALIZED",
85                                         "SEC_UNCHECKED", 
86                                         "SEC_EXCLUDED", 
87                                         "SEC_CHECKED" };
88  
89  
90      
91      /**
92       * Return the EJBObject/EJBHome for the given instanceKey.
93       * @param remoteHomeView True if this invocation is for the RemoteHome
94       * view of the bean.  False if for the RemoteBusiness view.
95       * Called from the ProtocolManager when a remote invocation arrives.
96       */
97      Remote   getTargetObject(byte[] instanceKey, String   remoteBusinessIntf);
98  
99      /**
100      * Release the EJBObject/EJBHome object.
101      * Called from the ProtocolManager after a remote invocation completes.
102      */
103     void releaseTargetObject(Remote   remoteObj);
104    
105     /**
106      * Performs pre external invocation setup such as setting application 
107      * context class loader.  Called by getTargetObject() and web service inv
108      */
109     public void externalPreInvoke();
110 
111     /**
112      * Performs post external invocation cleanup such as restoring the original
113      * class loader.  Called by releaseTargetObject() and web service inv
114      */
115     public void externalPostInvoke();
116 
117     /**
118      * Obtain an Entity EJBObject corresponding to the primary key.
119      * Used by the PersistenceManager.
120      */
121     EJBObject getEJBObjectForPrimaryKey(Object   pkey);
122 
123     /**
124      * Obtain an Entity EJBLocalObject corresponding to the primary key.
125      * Used by the PersistenceManager.
126      */
127     EJBLocalObject getEJBLocalObjectForPrimaryKey(Object   pkey, EJBContext ctx);
128     EJBLocalObject getEJBLocalObjectForPrimaryKey(Object   pkey);
129 
130     /**
131      * Verify that a given object is an EJBLocalObject of an ejb from this
132      * ejb container.  The given object must be an EJBLocalObject and have
133      * the same ejb type ( meaning same ejb-jar and same ejb-name ) as this
134      * container.  Note that for entity beans this equality check is independent of
135      * primary key.
136      *
137      * @exception EJBException Thrown when the assertion fails.
138      */
139     void assertValidLocalObject(Object   o) throws EJBException;
140 
141     /**
142      * Verify that a given object is an EJBObject of an ejb from this
143      * ejb container.  The given object must be an EJBObject and have
144      * the same ejb type ( meaning same ejb-jar and same ejb-name ) as this
145      * container.  Note that for entity beans this equality check is independent of
146      * primary key.
147      *
148      * @exception EJBException Thrown when the assertion fails.
149      */
150     void assertValidRemoteObject(Object   o) throws EJBException;
151 
152     /**
153      * Remove a bean. Used by the PersistenceManager.
154      */
155     void removeBeanUnchecked(EJBLocalObject bean);
156 
157     /**
158      * Remove a bean given primary key. Used by the PersistenceManager.
159      */
160     void removeBeanUnchecked(Object   pkey);
161 
162     /**
163      * Notification from persistence manager than an ejbSelect
164      * query is about to be invoked on a bean of the ejb type
165      * for this container.    This allows the ejb container
166      * to perform the same set of actions as take place before a
167      * finder method, such as calling ejbStore on bean instances.
168      * (See EJB 2.1, Section 10.5.3 ejbFind,ejbStore)
169      *
170      * @exception javax.ejb.EJBException  Thrown if an error occurs
171      *          during the preSelect actions performed by the container.
172      *          If thrown, the remaining select query steps should be 
173      *          aborted and an EJBException should be propagated
174      *          back to the application code.
175      */
176     void preSelect() throws javax.ejb.EJBException  ;
177 
178 
179     /**
180      * Called by the EJB(Local)Object/EJB(Local)Home before an invocation 
181      * on a bean.
182      */
183     void preInvoke(Invocation inv);
184 
185     /**
186      * Called by the EJB(Local)Object/EJB(Local)Home after an invocation 
187      * on a bean.
188      */
189     void postInvoke(Invocation inv);
190 
191     /**
192      * Called by the EJB(Local)Home after invoking ejbCreate on an EntityBean.
193      * After this postCreate the EJB(Local)Home can call ejbPostCreate on
194      * the EntityBean.
195      * @param primaryKey the value returned from ejbCreate.
196      */
197     void postCreate(Invocation inv, Object   primaryKey)
198     throws CreateException;
199 
200     /**
201      * Called by the EJB(Local)Home after invoking ejbFind* on an EntityBean.
202      * @param primaryKeys the primaryKey or collection of primaryKeys 
203      *        (Collection/Enumeration) returned from ejbFind.
204      * @param findParams the parameters to the ejbFind method.
205      * @return an EJBObject reference or Collection/Enumeration of EJBObjects.
206      */
207     Object   postFind(Invocation inv, Object   primaryKeys, Object  [] findParams)
208     throws FinderException;
209    
210     /**
211      * @return the EjbDescriptor containing deployment information 
212      * for the EJB type corresponding to this Container instance.
213      */
214     EjbDescriptor getEjbDescriptor();
215 
216     /**
217      * @return the MetaData for this EJB type.
218      */
219     EJBMetaData getEJBMetaData();
220 
221     /**
222      * @return the classloader of this container instance.
223      */
224     ClassLoader   getClassLoader();
225 
226     /**
227      * @return the EJBHome object reference for this container instance.
228      */
229     EJBHome getEJBHome();
230 
231     /**
232      * @return A SecurityManager object for this container. 
233      */
234     com.sun.enterprise.SecurityManager getSecurityManager();
235 
236     /**
237      * EJB spec makes a distinction between access to the UserTransaction
238      * object itself and access to its methods.  getUserTransaction covers
239      * the first check and this method covers the second.  It is called
240      * by the UserTransaction implementation to verify access.
241      */
242     boolean userTransactionMethodsAllowed(ComponentInvocation inv);
243 
244     /**
245      * Called from the TM when an EJB with Bean-Managed transactions starts a tx
246      */
247     void doAfterBegin(ComponentInvocation ci);
248 
249 
250     /**
251      * Called after all the components in the container's application
252      * have deployed successfully.  Allows containers to delay 
253      * public access to their resources until the end of the deployment
254      * process.
255      */
256     void doAfterApplicationDeploy();
257 
258     /** 
259      * Called from EJB JarManager when an application is undeployed.
260      */
261     void undeploy();
262 
263     /**  
264      * Called when server instance is Ready
265      */
266     void onReady();
267 
268     /** 
269      * Called when server instance is shuting down
270      */
271     void onShutdown();
272 
273     /** 
274      * Called when server instance is terminating. This method is the last
275      * one called during server shutdown.
276      */
277     void onTermination();
278 
279     /** 
280      * Called from NamingManagerImpl during java:comp/env lookup.
281      */
282     String   getComponentId();
283 
284     /**
285      * Start servicing invocations for EJB instances in this Container.
286 
287      */
288      void setStartedState();
289 
290     /**
291      * Stop servicing invocations for EJB instances in this Container.
292      * Subsequent EJB invocations will receive exceptions.
293      * Invocations already in progress will be allowed to complete eventually.
294      */
295      void setStoppedState();
296 
297     /**
298      * Stop servicing invocations for EJB instances in this Container as the 
299      * container is being undeployed.
300      * No new EJB invocations will be accepted from now on.
301      * Invocations already in progress will be allowed to complete eventually.
302      */
303      void setUndeployedState();
304 
305     /**
306      * Used by Invocation during JACC EnterpriseBean policy handler request
307      * for target EnterpriseBean instance.  
308      *
309      * @return EnterpriseBean instance or null if not applicable for this
310      *         invocation.
311      */
312     Object   getJaccEjb(Invocation inv);
313 
314     /**
315      * Go through ejb container to do ejb security manager authorization.
316      */
317     boolean authorize(Invocation inv);
318 
319 
320 }
321
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags