1/* 2 * Copyright (c) 2005, 2010, Thai Open Source Software Center Ltd 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are 7 * met: 8 * 9 * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in 14 * the documentation and/or other materials provided with the 15 * distribution. 16 * 17 * Neither the name of the Thai Open Source Software Center Ltd nor 18 * the names of its contributors may be used to endorse or promote 19 * products derived from this software without specific prior written 20 * permission. 21 * 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 25 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR 26 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 27 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 28 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33 */ 34 35package com.sun.xml.internal.org.relaxng.datatype; 36 37/** 38 * Datatype object. 39 * 40 * This object has the following functionality: 41 * 42 * <ol> 43 * <li> functionality to identify a class of character sequences. This is 44 * done through the isValid method. 45 * 46 * <li> functionality to produce a "value object" from a character sequence and 47 * context information. 48 * 49 * <li> functionality to test the equality of two value objects. 50 * </ol> 51 * 52 * This interface also defines the createStreamingValidator method, 53 * which is intended to efficiently support the validation of 54 * large character sequences. 55 * 56 * @author <a href="mailto:jjc@jclark.com">James Clark</a> 57 * @author <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a> 58 */ 59public interface Datatype { 60 61 /** 62 * Checks if the specified 'literal' matches this Datatype 63 * with respect to the current context. 64 * 65 * @param literal 66 * the lexical representation to be checked. 67 * @param context 68 * If this datatype is context-dependent 69 * (i.e. the {@link #isContextDependent} method returns true), 70 * then the caller must provide a non-null valid context object. 71 * Otherwise, the caller can pass null. 72 * 73 * @return 74 * true if the 'literal' is a member of this Datatype; 75 * false if it's not a member of this Datatype. 76 */ 77 boolean isValid( String literal, ValidationContext context ); 78 79 /** 80 * Similar to the isValid method but throws an exception with diagnosis 81 * in case of errors. 82 * 83 * <p> 84 * If the specified 'literal' is a valid lexical representation for this 85 * datatype, then this method must return without throwing any exception. 86 * If not, the callee must throw an exception (with diagnosis message, 87 * if possible.) 88 * 89 * <p> 90 * The application can use this method to provide detailed error message 91 * to users. This method is kept separate from the isValid method to 92 * achieve higher performance during normal validation. 93 * 94 * @exception DatatypeException 95 * If the given literal is invalid, then this exception is thrown. 96 * If the callee supports error diagnosis, then the exception should 97 * contain a diagnosis message. 98 */ 99 void checkValid( String literal, ValidationContext context ) 100 throws DatatypeException; 101 102 /** 103 * Creates an instance of a streaming validator for this type. 104 * 105 * <p> 106 * By using streaming validators instead of the isValid method, 107 * the caller can avoid keeping the entire string, which is 108 * sometimes quite big, in memory. 109 * 110 * @param context 111 * If this datatype is context-dependent 112 * (i.e. the {@link #isContextDependent} method returns true), 113 * then the caller must provide a non-null valid context object. 114 * Otherwise, the caller can pass null. 115 * The callee may keep a reference to this context object 116 * only while the returned streaming validator is being used. 117 */ 118 DatatypeStreamingValidator createStreamingValidator( ValidationContext context ); 119 120 /** 121 * Converts lexcial value and the current context to the corresponding 122 * value object. 123 * 124 * <p> 125 * The caller cannot generally assume that the value object is 126 * a meaningful Java object. For example, the caller cannot expect 127 * this method to return <code>java.lang.Number</code> type for 128 * the "integer" type of XML Schema Part 2. 129 * 130 * <p> 131 * Also, the caller cannot assume that the equals method and 132 * the hashCode method of the value object are consistent with 133 * the semantics of the datatype. For that purpose, the sameValue 134 * method and the valueHashCode method have to be used. Note that 135 * this means you cannot use classes like 136 * <code>java.util.Hashtable</code> to store the value objects. 137 * 138 * <p> 139 * The returned value object should be used solely for the sameValue 140 * and valueHashCode methods. 141 * 142 * @param context 143 * If this datatype is context-dependent 144 * (when the {@link #isContextDependent} method returns true), 145 * then the caller must provide a non-null valid context object. 146 * Otherwise, the caller can pass null. 147 * 148 * @return null 149 * when the given lexical value is not a valid lexical 150 * value for this type. 151 */ 152 Object createValue( String literal, ValidationContext context ); 153 154 /** 155 * Tests the equality of two value objects which were originally 156 * created by the createValue method of this object. 157 * 158 * The behavior is undefined if objects not created by this type 159 * are passed. It is the caller's responsibility to ensure that 160 * value objects belong to this type. 161 * 162 * @return 163 * true if two value objects are considered equal according to 164 * the definition of this datatype; false if otherwise. 165 */ 166 boolean sameValue( Object value1, Object value2 ); 167 168 169 /** 170 * Computes the hash code for a value object, 171 * which is consistent with the sameValue method. 172 * 173 * @return 174 * hash code for the specified value object. 175 */ 176 int valueHashCode( Object value ); 177 178 179 180 181 /** 182 * Indicates that the datatype doesn't have ID/IDREF semantics. 183 * 184 * This value is one of the possible return values of the 185 * {@link #getIdType} method. 186 */ 187 public static final int ID_TYPE_NULL = 0; 188 189 /** 190 * Indicates that RELAX NG compatibility processors should 191 * treat this datatype as having ID semantics. 192 * 193 * This value is one of the possible return values of the 194 * {@link #getIdType} method. 195 */ 196 public static final int ID_TYPE_ID = 1; 197 198 /** 199 * Indicates that RELAX NG compatibility processors should 200 * treat this datatype as having IDREF semantics. 201 * 202 * This value is one of the possible return values of the 203 * {@link #getIdType} method. 204 */ 205 public static final int ID_TYPE_IDREF = 2; 206 207 /** 208 * Indicates that RELAX NG compatibility processors should 209 * treat this datatype as having IDREFS semantics. 210 * 211 * This value is one of the possible return values of the 212 * {@link #getIdType} method. 213 */ 214 public static final int ID_TYPE_IDREFS = 3; 215 216 /** 217 * Checks if the ID/IDREF semantics is associated with this 218 * datatype. 219 * 220 * <p> 221 * This method is introduced to support the RELAX NG DTD 222 * compatibility spec. (Of course it's always free to use 223 * this method for other purposes.) 224 * 225 * <p> 226 * If you are implementing a datatype library and have no idea about 227 * the "RELAX NG DTD compatibility" thing, just return 228 * <code>ID_TYPE_NULL</code> is fine. 229 * 230 * @return 231 * If this datatype doesn't have any ID/IDREF semantics, 232 * it returns {@link #ID_TYPE_NULL}. If it has such a semantics 233 * (for example, XSD:ID, XSD:IDREF and comp:ID type), then 234 * it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or 235 * {@link #ID_TYPE_IDREFS}. 236 */ 237 public int getIdType(); 238 239 240 /** 241 * Checks if this datatype may need a context object for 242 * the validation. 243 * 244 * <p> 245 * The callee must return true even when the context 246 * is not always necessary. (For example, the "QName" type 247 * doesn't need a context object when validating unprefixed 248 * string. But nonetheless QName must return true.) 249 * 250 * <p> 251 * XSD's <code>string</code> and <code>short</code> types 252 * are examples of context-independent datatypes. 253 * Its <code>QName</code> and <code>ENTITY</code> types 254 * are examples of context-dependent datatypes. 255 * 256 * <p> 257 * When a datatype is context-independent, then 258 * the {@link #isValid} method, the {@link #checkValid} method, 259 * the {@link #createStreamingValidator} method and 260 * the {@link #createValue} method can be called without 261 * providing a context object. 262 * 263 * @return 264 * <b>true</b> if this datatype is context-dependent 265 * (it needs a context object sometimes); 266 * 267 * <b>false</b> if this datatype is context-<b>in</b>dependent 268 * (it never needs a context object). 269 */ 270 public boolean isContextDependent(); 271} 272