v1/docs/guide/conUnderstandingXMLTokens.html - xmlbeans - Git at Google

 <!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN">

 <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>&nbsp;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">&lt;/batchWidgetOrder&gt;</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>
	<!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN">

	<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>