| Frames | No Frames |
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: }