org.relaxng.datatype
Interface Datatype


public interface Datatype

Datatype object. This object has the following functionalities:

  1. functionality to identifies a class of character sequences. This is done through the isValid method.
  2. functionality to produce "value object" from a character sequence and a context information.
  3. functionality to test the equality of two value objects.
This interface also defines optional createStreamingValidator method, which is supposed to efficiently support the validation of large character sequence.

Author:
James Clark, Kohsuke KAWAGUCHI

Method Summary
 void checkValid(java.lang.String literal, ValidationContext context)
          similar to the isValid method but throws an exception with diagnosis in case of errors.
 DatatypeStreamingValidator createStreamingValidator(ValidationContext context)
          creates an instance of the streaming validator for this type.
 java.lang.Object createValue(java.lang.String literal, ValidationContext context)
          converts lexcial value and the current context to the corresponding value object.
 boolean isValid(java.lang.String literal, ValidationContext context)
          checks if the specified 'literal' matchs this Datatype under the current context.
 boolean sameValue(java.lang.Object value1, java.lang.Object value2)
          tests the equality of two value objects which was originally created by the createValue method of this object.
 int valueHashCode(java.lang.Object value)
          computes the hash code for a value object, which is consistent with the sameValue method.
 

Method Detail

isValid

public boolean isValid(java.lang.String literal,
                       ValidationContext context)
checks if the specified 'literal' matchs this Datatype under the current context.
Parameters:
literal - the lexical representation to be checked.
context - context information that may be necessary to validate the given literal.
Returns:
true if the 'literal' is a member of this Datatype; false if it's not a member of this Datatype.

checkValid

public void checkValid(java.lang.String literal,
                       ValidationContext context)
                throws DatatypeException
similar to the isValid method but throws an exception with diagnosis in case of errors.

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.

Throws:
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.

createStreamingValidator

public DatatypeStreamingValidator createStreamingValidator(ValidationContext context)
creates an instance of the streaming validator for this type.

By using streaming validators instead of the isValid method, the caller can avoid keeping the entire string into the memory, which is sometimes quite big.

Parameters:
context - context information that may be necessary to validate the given literal. The callee may keep a reference to this context object only while the returned streaming validator is being used.
Throws:
UnsupportedOperationException - if the streaming validation is not supported by the callee.

createValue

public java.lang.Object createValue(java.lang.String literal,
                                    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 Part2.

Also, the caller cannot assume that the equals method and the hashCode method of the value object is 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 method.

Returns:
null when the given lexical value is not a valid lexical value for this type.

sameValue

public boolean sameValue(java.lang.Object value1,
                         java.lang.Object value2)
tests the equality of two value objects which was originally created by the createValue method of this object. The bahavior is undefined if objects not created by this type is passed. It is the caller's responsibility to ensure that value objects belong to this type.
Returns:
true if two value objects are considered equal according to the definition of this datatype; false if otherwise.

valueHashCode

public int valueHashCode(java.lang.Object value)
computes the hash code for a value object, which is consistent with the sameValue method.
Returns:
hash code for the specified value object.