001: /*
002: * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package org.relaxng.datatype;
027:
028: /**
029: * Datatype object.
030: *
031: * This object has the following functionality:
032: *
033: * <ol>
034: * <li> functionality to identify a class of character sequences. This is
035: * done through the isValid method.
036: *
037: * <li> functionality to produce a "value object" from a character sequence and
038: * context information.
039: *
040: * <li> functionality to test the equality of two value objects.
041: * </ol>
042: *
043: * This interface also defines the createStreamingValidator method,
044: * which is intended to efficiently support the validation of
045: * large character sequences.
046: *
047: * @author <a href="mailto:jjc@jclark.com">James Clark</a>
048: * @author <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
049: */
050: public interface Datatype {
051:
052: /**
053: * Checks if the specified 'literal' matches this Datatype
054: * with respect to the current context.
055: *
056: * @param literal
057: * the lexical representation to be checked.
058: * @param context
059: * If this datatype is context-dependent
060: * (i.e. the {@link #isContextDependent} method returns true),
061: * then the caller must provide a non-null valid context object.
062: * Otherwise, the caller can pass null.
063: *
064: * @return
065: * true if the 'literal' is a member of this Datatype;
066: * false if it's not a member of this Datatype.
067: */
068: boolean isValid(String literal, ValidationContext context);
069:
070: /**
071: * Similar to the isValid method but throws an exception with diagnosis
072: * in case of errors.
073: *
074: * <p>
075: * If the specified 'literal' is a valid lexical representation for this
076: * datatype, then this method must return without throwing any exception.
077: * If not, the callee must throw an exception (with diagnosis message,
078: * if possible.)
079: *
080: * <p>
081: * The application can use this method to provide detailed error message
082: * to users. This method is kept separate from the isValid method to
083: * achieve higher performance during normal validation.
084: *
085: * @exception DatatypeException
086: * If the given literal is invalid, then this exception is thrown.
087: * If the callee supports error diagnosis, then the exception should
088: * contain a diagnosis message.
089: */
090: void checkValid(String literal, ValidationContext context)
091: throws DatatypeException;
092:
093: /**
094: * Creates an instance of a streaming validator for this type.
095: *
096: * <p>
097: * By using streaming validators instead of the isValid method,
098: * the caller can avoid keeping the entire string, which is
099: * sometimes quite big, in memory.
100: *
101: * @param context
102: * If this datatype is context-dependent
103: * (i.e. the {@link #isContextDependent} method returns true),
104: * then the caller must provide a non-null valid context object.
105: * Otherwise, the caller can pass null.
106: * The callee may keep a reference to this context object
107: * only while the returned streaming validator is being used.
108: */
109: DatatypeStreamingValidator createStreamingValidator(
110: ValidationContext context);
111:
112: /**
113: * Converts lexcial value and the current context to the corresponding
114: * value object.
115: *
116: * <p>
117: * The caller cannot generally assume that the value object is
118: * a meaningful Java object. For example, the caller cannot expect
119: * this method to return <code>java.lang.Number</code> type for
120: * the "integer" type of XML Schema Part 2.
121: *
122: * <p>
123: * Also, the caller cannot assume that the equals method and
124: * the hashCode method of the value object are consistent with
125: * the semantics of the datatype. For that purpose, the sameValue
126: * method and the valueHashCode method have to be used. Note that
127: * this means you cannot use classes like
128: * <code>java.util.Hashtable</code> to store the value objects.
129: *
130: * <p>
131: * The returned value object should be used solely for the sameValue
132: * and valueHashCode methods.
133: *
134: * @param context
135: * If this datatype is context-dependent
136: * (when the {@link #isContextDependent} method returns true),
137: * then the caller must provide a non-null valid context object.
138: * Otherwise, the caller can pass null.
139: *
140: * @return null
141: * when the given lexical value is not a valid lexical
142: * value for this type.
143: */
144: Object createValue(String literal, ValidationContext context);
145:
146: /**
147: * Tests the equality of two value objects which were originally
148: * created by the createValue method of this object.
149: *
150: * The behavior is undefined if objects not created by this type
151: * are passed. It is the caller's responsibility to ensure that
152: * value objects belong to this type.
153: *
154: * @return
155: * true if two value objects are considered equal according to
156: * the definition of this datatype; false if otherwise.
157: */
158: boolean sameValue(Object value1, Object value2);
159:
160: /**
161: * Computes the hash code for a value object,
162: * which is consistent with the sameValue method.
163: *
164: * @return
165: * hash code for the specified value object.
166: */
167: int valueHashCode(Object value);
168:
169: /**
170: * Indicates that the datatype doesn't have ID/IDREF semantics.
171: *
172: * This value is one of the possible return values of the
173: * {@link #getIdType} method.
174: */
175: public static final int ID_TYPE_NULL = 0;
176:
177: /**
178: * Indicates that RELAX NG compatibility processors should
179: * treat this datatype as having ID semantics.
180: *
181: * This value is one of the possible return values of the
182: * {@link #getIdType} method.
183: */
184: public static final int ID_TYPE_ID = 1;
185:
186: /**
187: * Indicates that RELAX NG compatibility processors should
188: * treat this datatype as having IDREF semantics.
189: *
190: * This value is one of the possible return values of the
191: * {@link #getIdType} method.
192: */
193: public static final int ID_TYPE_IDREF = 2;
194:
195: /**
196: * Indicates that RELAX NG compatibility processors should
197: * treat this datatype as having IDREFS semantics.
198: *
199: * This value is one of the possible return values of the
200: * {@link #getIdType} method.
201: */
202: public static final int ID_TYPE_IDREFS = 3;
203:
204: /**
205: * Checks if the ID/IDREF semantics is associated with this
206: * datatype.
207: *
208: * <p>
209: * This method is introduced to support the RELAX NG DTD
210: * compatibility spec. (Of course it's always free to use
211: * this method for other purposes.)
212: *
213: * <p>
214: * If you are implementing a datatype library and have no idea about
215: * the "RELAX NG DTD compatibility" thing, just return
216: * <code>ID_TYPE_NULL</code> is fine.
217: *
218: * @return
219: * If this datatype doesn't have any ID/IDREF semantics,
220: * it returns {@link #ID_TYPE_NULL}. If it has such a semantics
221: * (for example, XSD:ID, XSD:IDREF and comp:ID type), then
222: * it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or
223: * {@link #ID_TYPE_IDREFS}.
224: */
225: public int getIdType();
226:
227: /**
228: * Checks if this datatype may need a context object for
229: * the validation.
230: *
231: * <p>
232: * The callee must return true even when the context
233: * is not always necessary. (For example, the "QName" type
234: * doesn't need a context object when validating unprefixed
235: * string. But nonetheless QName must return true.)
236: *
237: * <p>
238: * XSD's <code>string</code> and <code>short</code> types
239: * are examples of context-independent datatypes.
240: * Its <code>QName</code> and <code>ENTITY</code> types
241: * are examples of context-dependent datatypes.
242: *
243: * <p>
244: * When a datatype is context-independent, then
245: * the {@link #isValid} method, the {@link #checkValid} method,
246: * the {@link #createStreamingValidator} method and
247: * the {@link #createValue} method can be called without
248: * providing a context object.
249: *
250: * @return
251: * <b>true</b> if this datatype is context-dependent
252: * (it needs a context object sometimes);
253: *
254: * <b>false</b> if this datatype is context-<b>in</b>dependent
255: * (it never needs a context object).
256: */
257: public boolean isContextDependent();
258: }
|