001package 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 */
025public 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}