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
|
<!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN">
<!-- Copyright 2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. -->
<html>
<head>
<!-- InstanceBeginEditable name="doctitle" -->
<title>Understanding XML Tokens</title>
<!-- InstanceEndEditable -->
<!--(Meta)==========================================================-->
<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
<!-- InstanceBeginEditable name="metatags" -->
<meta name="component" content="">
<!-- In the description metatag, please provide a BRIEF description of the topic contents. -->
<meta name="description" content="">
<!-- In the component metatag, please list keywords that will help a user search for this topic. -->
<meta name="keywords" content="">
<!-- InstanceEndEditable -->
<!--(Links)=========================================================-->
<!-- InstanceBeginEditable name="head" -->
<!-- InstanceEndEditable -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
<a href="../../../core/index.html" id="index"></a>
<script language="JavaScript" src="../../../core/topicInfo.js"></script>
<script language="JavaScript" src="../../../core/CookieClass.js"></script>
<script language="JavaScript" src="../../../core/displayContent.js"></script>
</head>
<!--(Body)==========================================================-->
<body>
<script language="JavaScript">
</script>
<!-- InstanceBeginEditable name="body" -->
<div id=topictitle>
<p class=Title>Understanding XML Tokens</p>
</div>
<div id=topictext>
<p>An XML cursor (an instance of the <a href="../reference/org/apache/xmlbeans/XmlCursor.html"><span class="langinline">XmlCursor</span></a>
interface) moves from token to token as your code moves the cursor. When you
move a cursor using a method such as <span class="langinline">toParent</span>,
<span class="langinline">toFirstAttribute</span>, <span class="langinline">toPrevSibling</span>,
and so on, the cursor moves to the token fitting the description. If there
is no appropriate token to move to, the cursor remains where it is, and <span class="langinline">false</span>
is returned to indicate that it didn't move. For example, if the cursor is
at the ENDDOC token (the last tag in the document), a call to the <span class="langinline">toNextSibling</span>
method will not move the cursor and will return <span class="langinline">false</span>
to indicate that the move was unsuccessful.</p>
<p>Note that while you can call the <span class="langinline">XmlCursor.currentTokenType</span>
method to find out which token type the cursor is at, you might find it more
convenient to use a method such as <span class="langinline">isEnddoc</span>.
The <span class="langinline">XmlCursor</span> interface provides several methods
that make it easy to discover whether the cursor you're moving is at the token
you're looking for. These methods, such as <span class="langinline">isStart</span>,
<span class="langinline">isAttr</span>, <span class="langinline">isText</span>,
and so on, return a <span class="langinline">boolean</span> value that indicates
whether the cursor is at the token type in question.</p>
<P>Tokens are represented by constants in the <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlCursor.TokenType.html">TokenType</a></span>
class, an inner class of the <span class="langinline">XmlCursor</span> interface.
Each has a constant you can use in switch statements to perform by-token actions.
The following table lists the token types:</P>
<TABLE id="Table1">
<TR>
<TD><STRONG>Token Type</STRONG></TD>
<TD><STRONG>Switch Constant</STRONG></TD>
<TD><STRONG>Description</STRONG></TD>
</TR>
<TR>
<TD>STARTDOC</TD>
<TD>INT_STARTDOC</TD>
<TD>Represents the start of the XML. Always the first token. The document
element itself is represented by a START token, not the STARTDOC token.</TD>
</TR>
<TR>
<TD>ENDDOC </TD>
<TD>INT_ENDDOC</TD>
<TD>Represents the end of the XML. Always the last token.</TD>
</TR>
<TR>
<TD>START </TD>
<TD>INT_START</TD>
<TD>Represents the start of an element.</TD>
</TR>
<TR>
<TD>END </TD>
<TD>INT_END</TD>
<TD>Represents the end of an element. The END token has no value, but marks
the element's end.</TD>
</TR>
<TR>
<TD>TEXT</TD>
<TD>INT_TEXT</TD>
<TD>Represents text.</TD>
</TR>
<TR>
<TD>ATTR </TD>
<TD>INT_ATTR</TD>
<TD>Represents an attribute. ATTR tokens are allowed to appear after a STARTDOC
or START token.</TD>
</TR>
<TR>
<TD>NAMESPACE</TD>
<TD>INT_NAMESPACE</TD>
<TD>Represents a namespace (xmlns) attribute. Also only allowed after START
or STARTDOC tokens.</TD>
</TR>
<TR>
<TD>COMMENT </TD>
<TD>INT_COMMENT</TD>
<TD>Represents a comment.</TD>
</TR>
<TR>
<TD>PROCINST </TD>
<TD>INT_PROCINST</TD>
<TD>Represents a processing instruction.</TD>
</TR>
</TABLE>
<P>As you use a cursor to navigate through XML, you can use one of the convenience
methods described above to discover whether you're at the token you're looking
for, or use the <span class="langinline">XmlCursor.currentTokenType</span> method
to discover the current token's type. The following figure illustrates example
locations for token types:</P>
<P><IMG src="../images/conCursorTokenLocations.gif" width="727" height="532">
<h2>Switching to Test for Token Types</h2>
<p>Here's a bit of code illustrating how you might use a Java <span class="langinline">switch</span>
statement to test for the START token type.</p>
<pre>
// Take an incoming XmlObject and insert a cursor.
XmlCursor documentCursor = xmlDoc.newCursor();
/*
* Loop through the document, passing the cursor when it stops at each token
* to a function designed to discover the token type. Continue the loop
* as long at the cursor is at a token (until it reaches the end).
*/
while (!documentCursor.toNextToken().isNone())
{
/*
* Use the intValue method to return the int corresponding to the
* current token type. If it is the value for INT_START,
* then you have a match.
*/
switch (cursor.currentTokenType().intValue())
{
case TokenType.INT_START:
// Print out the token type and a message.
System.out.println(cursor.currentTokenType() +
"; cursor is at the start of an element.");
break;
}
}
// Be sure to dispose of a cursor when you're finished.
documentCursor.dispose();
</pre>
<p>The scope of an XML cursor is the XML document in which it is created. For
example, you can create a cursor at the orderItem element in the example earlier
in this topic. If you then use that <span class="langinline">XmlCursor</span>
instance's <span class="langinline">toNextToken</span> method to move the
cursor until it won't move any further, you'll have reached the ENDDOC token.
In this example, that's at the <span class="langinline"></batchWidgetOrder></span>
tag. In other words, the cursor's scope is not limited to the element at which
it was created.</p>
<p class=relatedtopics>Related Topics</p>
<p><a href="../reference/org/apache/xmlbeans/XmlCursor.TokenType.html">XmlCursor.TokenType
Class</a></p>
<p><a href="conNavigatingXMLwithCursors.html">Navigating XML with Cursors</a></p>
</div>
<!-- InstanceEndEditable -->
<script language="JavaScript">
</script>
</body>
</html>
|
