Logo Search packages:      
Sourcecode: jing-trang version File versions  Download package

Datatype.java

package org.relaxng.datatype;

/**
 * Datatype object.
 * 
 * This object has the following functionality:
 * 
 * <ol>
 *  <li> functionality to identify a class of character sequences. This is
 *       done through the isValid method.
 * 
 *  <li> functionality to produce a "value object" from a character sequence and
 *           context information.
 * 
 *  <li> functionality to test the equality of two value objects.
 * </ol>
 * 
 * This interface also defines the createStreamingValidator method,
 * which is intended to efficiently support the validation of
 * large character sequences.
 * 
 * @author <a href="mailto:jjc@jclark.com">James Clark</a>
 * @author <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
 */
00025 public interface Datatype {
      
      /**
       * Checks if the specified 'literal' matches this Datatype
       * with respect to the current context.
       * 
       * @param literal
       *          the lexical representation to be checked.
       * @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.
       * 
       * @return
       *          true if the 'literal' is a member of this Datatype;
       *          false if it's not a member of this Datatype.
       */
      boolean isValid( String literal, ValidationContext context );
      
      /**
       * Similar to the isValid method but throws an exception with diagnosis
       * in case of errors.
       * 
       * <p>
       * 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.)
       * 
       * <p>
       * 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.
       * 
       * <p>
       * 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.
       * 
       * <p>
       * The caller cannot generally assume that the value object is
       * a meaningful Java object. For example, the caller cannot expect
       * this method to return <code>java.lang.Number</code> type for
       * the "integer" type of XML Schema Part 2.
       * 
       * <p>
       * 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
       * <code>java.util.Hashtable</code> to store the value objects.
       * 
       * <p>
       * 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.
       */
00153       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.
       */
00162       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.
       */
00171       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.
       */
00180       public static final int ID_TYPE_IDREFS = 3;
      
      /**
       * Checks if the ID/IDREF semantics is associated with this
       * datatype.
       * 
       * <p>
       * 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.)
       * 
       * <p>
       * If you are implementing a datatype library and have no idea about
       * the "RELAX NG DTD compatibility" thing, just return
       * <code>ID_TYPE_NULL</code> 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.
       * 
       * <p>
       * 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.)
       * 
       * <p>
       * XSD's <code>string</code> and <code>short</code> types
       * are examples of context-independent datatypes.
       * Its <code>QName</code> and <code>ENTITY</code> types
       * are examples of context-dependent datatypes.
       * 
       * <p>
       * 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
       *          <b>true</b> if this datatype is context-dependent
       *          (it needs a context object sometimes);
       * 
       *          <b>false</b> if this datatype is context-<b>in</b>dependent
       *          (it never needs a context object).
       */
      public boolean isContextDependent();
}

Generated by  Doxygen 1.6.0   Back to index