Datatype


1   package org.relaxng.datatype;
2   
3   /**
4    * Datatype object.
5    * 
6    * This object has the following functionality:
7    * 
8    * <ol>
9    *  <li> functionality to identify a class of character sequences. This is
10   *       done through the isValid method.
11   * 
12   *  <li> functionality to produce a "value object" from a character sequence and
13   *       context information.
14   * 
15   *  <li> functionality to test the equality of two value objects.
16   * </ol>
17   * 
18   * This interface also defines the createStreamingValidator method,
19   * which is intended to efficiently support the validation of
20   * large character sequences.
21   * 
22   * @author <a HREF="mailto:jjc@jclark.com">James Clark</a>
23   * @author <a HREF="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
24   */
25  public interface Datatype {
26      
27      /**
28       * Checks if the specified 'literal' matches this Datatype
29       * with respect to the current context.
30       * 
31       * @param literal
32       *      the lexical representation to be checked.
33       * @param context
34       *      If this datatype is context-dependent
35       *      (i.e. the {@link #isContextDependent} method returns true),
36       *      then the caller must provide a non-null valid context object.
37       *      Otherwise, the caller can pass null.
38       * 
39       * @return
40       *      true if the 'literal' is a member of this Datatype;
41       *      false if it's not a member of this Datatype.
42       */
43      boolean isValid( String   literal, ValidationContext context );
44      
45      /**
46       * Similar to the isValid method but throws an exception with diagnosis
47       * in case of errors.
48       * 
49       * <p>
50       * If the specified 'literal' is a valid lexical representation for this
51       * datatype, then this method must return without throwing any exception.
52       * If not, the callee must throw an exception (with diagnosis message,
53       * if possible.)
54       * 
55       * <p>
56       * The application can use this method to provide detailed error message
57       * to users. This method is kept separate from the isValid method to
58       * achieve higher performance during normal validation.
59       * 
60       * @exception DatatypeException
61       *      If the given literal is invalid, then this exception is thrown.
62       *      If the callee supports error diagnosis, then the exception should
63       *      contain a diagnosis message.
64       */
65      void checkValid( String   literal, ValidationContext context )
66          throws DatatypeException;
67      
68      /**
69       * Creates an instance of a streaming validator for this type.
70       * 
71       * <p>
72       * By using streaming validators instead of the isValid method,
73       * the caller can avoid keeping the entire string, which is
74       * sometimes quite big, in memory.
75       * 
76       * @param context
77       *      If this datatype is context-dependent
78       *      (i.e. the {@link #isContextDependent} method returns true),
79       *      then the caller must provide a non-null valid context object.
80       *      Otherwise, the caller can pass null.
81       *      The callee may keep a reference to this context object
82       *      only while the returned streaming validator is being used.
83       */
84      DatatypeStreamingValidator createStreamingValidator( ValidationContext context );
85      
86      /**
87       * Converts lexcial value and the current context to the corresponding
88       * value object.
89       * 
90       * <p>
91       * The caller cannot generally assume that the value object is
92       * a meaningful Java object. For example, the caller cannot expect
93       * this method to return <code>java.lang.Number</code> type for
94       * the "integer" type of XML Schema Part 2.
95       * 
96       * <p>
97       * Also, the caller cannot assume that the equals method and
98       * the hashCode method of the value object are consistent with
99       * the semantics of the datatype. For that purpose, the sameValue
100      * method and the valueHashCode method have to be used. Note that
101      * this means you cannot use classes like
102      * <code>java.util.Hashtable</code> to store the value objects.
103      * 
104      * <p>
105      * The returned value object should be used solely for the sameValue
106      * and valueHashCode methods.
107      * 
108      * @param context
109      *      If this datatype is context-dependent
110      *      (when the {@link #isContextDependent} method returns true),
111      *      then the caller must provide a non-null valid context object.
112      *      Otherwise, the caller can pass null.
113      * 
114      * @return  null
115      *      when the given lexical value is not a valid lexical
116      *      value for this type.
117      */
118     Object   createValue( String   literal, ValidationContext context );
119     
120     /**
121      * Tests the equality of two value objects which were originally
122      * created by the createValue method of this object.
123      * 
124      * The behavior is undefined if objects not created by this type
125      * are passed. It is the caller's responsibility to ensure that
126      * value objects belong to this type.
127      * 
128      * @return
129      *      true if two value objects are considered equal according to
130      *      the definition of this datatype; false if otherwise.
131      */
132     boolean sameValue( Object   value1, Object   value2 );
133     
134     
135     /**
136      * Computes the hash code for a value object,
137      * which is consistent with the sameValue method.
138      * 
139      * @return
140      *      hash code for the specified value object.
141      */
142     int valueHashCode( Object   value );
143 
144 
145 
146     
147     /**
148      * Indicates that the datatype doesn't have ID/IDREF semantics.
149      * 
150      * This value is one of the possible return values of the
151      * {@link #getIdType} method.
152      */
153     public static final int ID_TYPE_NULL = 0;
154     
155     /**
156      * Indicates that RELAX NG compatibility processors should
157      * treat this datatype as having ID semantics.
158      * 
159      * This value is one of the possible return values of the
160      * {@link #getIdType} method.
161      */
162     public static final int ID_TYPE_ID = 1;
163     
164     /**
165      * Indicates that RELAX NG compatibility processors should
166      * treat this datatype as having IDREF semantics.
167      * 
168      * This value is one of the possible return values of the
169      * {@link #getIdType} method.
170      */
171     public static final int ID_TYPE_IDREF = 2;
172     
173     /**
174      * Indicates that RELAX NG compatibility processors should
175      * treat this datatype as having IDREFS semantics.
176      * 
177      * This value is one of the possible return values of the
178      * {@link #getIdType} method.
179      */
180     public static final int ID_TYPE_IDREFS = 3;
181     
182     /**
183      * Checks if the ID/IDREF semantics is associated with this
184      * datatype.
185      * 
186      * <p>
187      * This method is introduced to support the RELAX NG DTD
188      * compatibility spec. (Of course it's always free to use
189      * this method for other purposes.)
190      * 
191      * <p>
192      * If you are implementing a datatype library and have no idea about
193      * the "RELAX NG DTD compatibility" thing, just return
194      * <code>ID_TYPE_NULL</code> is fine.
195      * 
196      * @return
197      *      If this datatype doesn't have any ID/IDREF semantics,
198      *      it returns {@link #ID_TYPE_NULL}. If it has such a semantics
199      *      (for example, XSD:ID, XSD:IDREF and comp:ID type), then
200      *      it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or
201      *      {@link #ID_TYPE_IDREFS}.
202      */
203     public int getIdType();
204     
205     
206     /**
207      * Checks if this datatype may need a context object for
208      * the validation.
209      * 
210      * <p>
211      * The callee must return true even when the context
212      * is not always necessary. (For example, the "QName" type
213      * doesn't need a context object when validating unprefixed
214      * string. But nonetheless QName must return true.)
215      * 
216      * <p>
217      * XSD's <code>string</code> and <code>short</code> types
218      * are examples of context-independent datatypes.
219      * Its <code>QName</code> and <code>ENTITY</code> types
220      * are examples of context-dependent datatypes.
221      * 
222      * <p>
223      * When a datatype is context-independent, then
224      * the {@link #isValid} method, the {@link #checkValid} method,
225      * the {@link #createStreamingValidator} method and
226      * the {@link #createValue} method can be called without
227      * providing a context object.
228      * 
229      * @return
230      *      <b>true</b> if this datatype is context-dependent
231      *      (it needs a context object sometimes);
232      * 
233      *      <b>false</b> if this datatype is context-<b>in</b>dependent
234      *      (it never needs a context object).
235      */
236     public boolean isContextDependent();
237 }
238
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags