- * 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(); -}