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 */ isValid( String literal, ValidationContext context )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 */ checkValid( String literal, ValidationContext context )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 */ createStreamingValidator( ValidationContext context )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 */ createValue( String literal, ValidationContext context )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 */ sameValue( Object value1, Object value2 )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 */ valueHashCode( Object value )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 */ getIdType()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 */ isContextDependent()236 public boolean isContextDependent(); 237 } 238