EntityPersistenceStore


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 Store.
33   *
34   * <p>These stores just deal with the persistence aspect of storing java 
35   *    objects. They need not be aware of the EJB semantics.  They act as
36   *    delegatees for the CMPEntityPersistenceManager class.
37   * 
38   * @see EntityPersistenceManager
39   * 
40   * @author <a HREF="mailto:rickard.oberg@telkel.com">Rickard �berg</a>
41   * @author <a HREF="mailto:marc.fleury@telkel.com">Marc Fleury</a>
42   * @author <a HREF="mailto:simone.bordet@compaq.com">Simone Bordet</a>
43   * @version $Revision: 37459 $
44   */
45  public interface EntityPersistenceStore
46     extends ContainerPlugin
47  {
48     /**
49      * Returns a new instance of the bean class or a subclass of the bean class.
50      * 
51      * @return   the new instance
52      *
53      * @throws Exception
54      */
55     Object   createBeanClassInstance() throws Exception  ;
56  
57     /**
58      * Initializes the instance context.
59      * 
60      * <p>This method is called before createEntity, and should
61      *    resetStats the value of all cmpFields to 0 or null.
62      *
63      * @param ctx
64      */
65     void initEntity(EntityEnterpriseContext ctx);
66  
67     /**
68      * This method is called whenever an entity is to be created.
69      * The persistence manager is responsible for handling the results properly
70      * wrt the persistent store.
71      *
72      * @param m           the create method in the home interface that was
73      *                    called
74      * @param args        any create parameters
75      * @param instance    the instance being used for this create call
76      * @return            The primary key computed by CMP PM or null for BMP
77      *
78      * @throws Exception
79      */
80     Object   createEntity(Method   m,
81                         Object  [] args,
82                         EntityEnterpriseContext instance)
83        throws Exception  ;
84  
85     /**
86      * This method is called after the createEntity.
87      * The persistence manager is responsible for handling the results properly
88      * wrt the persistent store.
89      *
90      * @param m           the ejbPostCreate method in the bean class that was
91      *                    called
92      * @param args        any create parameters
93      * @param instance    the instance being used for this create call
94      * @return            null
95      *
96      * @throws Exception
97      */
98     Object   postCreateEntity(Method   m,
99                         Object  [] args,
100                        EntityEnterpriseContext instance)
101       throws Exception  ;
102 
103    /**
104     * This method is called when single entities are to be found. The
105     * persistence manager must find out whether the wanted instance is
106     * available in the persistence store, if so it returns the primary key of
107     * the object.
108     *
109     * @param finderMethod    the find method in the home interface that was
110     *                        called
111     * @param args            any finder parameters
112     * @param instance        the instance to use for the finder call
113     * @return                a primary key representing the found entity
114     * 
115     * @throws RemoteException    thrown if some system exception occurs
116     * @throws Exception      thrown if some heuristic problem occurs
117     */
118    Object   findEntity(Method   finderMethod,
119                      Object  [] args,
120                      EntityEnterpriseContext instance,
121                      GenericEntityObjectFactory factory)
122       throws Exception  ;
123    
124    /**
125     * This method is called when collections of entities are to be found. The
126     * persistence manager must find out whether the wanted instances are
127     * available in the persistence store, and if so  it must return a
128     * collection of primaryKeys.
129     *
130     * @param finderMethod    the find method in the home interface that was
131     *                        called
132     * @param args            any finder parameters
133     * @param instance        the instance to use for the finder call
134     * @return                an primary key collection representing the found
135     *                        entities
136     *                        
137     * @throws RemoteException    thrown if some system exception occurs
138     * @throws Exception      thrown if some heuristic problem occurs
139     */
140    Collection   findEntities(Method   finderMethod,
141                            Object  [] args,
142                            EntityEnterpriseContext instance,
143                            GenericEntityObjectFactory factory)
144       throws Exception  ;
145 
146    /**
147     * This method is called when an entity shall be activated. 
148     *
149     * <p>With the PersistenceManager factorization most EJB calls should not
150     *    exists However this calls permits us to introduce optimizations in
151     *    the persistence store.  Particularly the context has a
152     *    "PersistenceContext" that a PersistenceStore can use (JAWS does for
153     *    smart updates) and this is as good a callback as any other to set it
154     *    up. 
155     *
156     * @param instance    the instance to use for the activation
157     * 
158     * @throws RemoteException    thrown if some system exception occurs
159     */
160    void activateEntity(EntityEnterpriseContext instance)
161       throws RemoteException  ;
162    
163    /**
164     * This method is called whenever an entity shall be load from the
165     * underlying storage. The persistence manager must load the state from
166     * the underlying storage and then call ejbLoad on the supplied instance.
167     *
168     * @param instance    the instance to synchronize
169     * 
170     * @throws RemoteException    thrown if some system exception occurs
171     */
172    void loadEntity(EntityEnterpriseContext instance)
173       throws RemoteException  ;
174       
175    /**
176     * This method is used to determine if an entity should be stored.
177     *
178     * @param instance    the instance to check
179     * @return true, if the entity has been modified
180     * @throws Exception    thrown if some system exception occurs
181     */
182    boolean isStoreRequired(EntityEnterpriseContext instance) throws Exception  ;
183 
184    /**
185     * This method is used to determined whether the instance was modified.
186     * NOTE, even if the method returns true the isStoreRequired for this same instance
187     * might return false, e.g. a CMR field that doesn't have a foreign key was modified.
188     *
189     * @param instance
190     * @return
191     * @throws Exception
192     */
193    boolean isModified(EntityEnterpriseContext instance) throws Exception  ;
194 
195    /**
196     * This method is called whenever an entity shall be stored to the
197     * underlying storage. The persistence manager must call ejbStore on the
198     * supplied instance and then store the state to the underlying storage.
199     *
200     * @param instance    the instance to synchronize
201     * 
202     * @throws RemoteException    thrown if some system exception occurs
203     */
204    void storeEntity(EntityEnterpriseContext instance)
205       throws RemoteException  ;
206 
207    /**
208     * This method is called when an entity shall be passivate. The persistence
209     * manager must call the ejbPassivate method on the instance.
210     *                                     
211     * <p>See the activate discussion for the reason for exposing EJB callback
212     *    calls to the store.
213     *
214     * @param instance    the instance to passivate
215     * 
216     * @throws RemoteException    thrown if some system exception occurs
217     */
218    void passivateEntity(EntityEnterpriseContext instance)
219       throws RemoteException  ;
220 
221    /**
222     * This method is called when an entity shall be removed from the
223     * underlying storage. The persistence manager must call ejbRemove on the
224     * instance and then remove its state from the underlying storage.
225     *
226     * @param instance    the instance to remove
227     * 
228     * @throws RemoteException    thrown if some system exception occurs
229     * @throws RemoveException    thrown if the instance could not be removed
230     */
231    void removeEntity(EntityEnterpriseContext instance)
232       throws RemoteException  , RemoveException  ;
233 }
234
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags