KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jboss > ejb > 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 JavaDoc;
25 import java.rmi.RemoteException JavaDoc;
26 import java.util.Collection JavaDoc;
27
28 import javax.ejb.RemoveException JavaDoc;
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 JavaDoc createBeanClassInstance() throws Exception JavaDoc;
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 JavaDoc createEntity(Method JavaDoc m,
81                        Object JavaDoc[] args,
82                        EntityEnterpriseContext instance)
83       throws Exception JavaDoc;
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 JavaDoc postCreateEntity(Method JavaDoc m,
99                        Object JavaDoc[] args,
100                        EntityEnterpriseContext instance)
101       throws Exception JavaDoc;
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 JavaDoc findEntity(Method JavaDoc finderMethod,
119                      Object JavaDoc[] args,
120                      EntityEnterpriseContext instance,
121                      GenericEntityObjectFactory factory)
122       throws Exception JavaDoc;
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 JavaDoc findEntities(Method JavaDoc finderMethod,
141                            Object JavaDoc[] args,
142                            EntityEnterpriseContext instance,
143                            GenericEntityObjectFactory factory)
144       throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc, RemoveException JavaDoc;
233 }
234
Popular Tags