PNameCoder


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.naming.api;
25  
26  import org.objectweb.jorm.type.api.PType;
27  import org.objectweb.jorm.api.PException;
28  
29  import java.util.Date  ;
30  import java.math.BigDecimal  ;
31  import java.math.BigInteger  ;
32  
33  /**
34   * The <b>PNameCoder</b> defines the external structure of the name it manages,
35   * which corresponds to the type involved in the encoding/decoding process.
36   * Furthermore, several name format may be supported by a particular name
37   * coder.
38   * @author  R. Basset, P. D?chamboux
39   */
40  public interface PNameCoder {
41      /**
42       * The coding type of the naming context is a <code>byte</code>.
43       */
44      static final int CTBYTE = 0x0001;
45      /**
46       * The coding type of the naming context is an <code>char</code>.
47       */
48      static final int CTCHAR = 0x0002;
49      /**
50       * The coding type of the naming context is a <code>short</code>.
51       */
52      static final int CTSHORT = 0x0004;
53      /**
54       * The coding type of the naming context is an <code>int</code>.
55       */
56      static final int CTINT = 0x0008;
57      /**
58       * The coding type of the naming context is a <code>long</code>.
59       */
60      static final int CTLONG = 0x0010;
61      /**
62       * The coding type of the naming context is a <code>byte</code>.
63       */
64      static final int CTOBYTE = 0x0020;
65      /**
66       * The coding type of the naming context is an <code>char</code>.
67       */
68      static final int CTOCHAR = 0x0040;
69      /**
70       * The coding type of the naming context is a <code>short</code>.
71       */
72      static final int CTOSHORT = 0x0080;
73      /**
74       * The coding type of the naming context is an <code>int</code>.
75       */
76      static final int CTOINT = 0x0100;
77      /**
78       * The coding type of the naming context is a <code>long</code>.
79       */
80      static final int CTOLONG = 0x0200;
81      /**
82       * The coding type of the naming context is a <code>string</code>.
83       */
84      static final int CTSTRING = 0x0400;
85      /**
86       * The coding type of the naming context is a <code>date</code>.
87       */
88      static final int CTDATE = 0x0800;
89      /**
90       * The coding type of the naming context is a <code>chararray</code>.
91       */
92      static final int CTCHARARRAY = 0x1000;
93      /**
94       * The coding type of the naming context is a <code>bytearray</code>.
95       */
96      static final int CTBYTEARRAY = 0x2000;
97      /**
98       * The coding type of the naming context is a <code>bytearray</code>.
99       */
100     static final int CTBIGINTEGER = 0x4000;
101     /**
102      * The coding type of the naming context is a <code>bytearray</code>.
103      */
104     static final int CTBIGDECIMAL = 0x8000;
105     /**
106      * The coding type of the naming context is an <code>Object</code> that
107      * is DS-specific.
108      */
109     static final int CTSYSTEM = 0x10000;
110     /**
111      * The coding type of the naming context is an <code>Object</code> that
112      * is composite name (e.g., a multi-fields relational primary key).
113      */
114     static final int CTCOMPOSITE = 0x80000;
115 
116     /**
117      * It tests if a given coding type is supported by this naming context.
118      * @param codingtype    One of the coding type defined by CTxxx constants
119      *                      defined within this interface.
120      * @return  It returns true if the coding type is supported by this naming
121      *          context.
122      */
123     boolean codingSupported(int codingtype);
124 
125     /**
126      * The <b>decode</b> methods recreates PName within a naming
127      * context from an encoded representation. In the case of this method, the
128      * encoded representation is an array of bytes. It must always be supported
129      * by a naming context.
130      * @param en    The byte to be decoded.
131      * @return  The resulting PName.
132      */
133     PName decode(byte[] en) throws PExceptionNaming;
134 
135     /**
136      * The <b>decodeAbstract</b> methods recreates PName within a naming
137      * context from an encoded representation. In the case of this method, the
138      * encoded representation is abstract, which means that this is a Java
139      * object of any complexity. One example of such object is a getter
140      * interface representing a relational primary key (also called composite
141      * names).
142      * @param context A context used to decode the related data.
143      * @param en    The Object to be decoded.
144      * @return  The resulting PName.
145      */
146     PName decodeAbstract(Object   en, Object   context) throws PExceptionNaming, UnsupportedOperationException  ;
147 
148     /**
149      * The <b>decodeByte</b> methods recreates PName within a naming
150      * context from an encoded representation. In the case of this method, the
151      * encoded representation is a byte.
152      * @param en    The byte to be decoded.
153      * @return  The resulting PName.
154      */
155     PName decodeByte(byte en) throws PExceptionNaming, UnsupportedOperationException  ;
156 
157     /**
158      * The <b>decodeObyte</b> methods recreates PName within a naming
159      * context from an encoded representation. In the case of this method, the
160      * encoded representation is a byte.
161      * @param en    The Byte to be decoded.
162      * @return  The resulting PName.
163      */
164     PName decodeObyte(Byte   en) throws PExceptionNaming, UnsupportedOperationException  ;
165 
166     /**
167      * The <b>decodeChar</b> methods recreates PName within a naming
168      * context from an encoded representation. In the case of this method, the
169      * encoded representation is a char.
170      * @param en    The char to be decoded.
171      * @return  The resulting PName.
172      */
173     PName decodeChar(char en) throws PExceptionNaming, UnsupportedOperationException  ;
174 
175     /**
176      * The <b>decodeOchar</b> methods recreates PName within a naming
177      * context from an encoded representation. In the case of this method, the
178      * encoded representation is a Character.
179      * @param en    The Character to be decoded.
180      * @return  The resulting PName.
181      */
182     PName decodeOchar(Character   en) throws PExceptionNaming, UnsupportedOperationException  ;
183 
184     /**
185      * The <b>decodeInt</b> methods recreates PName within a naming
186      * context from an encoded representation. In the case of this method, the
187      * encoded representation is an int.
188      * @param en    The int to be decoded.
189      * @return  The resulting PName.
190      */
191     PName decodeInt(int en) throws PExceptionNaming, UnsupportedOperationException  ;
192 
193     /**
194      * The <b>decodeOint</b> methods recreates PName within a naming
195      * context from an encoded representation. In the case of this method, the
196      * encoded representation is an Integer.
197      * @param en    The Integer to be decoded.
198      * @return  The resulting PName.
199      */
200     PName decodeOint(Integer   en) throws PExceptionNaming, UnsupportedOperationException  ;
201 
202     /**
203      * The <b>decodeLong</b> methods recreates PName within a naming
204      * context from an encoded representation. In the case of this method, the
205      * encoded representation is a long.
206      * @param en    The long to be decoded.
207      * @return  The resulting PName.
208      */
209     PName decodeLong(long en) throws PExceptionNaming, UnsupportedOperationException  ;
210 
211     /**
212      * The <b>decodeOlong</b> methods recreates PName within a naming
213      * context from an encoded representation. In the case of this method, the
214      * encoded representation is a Long.
215      * @param en    The Long to be decoded.
216      * @return  The resulting PName.
217      */
218     PName decodeOlong(Long   en) throws PExceptionNaming, UnsupportedOperationException  ;
219 
220     /**
221      * The <b>decodeShort</b> methods recreates PName within a naming
222      * context from an encoded representation. In the case of this method, the
223      * encoded representation is a short.
224      * @param en    The short to be decoded.
225      * @return  The resulting PName.
226      */
227     PName decodeShort(short en) throws PExceptionNaming, UnsupportedOperationException  ;
228 
229     /**
230      * The <b>decodeOshort</b> methods recreates PName within a naming
231      * context from an encoded representation. In the case of this method, the
232      * encoded representation is a Short.
233      * @param en    The Short to be decoded.
234      * @return  The resulting PName.
235      */
236     PName decodeOshort(Short   en) throws PExceptionNaming, UnsupportedOperationException  ;
237 
238     /**
239      * The <b>decodeString</b> methods recreates PName within a naming
240      * context from an encoded representation. In the case of this method, the
241      * encoded representation is a String.
242      * @param en    The String to be decoded.
243      * @return  The resulting PName.
244      */
245     PName decodeString(String   en) throws PExceptionNaming;
246 
247     /**
248      * The <b>decodeCharArray</b> methods recreates PName within a naming
249      * context from an encoded representation. In the case of this method, the
250      * encoded representation is a String.
251      * @param en    The char[] to be decoded.
252      * @return  The resulting PName.
253      */
254     PName decodeCharArray(char[] en) throws PExceptionNaming;
255 
256     /**
257      * The <b>decodeDate</b> methods recreates PName within a naming
258      * context from an encoded representation. In the case of this method, the
259      * encoded representation is a Date.
260      * @param en    The Date to be decoded.
261      * @return  The resulting PName.
262      */
263     PName decodeDate(Date   en) throws PExceptionNaming;
264 
265     /**
266      * The <b>decodeBigInteger</b> methods recreates PName within a naming
267      * context from an encoded representation. In the case of this method, the
268      * encoded representation is a BigInteger.
269      * @param en    The BigInteger to be decoded.
270      * @return  The resulting PName.
271      */
272     PName decodeBigInteger(BigInteger   en) throws PExceptionNaming;
273 
274     /**
275      * The <b>decodeBigDecimal</b> methods recreates PName within a naming
276      * context from an encoded representation. In the case of this method, the
277      * encoded representation is a BigDecimal.
278      * @param en    The BigDecimal to be decoded.
279      * @return  The resulting PName.
280      */
281     PName decodeBigDecimal(BigDecimal   en) throws PExceptionNaming;
282 
283     /**
284      * The <b>encode</b> method produces an encoded representation of a
285      * PName within a naming context. The encoding format in the case of this
286      * method is an array of bytes. It must be always supported by a naming
287      * context.
288      * @param pn    The PName to be encoded
289      * @return  The array of bytes corresponding to the encoded representation.
290      */
291     byte[] encode(PName pn) throws PExceptionNaming;
292 
293     /**
294      * The <b>encodeAbstract</b> method produces an encoded representation of a PName
295      * within a naming context. The encoding format is the case of this method
296      * is a Java object of any complexity. Example of such object is a getter
297      * interface giving access of the fields of a relational primary key (also
298      * called composite names).
299      * @param pn    The PName to be encoded.
300      * @return  The Object corresponding to the encoded representation.
301      */
302     Object   encodeAbstract(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
303 
304     /**
305      * The <b>encodeByte</b> method produces an encoded representation of a
306      * PName within a naming context. The encoding format in the case of this
307      * method is a byte.
308      * @param pn    The PName to be encoded
309      * @return  The byte corresponding to the encoded representation.
310      */
311     byte encodeByte(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
312 
313     /**
314      * The <b>encodeObyte</b> method produces an encoded representation of a
315      * PName within a naming context. The encoding format in the case of this
316      * method is a Byte.
317      * @param pn    The PName to be encoded
318      * @return  The Byte corresponding to the encoded representation.
319      */
320     Byte   encodeObyte(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
321 
322     /**
323      * The <b>encodeChar</b> method produces an encoded representation of a
324      * PName within a naming context. The encoding format in the case of this
325      * method is a char.
326      * @param pn    The PName to be encoded
327      * @return  The char corresponding to the encoded representation.
328      */
329     char encodeChar(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
330 
331     /**
332      * The <b>encodeOchar</b> method produces an encoded representation of a
333      * PName within a naming context. The encoding format in the case of this
334      * method is a Character.
335      * @param pn    The PName to be encoded
336      * @return  The Character corresponding to the encoded representation.
337      */
338     Character   encodeOchar(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
339 
340     /**
341      * The <b>encodeInt</b> method produces an encoded representation of a
342      * PName within a naming context. The encoding format in the case of this
343      * method is a int.
344      * @param pn    The PName to be encoded
345      * @return  The int corresponding to the encoded representation.
346      */
347     int encodeInt(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
348 
349     /**
350      * The <b>encodeOint</b> method produces an encoded representation of a
351      * PName within a naming context. The encoding format in the case of this
352      * method is a Integer.
353      * @param pn    The PName to be encoded
354      * @return  The Integer corresponding to the encoded representation.
355      */
356     Integer   encodeOint(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
357 
358     /**
359      * The <b>encodeLong</b> method produces an encoded representation of a
360      * PName within a naming context. The encoding format in the case of this
361      * method is a long.
362      * @param pn    The PName to be encoded
363      * @return  The long corresponding to the encoded representation.
364      */
365     long encodeLong(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
366 
367     /**
368      * The <b>encodeOlong</b> method produces an encoded representation of a
369      * PName within a naming context. The encoding format in the case of this
370      * method is a Long.
371      * @param pn    The PName to be encoded
372      * @return  The Long corresponding to the encoded representation.
373      */
374     Long   encodeOlong(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
375 
376     /**
377      * The <b>encodeShort</b> method produces an encoded representation of a
378      * PName within a naming context. The encoding format in the case of this
379      * method is a short.
380      * @param pn    The PName to be encoded
381      * @return  The short corresponding to the encoded representation.
382      */
383     short encodeShort(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
384 
385     /**
386      * The <b>encodeOshort</b> method produces an encoded representation of a
387      * PName within a naming context. The encoding format in the case of this
388      * method is a Short.
389      * @param pn    The PName to be encoded
390      * @return  The Short corresponding to the encoded representation.
391      */
392     Short   encodeOshort(PName pn) throws PExceptionNaming, UnsupportedOperationException  ;
393 
394     /**
395      * The <b>encodeString</b> method produces an encoded representation of a
396      * PName within a naming context. The encoding format in the case of this
397      * method is a String.
398      * @param pn    The PName to be encoded
399      * @return  The String corresponding to the encoded representation.
400      */
401     String   encodeString(PName pn) throws PExceptionNaming;
402 
403     /**
404      * The <b>encodeCharArray</b> method produces an encoded representation of a
405      * PName within a naming context. The encoding format in the case of this
406      * method is a char[].
407      * @param pn    The PName to be encoded
408      * @return  The char[] corresponding to the encoded representation.
409      */
410     char[] encodeCharArray(PName pn) throws PExceptionNaming;
411 
412     /**
413      * The <b>encodeDate</b> method produces an encoded representation of a
414      * PName within a naming context. The encoding format in the case of this
415      * method is a Date.
416      * @param pn    The PName to be encoded
417      * @return  The Date corresponding to the encoded representation.
418      */
419     Date   encodeDate(PName pn) throws PExceptionNaming;
420 
421     /**
422      * The <b>encodeBigInteger</b> method produces an encoded representation of a
423      * PName within a naming context. The encoding format in the case of this
424      * method is a BigInteger.
425      * @param pn    The PName to be encoded
426      * @return  The BigInteger corresponding to the encoded representation.
427      */
428     BigInteger   encodeBigInteger(PName pn) throws PExceptionNaming;
429 
430     /**
431      * The <b>encodeBigDecimal</b> method produces an encoded representation of a
432      * PName within a naming context. The encoding format in the case of this
433      * method is a BigDecimal.
434      * @param pn    The PName to be encoded
435      * @return  The BigDecimal corresponding to the encoded representation.
436      */
437     BigDecimal   encodeBigDecimal(PName pn) throws PExceptionNaming;
438 
439     /**
440      * It yields a "null" representation of a name within this naming context.
441      * @return  The "null" PName associated with this naming context.
442      */
443     PName getNull();
444 
445     /**
446      * It assignes a object which defines a null representation of a name
447      * within this naming context.
448      * @param o can be a PNameGetter (generic or generated), a pname, or
449      * a simple value (ex: Integer).
450      */
451     void setNullPName(Object   o) throws PException;
452 
453     /**
454      * Tests if this naming context supports comosite name through a dynamic
455      * approach, which means that encodingAbstract/decodingAbstract use getter
456      * objects that implement the PNameGetter interface.
457      * @return  true if dynamic getter is supported by composite name coding.
458      */
459     boolean supportDynamicComposite();
460 
461     /**
462      * In case of a naming context that supports composite names (i.e., names
463      * composed of several typed fields, whose type is limited to scalar ones),
464      * it tests if a particular field is defined by this composite name.
465      * It should be used by PClassMapping objects in order to verify, at
466      * deployment time, that naming contexts that are defined to manage the
467      * various references supports the same encoding name structure.
468      * @return  true if the proposed field is supported by this composite name.
469      */
470     boolean supportCompositeField(String   fn, PType ft);
471 
472     /**
473      * Tests if this naming context supports comosite name through a static
474      * approach, which means that encodingAbstract/decodingAbstract use getter
475      * objects that implement specific NsFieldGetter interface generated for
476      * a particular field "Field" within a particular NameDef space "Ns".
477      * @return  true if static getter is supported by composite name coding.
478      */
479     boolean supportStaticComposite();
480 
481     /**
482      * Retrieves the PType associated to the JORM class which is the type of
483      * the name managed by this naming context.
484      * @return  The related PType.
485      */
486     PType getPType();
487 
488 
489     /**
490      * Assigns the PType associated to the JORM class which is the type of
491      * the name managed by this naming context.
492      * @param pt    The PType of the JORM class reference managed by this naming
493      *              context.
494      */
495     void setPType(PType pt);
496 }
497
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags