001: /**
002: * Copyright (C) 2001-2004 France Telecom R&D
003: *
004: * This library is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 2 of the License, or (at your option) any later version.
008: *
009: * This library is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: */package org.objectweb.speedo.naming.api;
018:
019: import java.util.Collection;
020: import java.util.Map;
021: import java.util.Properties;
022:
023: import org.objectweb.jorm.api.PClassMapping;
024: import org.objectweb.jorm.api.PException;
025: import org.objectweb.jorm.api.PMapper;
026: import org.objectweb.jorm.metainfo.api.Class;
027: import org.objectweb.jorm.metainfo.api.ClassMapping;
028: import org.objectweb.jorm.metainfo.api.ClassRef;
029: import org.objectweb.jorm.metainfo.api.GenClassMapping;
030: import org.objectweb.jorm.metainfo.api.GenClassRef;
031: import org.objectweb.jorm.metainfo.api.Manager;
032: import org.objectweb.jorm.metainfo.api.MetaObject;
033: import org.objectweb.jorm.metainfo.api.NameDef;
034: import org.objectweb.jorm.naming.api.PBinder;
035: import org.objectweb.jorm.naming.api.PName;
036: import org.objectweb.jorm.naming.api.PNameCoder;
037: import org.objectweb.jorm.naming.api.PNamingContext;
038: import org.objectweb.jorm.type.api.PType;
039: import org.objectweb.perseus.cache.api.CacheManager;
040: import org.objectweb.speedo.api.SpeedoException;
041: import org.objectweb.speedo.generation.jorm.JormMIMappingBuilder;
042: import org.objectweb.speedo.mapper.api.JormFactory;
043: import org.objectweb.speedo.metadata.SpeedoClass;
044: import org.objectweb.speedo.metadata.SpeedoColumn;
045: import org.objectweb.speedo.metadata.SpeedoField;
046: import org.objectweb.speedo.pm.api.POManagerFactoryItf;
047: import org.objectweb.util.monolog.api.Logger;
048:
049: /**
050: * It defines a manager of a type of naming. This interface covers needs at
051: * compile time and at run time. In particular a naming manager is able to
052: * fill the Speedo meta information with the particularity of the a naming.
053: *
054: * @author S.Chassande-Barrioz
055: */
056: public interface NamingManager {
057:
058: String SEP = "/";
059:
060: /**
061: * Indicates if the naming manager is able to manage the identifier of a
062: * persistent class.
063: * @param sc The speedo meta object representing the persistent class
064: */
065: boolean canManage(SpeedoClass sc);
066:
067: /**
068: * indicates if the naming manager is able to build a PBinder instance for
069: * this hints parameter specified
070: * @param hints is the helper of the PBinder building
071: * @param classLoader is the classloader to use for instanciate the PBinder
072: */
073: boolean canProvidePBinder(Object hints, ClassLoader classLoader);
074:
075: /**
076: * indicates if the naming manager is able to build a PNC instance for
077: * this hints parameter specified
078: * @param hints is the helper of the PNC building
079: * @param classLoader is the classloader to use for instanciate the PNC
080: */
081: boolean canProvidePNamingContext(Object hints,
082: ClassLoader classLoader);
083:
084: /**
085: * Build a PBinder instance for this hints parameter specified
086: * @param hints is the helper of the PBinder building. This hints must be
087: * the result of the getJormConfig call.
088: * @param classLoader is the classloader to use for instanciate the PBinder
089: * @param mappingStructureRule indicates the rule to apply concerning the
090: * data strucuture. Indeed a PBinder building can require to read the data
091: * support.
092: * @param cn2binder is the map of the existing PBinder instance
093: * (key = class name, value = PBinder instance)
094: * @param cn2pnc is the map of the existing PNC instance
095: * (key = class name, value = PNC instance)
096: */
097: PBinder getPBinder(String className, String hints,
098: ClassLoader classLoader, byte mappingStructureRule,
099: Map cn2binder, Map cn2pnc) throws PException;
100:
101: /**
102: * Build a PNamingContext instance for this hints parameter specified
103: * @param hints is the helper of the PBinder building. This hints must be
104: * the result of the getJormConfig call.
105: * @param classLoader is the classloader to use for instanciate the PBinder
106: * @param mappingStructureRule indicates the rule to apply concerning the
107: * data strucuture. Indeed a PBinder building can require to read the data
108: * support.
109: * @param cn2binder is the map of the existing PBinder instance
110: * (key = class name, value = PBinder instance)
111: * @param cn2pnc is the map of the existing PNC instance
112: * (key = class name, value = PNC instance)
113: */
114: PNamingContext getPNamingContext(String className, String hints,
115: ClassLoader classLoader, byte mappingStructureRule,
116: Map cn2binder, Map cn2pnc, Manager miManager,
117: PClassMapping pcm) throws PException;
118:
119: /**
120: * Decodes an object identifier into a PName.
121: * @param pnc is the PNameCoder instance to use for the decoding the object
122: * identifier. The pnc parameter can be null. In this case the oid must
123: * @param oid is the object identifier
124: * @param clazz is the java.lang.Class of the persistent class identified by
125: * the oid
126: * @param jf is the JormFactory instance. It permits to
127: * @return the object identifier decode as PName
128: * @throws PException
129: */
130: PName decode(PNameCoder pnc, Object oid, java.lang.Class clazz,
131: JormFactory jf) throws PException;
132:
133: /**
134: * Encode a PName into an object
135: * @param pn is the pname to encode
136: */
137: Object encode(PName pn) throws PException;
138:
139: /**
140: * indicates if the use of PNamingContext is support by this mapping. If
141: * true then getPNamingContext method can be use, otherwise the getPBinder
142: * must be use instead. The case of PNamingContext are not supported, means
143: * the PBinder are used as PNameCoder by PBinding as reference coder.
144: */
145: boolean supportPNamingcontext();
146:
147: /**
148: * Fill the name def of an identifier or a reference
149: * @param nd is the name def to fill
150: * @param isIdentifier indicates if the name represents an identifier (true)
151: * or a reference (false).
152: * @param isInGenClass indicates if the name is defined in a generic class
153: * (true) of in a class (false).
154: * @param ref meta object which the name def must be
155: * defined. This value is used only in the case of isIdentifier == false and
156: * isInGenClass == false.
157: * @param tsc is the speedo meta object representing the referenced class.
158: * This value is used only in the case of isIdentifier == false.
159: * @param mo is the jorm meta object hosting the name def and on which the
160: * eventual hidden field will be created.
161: * @param hcm if the mapping structure hosting the mapping of the reference.
162: * This value must be ClassMapping or GenClassMapping instance.
163: * @param mb is the mapping builder permitting the creation of the mapping
164: * part.
165: * @param createdMOs is a result paramter. This collection must be fill with
166: * the created Jorm Meta objects representing a class or a composite name.
167: * Here only the new used composite name will be added.
168: * @throws SpeedoException if the speedo meta information is not completly
169: * defined.
170: void fillNameDef(MIBuilderHelper mibh,
171: Manager manager,
172: NameDef nd,
173: SpeedoClass tsc,
174: SpeedoClass ssc,
175: MetaObject mo,
176: Reference ref,
177: CommonClassMapping hcm,
178: JormMIMappingBuilder mb,
179: boolean isIdentifier,
180: boolean isInGenClass,
181: boolean createField,
182: Collection createdMOs) throws SpeedoException, PException;
183: */
184:
185: /**
186: * Fill the name def of a class identifier
187: * @param nd is the name def to fill
188: * @param sc is the speedo meta object representing the class.
189: * @param jc is the jorm meta object representing the class.
190: * @param cm if the mapping structure hosting the mapping of the class.
191: * @param mibh is a helper for the management of the JORM meta info
192: * @param mb is the mapping builder permitting the creation of the mapping
193: * objects.
194: * @param createdMOs is a result paramter. This collection must be fill with
195: * the created Jorm Meta objects representing a class or a composite name.
196: * Here only the new composite names have to be added.
197: * @throws SpeedoException if the speedo meta information is not completly
198: * defined.
199: */
200: void defineClassIdentifierNameDef(NameDef nd, Class jc,
201: SpeedoClass sc, ClassMapping cm, MIBuilderHelper mibh,
202: JormMIMappingBuilder mb, Collection createdMOs)
203: throws SpeedoException, PException;
204:
205: /**
206: * Fill the name def of the gen class identifier
207: * @param nd is the name def to fill
208: * @param gcr is the JORM meta object representing the generic class
209: * reference.
210: * @param sf is the speedo meta object representing the persistent
211: * reference to a generic class.
212: * @param currentClass is the class mapping the field
213: * @param gcm if the mapping structure hosting the mapping of the generic class.
214: * @param mibh is a helper for the management of the JORM meta info
215: * @param mb is the mapping builder permitting the creation of the mapping
216: * objects.
217: * @throws SpeedoException if the speedo meta information is not completly
218: * defined.
219: */
220: void defineGenClassIdentifierNameDef(NameDef nd, GenClassRef gcr,
221: SpeedoField sf, SpeedoClass currentClass,
222: GenClassMapping gcm, MIBuilderHelper mibh,
223: JormMIMappingBuilder mb) throws SpeedoException, PException;
224:
225: /**
226: * Fill the name def of the class reference from a class
227: * @param nd is the name def to fill
228: * @param cr is the speedo meta object representing the class.
229: * @param sf is the speedo meta object representing the persistent
230: * reference to a class.
231: * @param currentClass is the class mapping the field
232: * @param cm if the mapping structure hosting the mapping of the class.
233: * @param mibh is a helper for the management of the JORM meta info
234: * @param mb is the mapping builder permitting the creation of the mapping
235: * objects.
236: * @throws SpeedoException if the speedo meta information is not completly
237: * defined.
238: */
239: void defineClassReferenceNameDef(NameDef nd, ClassRef cr,
240: SpeedoField sf, SpeedoClass currentClass, ClassMapping cm,
241: MIBuilderHelper mibh, JormMIMappingBuilder mb)
242: throws SpeedoException, PException;
243:
244: /**
245: * Fill the name def of the class reference from a generic class
246: * @param nd is the name def to fill
247: * @param cr is the speedo meta object representing the class.
248: * @param sf is the speedo meta object representing the persistent
249: * reference to a class.
250: * @param currentClass is the class mapping the field
251: * @param gcm if the mapping structure hosting the mapping of the class.
252: * @param mibh is a helper for the management of the JORM meta info
253: * @param mb is the mapping builder permitting the creation of the mapping
254: * objects.
255: * @param createdMOs is a result paramter. This collection must be fill with
256: * the created Jorm Meta objects representing a class or a composite name.
257: * Here only the new composite names have to be added.
258: * @throws SpeedoException if the speedo meta information is not completly
259: * defined.
260: */
261: void defineClassReferenceNameDef(NameDef nd, ClassRef cr,
262: SpeedoField sf, SpeedoClass currentClass,
263: GenClassMapping gcm, MIBuilderHelper mibh,
264: JormMIMappingBuilder mb) throws SpeedoException, PException;
265:
266: /**
267: * Fill the name def of the generic class reference from a class
268: * @param nd is the name def to fill
269: * @param gcr is the speedo meta object representing the generic class.
270: * @param sf is the speedo meta object representing the persistent
271: * reference to a generic class.
272: * @param currentClass is the class mapping the field
273: * @param cm if the mapping structure hosting the mapping of the class.
274: * @param mibh is a helper for the management of the JORM meta info
275: * @param mb is the mapping builder permitting the creation of the mapping
276: * objects.
277: * @throws SpeedoException if the speedo meta information is not completly
278: * defined.
279: */
280: void defineGenClassReferenceNameDef(NameDef nd, GenClassRef gcr,
281: SpeedoField sf, SpeedoClass currentClass, ClassMapping cm,
282: MIBuilderHelper mibh, JormMIMappingBuilder mb)
283: throws SpeedoException, PException;
284:
285: boolean needInheritanceDiscriminator(SpeedoClass sc)
286: throws SpeedoException;
287:
288: /**
289: * computes the naming configuration information for a class or a reference.
290: * This information is store as a String. The string value will be passed
291: * to the getPBinder and getPNamingContext methods as hints. This method is
292: * used at generation time.
293: * <table>
294: * <tr><td>naming of a/td><td>MOClass/td></tr>
295: * <tr><td>class/td><td>Class/td></tr>
296: * <tr><td>reference to a Class/td><td>ClassRef/td></tr>
297: * <tr><td>reference to a GenClass/td><td>GenClassRef/td></tr>
298: * <tr><td>a GenClass identifier/td><td>GenClassRef/td></tr>
299: * </table>
300: *
301: * @param targetClass is the Speedo meta object representing the class which
302: * is designates by the
303: * @param result is the Properties which must be filled
304: */
305: void getJormNamingConfig(NameDef nd, SpeedoClass targetClass,
306: MetaObject sourceMO, String key, Properties result)
307: throws SpeedoException;
308:
309: /**
310: * compute a string value which permit to help the building of the class
311: * PName (export)
312: * @param sc is the Speedo class which the hints must be specified
313: * @param nd is the name def of the class
314: */
315: String getPNameHints(SpeedoClass sc, NameDef nd);
316:
317: Integer PNH_NULL_VALUE = new Integer(1);
318: Integer PNH_REF_STATE = new Integer(2);
319: Integer PNH_PFIELD = new Integer(3);
320:
321: Object[] getPNameHints2(SpeedoClass sc, NameDef nd);
322:
323: /**
324: * compute a string value which permit to help the building of the genclass
325: * PName (export)
326: * @param sc is the Speedo class which the hints must be specified
327: * @param nd is the name def of the gen class
328: */
329: String getGCPNameHints(SpeedoClass sc, NameDef nd);
330:
331: void setPMapper(PMapper mapper) throws PException;
332:
333: void setLogger(Logger logger);
334:
335: void setCache(CacheManager cache);
336:
337: void setPmf(POManagerFactoryItf pmf);
338:
339: SpeedoColumn[] getDefaultColumn(SpeedoClass sc);
340:
341: /**
342: * Retrieves the array of field used in the identifier of a persistent class
343: * and which values are not calculated by the application. The application
344: * field must be set at makePersistent time.
345: *
346: * @param sc is the speedo meta object of the persistent class
347: */
348: NamingField[] getNamingfields(SpeedoClass sc) throws PException;
349:
350: /**
351: * Defines the field used in an identifier and which must be set at
352: * makePersistent time.
353: */
354: public class NamingField {
355: private String userFieldName = null;
356: private java.lang.Class userFieldType = null;
357: private String namingFieldName = null;
358: private PType namingFieldType = null;
359:
360: /**
361: * @param userFieldName is the field name in the persistent class
362: * @param userFieldType is the field type (java type) in the persistent
363: * class
364: * @param namingFieldName is the field name in the identifier
365: * @param namingFieldType is the field type (Jorm type) in the identifier
366: */
367: public NamingField(String userFieldName,
368: java.lang.Class userFieldType, String namingFieldName,
369: PType namingFieldType) {
370: this .userFieldName = userFieldName;
371: this .userFieldType = userFieldType;
372: this .namingFieldName = namingFieldName;
373: this .namingFieldType = namingFieldType;
374: }
375:
376: /**
377: * @return the field name in the persistent class
378: */
379: public String getUserFieldName() {
380: return userFieldName;
381: }
382:
383: /**
384: * @return the field type (java type) in the persistent
385: */
386: public java.lang.Class getUserFieldType() {
387: return userFieldType;
388: }
389:
390: /**
391: * @return the field name in the identifier
392: */
393: public String getNamingFieldName() {
394: return namingFieldName;
395: }
396:
397: /**
398: * @return the field type (Jorm type) in the identifier
399: */
400: public PType getNamingFieldType() {
401: return namingFieldType;
402: }
403: }
404: }
|