RpcContainer


1   /**
2    * Redistribution and use of this software and associated documentation
3    * ("Software"), with or without modification, are permitted provided
4    * that the following conditions are met:
5    * 
6    * 1. Redistributions of source code must retain copyright
7    *    statements and notices.  Redistributions must also contain a
8    *    copy of this document.
9    * 
10   * 2. Redistributions in binary form must reproduce the
11   *    above copyright notice, this list of conditions and the
12   *    following disclaimer in the documentation and/or other
13   *    materials provided with the distribution.
14   * 
15   * 3. The name "Exolab" must not be used to endorse or promote
16   *    products derived from this Software without prior written
17   *    permission of Exoffice Technologies.  For written permission,
18   *    please contact info@exolab.org.
19   * 
20   * 4. Products derived from this Software may not be called "Exolab"
21   *    nor may "Exolab" appear in their names without prior written
22   *    permission of Exoffice Technologies. Exolab is a registered
23   *    trademark of Exoffice Technologies.
24   * 
25   * 5. Due credit should be given to the Exolab Project
26   *    (http://www.exolab.org/).
27   * 
28   * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
29   * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30   * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31   * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
32   * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33   * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36   * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37   * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39   * OF THE POSSIBILITY OF SUCH DAMAGE.
40   * 
41   * Copyright 1999 (C) Exoffice Technologies Inc. All Rights Reserved.
42   * 
43   * $Id: RpcContainer.java 1921 2005-06-19 22:40:34Z jlaskowski $
44   */
45  
46  package org.openejb;
47  
48  
49  import java.lang.reflect.Method  ;
50  
51  /**
52   * The RpcContainer manages enterprise beans at runtime. The RpcContainer is responsible
53   * for interposing between the client and the EntepriseBean objects its manages. The
54   * RpcContainer applies transaction, security and persistence behavior as described the
55   * the deployment attributes for these services.  The RpcContainer works closely with its
56   * ContainerManager to obtain references to the appropriate primary services.
57   * <p>
58   * A RpcContainer may managed one or more bean deployments of a particular kind (stateless,
59   * stateful, BMP and CMP entity).  A Stateful container, for example, could manage all the
60   * one or more types (deployments) of stateful beans.
61   * <p>
62   * The Application Server (AS) will map each bean proxy (home and remote)to its container
63   * and deployment IDs, which are unique across the container system. The AS delivers
64   * client bean requests directly to the RpcContainer that is responsible for the invoked bean.
65   * <p>
66   * Business method requests as well as create, find, and remove requests are delivered directly to the container.
67   * Business methods are those methods defined in the bean's remote interface that
68   * are NOT already defined in the EJBObject interface. The container will respond with either a return value or an
69   * OpenEJBException type.  Return values are the return values of the bean method (null if void)
70   * and must be returned by the bean stub.  Exceptions are handled according to their type (see below).
71   * <p>
72   * Requests for a EJBHome and EJBObject references are managed by both the application server and the
73   * RpcContainer.  The RpcContainer has specific methods for these requests that return a ProxyInfo object. The
74   * application server uses the ProxyInfo object returned by these methods to create a remote stub
75   * that resides on the client.  The implementation of the remote stub is application server specific, but the
76   * ProxyInfo object provides the application server with helpful information including: The Remote interface to
77   * implement (EJBHome or EJBObject types), DeplymentInfo, primary key (stateful and entity only), and a reference to the container.
78   * This data is associated with the remote reference in an application sever specific way, and delivered with the
79   * Method and arguments to the RpcContainer each time the remote stub is invoked.
80   * <p>
81   * The invoke( ) method all performs access control checks while processing the requests.  Access with out the proper permissions will result in a
82   * org.openejb.ApplicaitonException with a nest java.rmi.RemoteException (process this exception as described below).
83   * <p>
84   * The OpenEJBException is the standard exception thrown by all methods in all type in the
85   * RpcContainer Provider Interface (CPI).  The OpenEJBException has 3 subtypes each serving a different
86   * purpose.  The CPI will always thrown one of these subtype and never the OpenEJBException itself.
87   * <ul>
88   * <li><b>org.openejb.ApplicationException</b><br>
89   *     This type is thrown when a normal EnterpriseBean exception is thrown.  The ApplicationException's nested
90   *     Exception will be either an EJB ApplicationException ( a custom exception defined by the bean developer)
91   *     or a RemoteException.  The org.openejb.ApplicationException must be caught and its nested exception rethrown
92   *     by the bean proxy to the client.  The org.openejb.ApplicationException is non-system exception; it does NOT
93   *     indicate a problem with the contaienr itself.
94   * <li><b>org.openejb.InvalidateReferenceException</b><br>
95   *     This type is thrown when the EnterpriseBean throws a RuntimeException or system exception that results in the
96   *     eviction of the bean instance.  The InvalidateReferenceException's nested exception will be a RemoteException
97   *     or possibly an ObjectNotFoundException.  
98   *     The Application Server must catch the InvalidateReferenceException and its nested exception rethrown by the bean proxy
99   *     After the exception is re-thrown by the bean proxy, the bean proxy must be invalidated so that all subsequent invocations by
100  *     the client on that bean proxy throw a RemoteException. The proxy is made invalid. InvalidateReferenceException is non-system
101  *     exception; it does NOT indicate a problem with the container itself.
102  * <li><b>org.openejb.SystemException</b><br>
103  *     This type is thrown when the container has encountered an unresolvable system exception that make this RpcContainer
104  *     unable to process requests.  A breakdown in communication with one of the primary services or a RuntimeException
105  *     thrown within the container (not by a bean) is are good examples.  The org.openejb.SystemException represents a
106  *     serious problem with the RpcContainer.  The RpcContainer should be shut down and not used for any more processing.
107  * </ul>
108  * <p>
109  * The default implementation of this interface is provided by the
110  * org.openejb.core.stateful.StatefulContainer, org.openejb.core.stateless.StatelessContainer,
111  * and org.openejb.core.entity.EntityContainer.
112  * <p>
113  * 
114  * @author Richard Monson-Haefel
115  * @version 0.1, 3/21/2000
116  * @see org.openejb.core.stateful.StatefulContainer
117  * @see org.openejb.core.stateless.StatelessContainer
118  * @see org.openejb.core.entity.EntityContainer
119  * @see org.openejb.ProxyInfo
120  * @since JDK 1.2
121  */
122 public interface RpcContainer extends Container{
123     
124     /**
125      * Invokes a method on an instance of the specified bean deployment.
126      *
127      * @param deployID the dployment id of the bean deployment
128      * @param callMethod the method to be called on the bean instance
129      * @param args the arguments to use when invoking the specified method
130      * @param primKey the primary key class of the bean or null if the bean does not need a primary key
131      * @param securityIdentity identity
132      * @return the result of invoking the specified method on the bean instance
133      * @throws OpenEJBException 
134      * @see org.openejb.core.stateful.StatefulContainer#invoke StatefulContainer.invoke
135      * @see org.openejb.core.stateless.StatelessContainer#invoke StatelessContainer.invoke
136      */
137     public Object   invoke(Object   deployID, Method   callMethod, Object   [] args, Object   primKey, Object   securityIdentity) throws OpenEJBException;
138 }
139
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags