KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > jorm > api > PClassMapping


1 /**
2  * JORM: an implementation of a generic mapping system for persistent Java
3  * objects. Two mapping are supported: to RDBMS and to binary files.
4  * Copyright (C) 2001-2003 France Telecom R&D - INRIA
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19  *
20  * Contact: jorm-team@objectweb.org
21  *
22  */

23
24 package org.objectweb.jorm.api;
25
26 import org.objectweb.jorm.metainfo.api.MetaObject;
27 import org.objectweb.jorm.naming.api.PBinder;
28 import org.objectweb.jorm.naming.api.PExceptionNaming;
29 import org.objectweb.jorm.naming.api.PName;
30 import org.objectweb.jorm.naming.api.PNameCoder;
31 import org.objectweb.jorm.type.api.PExceptionTyping;
32 import org.objectweb.jorm.type.api.PType;
33 import org.objectweb.medor.tuple.api.TupleCollection;
34
35 import java.util.HashMap JavaDoc;
36 import java.util.Iterator JavaDoc;
37
38 /**
39  * The <b>PClassMapping</b> interface defines the behaviour of objects that
40  * contain all information required to map a JORM class. It is a PBinder but
41  * mainly delegates this behaviour to a nested PBinder that it must reference.
42  * It allows the creation or deletion of the persistent structures required to
43  * map this class within a particular hosting data store.
44  * It also holds references to naming contexts associated to reference fields,
45  * as well as to PClassMapping associated to generic class instances of
46  * relevant fields.
47  * @author P. Dechamboux
48  */

49 public interface PClassMapping {
50     /**
51      * It tells that a cleanup is required for a JORM class with
52      * the removal of existing data as well as hosting structures.
53      */

54     final static byte CLEANUP_REMOVEALL = 1;
55     /**
56      * It tells that a cleanup is required for a JORM class with
57      * the removal of only existing data.
58      */

59     final static byte CLEANUP_REMOVEDATA = 2;
60     /**
61      * It permits to specify to create the if it does not already exist. If the
62      * table exist then nothing is done.
63      */

64     final static byte CREATE_STRUCTURE_IF_NEEDED = 3;
65     /**
66      * It tells that a cleanup is required for a JORM class with
67      * nothing to do on existing data or hosting structures.
68      */

69     final static byte CLEANUP_DONOTHING = 4;
70
71     /**
72      * It creates a new PBinding.
73      * @return The new PBinding with lifecycle state set to
74      * LIFECYCLE_NOTBOUND.
75      */

76     PBinding createPBinding() throws PException;
77
78     /**
79      * It intialises the class mapping. It especially assigns a mapper as well
80      * as a meta-object describing either a class or a generic class. It also
81      * defines all type information related to this class mapping.
82      * @param mapper The mapper to be assigned to this class mapping.
83      * @param metaclass The meta-object describing the associated class. It may
84      * be null.
85      */

86     void init(PMappingCallback mapper, MetaObject metaclass)
87             throws PException;
88
89     /**
90      * Register the mapping structures and the dependencies.
91      * @param pmsm The PMappingStructuresManager in which mapping structures
92      * are registered.
93      * @throws PException
94      */

95     void init(PMappingStructuresManager pmsm)
96         throws PException;
97     
98     /**
99      * Register the class in the cluster.
100      * @param pmsm
101      * @throws PException
102      */

103     void classDefined(PMappingStructuresManager pmsm) throws PException;
104     
105     /**
106      * It retrieves the name of the class referenced by this PClassMapping.
107      * should be the same as the one get when calling
108      * "getPBinder().getPType().getJormName()" if the PType exists, that is a
109      * fully qualified name.
110      * @return The name of this class.
111      */

112     String JavaDoc getClassName();
113
114     /**
115      * It retrieves the project name.
116      */

117     String JavaDoc getProjectName();
118
119     /**
120      * It gives access to the PClassMapping associated to the element of a
121      * generic class whose type is a generic class.
122      * @return The PClassMapping of the generic class instance.
123      * @exception UnsupportedOperationException Raised when the method is not
124      * supported by the PClassMapping.
125      */

126     PClassMapping getGenClassMapping() throws UnsupportedOperationException JavaDoc;
127
128     /**
129      * It gives access to the PClassMapping associated to a field whose type is
130      * a generic class.
131      * @param fn The name of the generic class field.
132      * @return The PClassMapping of the generic class instance.
133      * @exception UnsupportedOperationException Raised when the method is not
134      * supported by the PClassMapping.
135      */

136     PClassMapping getGenClassMapping(String JavaDoc fn)
137             throws UnsupportedOperationException JavaDoc;
138
139     /**
140      * It returns the Class/GenClass object representing the meta-information
141      * associated to the JORM class/generic class whose mapping is defined by
142      * this PClassMapping. It may be null if not requested at mapping time.
143      * @return The Class/GenClass meta-object or null.
144      * @see org.objectweb.jorm.api.PMapper#map
145      */

146     MetaObject getMetaInfo();
147
148     /**
149      * It yields the PBinder associated to this PClassMapping. As a PBinder
150      * itself, this PClassMapping delegates this behaviour to this PBinder.
151      * @return The PBinder associated to this PClassMapping.
152      */

153     PBinder getPBinder();
154
155     /**
156      * It gives access to the mapper that has mapped the associated JORM class
157      * as defined by this PClassMapping.
158      * @return The associated PMapper.
159      */

160     PMapper getPMapper();
161
162     /**
163      * It returns the naming context that manages the references contained by
164      * the generic class instance whose mapping is defined by this
165      * PClassMapping.
166      * @return The naming context that manages references contained by a
167      * generic class instance.
168      * @exception UnsupportedOperationException It is raised when this
169      * PClassMapping does not map
170      * a generic class instance, or
171      * when the elements of this
172      * generic class instance are
173      * not references.
174      */

175     PNameCoder getPNameCoder()
176             throws UnsupportedOperationException JavaDoc;
177
178     /**
179      * It returns the naming context that manages the reference associated to
180      * a field whose type is a JORM class.
181      * @return The naming context that manages the reference defined by a
182      * field.
183      * @exception UnsupportedOperationException It is raised when no naming
184      * context is associated to
185      * the corresponding field.
186      */

187     PNameCoder getPNameCoder(String JavaDoc fn)
188             throws UnsupportedOperationException JavaDoc;
189
190     /**
191      * It returns the PNameCoder to use for the class. This PNamingContext
192      * manages also the sub classes.
193      */

194     PNameCoder getClassPNameCoder();
195
196     /**
197      * It returns an iterator over all pname of persitent objects availlable in
198      * this class. When you use the returned iterator you must leave the
199      * connection opened.
200      * @param conn is the connection which permits to access to the support
201      * @param withSubType indicates if the subclass instances must be included
202      * into the iterator
203      * @param prefetching indicates if prefething must be activated during the
204      * query on the persistent support.
205      * @param txctx The transaction context that can be used in case of
206      * prefetching.
207      * @return the iterator over PName objects
208      * @exception PExceptionProtocol A problem occured during the request
209      * that is not related to I/O.
210      * @exception PExceptionIO A problem occured during the request.
211      */

212     PNameIterator getPNameIterator(Object JavaDoc conn,
213                                    boolean withSubType,
214                                    boolean prefetching,
215                                    Object JavaDoc txctx) throws PException;
216
217     /**
218      * @deprecated use getPNameIterator(Object, boolean, boolean)
219      */

220     Iterator JavaDoc getPNameIterator(Object JavaDoc conn) throws PException;
221
222
223     /**
224      * Retrieves the PType of this mapped JORM class.
225      * @return The PTYpe.
226      */

227     PType getPType();
228
229     /**
230      * Gets the list of the sub PClassMappings.
231      * @return the list of sub pcms or null if the class has no child
232      * @exception PException if the PType is not defined for the PClassMapping
233      */

234     PClassMapping[] getSubPCMs() throws PException;
235     
236     /**
237      * It specifies if the given kind of PMapper is supported by this
238      * PClassMapping.
239      * @param mappername The name defining the PMapper kind.
240      * @return true if this kind of mapper is supported.
241      */

242     boolean isConform(String JavaDoc mappername);
243
244     /**
245      * It assigns the PBinder associated to this PClassMapping. As a PBinder
246      * itself, this PClassMapping delegates this behaviour to this PBinder.
247      * @param pb The PBinder associated to this PClassMapping.
248      * @exception PExceptionTyping It is raised when the structure of the
249      * the name that identifies the DSI for
250      * the PClassMapping is not supported by
251      * this PBinder that should be connected
252      * to this PClassMapping.
253      */

254     void setPBinder(PBinder pb) throws PException;
255
256     /**
257      * It permits to assign the PNameCoder of all the reference fields
258      * of the persitent class. The implementation of this method must call both
259      * method 'getPNameCoder' and 'isCodingOnly' of the specified PNCGetter.
260      * for each field which is a reference (to a class or a GenClass).
261      * @param rc is the callback object which knows the PNameCoder to use.
262      *
263      * @exception PExceptionTyping It is raised when the structure of the
264      * the names that reference the DSI stored
265      * within the generic class instance is not
266      * supported by the naming context returned
267      * by the callBack method.
268      *
269      */

270     void configureRefFields(ReferenceConfigurator rc) throws PException, UnsupportedOperationException JavaDoc;
271
272     /**
273      *
274      */

275     public interface ReferenceConfigurator {
276         /**
277          * It retrieves the PNameCoder which must be associated to the field
278          * specified in parameter.
279          * @param sourceclassName is the class name which reference the object.
280          * @param refFieldName is the reference field.
281          * @param destclassName is the class name of the referenced Object.
282          * @return the PNameCoder to use for the specified field
283          */

284         PNameCoder getPNameCoder(String JavaDoc sourceclassName,
285                                  String JavaDoc refFieldName,
286                                  String JavaDoc destclassName);
287
288         /**
289          * It retrieves the PNameCoder which should manage the reference.
290          * @param refFieldName is the reference field.
291          * @param sourceclassName is the class name of the non generic class name
292          * which references a begin of the chain of generic Object.
293          * @param genClassNames is the list of the generic class name.
294          * @return the PNameCoder to use for the specified field
295          */

296         PNameCoder getPNameCoder(String JavaDoc sourceclassName,
297                                  String JavaDoc refFieldName,
298                                  String JavaDoc[] genClassNames);
299
300         /**
301          * It retrieves the PClassMapping which must be associated to the field
302          * specified in parameter.
303          * @param refFieldName is the reference field.
304          * @param sourceclassName is the class name of the non generic class name
305          * which references a begin of the chain of generic Object.
306          * @param genClassNames is the list of the generic class name.
307          * @return the PClassMapping to use for the specified field
308          */

309         PClassMapping getGenClassMapping(String JavaDoc sourceclassName,
310                                          String JavaDoc refFieldName,
311                                          String JavaDoc[] genClassNames);
312
313         /**
314          * It retrieves the PClassMapping which must be associated to the field
315          * specified in parameter.
316          * @param refFieldName is the reference field.
317          * @param sourceclassName is the class name of the non generic class name
318          * which references a begin of the chain of generic Object.
319          * @param genClassNames is the list of the generic class name.
320          * @param destclassName is the class name of the referenced Object.
321          * @return the PClassMapping to use for the specified field
322          */

323         PClassMapping getGenClassMapping(String JavaDoc sourceclassName,
324                                          String JavaDoc refFieldName,
325                                          String JavaDoc[] genClassNames,
326                                          String JavaDoc destclassName);
327     }
328
329     /**
330      * It verifies if the DSI attached to a binding exists within the DS.
331      * @param pb is the PBinding instance
332      * @param conn The connection that can be used to refer to the DS.
333      * @return It returns true if the DSI exists.
334      * @exception PExceptionIO It is raised when a problem occured while
335      * accessing to the DS.
336      * @exception PExceptionNaming It is raised when there is a problem for the
337      * associated binder to manage this PName.
338      * @exception PExceptionProtocol It is raised when it is called with a
339      * state different from the following ones:
340      * LIFECYCLE_ACTIVEFORIO
341      */

342     boolean exist(PBinding pb, Object JavaDoc conn) throws PException;
343
344     /**
345      * It reads the data store instance designated by the PName of a
346      * binding and transfers each attribute value to the accessor object.
347      * @param conn The connection that can be used to refer to the DS.
348      * @param pa The PAccessor used to access memory variables.
349      * @exception PExceptionIO It is raised when a problem occured while
350      * accessing to the DS.
351      * @exception PExceptionNaming It is raised when there is a problem for the
352      * associated binder to manage this PName.
353      * @exception PExceptionProtocol It is raised when it is called with a
354      * state different from the following ones:
355      * LIFECYCLE_ACTIVEFORIO
356      */

357     void read(PBinding pb, Object JavaDoc conn, PAccessor pa) throws PException;
358
359     /**
360      * It reads the data store instance designated by the PName of a
361      * binding and transfers each attribute value to the accessor object.
362      * This read method should be used when prefetching is requested.
363      * @param conn The connection that can be used to refer to the DS.
364      * @param pa The PAccessor used to access memory variables.
365      * @param txctx The transaction context that can be used in case of
366      * prefetching.
367      * @exception PExceptionIO It is raised when a problem occured while
368      * accessing to the DS.
369      * @exception PExceptionNaming It is raised when there is a problem for the
370      * associated binder to manage this PName.
371      * @exception PExceptionProtocol It is raised when it is called with a
372      * state different from the following ones:
373      * LIFECYCLE_ACTIVEFORIO
374      */

375     void read(PBinding pb, Object JavaDoc conn, PAccessor pa, Object JavaDoc txctx) throws PException;
376
377     /**
378      * It transfers each attribute value taken from the PAccessor
379      * object to the data store instance designated by the PName
380      * associated with a binding.
381      * @param conn The connection that can be used to refer to the DS.
382      * @param pa The PAccessor used to access memory variables.
383      * @exception PExceptionIO It is raised when a problem occured while
384      * accessing to the DS.
385      * @exception PExceptionNaming It is raised when there is a problem for the
386      * associated binder to manage this PName.
387      * @exception PExceptionProtocol It is raised when it is called with a
388      * state different from the following ones:
389      * LIFECYCLE_ACTIVEFORIO
390      * LIFECYCLE_NEWTOWRITE
391      * LIFECYCLE_DELTOWRITE
392      * @exception PExceptionTyping It is raised when a reference to be stored
393      * has a type incompatible with the respective
394      * field definition.
395      */

396     void write(PBinding pb, Object JavaDoc conn, PAccessor pa) throws PException;
397
398     /**
399      * Returns the map storing association between a pclassmapping on which is done a query
400      * and a table of int representing the fields numbers to select in the tuple to fill in
401      * the field of an instance of the class.
402      * Example:
403      * Let's say we are instanciating D objects
404      * A(pk1, pk2, f1), B(f2), C(f3, f4), D(f5)
405      * _________A_______
406      * B C____
407      * D
408      *
409      * The prefetch query on A will be:
410      * Select pk1, pk2, f1, f2, f3, f4, f5
411      * For D, the index table will be [1,2,3,5,6,7] because we need only pk1, pk2, f1, f3, f4, f5
412      * to instanciate D objects
413      * The prefetch query on C will be:
414      * Select pk1, pk2, f1, f3, f4, f5
415      * For D, the index table will be [1,2,3,4,5,6] because we need all the fields
416      * to instanciate D objects
417      *
418      * Then, the map returned for D will be:
419      * [ pclassmapping of A, [1,2,3,5,6,7]]
420      * [ pclassmapping of C, [1,2,3,4,5,6]]
421      */

422     HashMap JavaDoc getAssociationTable();
423     
424     /**
425      * Adds an association [pclassmapping-> table of indexes] to the association table.
426      * If the map already has an entry corresponding to the pclassmapping,
427      * this entry is replaced by the new one.
428      * @param targetClass the PClassMapping on which is done the query
429      * @param indexes a table of int composed of the indexes of fields required
430      */

431     void addAssociation(PClassMapping targetClass, int[] indexes);
432     
433     /**
434      * Returns the indexes table associated to the pclassmapping targetClass,
435      * null if not contained in the map.
436      */

437     int[] getIndexesTable(PClassMapping targetClass);
438     
439     /**
440      * It returns the PName valid in the "good" binder.
441      * @param conn The connection that can be used to refer to the DS.
442      */

443     PName resolve(Object JavaDoc conn, PName pname) throws PException;
444     
445     /**
446      * Returns true if the object obj matches (exactly) this class,
447      * else it returns false.
448      */

449     boolean match(Object JavaDoc obj, boolean intermediaryTuple) throws PException;
450     
451     /**
452      * It returns the PName valid in the "good" binder according to the tuple collection.
453      * @throws PException
454      */

455     PName getDecodedPName(TupleCollection tc, PName pname, boolean intermediaryTuple) throws PException;
456 }
457
Popular Tags