API Overview API Index Package Overview Direct link to this page
JDK 1.6
  org.relaxng.datatype. Datatype View Javadoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238

font color='#880088'>
package org.relaxng.datatype;

/**
 * Datatype object.
 * 
 * This object has the following functionality:
 * 
 * <ol>
 *  <li> functionality to identify a class of character sequences. This is
 *       done through the isValid method.
 * 
 *  <li> functionality to produce a "value object" from a character sequence and
 *		 context information.
 * 
 *  <li> functionality to test the equality of two value objects.
 * </ol>
 * 
 * This interface also defines the createStreamingValidator method,
 * which is intended to efficiently support the validation of
 * large character sequences.
 * 
 * @author <a href="mailto:jjc@jclark.com">James Clark</a>
 * @author <a href="mailto:kohsuke.kawaguchi@sun.com">Kohsuke KAWAGUCHI</a>
 */
public interface Datatype {
	
	/**
	 * Checks if the specified 'literal' matches this Datatype
	 * with respect to the current context.
	 * 
	 * @param literal
	 *		the lexical representation to be checked.
	 * @param context
	 *		If this datatype is context-dependent
	 *		(i.e. the {@link #isContextDependent} method returns true),
	 *		then the caller must provide a non-null valid context object.
	 *		Otherwise, the caller can pass null.
	 * 
	 * @return
	 *		true if the 'literal' is a member of this Datatype;
	 *		false if it's not a member of this Datatype.
	 */
	boolean isValid( String literal, ValidationContext context );
	
	/**
	 * Similar to the isValid method but throws an exception with diagnosis
	 * in case of errors.
	 * 
	 * <p>
	 * If the specified 'literal' is a valid lexical representation for this
	 * datatype, then this method must return without throwing any exception.
	 * If not, the callee must throw an exception (with diagnosis message,
	 * if possible.)
	 * 
	 * <p>
	 * The application can use this method to provide detailed error message
	 * to users. This method is kept separate from the isValid method to
	 * achieve higher performance during normal validation.
	 * 
	 * @exception DatatypeException
	 *		If the given literal is invalid, then this exception is thrown.
	 *		If the callee supports error diagnosis, then the exception should
	 *		contain a diagnosis message.
	 */
	void checkValid( String literal, ValidationContext context )
		throws DatatypeException;
	
	/**
	 * Creates an instance of a streaming validator for this type.
	 * 
	 * <p>
	 * By using streaming validators instead of the isValid method,
	 * the caller can avoid keeping the entire string, which is
	 * sometimes quite big, in memory.
	 * 
	 * @param context
	 *		If this datatype is context-dependent
	 *		(i.e. the {@link #isContextDependent} method returns true),
	 *		then the caller must provide a non-null valid context object.
	 *		Otherwise, the caller can pass null.
	 *		The callee may keep a reference to this context object
	 *		only while the returned streaming validator is being used.
	 */
	DatatypeStreamingValidator createStreamingValidator( ValidationContext context );
	
	/**
	 * Converts lexcial value and the current context to the corresponding
	 * value object.
	 * 
	 * <p>
	 * The caller cannot generally assume that the value object is
	 * a meaningful Java object. For example, the caller cannot expect
	 * this method to return <code>java.lang.Number</code> type for
	 * the "integer" type of XML Schema Part 2.
	 * 
	 * <p>
	 * Also, the caller cannot assume that the equals method and
	 * the hashCode method of the value object are consistent with
	 * the semantics of the datatype. For that purpose, the sameValue
	 * method and the valueHashCode method have to be used. Note that
	 * this means you cannot use classes like
	 * <code>java.util.Hashtable</code> to store the value objects.
	 * 
	 * <p>
	 * The returned value object should be used solely for the sameValue
	 * and valueHashCode methods.
	 * 
	 * @param context
	 *		If this datatype is context-dependent
	 *		(when the {@link #isContextDependent} method returns true),
	 *		then the caller must provide a non-null valid context object.
	 *		Otherwise, the caller can pass null.
	 * 
	 * @return	null
	 *		when the given lexical value is not a valid lexical
	 *		value for this type.
	 */
	Object createValue( String literal, ValidationContext context );
	
	/**
	 * Tests the equality of two value objects which were originally
	 * created by the createValue method of this object.
	 * 
	 * The behavior is undefined if objects not created by this type
	 * are passed. It is the caller's responsibility to ensure that
	 * value objects belong to this type.
	 * 
	 * @return
	 *		true if two value objects are considered equal according to
	 *		the definition of this datatype; false if otherwise.
	 */
	boolean sameValue( Object value1, Object value2 );
	
	
	/**
	 * Computes the hash code for a value object,
	 * which is consistent with the sameValue method.
	 * 
	 * @return
	 *		hash code for the specified value object.
	 */
	int valueHashCode( Object value );



	
	/**
	 * Indicates that the datatype doesn't have ID/IDREF semantics.
	 * 
	 * This value is one of the possible return values of the
	 * {@link #getIdType} method.
	 */
	public static final int ID_TYPE_NULL = 0;
	
	/**
	 * Indicates that RELAX NG compatibility processors should
	 * treat this datatype as having ID semantics.
	 * 
	 * This value is one of the possible return values of the
	 * {@link #getIdType} method.
	 */
	public static final int ID_TYPE_ID = 1;
	
	/**
	 * Indicates that RELAX NG compatibility processors should
	 * treat this datatype as having IDREF semantics.
	 * 
	 * This value is one of the possible return values of the
	 * {@link #getIdType} method.
	 */
	public static final int ID_TYPE_IDREF = 2;
	
	/**
	 * Indicates that RELAX NG compatibility processors should
	 * treat this datatype as having IDREFS semantics.
	 * 
	 * This value is one of the possible return values of the
	 * {@link #getIdType} method.
	 */
	public static final int ID_TYPE_IDREFS = 3;
	
	/**
	 * Checks if the ID/IDREF semantics is associated with this
	 * datatype.
	 * 
	 * <p>
	 * This method is introduced to support the RELAX NG DTD
	 * compatibility spec. (Of course it's always free to use
	 * this method for other purposes.)
	 * 
	 * <p>
	 * If you are implementing a datatype library and have no idea about
	 * the "RELAX NG DTD compatibility" thing, just return
	 * <code>ID_TYPE_NULL</code> is fine.
	 * 
	 * @return
	 *		If this datatype doesn't have any ID/IDREF semantics,
	 *		it returns {@link #ID_TYPE_NULL}. If it has such a semantics
	 *		(for example, XSD:ID, XSD:IDREF and comp:ID type), then
	 *		it returns {@link #ID_TYPE_ID}, {@link #ID_TYPE_IDREF} or
	 *		{@link #ID_TYPE_IDREFS}.
	 */
	public int getIdType();
	
	
	/**
	 * Checks if this datatype may need a context object for
	 * the validation.
	 * 
	 * <p>
	 * The callee must return true even when the context
	 * is not always necessary. (For example, the "QName" type
	 * doesn't need a context object when validating unprefixed
	 * string. But nonetheless QName must return true.)
	 * 
	 * <p>
	 * XSD's <code>string</code> and <code>short</code> types
	 * are examples of context-independent datatypes.
	 * Its <code>QName</code> and <code>ENTITY</code> types
	 * are examples of context-dependent datatypes.
	 * 
	 * <p>
	 * When a datatype is context-independent, then
	 * the {@link #isValid} method, the {@link #checkValid} method,
	 * the {@link #createStreamingValidator} method and
	 * the {@link #createValue} method can be called without
	 * providing a context object.
	 * 
	 * @return
	 *		<b>true</b> if this datatype is context-dependent
	 *		(it needs a context object sometimes);
	 * 
	 *		<b>false</b> if this datatype is context-<b>in</b>dependent
	 *		(it never needs a context object).
	 */
	public boolean isContextDependent();
}

Generated By: JavaOnTracks Doclet 0.1.4     ©Thibaut Colar