org.relaxng.datatype
Interface DataType


public interface DataType

Datatype object. Every datatype object has several functionalities. Particularly,

  1. ability to identifies a class of character sequences. This is done through allows method.
  2. ability to produce "value object" from a character sequence and a context information.
  3. ability to test equality of two value objects.
This interface also defines optional diagnose method, which provides human-friendly error diagnosis.

Author:
Kohsuke KAWAGUCHI

Method Summary
 boolean allows(java.lang.String literal, ValidationContext context)
          checks if 'literal' matchs this datatype under the current context.
 void check(java.lang.String literal, ValidationContext context)
          diagnoses the reason of error.
 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.
 java.lang.String displayName()
          gets type name suitable for display (something like "string","dateTim", and so on.) the callee cannot return null.
 boolean sameValue(java.lang.Object value1, java.lang.Object value2)
          tests the equality of two value objects which belongs to this type.
 

Method Detail

allows

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

check

public void check(java.lang.String literal,
                  ValidationContext context)
           throws java.lang.UnsupportedOperationException,
                  DataTypeException
diagnoses the reason of error. Application can call this method to provide detailed error message to users. This method is kept separate from verify method to achieve higher performance during normal validation. This method is optional and may not be implemented by some of datatypes.

This method is optional and implementations are free to throw UnsupportedOperationException to indicate that this method is not implemented.

Throws:
java.lang.UnsupportedOperationException - if diagnosis is not supported by the callee.
DataTypeException - If the callee supports the diagnosis and the given literal is invalid, then this exception that contains diagnosis information is thrown.

createStreamingValidator

public DataTypeStreamingValidator createStreamingValidator(ValidationContext context)
                                                    throws java.lang.UnsupportedOperationException
creates an instance of the streaming validator for this type. By using streaming validators instead of the accepts method, the caller can avoid keeping the entire string into the memory, which is sometimes quite big.

This method is optional and implementations are free to throw UnsupportedOperationException to indicate that this method is not implemented.

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

displayName

public java.lang.String displayName()
gets type name suitable for display (something like "string","dateTim", and so on.) the callee cannot return null.

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.

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 belongs to this type. The bahavior is undefined if objects not belonged to this type is passed. It is the caller's responsibility to ensure that objects belong to this type.
Returns:
true if two value objects are considered equal; false if otherwise.