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
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<meta http-equiv="CONTENT-TYPE" content="text/html; charset=iso-8859-1">
<title>Using the Sun[TM] XML Datatypes Library</title>
</head>
<!-- $Id: HowToUse.html 1549 2003-04-28 19:06:50Z kk122374 $ -->
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#dddddd">
<tr>
<td align="center" valign="middle">
<table width="100%" border="1" cellspacing="3" cellpadding="3" height="100%">
<tr>
<td valign="top" bgcolor="#FFFFFF">
<h1>Using the Sun<small><sup>TM</sup></small> XML Datatypes Library</h1>
</td>
<td rowspan="2" align="center" valign="middle" bgcolor="#dddddd">
<p><strong>Version @@VERSION@@</strong></p>
<p><a href="mailto:kohsuke.kawaguchi@eng.sun.com"><strong>Kohsuke KAWAGUCHI</strong></a></p>
</td>
<td rowspan="2" align="right" valign="middle" bgcolor="#FFFFFF" nowrap><small><em>Copyright © 2001-@@YEAR@@</em></small><br>
<small><em>Sun Microsystems, Inc.</em></small><br>
<small><em>All Rights Reserved</em></small></td>
</tr>
<tr>
<td align="left" valign="top" bgcolor="#FFFFFF">
<h2><font color="#0000FF"><em>Sun's Java<small><sup>TM</sup></small> Technology Implementation of XML Schema Part 2</em></font></h2>
</td>
</tr>
</table>
</td>
</tr>
</table>
<blockquote>
<p>The Sun XML Datatypes Library, Sun's Java<small><sup>TM</sup></small> technology implementation of <a href="http://www.w3.org/TR/xmlschema-2/">XML Schema Part 2</a>, is intended for use with applications that incorporate XML Schema Part 2.</p>
</blockquote>
<h2><font color="#0000FF">Contents</font></h2>
<ul>
<li><a href="#intro">Introduction</a></li>
<li><a href="#derivation">Deriving A New Type</a></li>
<li><a href="#diagnosis">Diagnosing Errors</a></li>
<li><a href="#limits">Known Limitations</a></li>
<li><a href="#misc">Miscellaneous Notes</a></li>
</ul>
<hr>
<blockquote>
<table width="85%" cellspacing="3" cellpadding="3">
<tr align="left" valign="top">
<td><strong>Note:</strong></td>
<td><em>This distribution of the XML Datatypes Library includes a sample class file, <code>src/com/sun/tranquilo/datatype/CommandLineTester.java</code>, which is provided as a guide for implementing your own Java classes with the Datatypes Library. </em></td>
</tr>
</table>
</blockquote>
<hr>
<h2><a name="intro"></a><font color="#0000FF">Introduction: Validating Strings</font></h2>
<blockquote>
<p>The following example validates a string with integer datatype. The <code>getTypeByName</code> method lets you obtain a reference to a built-in datatype.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
<tr>
<td bgcolor="#eeeeee">
<pre>import com.sun.msv.datatype.xsd.XSDatatype;
void f( String v ) {
// obtain a type object
XSDatatype dt = DatatypeFactory.getTypeByName("integer");
// validates a type
if( dt.isValid(v,null) )
; // v is a valid integer
else
; // v is not a valid integer
}</pre>
</td>
</tr>
</table>
<hr>
<p>
Some datatypes require context information to validate. For example, the <code>QName</code> type, which validates something like <code>prefix:localPart</code>, needs to know that the given prefix is properly declared. This information must be supplied to <code>Datatype</code> object by the caller. To do this, the caller must provide an object that implements the <code>ValidationContext</code> interface and pass it as the second parameter of the verify method.
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
<tr>
<td bgcolor="#eeeeee">
<pre>import org.relaxng.datatype.ValidationContext;
class MyContext implements ValidationContext
{
String resolveNamespacePrefix( String prefix ) {
// resolves namespace prefix to namespace URI.
}
boolean isUnparsedEntity( String entityName ) {
// checks if given name is a valid entity name.
}
...
}
void f( String v, MyContext context ) {
// obtain a type object
XSDatatype dt = DatatypeFactory.getTypeByName("QName");
// validates a type
if( dt.isValid(v,context) )
; // v is a valid QName
else
; // v is not a valid QName
}</pre>
</td></tr>
</table>
<hr>
<p>When the datatype is "context-dependent", the caller must provide a valid <code>ValidationContext</code>, as in the second example. For other datatypes, the caller can pass null, as in the first example. Use the <code>isContextDependent</code> method to check if a datatype is context dependent or not.</p>
</blockquote>
<hr>
<h2><a name="derivation"></a><font color="#0000FF">Deriving A New Type</font></h2>
<h3><em><font color="#0000FF">By List</font></em></h3>
<blockquote>
<p>The following example derives a new type from an existing <code>XSDatatype</code> object by list.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
<tr>
<td bgcolor="#eeeeee">
<pre>XSDatatype deriveByList( XSDatatype itemType ) throws DatatypeException {
return DatatypeFactory.deriveByList("","myType",itemType);
}</pre>
</td>
</tr>
</table>
<hr>
<p>The first two parameters specifiy the namespace URI and the local name of the newly created type.
<p>When an error is found during derivation, a <code>org.relaxng.datatype.DatatypeException</code> will be thrown. For example, if you derive a type by list from another list type, an exception will be thrown.</p>
</blockquote>
<h3><em><font color="#0000FF">By Union</font></em></h3>
<blockquote>
<p>The following example derives a new type from existing <code>XSDatatype</code> objects by union.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
<tr>
<td bgcolor="#eeeeee">
<pre>XSDatatype deriveByUnion( XSDatatype[] memberTypes ) throws DatatypeException {
return DatatypeFactory.deriveByUnion("","myType",memberTypes);
}</pre>
</td>
</tr>
</table>
<hr>
</blockquote>
<h3><em><font color="#0000FF">By Restriction</font></em></h3>
<blockquote>
<p>The following example derives a new type by adding facets.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
<tr>
<td bgcolor="#eeeeee">
<pre>XSDatatype f() throws DatatypeException {
XSDatatype baseType = DatatypeFactory.getTypeByName("string");
// create a type incubator with the base type
TypeIncubator incubator = new TypeIncubator(baseType);
// add facets
incubator.addFacet( "minLength", "5", false, null );
incubator.addFacet( "maxLength", "20", false, null );
// derive a new type by those facets
XSDatatype derived = incubator.derive("","newTypeName");
return derived;
}</pre>
</td>
</tr>
</table>
<hr>
<p>The third parameter to the addFacet method specifies whether that facet should be "fixed" or not. Once a facet is fixed, a derived type can no longer restrict that facet.</p>
<p>The fourth parameter is again <code>ValidationContext</code>, which is sometimes necessary (imagine adding an enumeration facet to QName.) The above example does not supply one since we know the base type is a context independent datatype, but in general the caller should supply an object that implements <code>ValidationContext</code>.</p>
<p><code>DatatypeException</code> can be thrown when you add a facet, or when you call the derive method.</p>
</blockquote>
<hr>
<h2><a name="diagnosis"></a><font color="#0000FF">Diagnosing Errors</font></h2>
<blockquote>
<p>The following example provides a diagnostic message to users about what is wrong with their value.</p>
<hr>
<table border="0" cellspacing="5" cellpadding="5" bgcolor="#eeeeee">
<tr>
<td bgcolor="#eeeeee">
<pre>void test( XSDatatype dt, String v, ValidationContext context ) {
try {
dt.checkValid(v,context);
System.out.println("valid");
} catch( DatatypeException e ) {
if( d.getMessage()==null )
System.out.println("invalid: diagnosis not supported");
else
System.out.println("invalid: "+d.getMessage());
}
}</pre>
</td>
</tr>
</table>
<hr>
<p>In this way, the user gets informative error messages. If the <code>Datatype</code> object does not support diagnosis, the getMessage method returns null. It is the caller's responsibility to handle this situation correctly.</p>
</blockquote>
<hr>
<h2><a name="limits"></a><font color="#0000FF">Known Limitations</font></h2>
<ol>
<li>
<p>Types <code>float</code> and <code>double</code>: the spec says a lexical value must be mapped to the closest value in the value space. However, This library cannot accept values that are larger than the maximum value for that type or smaller than the minimum value for that type. This should not be a problem for most users.</p>
</li>
<li>
<p><code>ID</code>, <code>IDREF</code>, and <code>IDREFS</code> types are not implemented. Although uniqueness constraints are removed from Part 2, these types are still intended to be used with uniqueness constraints. These constraints are so special that it is impossible to provide a generic implementation. <code>com.sun.tranquilo.datatype.DatatypeFactory</code> does not recognize these three types.</p>
</li>
<li>
<p><code>NOTATION</code> type is not implemented. <code>com.sun.tranquilo.datatype.DatatypeFactory</code> does not recognize this type.</p>
</li>
<li>
<p><code>length</code>, <code>minLength</code>, and <code>maxLength</code> facets are effectively limited to the value 2147483647. Values above this limit are recognized, but will be treated as this limit. Items larger than this limit will not be validated correctly. This limitation has no practical impact.</p>
</li>
<li>
<p>Regarding <code>length</code> and <code>min/maxLength</code> facets of <code>anyURI</code> the spec does not define what is the unit of length. This version implements <code>length</code> facet as being in units of XML characters in the lexical space.</p>
</li>
<li>
<p>Regarding <code>length</code> and <code>min/maxLength</code> facets of <code>QName</code>: again, the specification does not define the unit of length. This version implements <code>length</code> facet as being in units of XML characters in the value space ( # of chars in namespace URI + local part ). Users are strongly discouraged from applying length-related facets to <code>QName</code> type.</p>
</li>
<li>
<p><code>anyURI</code> (formerly <code>uriReference</code>) is made to accept several IP v6 addresses like <code>::192.168.0.1</code>, which are not accepted by the original BNF specified in RFC 2373. This modification should be considered as a "bug fix." Although the BNF specified in RFC 2373 has several other problems, those are not fixed. For example, the current release accepts <code>1:2:3:4:5:6:7:8:9</code>, which is not a valid IP v6 address.</p>
</li>
<li>
<p><code>language</code> type is implemented in accordance with RFC 1766, and language identifiers are treated in a case-insensitive way. XML SchemaPart 2 says that the lexical space of the language type will be as defined in XML1.0 Recommendation 2nd edition, but that production was thrown away in the 2nd edition. Furthermore, the derivation shown inXML Schema Part 2 does not correctly implement the definition given in RFC 1766, so apparently there is a problem in the definition of the language type. However, by making <code>language</code> case-insensitive, it is no longer a derived type of <code>token</code> type.</p>
</li>
<li>
<p>Regarding <code>base64Binary</code> type, RFC 2045 states that "any characters outside of the base64 alphabet are to be ignored in base64-encoded data." This makes "validation" of <code>base64Binary</code> meaningless. For example, <code><picture>))))</picture></code>; is considered as valid <code>base64Binary</code>. Developers should keep this in mind.</p>
</li>
<li>
<p><code>minInclusive</code>, <code>maxInclusive</code>, <code>minExclusive</code>, and <code>maxExclusive</code> facets of date/time related types do not work properly. XML Schema Part 2 is broken as regards the order relation of these types. This also affects the behavior of the "enumeration" facet (since equality is a part of order-relation). See Kawaguchi's comments to <a href="http://lists.w3.org/Archives/Public/www-xml-schema-comments/">www-xml-schema-comments@w3.org</a> for details (
<a href="http://lists.w3.org/Archives/Public/www-xml-schema-comments/2001JanMar/0365.html">[1]</a>
<a href="http://lists.w3.org/Archives/Public/www-xml-schema-comments/2001JanMar/0366.html">[2]</a>
<a href="http://lists.w3.org/Archives/Public/www-xml-schema-comments/2001JanMar/0367.html">[3]</a> and
<a href="http://lists.w3.org/Archives/Public/www-xml-schema-comments/2001JanMar/0368.html">[4]</a>
).</p>
</li>
</ol>
</body>
</html>
|
