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(
085: ValidationContext context);
086:
087: /**
088: * Converts lexcial value and the current context to the corresponding
089: * value object.
090: *
091: * <p>
092: * The caller cannot generally assume that the value object is
093: * a meaningful Java object. For example, the caller cannot expect
094: * this method to return <code>java.lang.Number</code> type for
095: * the "integer" type of XML Schema Part 2.
096: *
097: * <p>
098: * Also, the caller cannot assume that the equals method and
099: * the hashCode method of the value object are consistent with
100: * the semantics of the datatype. For that purpose, the sameValue
101: * method and the valueHashCode method have to be used. Note that
102: * this means you cannot use classes like
103: * <code>java.util.Hashtable</code> to store the value objects.
104: *
105: * <p>
106: * The returned value object should be used solely for the sameValue
107: * and valueHashCode methods.
108: *
109: * @param context
110: * If this datatype is context-dependent
111: * (when the {@link #isContextDependent} method returns true),
112: * then the caller must provide a non-null valid context object.
113: * Otherwise, the caller can pass null.
114: *
115: * @return null
116: * when the given lexical value is not a valid lexical
117: * value for this type.
118: */
119: Object createValue(String literal, ValidationContext context);
120:
121: /**
122: * Tests the equality of two value objects which were originally
123: * created by the createValue method of this object.
124: *
125: * The behavior is undefined if objects not created by this type
126: * are passed. It is the caller's responsibility to ensure that
127: * value objects belong to this type.
128: *
129: * @return
130: * true if two value objects are considered equal according to
131: * the definition of this datatype; false if otherwise.
132: */
133: boolean sameValue(Object value1, Object value2);
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: * Indicates that the datatype doesn't have ID/IDREF semantics.
146: *
147: * This value is one of the possible return values of the
148: * {@link #getIdType} method.
149: */
150: public static final int ID_TYPE_NULL = 0;
151:
152: /**
153: * Indicates that RELAX NG compatibility processors should
154: * treat this datatype as having ID semantics.
155: *
156: * This value is one of the possible return values of the
157: * {@link #getIdType} method.
158: */
159: public static final int ID_TYPE_ID = 1;
160:
161: /**
162: * Indicates that RELAX NG compatibility processors should
163: * treat this datatype as having IDREF semantics.
164: *
165: * This value is one of the possible return values of the
166: * {@link #getIdType} method.
167: */
168: public static final int ID_TYPE_IDREF = 2;
169:
170: /**
171: * Indicates that RELAX NG compatibility processors should
172: * treat this datatype as having IDREFS semantics.
173: *
174: * This value is one of the possible return values of the
175: * {@link #getIdType} method.
176: */
177: public static final int ID_TYPE_IDREFS = 3;
178:
179: /**
180: * Checks if the ID/IDREF semantics is associated with this
181: * datatype.
182: *
183: * <p>
184: * This method is introduced to support the RELAX NG DTD
185: * compatibility spec. (Of course it's always free to use
186: * this method for other purposes.)
187: *
188: * <p>
189: * If you are implementing a datatype library and have no idea about
190: * the "RELAX NG DTD compatibility" thing, just return
191: * <code>ID_TYPE_NULL</code> is fine.
192: *
193: * @return
194: * If this datatype doesn't have any ID/IDREF semantics,
195: * it returns {@link #ID_TYPE_NULL}. If it has such a semantics
196: * (for example, XSD:ID, XSD:IDREF and comp:ID type), then
197: * it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or
198: * {@link #ID_TYPE_IDREFS}.
199: */
200: public int getIdType();
201:
202: /**
203: * Checks if this datatype may need a context object for
204: * the validation.
205: *
206: * <p>
207: * The callee must return true even when the context
208: * is not always necessary. (For example, the "QName" type
209: * doesn't need a context object when validating unprefixed
210: * string. But nonetheless QName must return true.)
211: *
212: * <p>
213: * XSD's <code>string</code> and <code>short</code> types
214: * are examples of context-independent datatypes.
215: * Its <code>QName</code> and <code>ENTITY</code> types
216: * are examples of context-dependent datatypes.
217: *
218: * <p>
219: * When a datatype is context-independent, then
220: * the {@link #isValid} method, the {@link #checkValid} method,
221: * the {@link #createStreamingValidator} method and
222: * the {@link #createValue} method can be called without
223: * providing a context object.
224: *
225: * @return
226: * <b>true</b> if this datatype is context-dependent
227: * (it needs a context object sometimes);
228: *
229: * <b>false</b> if this datatype is context-<b>in</b>dependent
230: * (it never needs a context object).
231: */
232: public boolean isContextDependent();
233: }
|