Source for org.relaxng.datatype.Datatype

   1: package org.relaxng.datatype;
   2: 
   3: /**
   4:  * Datatype object.
   5:  * 
   6:  * This object has the following functionality:
   7:  * 
   8:  * <ol>
   9:  *  <li> functionality to identify a class of character sequences. This is
  10:  *       done through the isValid method.
  11:  * 
  12:  *  <li> functionality to produce a "value object" from a character sequence and
  13:  *         context information.
  14:  * 
  15:  *  <li> functionality to test the equality of two value objects.
  16:  * </ol>
  17:  * 
  18:  * This interface also defines the createStreamingValidator method,
  19:  * which is intended to efficiently support the validation of
  20:  * large character sequences.
  21:  * 
  22:  * @author <a href="mailto:jjc@jclark.com">James Clark</a>
  23:  * @author <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
  24:  */
  25: public interface Datatype {
  26:     
  27:     /**
  28:      * Checks if the specified 'literal' matches this Datatype
  29:      * with respect to the current context.
  30:      * 
  31:      * @param literal
  32:      *        the lexical representation to be checked.
  33:      * @param context
  34:      *        If this datatype is context-dependent
  35:      *        (i.e. the {@link #isContextDependent} method returns true),
  36:      *        then the caller must provide a non-null valid context object.
  37:      *        Otherwise, the caller can pass null.
  38:      * 
  39:      * @return
  40:      *        true if the 'literal' is a member of this Datatype;
  41:      *        false if it's not a member of this Datatype.
  42:      */
  43:     boolean isValid( String literal, ValidationContext context );
  44:     
  45:     /**
  46:      * Similar to the isValid method but throws an exception with diagnosis
  47:      * in case of errors.
  48:      * 
  49:      * <p>
  50:      * If the specified 'literal' is a valid lexical representation for this
  51:      * datatype, then this method must return without throwing any exception.
  52:      * If not, the callee must throw an exception (with diagnosis message,
  53:      * if possible.)
  54:      * 
  55:      * <p>
  56:      * The application can use this method to provide detailed error message
  57:      * to users. This method is kept separate from the isValid method to
  58:      * achieve higher performance during normal validation.
  59:      * 
  60:      * @exception DatatypeException
  61:      *        If the given literal is invalid, then this exception is thrown.
  62:      *        If the callee supports error diagnosis, then the exception should
  63:      *        contain a diagnosis message.
  64:      */
  65:     void checkValid( String literal, ValidationContext context )
  66:         throws DatatypeException;
  67:     
  68:     /**
  69:      * Creates an instance of a streaming validator for this type.
  70:      * 
  71:      * <p>
  72:      * By using streaming validators instead of the isValid method,
  73:      * the caller can avoid keeping the entire string, which is
  74:      * sometimes quite big, in memory.
  75:      * 
  76:      * @param context
  77:      *        If this datatype is context-dependent
  78:      *        (i.e. the {@link #isContextDependent} method returns true),
  79:      *        then the caller must provide a non-null valid context object.
  80:      *        Otherwise, the caller can pass null.
  81:      *        The callee may keep a reference to this context object
  82:      *        only while the returned streaming validator is being used.
  83:      */
  84:     DatatypeStreamingValidator createStreamingValidator( ValidationContext context );
  85:     
  86:     /**
  87:      * Converts lexcial value and the current context to the corresponding
  88:      * value object.
  89:      * 
  90:      * <p>
  91:      * The caller cannot generally assume that the value object is
  92:      * a meaningful Java object. For example, the caller cannot expect
  93:      * this method to return <code>java.lang.Number</code> type for
  94:      * the "integer" type of XML Schema Part 2.
  95:      * 
  96:      * <p>
  97:      * Also, the caller cannot assume that the equals method and
  98:      * the hashCode method of the value object are consistent with
  99:      * the semantics of the datatype. For that purpose, the sameValue
 100:      * method and the valueHashCode method have to be used. Note that
 101:      * this means you cannot use classes like
 102:      * <code>java.util.Hashtable</code> to store the value objects.
 103:      * 
 104:      * <p>
 105:      * The returned value object should be used solely for the sameValue
 106:      * and valueHashCode methods.
 107:      * 
 108:      * @param context
 109:      *        If this datatype is context-dependent
 110:      *        (when the {@link #isContextDependent} method returns true),
 111:      *        then the caller must provide a non-null valid context object.
 112:      *        Otherwise, the caller can pass null.
 113:      * 
 114:      * @return    null
 115:      *        when the given lexical value is not a valid lexical
 116:      *        value for this type.
 117:      */
 118:     Object createValue( String literal, ValidationContext context );
 119:     
 120:     /**
 121:      * Tests the equality of two value objects which were originally
 122:      * created by the createValue method of this object.
 123:      * 
 124:      * The behavior is undefined if objects not created by this type
 125:      * are passed. It is the caller's responsibility to ensure that
 126:      * value objects belong to this type.
 127:      * 
 128:      * @return
 129:      *        true if two value objects are considered equal according to
 130:      *        the definition of this datatype; false if otherwise.
 131:      */
 132:     boolean sameValue( Object value1, Object value2 );
 133:     
 134:     
 135:     /**
 136:      * Computes the hash code for a value object,
 137:      * which is consistent with the sameValue method.
 138:      * 
 139:      * @return
 140:      *        hash code for the specified value object.
 141:      */
 142:     int valueHashCode( Object value );
 143: 
 144: 
 145: 
 146:     
 147:     /**
 148:      * Indicates that the datatype doesn't have ID/IDREF semantics.
 149:      * 
 150:      * This value is one of the possible return values of the
 151:      * {@link #getIdType} method.
 152:      */
 153:     public static final int ID_TYPE_NULL = 0;
 154:     
 155:     /**
 156:      * Indicates that RELAX NG compatibility processors should
 157:      * treat this datatype as having ID semantics.
 158:      * 
 159:      * This value is one of the possible return values of the
 160:      * {@link #getIdType} method.
 161:      */
 162:     public static final int ID_TYPE_ID = 1;
 163:     
 164:     /**
 165:      * Indicates that RELAX NG compatibility processors should
 166:      * treat this datatype as having IDREF semantics.
 167:      * 
 168:      * This value is one of the possible return values of the
 169:      * {@link #getIdType} method.
 170:      */
 171:     public static final int ID_TYPE_IDREF = 2;
 172:     
 173:     /**
 174:      * Indicates that RELAX NG compatibility processors should
 175:      * treat this datatype as having IDREFS semantics.
 176:      * 
 177:      * This value is one of the possible return values of the
 178:      * {@link #getIdType} method.
 179:      */
 180:     public static final int ID_TYPE_IDREFS = 3;
 181:     
 182:     /**
 183:      * Checks if the ID/IDREF semantics is associated with this
 184:      * datatype.
 185:      * 
 186:      * <p>
 187:      * This method is introduced to support the RELAX NG DTD
 188:      * compatibility spec. (Of course it's always free to use
 189:      * this method for other purposes.)
 190:      * 
 191:      * <p>
 192:      * If you are implementing a datatype library and have no idea about
 193:      * the "RELAX NG DTD compatibility" thing, just return
 194:      * <code>ID_TYPE_NULL</code> is fine.
 195:      * 
 196:      * @return
 197:      *        If this datatype doesn't have any ID/IDREF semantics,
 198:      *        it returns {@link #ID_TYPE_NULL}. If it has such a semantics
 199:      *        (for example, XSD:ID, XSD:IDREF and comp:ID type), then
 200:      *        it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or
 201:      *        {@link #ID_TYPE_IDREFS}.
 202:      */
 203:     public int getIdType();
 204:     
 205:     
 206:     /**
 207:      * Checks if this datatype may need a context object for
 208:      * the validation.
 209:      * 
 210:      * <p>
 211:      * The callee must return true even when the context
 212:      * is not always necessary. (For example, the "QName" type
 213:      * doesn't need a context object when validating unprefixed
 214:      * string. But nonetheless QName must return true.)
 215:      * 
 216:      * <p>
 217:      * XSD's <code>string</code> and <code>short</code> types
 218:      * are examples of context-independent datatypes.
 219:      * Its <code>QName</code> and <code>ENTITY</code> types
 220:      * are examples of context-dependent datatypes.
 221:      * 
 222:      * <p>
 223:      * When a datatype is context-independent, then
 224:      * the {@link #isValid} method, the {@link #checkValid} method,
 225:      * the {@link #createStreamingValidator} method and
 226:      * the {@link #createValue} method can be called without
 227:      * providing a context object.
 228:      * 
 229:      * @return
 230:      *        <b>true</b> if this datatype is context-dependent
 231:      *        (it needs a context object sometimes);
 232:      * 
 233:      *        <b>false</b> if this datatype is context-<b>in</b>dependent
 234:      *        (it never needs a context object).
 235:      */
 236:     public boolean isContextDependent();
 237: }