1 package org.relaxng.datatype;
\r
6 * This object has the following functionality:
\r
9 * <li> functionality to identify a class of character sequences. This is
\r
10 * done through the isValid method.
\r
12 * <li> functionality to produce a "value object" from a character sequence and
\r
13 * context information.
\r
15 * <li> functionality to test the equality of two value objects.
\r
18 * This interface also defines the createStreamingValidator method,
\r
19 * which is intended to efficiently support the validation of
\r
20 * large character sequences.
\r
22 * @author <a href="mailto:jjc@jclark.com">James Clark</a>
\r
23 * @author <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
\r
25 public interface Datatype {
\r
28 * Checks if the specified 'literal' matches this Datatype
\r
29 * with respect to the current context.
\r
32 * the lexical representation to be checked.
\r
34 * If this datatype is context-dependent
\r
35 * (i.e. the {@link #isContextDependent} method returns true),
\r
36 * then the caller must provide a non-null valid context object.
\r
37 * Otherwise, the caller can pass null.
\r
40 * true if the 'literal' is a member of this Datatype;
\r
41 * false if it's not a member of this Datatype.
\r
43 boolean isValid( String literal, ValidationContext context );
\r
46 * Similar to the isValid method but throws an exception with diagnosis
\r
47 * in case of errors.
\r
50 * If the specified 'literal' is a valid lexical representation for this
\r
51 * datatype, then this method must return without throwing any exception.
\r
52 * If not, the callee must throw an exception (with diagnosis message,
\r
56 * The application can use this method to provide detailed error message
\r
57 * to users. This method is kept separate from the isValid method to
\r
58 * achieve higher performance during normal validation.
\r
60 * @exception DatatypeException
\r
61 * If the given literal is invalid, then this exception is thrown.
\r
62 * If the callee supports error diagnosis, then the exception should
\r
63 * contain a diagnosis message.
\r
65 void checkValid( String literal, ValidationContext context )
\r
66 throws DatatypeException;
\r
69 * Creates an instance of a streaming validator for this type.
\r
72 * By using streaming validators instead of the isValid method,
\r
73 * the caller can avoid keeping the entire string, which is
\r
74 * sometimes quite big, in memory.
\r
77 * If this datatype is context-dependent
\r
78 * (i.e. the {@link #isContextDependent} method returns true),
\r
79 * then the caller must provide a non-null valid context object.
\r
80 * Otherwise, the caller can pass null.
\r
81 * The callee may keep a reference to this context object
\r
82 * only while the returned streaming validator is being used.
\r
84 DatatypeStreamingValidator createStreamingValidator( ValidationContext context );
\r
87 * Converts lexcial value and the current context to the corresponding
\r
91 * The caller cannot generally assume that the value object is
\r
92 * a meaningful Java object. For example, the caller cannot expect
\r
93 * this method to return <code>java.lang.Number</code> type for
\r
94 * the "integer" type of XML Schema Part 2.
\r
97 * Also, the caller cannot assume that the equals method and
\r
98 * the hashCode method of the value object are consistent with
\r
99 * the semantics of the datatype. For that purpose, the sameValue
\r
100 * method and the valueHashCode method have to be used. Note that
\r
101 * this means you cannot use classes like
\r
102 * <code>java.util.Hashtable</code> to store the value objects.
\r
105 * The returned value object should be used solely for the sameValue
\r
106 * and valueHashCode methods.
\r
109 * If this datatype is context-dependent
\r
110 * (when the {@link #isContextDependent} method returns true),
\r
111 * then the caller must provide a non-null valid context object.
\r
112 * Otherwise, the caller can pass null.
\r
115 * when the given lexical value is not a valid lexical
\r
116 * value for this type.
\r
118 Object createValue( String literal, ValidationContext context );
\r
121 * Tests the equality of two value objects which were originally
\r
122 * created by the createValue method of this object.
\r
124 * The behavior is undefined if objects not created by this type
\r
125 * are passed. It is the caller's responsibility to ensure that
\r
126 * value objects belong to this type.
\r
129 * true if two value objects are considered equal according to
\r
130 * the definition of this datatype; false if otherwise.
\r
132 boolean sameValue( Object value1, Object value2 );
\r
136 * Computes the hash code for a value object,
\r
137 * which is consistent with the sameValue method.
\r
140 * hash code for the specified value object.
\r
142 int valueHashCode( Object value );
\r
148 * Indicates that the datatype doesn't have ID/IDREF semantics.
\r
150 * This value is one of the possible return values of the
\r
151 * {@link #getIdType} method.
\r
153 public static final int ID_TYPE_NULL = 0;
\r
156 * Indicates that RELAX NG compatibility processors should
\r
157 * treat this datatype as having ID semantics.
\r
159 * This value is one of the possible return values of the
\r
160 * {@link #getIdType} method.
\r
162 public static final int ID_TYPE_ID = 1;
\r
165 * Indicates that RELAX NG compatibility processors should
\r
166 * treat this datatype as having IDREF semantics.
\r
168 * This value is one of the possible return values of the
\r
169 * {@link #getIdType} method.
\r
171 public static final int ID_TYPE_IDREF = 2;
\r
174 * Indicates that RELAX NG compatibility processors should
\r
175 * treat this datatype as having IDREFS semantics.
\r
177 * This value is one of the possible return values of the
\r
178 * {@link #getIdType} method.
\r
180 public static final int ID_TYPE_IDREFS = 3;
\r
183 * Checks if the ID/IDREF semantics is associated with this
\r
187 * This method is introduced to support the RELAX NG DTD
\r
188 * compatibility spec. (Of course it's always free to use
\r
189 * this method for other purposes.)
\r
192 * If you are implementing a datatype library and have no idea about
\r
193 * the "RELAX NG DTD compatibility" thing, just return
\r
194 * <code>ID_TYPE_NULL</code> is fine.
\r
197 * If this datatype doesn't have any ID/IDREF semantics,
\r
198 * it returns {@link #ID_TYPE_NULL}. If it has such a semantics
\r
199 * (for example, XSD:ID, XSD:IDREF and comp:ID type), then
\r
200 * it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or
\r
201 * {@link #ID_TYPE_IDREFS}.
\r
203 public int getIdType();
\r
207 * Checks if this datatype may need a context object for
\r
211 * The callee must return true even when the context
\r
212 * is not always necessary. (For example, the "QName" type
\r
213 * doesn't need a context object when validating unprefixed
\r
214 * string. But nonetheless QName must return true.)
\r
217 * XSD's <code>string</code> and <code>short</code> types
\r
218 * are examples of context-independent datatypes.
\r
219 * Its <code>QName</code> and <code>ENTITY</code> types
\r
220 * are examples of context-dependent datatypes.
\r
223 * When a datatype is context-independent, then
\r
224 * the {@link #isValid} method, the {@link #checkValid} method,
\r
225 * the {@link #createStreamingValidator} method and
\r
226 * the {@link #createValue} method can be called without
\r
227 * providing a context object.
\r
230 * <b>true</b> if this datatype is context-dependent
\r
231 * (it needs a context object sometimes);
\r
233 * <b>false</b> if this datatype is context-<b>in</b>dependent
\r
234 * (it never needs a context object).
\r
236 public boolean isContextDependent();
\r