Source code: com/RuntimeCollective/webapps/EntityBeanStore.java
1 /* $Header: /home/CVS/rjp/src/com/RuntimeCollective/webapps/EntityBeanStore.java,v 1.11 2003/09/30 15:13:03 joe Exp $
2 * $Revision: 1.11 $
3 * $Date: 2003/09/30 15:13:03 $
4 *
5 * ====================================================================
6 *
7 * Josephine : http://www.runtime-collective.com/josephine/index.html
8 *
9 * Copyright (C) 2003 Runtime Collective
10 *
11 * This product includes software developed by the
12 * Apache Software Foundation (http://www.apache.org/).
13 *
14 * This library is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU Lesser General Public
16 * License as published by the Free Software Foundation; either
17 * version 2.1 of the License, or (at your option) any later version.
18 *
19 * This library is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * Lesser General Public License for more details.
23 *
24 * You should have received a copy of the GNU Lesser General Public
25 * License along with this library; if not, write to the Free Software
26 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
27 *
28 */
29
30 package com.RuntimeCollective.webapps;
31
32 import com.RuntimeCollective.webapps.bean.EntityBean;
33 import com.RuntimeCollective.webapps.Cache;
34
35 import java.sql.SQLException;
36 import java.util.Iterator;
37 import java.util.List;
38
39 /** A store for <code>EntityBean</code>s that ensures that multiple instances of the same bean are never recreated from the database.
40 * <p> There are three advantages to using EntityBeanStores:
41 * <ol>
42 * <li> Reduces the overhead in creating new Java objects.
43 * <li> Reduces the overhead in extra reads from the database.
44 * <li> Eliminates the problem of keeping multiple instances of the same bean synchronised.
45 * </ol>
46 *
47 * <p> There are four stages to using this store:
48 * <ol>
49 * <li> <strong>Register bean types</strong> (<code>registerBean()</code>) Register each type of bean class that the store will hold, using a specified cache class.
50 * <li> <strong>Initialise the store</strong> (<code>init()</code>) The store will then construct a hashtable, keyed by primary key, for holding each type of bean.
51 * <li> <strong>Get bean instances</strong> (<code>get()</code> and <code>create()</code>) Threads within a Runtime Struts application should <strong>never</strong> create new beans directly (except if they are <i>guaranteed</i> to be used only by a single thread). Instead they should get new bean instances from this store. If the bean has not yet bean created, then it will be generated from the database, stored in memory inside the store, and can be accessed by the thread.
52 * <li> <strong>Manipulate bean instances</strong> (<code>save()</code> and <code>delete()</code>) Threads should never save or delete beans directly, but on ly via the store.
53 * </ol>
54 *
55 * <p> An EntityBeanStore will be initialised automatically from the InitialiserServlet if the appropriate init-params are included in web.xml. Once initialised it is available from <code>RuntimeParameters.getStore()</code>.
56 * <p> It is up to particular implementations of this interface to ensure that they are thread-safe. Interface methods are not declared synchronized, but implemented code may have to be.
57 * @version $Id: EntityBeanStore.java,v 1.11 2003/09/30 15:13:03 joe Exp $
58 * @see com.RuntimeCollective.webapps.bean.EntityBean
59 * @see com.RuntimeCollective.webapps.servlet.InitialiserServlet
60 * @see com.RuntimeCollective.webapps.SimpleEntityBeanStore
61 * @see com.RuntimeCollective.webapps.IndexedEntityBeanStore
62 * @see com.RuntimeCollective.webapps.RuntimeParameters
63 */
64 public interface EntityBeanStore {
65
66 /** Register an Entity Bean class on this store.
67 * @param className The fully-resolved name of the class of this bean. The method checks whether this class implements the <code>EntityBean</code> interface, and whether it is abstract/has suitable constructors (if it doesn't, we register it nonetheless).
68 * @param cacheName The fully-resolved name of the Cache class to use for this bean. The method checks whether this class implements the <code>Cache</code> interface, if not throws an error.
69 * @exception RuntimeException thrown if there was a problem registering this bean class.
70 */
71 public void registerBean(String className, String cacheName);
72
73
74 /** Initialise the store, creating the necessary caches to store the registered bean types.
75 */
76 public void init();
77
78
79 /** Get an entity bean.
80 * @param className The name of the class of entity to create.
81 * @param id The primary key of the entity.
82 * @return An entity bean, either generated from the database, or retrieved from memory. Returns <code>null</code> if no such bean exists for that name and id.
83 */
84 public EntityBean get(String className, int id);
85
86 /** Refresh an entity bean in memory, this will flush the bean and get (reload) it.
87 * @param eb The entity bean
88 * @return the refreshed entity bean.
89 * @exception RuntimeException thrown if there is any problem.
90 */
91 public EntityBean refresh(EntityBean eb);
92
93 /** Refresh an entity bean in memory. This will flush the bean and reload it.
94 * @param className The name of the class of entity to flush.
95 * @param id The primary key of the entity.
96 * @return the refreshed entity bean.
97 */
98 public EntityBean refresh(String className, int id);
99
100
101 /** Flush an entity bean from the memory, useful to spare memory, or for testing.
102 * @param eb The entity bean
103 * @exception RuntimeException thrown if there is any problem.
104 */
105 public void flush(EntityBean eb);
106
107 /** Flush an entity bean from the memory -- useful to spare memory, or for testing.
108 * @param className The name of the class of entity to flush.
109 * @param id The primary key of the entity.
110 */
111 public void flush(String className, int id);
112
113
114 /** Generate a new entity bean of the given class, with a new unique id.
115 * @param className The name of the class of entity to create.
116 * @return The new bean instance.
117 */
118 public EntityBean create(String className);
119
120
121 /** Clear the store of all bean instances*/
122 public void clear();
123
124
125 /** Save the current state of an entity bean.
126 * This should be called after every update to the internal state of a bean.
127 */
128 public void save(EntityBean bean);
129
130 /** Save the current state of an entity bean.
131 * This should be called after every update to the internal state of a bean.
132 */
133 public void save(String className, int id);
134
135
136 /** Delete an entity bean.
137 * This will remove the bean from the cache, as well as from the database.
138 */
139 public void delete(EntityBean bean);
140
141 /** Delete an entity bean.
142 * This will remove the bean from the cache, as well as from the database.
143 */
144 public void delete(String className, int id);
145
146
147
148 /** Get the EntityBeanStore for a Class name.
149 * @param className The fully-resolved name of the class of this bean.
150 * @return an EntityBeanStore, possibly null
151 */
152 public EntityBeanStore getStoreForBean(String className);
153
154
155 /** Get the Cache for a Class name.
156 * @param className The fully-resolved name of the class of this bean.
157 * @return a Cache
158 */
159 public Cache getBeanCache(String className);
160
161
162 /** Get an iterator of all saved beans of this class name
163 */
164 public Iterator getAll(String className) throws SQLException;
165
166 /** Get an iterator of all saved beans' ids of this class name
167 */
168 public Iterator getAllIds(String className) throws SQLException;
169
170 /** Get an iterator of all saved beans of this class name,
171 * but only this class, not sub-classes
172 */
173 public Iterator getExactNameAll(String className) throws SQLException;
174
175 /** Get an iterator of all saved beans' ids of this class name,
176 * but only this class, not sub-classes
177 */
178 public Iterator getExactNameAllIds(String className) throws SQLException;
179
180 /** Get a list of all saved beans of this class name
181 */
182 public List getAllAsList(String className) throws SQLException;
183
184 /** Get a list of all saved beans' ids of this class name
185 */
186 public List getAllIdsAsList(String className) throws SQLException;
187
188 /** Get a list of all saved beans of this class name,
189 * but only this class, not sub-classes
190 */
191 public List getExactNameAllAsList(String className) throws SQLException;
192
193 /** Get a list of all saved beans' ids of this class name,
194 * but only this class, not sub-classes
195 */
196 public List getExactNameAllIdsAsList(String className) throws SQLException;
197
198 /** Get an iterator of all class names that the EntityBeanStore handles
199 */
200 public Iterator getAllClasses() throws SQLException;
201
202 /** Get a list of all beans in the id array, as a lazy-loading list
203 * @param className the class of the beans that will be returned
204 * (used to determine which EBS to use)
205 * @param ids a list of the ids of which beans to return
206 */
207 public List getAsLazyList(String className, int[] ids);
208
209 /** Get a list of all beans in the id array, as a lazy-loading list
210 * @param className the class of the beans that will be returned
211 * (used to determine which EBS to use)
212 * @param ids a List of Integer ids of which beans to return
213 */
214 public List getAsLazyList(String className, List ids);
215
216 /** Get a list of all beans whose ids are selected by the given query,
217 * as a lazy-loading list
218 * @param className the class of the beans that will be returned
219 * (used to determine which EBS to use)
220 * @param query an SQL query that selects the numerical ids of all beans
221 * to include in the returned List
222 */
223 public List getAsLazyList(String className, String query);
224
225 }