EntityPersistenceManager


1   /*
2   * JBoss, Home of Professional Open Source
3   * Copyright 2005, JBoss Inc., and individual contributors as indicated
4   * by the @authors tag. See the copyright.txt in the distribution for a
5   * full listing of individual contributors.
6   *
7   * This is free software; you can redistribute it and/or modify it
8   * under the terms of the GNU Lesser General Public License as
9   * published by the Free Software Foundation; either version 2.1 of
10  * the License, or (at your option) any later version.
11  *
12  * This software is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this software; if not, write to the Free
19  * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20  * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21  */
22  package org.jboss.ejb;
23  
24  import java.lang.reflect.Method  ;
25  import java.rmi.RemoteException  ;
26  import java.util.Collection  ;
27  
28  import javax.ejb.RemoveException  ;
29  
30  
31  /**
32   *  This interface is implemented by any EntityBean persistence managers plugins.
33   *
34   * <p>Implementations of this interface are called by other plugins in the
35   *    container.  If the persistence manager wants to, it may attach any
36   *    instance specific metadata to the EntityEnterpriseContext that is
37   *    passed in method calls.
38   *
39   * @see EntityContainer
40   * 
41   * @author <a HREF="mailto:rickard.oberg@telkel.com">Rickard �berg</a>
42   * @author <a HREF="mailto:dain@daingroup.com">Dain Sundstrom</a>
43   * @version $Revision: 37459 $
44   */
45  public interface EntityPersistenceManager extends ContainerPlugin
46  {
47     /**
48      * Returns a new instance of the bean class or a subclass of the bean class.
49      * 
50      * @return the new instance
51      */
52     Object   createBeanClassInstance() throws Exception  ;
53  
54     /**
55      * This method is called whenever an entity is to be created. The
56      * persistence manager is responsible for calling the ejbCreate method
57      * on the instance and to handle the results properly wrt the persistent
58      * store.
59      *
60      * @param m           the create method in the home interface that was
61      *                    called
62      * @param args        any create parameters
63      * @param instance    the instance being used for this create call
64      */
65     void createEntity(Method   m,
66                       Object  [] args,
67                       EntityEnterpriseContext instance)
68        throws Exception  ;
69  
70     /**
71      * This method is called whenever an entity is to be created. The
72      * persistence manager is responsible for calling the ejbPostCreate method
73      * on the instance and to handle the results properly wrt the persistent
74      * store.
75      *
76      * @param m           the create method in the home interface that was
77      *                    called
78      * @param args        any create parameters
79      * @param instance    the instance being used for this create call
80      */
81     void postCreateEntity(Method   m,
82                       Object  [] args,
83                       EntityEnterpriseContext instance)
84        throws Exception  ;
85  
86     /**
87      * This method is called when single entities are to be found. The
88      * persistence manager must find out whether the wanted instance is
89      * available in the persistence store, and if so it shall use the
90      * EJBProxyFactory plugin to create an EJBObject to the instance, which
91      * is to be returned as result.
92      *
93      * @param finderMethod    the find method in the home interface that was
94      *                        called
95      * @param args            any finder parameters
96      * @param instance        the instance to use for the finder call
97      * @return                an EJBObject representing the found entity
98      */
99     Object   findEntity(Method   finderMethod,
100                      Object  [] args,
101                      EntityEnterpriseContext instance,
102                      GenericEntityObjectFactory factory)
103       throws Exception  ;
104 
105    /**
106     * This method is called when collections of entities are to be found. The
107     * persistence manager must find out whether the wanted instances are
108     * available in the persistence store, and if so it shall use the
109     * EJBProxyFactory plugin to create EJBObjects to the instances, which are
110     * to be returned as result.
111     *
112     * @param finderMethod    the find method in the home interface that was
113     *                        called
114     * @param args            any finder parameters
115     * @param instance        the instance to use for the finder call
116     * @return                an EJBObject collection representing the found
117     *                        entities
118     */
119    Collection   findEntities(Method   finderMethod,
120                            Object  [] args,
121                            EntityEnterpriseContext instance,
122                            GenericEntityObjectFactory factory)
123       throws Exception  ;
124 
125    /**
126     * This method is called when an entity shall be activated. The persistence
127     * manager must call the ejbActivate method on the instance.
128     *
129     * @param instance    the instance to use for the activation
130     * 
131     * @throws RemoteException    thrown if some system exception occurs
132     */
133    void activateEntity(EntityEnterpriseContext instance)
134       throws RemoteException  ;
135    
136    /**
137     * This method is called whenever an entity shall be load from the
138     * underlying storage. The persistence manager must load the state from
139     * the underlying storage and then call ejbLoad on the supplied instance.
140     *
141     * @param instance    the instance to synchronize
142     * 
143     * @throws RemoteException    thrown if some system exception occurs
144     */
145    void loadEntity(EntityEnterpriseContext instance)
146       throws RemoteException  ;
147       
148    /**
149     * This method is used to determine if an entity should be stored.
150     *
151     * @param instance    the instance to check
152     * @return true, if the entity has been modified
153     * @throws Exception    thrown if some system exception occurs
154     */
155    boolean isStoreRequired(EntityEnterpriseContext instance) throws Exception  ;
156 
157    /**
158     * This method is used to determined whether the instance was modified.
159     * NOTE, even if the method returns true the isStoreRequired for this same instance
160     * might return false, e.g. a CMR field that doesn't have a foreign key was modified.
161     *  
162     * @param ctx
163     * @return
164     * @throws Exception
165     */
166    boolean isModified(EntityEnterpriseContext ctx) throws Exception  ;
167 
168    /**
169     * This method is called whenever an entity shall be stored to the
170     * underlying storage. The persistence manager must call ejbStore on the
171     * supplied instance and then store the state to the underlying storage.
172     *
173     * @param instance    the instance to synchronize
174     * 
175     * @throws RemoteException    thrown if some system exception occurs
176     */
177    void storeEntity(EntityEnterpriseContext instance)
178       throws RemoteException  ;
179 
180    /**
181     * Invokes ejbStore on the instance.
182     *
183     * @param instance
184     * @throws RemoteException
185     */
186    void invokeEjbStore(EntityEnterpriseContext instance)
187       throws RemoteException  ;
188    
189    /**
190     * This method is called when an entity shall be passivate. The persistence
191     * manager must call the ejbPassivate method on the instance.
192     *
193     * @param instance    the instance to passivate
194     * 
195     * @throws RemoteException    thrown if some system exception occurs
196     */
197    void passivateEntity(EntityEnterpriseContext instance)
198       throws RemoteException  ;
199 
200    /**
201     * This method is called when an entity shall be removed from the
202     * underlying storage. The persistence manager must call ejbRemove on the
203     * instance and then remove its state from the underlying storage.
204     *
205     * @param instance    the instance to remove
206     * 
207     * @throws RemoteException    thrown if some system exception occurs
208     * @throws RemoveException    thrown if the instance could not be removed
209     */
210    void removeEntity(EntityEnterpriseContext instance)
211       throws RemoteException  , RemoveException  ;
212 }
213 
214
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags