lib/classpath/external/relaxngDatatype/org/relaxng/datatype/Datatype.java

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