5543eb9de8
git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1824563 13f79535-47bb-0310-9956-ffa450edef68
190 lines
8.0 KiB
HTML
190 lines
8.0 KiB
HTML
<!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>
|