You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlbeans.apache.org by ra...@apache.org on 2005/11/18 21:09:47 UTC
svn commit: r345361 [92/181] - in /xmlbeans/site: build/site/docs/2.1.0/
build/site/docs/2.1.0/guide/ build/site/docs/2.1.0/images/
build/site/docs/2.1.0/reference/ build/site/docs/2.1.0/reference/javax/
build/site/docs/2.1.0/reference/javax/xml/ build...
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conJavaTypesGeneratedFromUserDerived.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conJavaTypesGeneratedFromUserDerived.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conJavaTypesGeneratedFromUserDerived.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conJavaTypesGeneratedFromUserDerived.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,471 @@
+<!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>Java Types Generated from Schema</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" -->
+
+<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
+
+<!--(Meta)==========================================================-->
+
+
+
+<meta name="author" content="your name">
+<meta name="description" content="A description of the topic contents.">
+<meta name="keywords" content="keywords to help in searches">
+<meta name="date last modified" content="10/25/02">
+<!--(Links)=========================================================-->
+<!--(Body)==========================================================--><!-- 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" -->
+<h1> Java Types Generated from User-Derived Schema Types</h1>
+<div id="topictext">
+ <p>When you compile XML schema, the resulting API is made up of two categories
+ of types: built-in types that mirror those in the schema specification and
+ others that are generated from user-derived schema types. This topic provides
+ an overview of the Java types generated for user-derived types, describing
+ the methods the Java types provide. For more information about built-in types,
+ see <a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support for
+ Built-In Schema Types</a>. For specific information about the methods exposed
+ by generated types, see <a href="conMethodsForGeneratedJavaTypes.html">Methods
+ for Generated Java Types</a>.</p>
+ <p>In general, an API generated from schema is an intuitive means to access
+ XML instances based on the schema. You'll probably find that for most uses
+ it's unnecessary to know the rules for generating it in order to use it. However,
+ for those cases when it's unclear what's going on behind the scenes (or if
+ you're just curious), this topic describes the rules.</p>
+ <p class="notepara"><strong>Note:</strong> The XMLBeans API also provides a
+ way for you to get information <em>about </em>the type system itself —
+ in other words, about the API and the underlying schema. For more information,
+ see <a href="conIntroToTheSchemaTypeSystem.html">Introduction to Schema Type
+ Signatures</a>.</p>
+ <p>Each of the types generated when you compile a schema is designed specifically
+ for access to XML instances conforming to that part of the schema. Start by
+ taking a look at a simple XML and schema example. The following schema describes
+ an XML document to contain a stock price quote.</p>
+ <pre><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+ <xs:element name="price-quote">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="stock-symbol" type="xs:string"/>
+ <xs:element name="stock-price" type="xs:float"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+</xs:schema>
+</pre>
+ <p>The following is an example of XML that conforms to this schema.</p>
+ <pre><price-quote>
+ <stock-symbol>BEAS</stock-symbol>
+ <stock-price>59.21</stock-price>
+</price-quote></pre>
+ <p>When you compile this schema, you get two generated XMLBeans interfaces:
+ <span class="langinline"> PriceQuoteDocument</span> and <span class="langinline">PriceQuoteDocument.PriceQuote</span>.</p>
+ <p>From the schema point of view, the generated <span class="langinline">PriceQuote</span>
+ interface represents the <em>complex type</em> you see inside the schema's
+ <span class="langinline">price-quote</span> element declaration. Looking at
+ the XML instance, you can see that this complex type translates into a sequence
+ of two elements, <span class="langinline">stock-symbol</span> and <span class="langinline">stock-price</span>.
+ So it's not surprising that the <span class="langinline">PriceQuote</span>
+ interface exposes methods such as <span class="langinline">getStockPrice</span>
+ and <span class="langinline">setStockPrice</span> to set the value <span class="langinline">stock-price</span>
+ element.</p>
+ <p>The <span class="langinline">PriceQuoteDocument</span> interface, on the
+ other hand, represents the <span class="langinline">price-quote</span> <em>document</em>
+ that contains the root <span class="langinline">price-quote</span> element.
+ XMLBeans creates a special "document" type for global element types.
+ A document type provides a way for you to get and set the value of the underlying
+ type, here represented by <span class="langinline">PriceQuote</span>. The
+ <span class="langinline">price-quote</span> element is considered a <em>global</em>
+ element because it can be referenced from anywhere else in the schema. For
+ global elements, the XMLBeans schema compiler generates an interface whose
+ name ends with "Document." This is because an XML schema has no
+ way of defining a "root" element; any global element can be the
+ root.</p>
+ <p>The following bit of Java code illustrates how you might use these interfaces
+ to get the stock price contained in the XML.</p>
+ <pre>
+public static float getStockPrice(java.io.File orderXML) throws Exception
+{
+ PriceQuoteDocument docXML = PriceQuoteDocument.Factory.parse(orderXML);
+ PriceQuote quoteXML = docXML.getPriceQuote();
+ float stockPrice = quoteXML.getStockPrice();
+ return stockPrice;
+}
+</pre>
+ <p>This code loads the XML from a <span class="langinline">File</span> object,
+ converting the <span class="langinline">parse</span> method's return value
+ to a <span class="langinline">PriceQuoteDocument</span> instance. It then
+ uses this instance to get an instance of <span class="langinline">PriceQuote</span>.
+ With <span class="langinline">PriceQuote</span>, the code extracts the stock
+ price. </p>
+</div>
+<div>
+ <div id="topictext">
+ <p>The XML schema specification provides a rich set of rules through which
+ you can derive new types. When you generate interfaces from your schema,
+ XMLBeans uses the schema's rules to determine how to generate interfaces.
+ The following describes some of the guidelines by which this is done.</p>
+ <h2>Names for Interfaces</h2>
+ <p>Interfaces are generated for schema types (both simple and complex). Anonymous
+ schema types result in inner interfaces inside the type interface in which
+ they are defined. Their name comes from the element or attribute in which
+ they is defined.</p>
+ <p>Names for schema types become Java-friendly names when the schema is compiled.
+ In other words, names such as "price-quote" become "PriceQuote." In addition,
+ a schema's XML namespace URIs become package names for XMLBean types generated
+ from the schema. The way this name translation is done is described by section
+ C of the Java API for XML Binding (JAXB) specification at <a href="http://java.sun.com/xml/downloads/jaxb.html" target="_blank">
+ http://java.sun.com/xml/jaxb.html.</a> </p>
+ <p>Here are a few examples:</p>
+ <table>
+ <tr>
+ <td><strong>Schema Target Namespace</strong></td>
+ <td width="155"><strong>XML Localname</strong></td>
+ <td><strong>Fully-Qualified XMLBean Type Name</strong></td>
+ </tr>
+ <tr>
+ <td>http://www.mycompany.com/2002/buyer</td>
+ <td width="155">purchase-order-4</td>
+ <td>com.mycompany.x2002.buyer.PurchaseOrder4</td>
+ </tr>
+ <tr>
+ <td>http://myco.com/sample.html</td>
+ <td width="155">SampleDocument</td>
+ <td>com.myco.sample.SampleDocument</td>
+ </tr>
+ <tr>
+ <td>http://openuri.org/test_case_1</td>
+ <td width="155">test_type</td>
+ <td>org.openuri.testCase1.TestType</td>
+ </tr>
+ </table>
+ <p>When there are name collisions, the generated types will have names with
+ numerals appended for example, "TestType2".</p>
+ <h2>Global Elements and Attributes</h2>
+ <p>In schema, global element and attribute definitions are those that are
+ declared at the top level of the schema (that is, immediately within the
+ <span class="langinline">schema</span> root element). Because they are global,
+ they may be referenced from inside the schema by name. The <span class="langinline">creditReport</span>
+ (not the <span class="langinline">creditReportType</span> complex type)
+ element defined in the following schema is an example.</p>
+ <pre>
+<xs:schema targetNamespace="http://openuri.org/samples/creditReport"
+ xmlns:cr="http://openuri.org/samples/creditReport"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ elementFormDefault="qualified"
+ attributeFormDefault="unqualified">
+ <xs:complexType name="creditReportType">
+ <xs:sequence>
+ <xs:element name="bankReport" type="xs:string"/>
+ <xs:element name="taxReport" type="xs:string"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:element name="creditReport" type="cr:creditReportType"/>
+</xs:schema></pre>
+ <p>XMLBeans generates a separate interface for each of these. Also, global
+ element and attribute types are somewhat unique in that the schema compiler
+ will create special types to hold the globally defined element or attribute.
+ The names of these types will be appended with "Document" (for
+ elements) or "Attribute" (for attributes). You can retrieve the
+ element or attribute itself (or create a new one) by calling the accessor
+ methods that the special types provide. The following example would create
+ a new instance of the creditReport element.</p>
+ <pre>
+// Create an instance of the special document type.
+CreditReportDocument reportDoc = CreditReportDocument.Factory.newInstance();
+/*
+ * Use the document type to add a new creditReport element to the XML instance.
+ * Note that the type returned by the addNewCreditReport method is the
+ * creditReportType complex type defined for it in schema.
+ */
+CreditReportType report = reportDoc.addNewCreditReport();
+</pre>
+ <h2>Global User-Derived Types</h2>
+ <p>A <em>user-derived</em> type is one defined with a <span class="langinline">complexType</span>
+ or <span class="langinline">simpleType</span> element in schema. User-derived
+ types at the top level of a schema are global. XMLBeans generates an interface
+ for each of these, as it does with global elements and attributes. These
+ interfaces include methods through which you can get and set the type's
+ values, including any nested derived types it may contain. The following
+ schema snippet defines a user-derived complex type called <span class="langinline">itemType</span>,
+ along with a <span class="langinline">priceType</span> that uses it as the
+ type for an <span class="langinline">item</span> child element.</p>
+ <pre>
+<xs:complexType name="itemType">
+ <xs:sequence>
+ <xs:element name="name" type="xs:string"/>
+ <xs:element name="amount" type="xs:int"/>
+ <xs:element name="price" type="xs:double"/>
+ </xs:sequence>
+</xs:complexType>
+<xs:complexType name="priceType">
+ <xs:sequence>
+ <xs:element name="item" type="ps:itemType" minOccurs="0" maxOccurs="unbounded"/>
+ </xs:sequence>
+</xs:complexType>
+<xs:element name="price" type="ps:priceType"/>
+</pre>
+ <p>By default, the generated Java type for <span class="langinline">itemType</span>
+ would be an interface called <span class="langinline">ItemType</span>. With
+ this type, you would be able to get and set the values of its <span class="langinline">name</span>,
+ <span class="langinline">amount</span>, and <span class="langinline">price</span>
+ child elements. However, a user-derived type (as opposed to an element or
+ attribute) is always intended for use as the type to which an element or
+ attribute is bound. In other words, it's contained by an element or attribute.
+ While you can create a new instance of a user-derived type, the new instance's
+ underlying XML is a fragment. As the generated API would make clear, the
+ <span class="langinline">itemType</span> becomes the return type of a get
+ method, or the parameter of a set method.</p>
+ <pre>
+// Create a new price document.
+PriceDocument priceDoc = PriceDocument.Factory.newInstance();
+PriceType price = priceDoc.getPrice();
+
+/*
+ * Create a new instance of ItemType and set the values of its
+ * child elements.
+ */
+ItemType item = ItemType.Factory.newInstance();
+item.setName("bicycle");
+item.setAmount(12);
+item.setPrice(560.00);
+
+/*
+ * Use the new ItemType instance to set the value of the
+ * price element's first item child element. Notice that the set method
+ * here is an "Array" method. This is because the item element
+ * is defined with a maxOccurs="unbounded" attribute. It can occur
+ * many times as a child of price.
+ */
+price.setItemArray(0, item);
+</pre>
+ <h2>Nested Elements and Derived Types</h2>
+ <p>When your schema includes named types that are declared locallywithin
+ the declaration of another element or typethe schema type's generated Java
+ interface will be an inner interface within the type it's nested in.</p>
+ <p>For example, the following schema snippet defines <span class="langinline">name</span>
+ and <span class="langinline">gender</span> elements nested within a <span class="langinline">person</span>
+ complex type. In particular, note that the gender element is defined as
+ deriving from the xs:NMTOKEN built-in type.</p>
+ <pre>
+<xs:complexType name="person">
+ <xs:sequence>
+ <xs:element name="name" type="xs:string"/>
+ <xs:element name="gender">
+ <xs:simpleType>
+ <xs:restriction base="xs:NMTOKEN">
+ <xs:enumeration value="male"/>
+ <xs:enumeration value="female"/>
+ </xs:restriction>
+ </xs:simpleType>
+ </xs:element>
+ </xs:sequence>
+</xs:complexType>
+</pre>
+ <p>The generated interfaces for person and gender would be organized in source
+ something like the following. Of course, you wouldn't see the source, but
+ you can see here that the Gender interface is nested with Person. Also,
+ notice that it extends XmlNMTOKEN, mirroring the schema.</p>
+ <pre>public interface Person extends XmlObject
+{
+ public interface Gender extends XmlNMTOKEN
+ {
+ // Methods omitted for this example
+ }
+ // Methods omitted for this example
+}
+</pre>
+ <p>You could create a new instance of the <span class="langinline">Gender</span>
+ type in this way (there are also various alternatives to this):</p>
+ <pre>
+// Create a new Person instance.
+Person person = Person.Factory.newInstance();
+/*
+ * Set the gender element's value using the
+ * enumeration generated from the schema.
+ */
+person.setGender(Gender.FEMALE);</pre>
+ <h2>User-Derived Simple Types</h2>
+ <p>In addition to the 46 built-in simple types in XML schema, a schema can
+ include its own custom simple types using <span class="langinline">xs:simpleType</span>
+ declarations. These user-derived simple types are always based on the built-in
+ XML schema types. The built-in types can be modified by <em>restricting</em>
+ them, taking <em>unions</em> of them, or making space-separated <em>lists</em>
+ of them. Each XML simple type is translated into a Java type that provides
+ access to the underlying data.</p>
+ <h3>Unions</h3>
+ <p>In schema, you can use <span class="langinline">xs:union</span> to specify
+ a simple type that is allowed to contain values of a number of other simple
+ types. XMLBeans generates a type for a union, just as it generates a type
+ for any other schema type. At run time, you can discover the underlying
+ type of an instance of a union type by calling the <span class="langinline">XmlObject</span>
+ interface's <span class="langinline">instanceType</span> method. Once you
+ have determined the type, you can cast an instance of a union type to the
+ actual underlying instance type.</p>
+ <pre>
+<xs:simpleType name="intOrString">
+ <xs:union memberTypes="xs:int xs:string">
+</xs:simpleType>
+</pre>
+ <p>Given the preceding schema snippet, you could set the intOrString value
+ to, say, 6 or "six". The union of <span class="langinline">xs:int</span>
+ and <span class="langinline">xs:string</span> makes both allowable.</p>
+ <pre>
+// Create a new instance of the type.
+IntOrString intOrString = IntOrString.Factory.newInstance();
+intOrString.set("5");
+// This code prints "XmlInt" to the console.
+System.out.println(intOrString.instanceType().getShortJavaName());
+</pre>
+ <h3>Restrictions</h3>
+ <p>XML schema restrictions on simple XMLBeans types are enforced. So, for
+ example, it is illegal to set a number outside its restricted range. </p>
+ <h4>Numeric Type Restrictions</h4>
+ <p>In schema, you can restrict numeric types to allow, for example, only a
+ particular range of values. For such a restriction, XMLBeans tailors the
+ resulting natural Java alternative. For example, suppose you have the following
+ element defined in schema:</p>
+ <pre>
+<xs:element name="number">
+ <xs:simpleType>
+ <xs:restriction base="xs:integer">
+ <xs:minInclusive value="1"/>
+ <xs:maxInclusive value="1000000"/>
+ </xs:restriction>
+ </xs:simpleType>
+</xs:element>
+</pre>
+ <p>The type is restricted from <span class="langinline">xs:integer</span>,
+ but because the number's range is limited to between 1 and 1000000, it will
+ fit into a Java <span class="langinline">int</span>. A <span class="langinline">long</span>
+ or <span class="langinline">java.math.BigInteger</span> would be too big
+ for the need. In other words, the <span class="langinline">getNumber</span>
+ method generated for this type will return an <span class="langinline">int</span>,
+ rather than a <span class="langinline">BigInteger</span> or a <span class="langinline">long</span>.</p>
+ <p>By the same token, an long can be compiled to an int if the totalDigits
+ attribute is <=9, or the min and max attribute values are within 32-bit
+ 2s complement range.</p>
+ <p>The single primitive XML type xs:decimal can be restricted in several ways
+ that influence the resulting natural Java type. For example, it can be:</p>
+ </div>
+</div>
+<ul>
+ <li>
+ <div>
+ <div>Compiled to a <span class="langinline">BigInteger</span> if its <span class="langinline">fractionDigit</span>
+ attribute is set to 0. </div>
+ </div>
+ </li>
+ <li>
+ <div>
+ <div>Compiled to a <span class="langinline">long</span> if its totalDigits
+ attribute is <=18, or the min and max are within 64-bit 2s complement
+ range.</div>
+ </div>
+ </li>
+</ul>
+<div>
+ <div>
+ <h3>Enumerations</h3>
+ <p>In schema, you can derive a new type by restricting a built-in type so
+ that only a finite set of values are allowable. Where schema does this by
+ restricting <span class="langinline">xs:string</span>, XMLBeans generates
+ a special <span class="langinline">Enum</span> type. With an <span class="langinline">Enum</span>,
+ you can select the enumerated value either by its <span class="langinline">String</span>
+ value or by a numeric index. The index's value is determined based on the
+ <span class="langinline">String</span> value's order in the schema. Having
+ an index can be useful in Java switch statements.</p>
+ <p>For example, suppose you had a document containing price elements whose
+ type was the priceType defined in the following schema snippet:</p>
+ <pre><xs:complexType name="priceType">
+ <xs:sequence>
+ <xs:element name="item" type="ps:itemType" minOccurs="0"
+ maxOccurs="unbounded"/>
+ </xs:sequence>
+ <xs:attribute name="threshold">
+ <xs:simpleType>
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="Below10Dollars"/>
+ <xs:enumeration value="Between10And20Dollars"/>
+ <xs:enumeration value="Above20Dollars"/>
+ </xs:restriction>
+ </xs:simpleType>
+ </xs:attribute>
+</xs:complexType></pre>
+ <p>Using types generated from the schema, you would be able to write the following
+ Java code to "switch" on the threshold attribute's enumeration:</p>
+ <pre>
+/*
+ * Use the intValue method provided by the Enum type to determine the threshold
+ * attribute's current enumeration value.
+ */
+switch(priceElements[i].getThreshold().intValue())
+{
+ // Use the Threshold type's enumeration values to test for an attribute value.
+ case PriceType.Threshold.INT_BELOW_10_DOLLARS:
+ zeroBuffer.append(item.getTitle() + "\n");
+ break;
+ case PriceType.Threshold.INT_BETWEEN_10_AND_20_DOLLARS:
+ tenBuffer.append(item.getTitle() + "\n");
+ break;
+ case PriceType.Threshold.INT_ABOVE_20_DOLLARS:
+ twentyBuffer.append(item.getTitle() + "\n");
+ break;
+ default:
+ System.out.println("Yo! Something unexpected happened!");
+ break;
+}</pre>
+ </div>
+ <p class="relatedtopics">Related Topics</p>
+ <p><a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support for
+ Built-In Schema Types</a></p>
+</div>
+ <!-- InstanceEndEditable -->
+<script language="JavaScript">
+
+</script>
+</body>
+</html>
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conMethodsForGeneratedJavaTypes.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conMethodsForGeneratedJavaTypes.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conMethodsForGeneratedJavaTypes.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conMethodsForGeneratedJavaTypes.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,275 @@
+<!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>Methods for Types Generated From Schema</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>Methods for Types Generated From Schema</p>
+</div>
+<div id=topictext>
+ <p>As you may have seen in <a href="conGettingStartedwithXMLBeans.html">Getting
+ Started with XMLBeans</a>, you use the types generated from schema to access
+ XML instances based on the schema. If you're familiar with the JavaBeans technology,
+ the conventions used in the generated API will be recognizable. </p>
+ <p>In general, elements and attributes are treated as "properties"
+ in the JavaBeans sense. In other words, as you would with JavaBeans properties,
+ you manipulate parts of the XML through accessor methods such as getCustomer()
+ (where you have a "customer" element), setId(String) (where you
+ have an "id" attribute), and so on. However, because schema structures
+ can be somewhat complex, XMLBeans provides several other method styles for
+ handling those structures in XML instances.</p>
+ <div>
+ <h2>Prototypes for Methods in Generated Interfaces</h2>
+ <p>Several methods are generated for each element or attribute within the
+ complex type. This topic lists each method that could be generated for a
+ given element or attribute. </p>
+ <p>Note that whether or not a given method is generated is based on how the
+ element or attribute is defined in schema. For example, a customer element
+ definition with a <span class="langinline">maxOccurs</span> attribute value
+ of 1 will result in a getCustomer method, but not a getCustomerArray method
+ — after all, only one customer element is possible in an instance
+ document.</p>
+ <p>Note, too, that there may be two sets of parallel methods: one whose prototype
+ starts with an "x". An "x" method such as xgetName or
+ xsetName would be generated for elements or attribute whose type is a simple
+ type. A simple type may be one of the 44 built-in simple types or may be
+ a restriction in schema of one of those built-in types. Of course, an attribute
+ will always be of a simple type. For built-in simple types, an "x"
+ method will get or set one of the types provided with XMLBeans, such as
+ <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlString.html">XmlString</a></span>,
+ <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlInteger.html">XmlInteger</a></span>,
+ <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlGDay.html">XmlGDay</a></span>,
+ and so on. For derived types, the "x" method will get or set a
+ generated type.</p>
+ <h3>Single Occurrence Methods</h3>
+ <p>Methods generated for elements or attributes that allow a single occurrence.
+ An element is singular if it was declared with maxOccurs="1".
+ An attribute is singular if it was not declared with use="prohibited".</p>
+ <pre>
+Type getFoo()
+void setFoo(Type newValue)
+</pre>
+ </div>
+ <blockquote>
+ <div>Returns or sets the value of Foo. Generated when Foo is an attribute,
+ or is an element that can occur only once as a child.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>XmlType xgetFoo()
+void xsetFoo(XmlType newValue)</pre>
+ </div>
+ <blockquote>
+ <div>Returns or sets the value of Foo as an XMLBean simple type. These methods
+ are generated if Foo's type is defined in schema as a simpleType.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>boolean isNilFoo()
+void setNilFoo()</pre>
+ </div>
+ <blockquote>
+ <div>Determines or specifies whether the Foo element is nil (in other words,
+ "null" in schema terms), meaning it can be empty. A nil element
+ looks something like this:</div>
+ <div>
+ <pre><foo/></pre>
+ </div>
+ <div>These methods are only generated when an element type is declared as
+ nillable in schema — it has a nillable="true" attribute.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>XmlType addNewFoo()</pre>
+ </div>
+ <blockquote>
+ <div>Adds a new Foo as an XMLBean simple to the document, or returns Foo's
+ value if one exists already.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>boolean isSetFoo()
+void unSetFoo()</pre>
+ </div>
+ <blockquote>
+ <div>Determines whether the Foo element or attribute exists in the document;
+ removes Foo. These methods are generated for elements and attributes that
+ are optional. In schema, and optional element has an <span class="langinline">minOccurs</span>
+ attribute set to "0"; an optional attribute has a <span class="langinline">use</span>
+ attribute set to "optional".</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <h3>Multiple Occurrence Methods</h3>
+ <p>Methods generated for elements that allow multiple occurrences. </p>
+ <p>An element may occur multiple times if it has a <span class="langinline">maxOccurs</span>
+ attribute set to "unbounded" or greater than 1. Attributes can't
+ occur multiple times.</p>
+ <pre>Type[] getFooArray()
+void setFooArray(Type[] newValue) </pre>
+ </div>
+ <blockquote>
+ <div>Returns or sets all of the Foo elements. </div>
+ <div>
+ <pre>
+// Get an array of the all of the purchase-order elements item children.
+Item[] items = myPO.getItemArray();
+</pre>
+ </div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>Type getFooArray(int index)
+void setFooArray(Type newValue, int index)</pre>
+ </div>
+ <blockquote>
+ <div>Returns or sets the Foo child element at the specified index.</div>
+ <div>
+ <pre>// Sets the value of the third item child element.
+myPO.setItem(newItem, 2);</pre>
+ </div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>int sizeOfFooArray()</pre>
+ </div>
+ <blockquote>
+ <div>Returns the number of Foo child elements.</div>
+ <div>
+ <pre>// Returns the number of item child elements.
+int itemCount = myPO.sizeOfItemArray();</pre>
+ </div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>void removeFoo(int index)</pre>
+ </div>
+ <blockquote>
+ <div>Removes the Foo child element at the specified index.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>XmlType[] xgetFooArray()
+void xsetFooArray(XmlType[] arrayOfNewValues)</pre>
+ </div>
+ <blockquote>
+ <div>Returns or sets all of the Foo elements as XMLBeans simple types. Generated
+ only when the Foo element is defined as a simple type.</div>
+ <div>
+ <pre>/*
+ * Returns values of all the phone child elements of an employee element,
+ * where the phone element has been defined as xs:string.
+ */
+XmlString[] empPhones = currentEmployee.xGetPhoneArray();
+</pre>
+ </div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>XmlType xgetFooArray(int index)
+void xsetFooArray(int index, XmlType newValue)</pre>
+ </div>
+ <blockquote>
+ <div>Returns or sets the Foo element at the specified index, using an XMLBeans
+ simple type value. Generated for an element defined as a simple type in
+ schema.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>void insertFoo(int index, FooType newValue)</pre>
+ </div>
+ <blockquote>
+ <div>Inserts the specified Foo child element at the specified index.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>void addFoo(FooType newValue)</pre>
+ </div>
+ <blockquote>
+ <div>Adds the specified Foo to the end of the list of Foo child elements.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>XmlType insertNewFoo(int index)</pre>
+ </div>
+ <blockquote>
+ <div>Inserts a new Foo at the specified index, returning an XMLBeans simple
+ type representing the new element; returns the existing Foo if there's already
+ one at index.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>XmlType addNewFoo()</pre>
+ </div>
+ <blockquote>
+ <div>Adds a new Foo element to the end of the list of Foo child elements,
+ returning an XMLBeans simple type representing the newly added element.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ <pre>boolean isNilFooArray(int index)
+void setNilFooArray(int index)</pre>
+ </div>
+ <blockquote>
+ <div>Determines or specifies whether the Foo element at the specified index
+ is nil.</div>
+ </blockquote>
+ <div>
+ <hr size="1">
+ </div>
+ <div id="topictext"></div>
+ <p class=relatedtopics>Related Topics</p>
+ <p><a href="conJavaTypesGeneratedFromUserDerived.html">Java Types Generated
+ from User-Derived Schema Types</a></p>
+</div>
+<!-- InstanceEndEditable -->
+<script language="JavaScript">
+
+</script>
+</body>
+</html>
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conNavigatingXMLwithCursors.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conNavigatingXMLwithCursors.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conNavigatingXMLwithCursors.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conNavigatingXMLwithCursors.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,222 @@
+<!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>Navigating XML with Cursors</title>
+<!-- InstanceEndEditable -->
+<!--(Meta)==========================================================-->
+
+<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
+
+
+<!-- InstanceBeginEditable name="metatags" -->
+
+<meta content="your name" name="author">
+<meta content="A description of the topic contents." name="description">
+<meta content="keywords to help in searches" name="keywords">
+<meta content="10/25/02" name="date last modified">
+<!-- InstanceEndEditable -->
+
+<!--(Links)=========================================================-->
+<!-- InstanceBeginEditable name="head" -->
+<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
+<!-- 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" -->
+<h1> Navigating XML with Cursors </h1>
+<div id="topictext">
+ <p>XML cursors are a way to navigate through an XML instance document. Once
+ you load an XML document, you can create a cursor to represent a specific
+ place in the XML. Because you can use a cursor with or without a schema corresponding
+ to the XML, cursors are an ideal way to handle XML without a schema.</p>
+ <p>With an XML cursor, you can:</p>
+</div>
+<UL>
+ <li>
+ <div><a href="conUnderstandingXMLTokens.html">Use the token model</a> to move
+ through XML in small increments, or in a manner similar to using a DOM-based
+ model.</div>
+ <LI>
+ <DIV>Get and set values within the XML.</DIV>
+ <LI>
+ <DIV><a href="#adding_elements_attributes">Change the structure</a> of an
+ XML document by inserting, removing, and moving elements and attributes.</DIV>
+ <LI>
+ <DIV><a href="conSelectingXMLwithXQueryPathXPath.html">Execute XQuery expressions</a>
+ against the XML represented by the cursor.</DIV>
+ <LI>
+ <DIV><a href="conUsingBookmarksToAnnotateXML.html">Insert bookmarks</a> to
+ mark locations in XML.</DIV>
+</UL>
+<P>When you're finished using a cursor, your code should call its <span class="langinline">dispose</span>
+ method.</P>
+<h2>Creating and Moving a Cursor</h2>
+<P>With an XML instance document bound to <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlObject.html">XmlObject</a></span>
+ (or a type inheriting from it), you create a new cursor by calling the <span class="langinline">newCursor</span>
+ method. The <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlCursor.html">XmlCursor</a></span>
+ interface represents a cursor. From a cursor standpoint, an XML document is
+ a collection of <EM>tokens</EM> that represent the kinds of things that can
+ appear in XML. These include attributes, the start and end of elements,
+ comments, and so on. Each piece of information in XML is represented by
+ a <em>token type</em>.</P>
+<P class="notepara"><strong>Note:</strong> For a more complete description of
+ XML tokens, see <a href="conUnderstandingXMLTokens.html">Understanding XML Tokens</a>.</P>
+<P>For example, the following code loads the XML instance described above
+ from a <span class="langinline">File</span> object, then creates a new cursor.
+ The <span class="langinline">toFirstChild</span> takes the cursor to the start
+ tag of the <span class="langinline">batchWidgetOrder</span> document element.
+ The code then prints the type for the token at the cursor's location, along
+ with the XML the cursor representsin other words, <span class="filepath">Token
+ type: START /</span> and the <span class="filepath">batchWidgetOrderElement</span>
+ and its contents.</P>
+<pre>public static void insertCursor(File orderFile) throws Exception
+{
+ BatchWidgetOrderDocument xmlDoc = BatchWidgetOrderDocument.Factory.parse(orderFile);
+ XmlCursor orderCursor = xmlDoc.newCursor();
+ orderCursor.toFirstChild();
+ System.out.println("Token type: " + orderCursor.currentTokenType() +
+ " / " + orderCursor.xmlText());
+}
+</pre>
+<p class="notepara"><STRONG>Note</STRONG>: The <span class="langinline">XmlCursor</span>
+ interface provides many methods you can use to put a cursor where you want it.
+ For a list of those methods, see <a href="../reference/org/apache/xmlbeans/XmlCursor.html">XmlCursor
+ Interface</a>.</p>
+<h2><a name="adding_elements_attributes" id="adding_elements_attributes"></a>Adding
+ Elements and Attributes</h2>
+<p>The <span class="langinline">XmlCursor</span> interface provides several methods
+ you can use to add elements and attributes to XML. </p>
+<p>One way to add new XML is with the <span class="langinline">beginElement</span>
+ method. This method is designed to insert a new element at the cursor's location,
+ and do it so the cursor ends up between the new element's START and END tokens.
+ From this position, you can insert attributes (they're automatically placed
+ in the start tag, where they belong) and insert a value. Here's an example:</p>
+<pre>
+// Create a new chunk of XML.
+XmlObject newXml = XmlObject.Factory.newInstance();
+/*
+ * Insert a new cursor and move it to the first START token (where the
+ * XML actually begins.
+ */
+XmlCursor cursor = newXml.newCursor();
+cursor.toNextToken();
+// Begin a new item element whose namespace URI is "http://openuri.org".
+cursor.beginElement("item", "http://openuri.org/");
+// Insert an ID attribute on the item element, along with an attribute value.
+cursor.insertAttributeWithValue("id", "4056404");
+// Insert "bicycle" as an element value.
+cursor.insertChars("bicycle");
+cursor.dispose();
+</pre>
+<p>This example results in something like the following:</p>
+<pre><ns1:item id="4056404" xmlns:ns1="http://openuri.org/">bicycle</ns1:item>
+</pre>
+<h2> Using Stored Cursor Locations with push() and pop()</h2>
+<div id="topictext">
+ <p>When you want to move a cursor around, but want to keep track of a former
+ location, you can use the <span class="langinline">XmlCursor</span> interface's
+ <span class="langinline">push</span> and <span class="langinline">pop</span>
+ methods. The <span class="langinline">push</span> method pushes the cursor's
+ current location onto a stack of locations maintained for that particular
+ cursor; the <span class="langinline">pop</span> method removes the location
+ from the top of the stack and moves the cursor to that location.</p>
+ <p>For example, consider the following <employee> element, used in the
+ example below.</p>
+ <pre>
+<employee>
+ <name>Gladys Kravitz</name>
+ <address location="home">
+ <street>1313 Mockingbird Lane</street>
+ <city>Seattle</city>
+ <state>WA</state>
+ <zip>98115</zip>
+ </address>
+ <address location="work">
+ <street>2011 152nd Avenue NE</street>
+ <city>Redmond</city>
+ <state>WA</state>
+ <zip>98052</zip>
+ </address>
+ <phone location="work">(425) 555-6897</phone>
+ <phone location="home">(206) 555-6594</phone>
+ <phone location="mobile">(206) 555-7894</phone>
+</employee>
+</pre>
+ <p>The following Java code illustrates how you can use <span class="langinline">push</span>
+ and <span class="langinline">pop</span> to put the cursor back to a saved
+ location after a bit of traveling.</p>
+ <pre>
+/**
+ * Pass to the trySelectPath method an XmlObject instance that contains
+ * the XML above.
+ */
+public void trySelectPath(XmlObject xml)
+{
+ /*
+ * Inserts the cursor at the STARTDOC token (the very beginning,
+ * before any elements).
+ */
+ XmlCursor cursor = xml.newCursor();
+ // Moves the cursor to just before <employee>
+ cursor.toFirstChild();
+ // Pushes the cursor's current location onto the stack.
+ cursor.push();
+ // Moves the cursor to just before the "work" <phone> element.
+ cursor.toChild(2);
+ // Moves the cursor to just before the "home" <phone> element.
+ cursor.toNextSibling();
+ // Moves the cursor back to just before <employee>
+ cursor.pop();
+}
+</pre>
+ <p>Of course, you can call <span class="langinline">push</span> and <span class="langinline">pop</span>
+ multiple times. Each new call to the <span class="langinline">push</span>
+ method pushes the current location onto the stack. As you call the <span class="langinline">pop</span>
+ method, you're always getting what's on top of the stack. So if you called
+ <span class="langinline">push</span> three times before calling <span class="langinline">pop</span>
+ — 1, 2, 3 — calling <span class="langinline">pop</span> three
+ times would get those locations in reverse order — 3, 2, 1.</p>
+ <p>The <span class="langinline">push</span> and <span class="langinline">pop</span>
+ methods can be handy as an alternative to creating new cursors that are designed
+ simply to mark a particular location while you move another cursor around.
+ The resources required to maintain a location stack through <span class="langinline">push</span>
+ and <span class="langinline">pop</span> are far less than those needed by
+ cursors. </p>
+ <H1>Disposing of a Cursor</H1>
+ <p>When you're through with a cursor, your code should call its <span class="langinline">dispose</span>
+ method to indicate that it's no longer needed.</p>
+ <p class="relatedtopics">Related Topics</p>
+ <p><a href="conUnderstandingXMLTokens.html">Understanding XML Tokens</a></p>
+ <p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p>
+</div>
+<!-- InstanceEndEditable -->
+<script language="JavaScript">
+
+</script>
+</body>
+</html>
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conSelectingXMLwithXQueryPathXPath.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conSelectingXMLwithXQueryPathXPath.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conSelectingXMLwithXQueryPathXPath.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conSelectingXMLwithXQueryPathXPath.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,338 @@
+<!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>Selecting XML with XQuery and XPath</title>
+<!-- InstanceEndEditable -->
+<!--(Meta)==========================================================-->
+
+<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
+
+
+<!-- InstanceBeginEditable name="metatags" -->
+
+<meta content="your name" name="author">
+<meta content="A description of the topic contents." name="description">
+<meta content="keywords to help in searches" name="keywords">
+<meta content="10/25/02" name="date last modified">
+<!-- InstanceEndEditable -->
+
+<!--(Links)=========================================================-->
+<!-- InstanceBeginEditable name="head" -->
+<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
+<!-- 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" -->
+<h1> Selecting XML with XQuery and XPath</h1>
+<div id="topictext">
+ <p>You can use XPath and XQuery to retrieve specific pieces of XML as you might
+ retrieve data from a database. XQuery and XPath provide a syntax for specifying
+ which elements and attributes you're interested in. The XMLBeans API provides
+ two methods for executing XQuery and XPath expressions, and two ways to use them. The methods are <span class="langinline">selectPath</span>
+ for XPath and <span class="langinline">execQuery</span> for XQuery. </p>
+ <p>You can call them from and <a href="../reference/org/apache/xmlbeans/XmlObject.html"><span class="langinline"> XmlObject</span></a> instance (or a generated type inheriting from it) or an <a href="../reference/org/apache/xmlbeans/XmlCursor.html"><span class="langinline">XmlCursor</span></a> instance.
+ As noted below, each of the four methods works slightly differently; be sure to keep these differences in mind when choosing your approach.</p>
+ <p class="notepara"><strong>Note:</strong> Both XQuery and complex XPath expressions require additional classes on the class path, as noted in the sections that follow. Also, be sure to see the XMLBeans <a href="../../../documentation/conInstallGuide.html">installation instructions</a>. </p>
+ <h2><a name="xpath_selectpath"></a>Using XPath with the selectPath Method</h2>
+</div>
+<div>
+ <p>You can execute XPath expressions use the <span class="langinline">selectPath</span> method. When you use XPath with the <span class="langinline">selectPath</span>
+ method, the value returned is view of values from the <em>current document</em> — not a copy of those values. In other words, changes your code makes to XML returned by the selectPath method change the XML in the document queried against. In contrast, with XQuery executed using the <span class="langinline">execQuery</span> method, the value returned is a <em>copy of values in the XML queried against</em>.</p>
+ <p> Note that XPath itself does not provide syntax for declaring prefix to URI bindings. For user convenience, we allow XQuery syntax to be used for such purposes. You can consult the latest XQuery draft when using syntax for declaring namespaces.</p>
+ <blockquote>
+ <p><strong>Note:</strong> By default, XMLBeans supports only very simple XPath expressions. To execute complex expressions — such as those with predicates, function calls, and the like — you will need xbean_xpath.jar on your class path. This JAR is among those created when you build XMLBeans from source.</p>
+ </blockquote>
+ <h3>Calling XmlObject.selectPath</h3>
+ <p>When called from <span class="langinline">XmlObject</span> (or a type that
+ inherits from it), the <code>selectPath</code> method returns an array of objects. If the expression
+ is executed against types generated from schema, then the type for the returned
+ array is one of the Java types corresponding to the schema, and you can cast it accordingly. </p>
+ <p>For example, imagine you have the following XML containing employee information.
+ You've compiled the schema describing this XML and the types generated from
+ schema are available to your code.</p>
+<pre>
+<xq:employees xmlns:xq="http://xmlbeans.apache.org/samples/xquery/employees">
+ <xq:employee>
+ <xq:name>Fred Jones</xq:name>
+ <xq:address location="home">
+ <xq:street>900 Aurora Ave.</xq:street>
+ <xq:city>Seattle</xq:city>
+ <xq:state>WA</xq:state>
+ <xq:zip>98115</xq:zip>
+ </xq:address>
+ <xq:address location="work">
+ <xq:street>2011 152nd Avenue NE</xq:street>
+ <xq:city>Redmond</xq:city>
+ <xq:state>WA</xq:state>
+ <xq:zip>98052</xq:zip>
+ </xq:address>
+ <xq:phone location="work">(425)555-5665</xq:phone>
+ <xq:phone location="home">(206)555-5555</xq:phone>
+ <xq:phone location="mobile">(206)555-4321</xq:phone>
+ </xq:employee>
+</xq:employees>
+</pre>
+ If you wanted to find the phone numbers whose area code was 206, you could capture
+ the XPath expression in this way:
+ <pre>
+String queryExpression =
+ "declare namespace xq='http://xmlbeans.apache.org/samples/xquery/employees';" +
+ "$this/xq:employees/xq:employee/xq:phone[contains(., '(206)')]";
+</pre>
+ <p>Notice in the query expression that the variable <span class="langinline">$this</span>
+ represents the current context node (the <span class="langinline">XmlObject</span>
+ that you are querying from). In this example you are querying from the document
+ level <span class="langinline">XmlObject</span>.</p>
+ <p>You could then print the results with code such as the following:</p>
+ <pre>// Retrieve the matching phone elements and assign the results to the corresponding
+// generated type.
+PhoneType[] phones = (PhoneType[])empDoc.selectPath(queryExpression);
+
+// Loop through the results, printing the value of the phone element.
+for (int i = 0; i < phones.length; i++)
+{
+ System.out.println(phones[i].stringValue());
+}</pre>
+
+ <h3>Calling XmlCursor.selectPath</h3>
+ <p>When called from an <span class="langinline">XmlCursor</span> instance, the
+ <span class="langinline">selectPath</span> method retrieves a list of <em>selections</em>,
+ or locations in the XML. The selections are remembered by the cursor instance.
+ You can use methods such as <span class="langinline">toNextSelection</span>
+ to navigate among them.</p>
+ <div>
+ <p>The <span class="langinline">selectPath</span> method takes an XPath expression.
+ If the expression returns any results, each of those results is added as
+ a selection to the cursor's list of selections. You can move through these
+ selections in the way you might use <span class="langinline">java.util.Iterator</span>
+ methods to move through a collection.</p>
+ <p> For example, for a path such as <span class="langinline">$this/employees/employee</span>,
+ the cursor instance from which you called <code>selectPath</code> would include a selection for each employee element found by
+ the expression. Note that the variable <span class="langinline">$this</span>
+ is always bound to the current context node, which in this example is the
+ document. After calling the <span class="langinline">selectPath</span> method,
+ you would use various "selection"-related methods to work with
+ the results. These methods include:</p>
+ </div>
+ <ul>
+ <li>
+ <div><span class="langinline">getSelectionCount() </span>to retrieve the
+ number of selections resulting from the query.</div>
+ </li>
+ <li>
+ <div> <span class="langinline">toNextSelection()</span> to move the cursor
+ to the next selection in the list (such as to the one pointing at the
+ next employee element found).</div>
+ </li>
+ <li>
+ <div> <span class="langinline">toSelection(int)</span> to move the cursor
+ to the selection at the specified index (such as to the third employee
+ element in the selection).</div>
+ </li>
+ <li>
+ <div> <span class="langinline">hasNextSelection()</span> to find out if
+ there are more selections after the cursor's current position.</div>
+ </li>
+ <li>
+ <div><span class="langinline"> clearSelections()</span> clears the selections
+ from the current cursor. This doesn't modify the document (in other words,
+ it doesn't delete the selected XML); it merely clears the selection list
+ so that the cursor is no longer keeping track of those positions.</div>
+ </li>
+ </ul>
+ <div>
+ <p>The following example shows how you might use <span class="langinline">selectPath</span>,
+ in combination with the <span class="langinline">push</span> and <span class="langinline">pop</span>
+ methods, to maneuver through XML, retrieving specific values. </p>
+ <pre>
+public void printZipsAndWorkPhones(XmlObject xml)
+{
+ // Declare the namespace that will be used.
+ String xqNamespace =
+ "declare namespace xq='http://xmlbeans.apache.org/samples/xquery/employees';";
+
+ // Insert a cursor and move it to the first element.
+ XmlCursor cursor = xml.newCursor();
+ cursor.toFirstChild();
+
+ // Save the cursor's current location by pushing it
+ // onto a stack of saved locations.
+ cursor.push();
+ // Query for zip elements.
+ cursor.selectPath(xqNamespace + "$this//xq:zip");
+
+ // Loop through the list of selections, getting the value of
+ // each element.
+ while (cursor.toNextSelection())
+ {
+ System.out.println(cursor.getTextValue());
+ }
+ // Pop the saved location off the stack.
+ cursor.pop();
+ // Query again from the top, this time for work phone numbers.
+ cursor.selectPath(xqNamespace + "$this//xq:phone[@location='work']");
+
+ // Move the cursor to the first selection, then print that element's
+ // value.
+ cursor.toNextSelection();
+ System.out.println(cursor.getTextValue());
+ // Dispose of the cursor.
+ cursor.dispose();
+}
+</pre>
+ <p>Using selections is somewhat like tracking the locations of multiple cursors
+ with a single cursor. This becomes especially clear when you remove the
+ XML associated with a selection. When you do so the selection itself remains
+ at the location where the removed XML was, but now the selection's location
+ is immediately before the XML that was after the XML you removed. In other
+ words, removing XML created a kind of vacuum that was filled by the XML
+ after it, which shifted up into the space — up into position immediately
+ after the selection location. This is exactly the same as if the selection
+ had been another cursor.</p>
+ <p>Finally, when using selections keep in mind that the list of selections
+ is in a sense "live". The cursor you're working with is keeping
+ track of the selections in the list. In other words, be sure to call the
+ <span class="langinline">clearSelections</span> method when you're finished
+ with the selections, just as you should call the <span class="langinline">XmlCursor.dispose()</span>
+ method when you're finished using the cursor.</p>
+ </div>
+ <h2><a name="xquery_execquery"></a>Using XQuery with the execQuery Method</h2>
+ <p>You use the <span class="langinline">execQuery</span> method to execute XQuery
+ expressions. With XQuery expressions, XML returned is a copy of XML in the document queried against. In other words, changes your code makes to the values returned by <code>execQuery</code> are not reflected in the document queried against.</p>
+ <blockquote>
+ <p><strong>Note:</strong> To execute XQuery expressions, you must have the Saxon 8.1.1 JAR on your class path. Look for the download at the <a href="http://sourceforge.net/project/showfiles.php?group_id=29872&package_id=21888">Saxon web site</a>. This JAR is also included in the lib directory when you build XMLBeans from source.</p>
+ </blockquote>
+ <h3>Calling XmlObject.execQuery</h3>
+ <p>As with <span class="langinline">selectPath</span>, calling <span class="langinline">execQuery</span>
+ from an <span class="langinline">XmlObject</span> instance will return an
+ <span class="langinline">XmlObject</span> array.</p>
+ <p> The following example retrieves work <code><zip></code> elements from the incoming XML, adding the elements as children to a new <code><zip-list></code> element.</p>
+ <pre>public boolean collectZips(XmlObject empDoc)
+{
+ String namespaceDeclaration =
+ "declare namespace xq='http://xmlbeans.apache.org/samples/xquery/employees';";
+ // The query is designed to return results, so return
+ // true if it does.
+ boolean hasResults = false;
+
+ // The expression: Get the <zip> elements and return them as children
+ // of a new <zip-list> element.
+ String queryExpression =
+ "let $e := $this/xq:employees " +
+ "return " +
+ "<zip-list> " +
+ "{for $z in $e/xq:employee/xq:address/xq:zip " +
+ "return $z} " +
+ "</zip-list>";
+
+ // Execute the query. Results will be copies of the XML queried against,
+ // stored as members of an XmlObject array.
+ XmlObject[] results =
+ empDoc.execQuery(namespaceDeclaration + queryExpression);
+
+ // Print the results.
+ if (results.length > 0)
+ {
+ hasResults = true;
+ System.out.println("The query results: \n");
+ System.out.println(results[0].toString() + "\n");
+ }
+ return hasResults;
+}</pre>
+ <h3>Calling XmlCursor.execQuery</h3>
+</div>
+
+<div>
+ <p>Unlike the <code>selectPath</code> method called from a cursor, the <span class="langinline">execQuery</span> method doesn't return <code>void</code>. Instead it returns an <span class="langinline">XmlCursor</span> instance positioned at the beginning of a new XML document representing
+ the query results. Rather than accessing results as selections, you use the cursor to move through the results in typical cursor fashion (for more information, see <a href="conNavigatingXMLwithCursors.html">Navigating
+ XML with Cursors</a>). The models are very different.</p>
+ <p>As always, you can cast the results to a type generated from schema if you know that the results conform to that type.</p>
+ <p>The following example retrieves work <code><phone></code> elements from the incoming XML, then changes the number in the results.</p>
+ <pre>public boolean updateWorkPhone(XmlObject empDoc)
+{
+ boolean hasResults = false;
+
+ // A cursor instance to query with.
+ XmlCursor empCursor = empDoc.newCursor();
+ empCursor.toNextToken();
+
+ // The expression: Get the <employee> elements with <state> elements whose
+ // value is "WA".
+ String queryExpression =
+ "for $e in $this/xq:employees/xq:employee " +
+ "let $s := $e/xq:address/xq:state " +
+ "where $s = 'WA' " +
+ "return $e//xq:phone[@location='work']";
+
+ // Execute the query. Results, if any, will be available at
+ // the position of the resultCursor in a new XML document.
+ XmlCursor resultCursor =
+ empCursor.execQuery(namespaceDeclaration + queryExpression);
+
+ System.out.println("The query results, element copies made " +
+ "from the received document: \n");
+ System.out.println(resultCursor.getObject().toString() + "\n");
+
+ // If there are results, the results will be children of the fragment root
+ // where the new cursor is positioned. This statement tests for children
+ // and moves the cursor if to the first if it exists.
+ if (resultCursor.toFirstChild())
+ {
+ hasResults = true;
+ // Use the cursor to loop through the results, printing each sibling
+ // <employee>element returned by the query.
+ int i = 0;
+ do
+ {
+ // Change the phone numbers.
+ XmlCursor editCursor = resultCursor.newCursor();
+ editCursor.toLastAttribute();
+ editCursor.toNextToken();
+ editCursor.removeXml();
+ editCursor.insertChars("(206)555-1234");
+ } while (resultCursor.toNextSibling());
+
+ resultCursor.toStartDoc();
+ System.out.println("The query results after changes: \n");
+ System.out.println(resultCursor.getObject().toString() + "\n");
+
+ System.out.println("The received document -- note that it is unchanged. " +
+ "Changes were made to the copy created by the execQuery method. \n");
+ System.out.println(empDoc + "\n");
+ }
+ return hasResults;
+}</pre>
+ <h2>Related Topics</h2>
+</div>
+<p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p>
+<!-- InstanceEndEditable -->
+<script language="JavaScript">
+
+</script>
+</body>
+</html>
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUnderstandingXMLTokens.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUnderstandingXMLTokens.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUnderstandingXMLTokens.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUnderstandingXMLTokens.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,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>
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUsingBookmarksToAnnotateXML.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUsingBookmarksToAnnotateXML.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUsingBookmarksToAnnotateXML.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conUsingBookmarksToAnnotateXML.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,97 @@
+<!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>Using Bookmarks to Annotate XML</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>Using Bookmarks to Annotate XML</p>
+</div>
+<div id=topictext>
+ <p>You can use a cursor to insert bookmarks that annotate XML with markers containing
+ information you design. These bookmarks aren't written into the XML itself,
+ but in a sense "hang" from the location where it was inserted. In this way
+ you can associate arbitrary pieces of information with specific parts of the
+ XML.</p>
+ <P>You design your own bookmark classes by extending <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlCursor.XmlBookmark.html">XmlBookmark</a></span>,
+ a nested class of <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlCursor.html">XmlCursor</a></span>.
+ You can design your bookmark class to contain information specific to your
+ needs. </P>
+ <P>In the following example, <span class="langinline">OrderBookmark</span> is
+ an inner class that extends <span class="langinline">XmlCursor.XmlBookmark</span>.
+ It merely stores a piece of text.</P>
+ <PRE>
+/*
+ * The OrderBookmark class includes a constructor through which you will
+ * insert your bookmark's content. It also includes get and set methods
+ * you can use to retrieve and change the content.
+ */
+static class OrderBookmark extends XmlCursor.XmlBookmark {
+ public OrderBookmark (String text) { TEXT = text; }
+ public String TEXT;
+ public String getText() { return TEXT; }
+ public void setText(String newText) { TEXT = newText; }
+}
+</PRE>
+ <p>You can use instances of this class to store bookmarks at places in your
+ XML. The following excerpt of code creates a cursor and an instance of the
+ <span class="langinline">OrderBookmark</span> class. Then it uses the cursor
+ to insert the bookmark at the cursor's current location.</p>
+ <pre>
+ XmlCursor orderCursor = xmlDoc.newCursor();
+ OrderBookmark thisBookmark = new OrderBookmark("foo");
+ orderCursor.setBookmark(thisAnnotation);
+</pre>
+ <p class=relatedtopics>Related Topics</p>
+ <p><a href="conNavigatingXMLwithCursors.html">Navigating XML with Cursors</a></p>
+</div>
+<!-- InstanceEndEditable -->
+<script language="JavaScript">
+
+</script>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlbeans.apache.org
For additional commands, e-mail: commits-help@xmlbeans.apache.org