* If the specified 'literal' is a valid lexical representation for this * datatype, then this method must return without throwing any exception. * If not, the callee must throw an exception (with diagnosis message, * if possible.) * *
* The application can use this method to provide detailed error message * to users. This method is kept separate from the isValid method to * achieve higher performance during normal validation. * * @exception DatatypeException * If the given literal is invalid, then this exception is thrown. * If the callee supports error diagnosis, then the exception should * contain a diagnosis message. */ void checkValid( String literal, ValidationContext context ) throws DatatypeException; /** * Creates an instance of a streaming validator for this type. * *
* By using streaming validators instead of the isValid method, * the caller can avoid keeping the entire string, which is * sometimes quite big, in memory. * * @param context * If this datatype is context-dependent * (i.e. the {@link #isContextDependent} method returns true), * then the caller must provide a non-null valid context object. * Otherwise, the caller can pass null. * The callee may keep a reference to this context object * only while the returned streaming validator is being used. */ DatatypeStreamingValidator createStreamingValidator( ValidationContext context ); /** * Converts lexcial value and the current context to the corresponding * value object. * *
* The caller cannot generally assume that the value object is
* a meaningful Java object. For example, the caller cannot expect
* this method to return java.lang.Number type for
* the "integer" type of XML Schema Part 2.
*
*
* Also, the caller cannot assume that the equals method and
* the hashCode method of the value object are consistent with
* the semantics of the datatype. For that purpose, the sameValue
* method and the valueHashCode method have to be used. Note that
* this means you cannot use classes like
* java.util.Hashtable to store the value objects.
*
*
* The returned value object should be used solely for the sameValue * and valueHashCode methods. * * @param context * If this datatype is context-dependent * (when the {@link #isContextDependent} method returns true), * then the caller must provide a non-null valid context object. * Otherwise, the caller can pass null. * * @return null * when the given lexical value is not a valid lexical * value for this type. */ Object createValue( String literal, ValidationContext context ); /** * Tests the equality of two value objects which were originally * created by the createValue method of this object. * * The behavior is undefined if objects not created by this type * are passed. It is the caller's responsibility to ensure that * value objects belong to this type. * * @return * true if two value objects are considered equal according to * the definition of this datatype; false if otherwise. */ boolean sameValue( Object value1, Object value2 ); /** * Computes the hash code for a value object, * which is consistent with the sameValue method. * * @return * hash code for the specified value object. */ int valueHashCode( Object value ); /** * Indicates that the datatype doesn't have ID/IDREF semantics. * * This value is one of the possible return values of the * {@link #getIdType} method. */ public static final int ID_TYPE_NULL = 0; /** * Indicates that RELAX NG compatibility processors should * treat this datatype as having ID semantics. * * This value is one of the possible return values of the * {@link #getIdType} method. */ public static final int ID_TYPE_ID = 1; /** * Indicates that RELAX NG compatibility processors should * treat this datatype as having IDREF semantics. * * This value is one of the possible return values of the * {@link #getIdType} method. */ public static final int ID_TYPE_IDREF = 2; /** * Indicates that RELAX NG compatibility processors should * treat this datatype as having IDREFS semantics. * * This value is one of the possible return values of the * {@link #getIdType} method. */ public static final int ID_TYPE_IDREFS = 3; /** * Checks if the ID/IDREF semantics is associated with this * datatype. * *
* This method is introduced to support the RELAX NG DTD * compatibility spec. (Of course it's always free to use * this method for other purposes.) * *
* If you are implementing a datatype library and have no idea about
* the "RELAX NG DTD compatibility" thing, just return
* ID_TYPE_NULL is fine.
*
* @return
* If this datatype doesn't have any ID/IDREF semantics,
* it returns {@link #ID_TYPE_NULL}. If it has such a semantics
* (for example, XSD:ID, XSD:IDREF and comp:ID type), then
* it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or
* {@link #ID_TYPE_IDREFS}.
*/
public int getIdType();
/**
* Checks if this datatype may need a context object for
* the validation.
*
*
* The callee must return true even when the context * is not always necessary. (For example, the "QName" type * doesn't need a context object when validating unprefixed * string. But nonetheless QName must return true.) * *
* XSD's string and short types
* are examples of context-independent datatypes.
* Its QName and ENTITY types
* are examples of context-dependent datatypes.
*
*
* When a datatype is context-independent, then * the {@link #isValid} method, the {@link #checkValid} method, * the {@link #createStreamingValidator} method and * the {@link #createValue} method can be called without * providing a context object. * * @return * true if this datatype is context-dependent * (it needs a context object sometimes); * * false if this datatype is context-independent * (it never needs a context object). */ public boolean isContextDependent(); }