001 package org.relaxng.datatype;
002
003 /**
004 * Datatype object.
005 *
006 * This object has the following functionality:
007 *
008 * <ol>
009 * <li> functionality to identify a class of character sequences. This is
010 * done through the isValid method.
011 *
012 * <li> functionality to produce a "value object" from a character sequence and
013 * context information.
014 *
015 * <li> functionality to test the equality of two value objects.
016 * </ol>
017 *
018 * This interface also defines the createStreamingValidator method,
019 * which is intended to efficiently support the validation of
020 * large character sequences.
021 *
022 * @author <a href="mailto:jjc@jclark.com">James Clark</a>
023 * @author <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
024 */
025 public interface Datatype {
026
027 /**
028 * Checks if the specified 'literal' matches this Datatype
029 * with respect to the current context.
030 *
031 * @param literal
032 * the lexical representation to be checked.
033 * @param context
034 * If this datatype is context-dependent
035 * (i.e. the {@link #isContextDependent} method returns true),
036 * then the caller must provide a non-null valid context object.
037 * Otherwise, the caller can pass null.
038 *
039 * @return
040 * true if the 'literal' is a member of this Datatype;
041 * false if it's not a member of this Datatype.
042 */
043 boolean isValid( String literal, ValidationContext context );
044
045 /**
046 * Similar to the isValid method but throws an exception with diagnosis
047 * in case of errors.
048 *
049 * <p>
050 * If the specified 'literal' is a valid lexical representation for this
051 * datatype, then this method must return without throwing any exception.
052 * If not, the callee must throw an exception (with diagnosis message,
053 * if possible.)
054 *
055 * <p>
056 * The application can use this method to provide detailed error message
057 * to users. This method is kept separate from the isValid method to
058 * achieve higher performance during normal validation.
059 *
060 * @exception DatatypeException
061 * If the given literal is invalid, then this exception is thrown.
062 * If the callee supports error diagnosis, then the exception should
063 * contain a diagnosis message.
064 */
065 void checkValid( String literal, ValidationContext context )
066 throws DatatypeException;
067
068 /**
069 * Creates an instance of a streaming validator for this type.
070 *
071 * <p>
072 * By using streaming validators instead of the isValid method,
073 * the caller can avoid keeping the entire string, which is
074 * sometimes quite big, in memory.
075 *
076 * @param context
077 * If this datatype is context-dependent
078 * (i.e. the {@link #isContextDependent} method returns true),
079 * then the caller must provide a non-null valid context object.
080 * Otherwise, the caller can pass null.
081 * The callee may keep a reference to this context object
082 * only while the returned streaming validator is being used.
083 */
084 DatatypeStreamingValidator createStreamingValidator( ValidationContext context );
085
086 /**
087 * Converts lexcial value and the current context to the corresponding
088 * value object.
089 *
090 * <p>
091 * The caller cannot generally assume that the value object is
092 * a meaningful Java object. For example, the caller cannot expect
093 * this method to return <code>java.lang.Number</code> type for
094 * the "integer" type of XML Schema Part 2.
095 *
096 * <p>
097 * Also, the caller cannot assume that the equals method and
098 * the hashCode method of the value object are consistent with
099 * 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 }