You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlbeans.apache.org by kk...@apache.org on 2005/02/04 01:39:43 UTC
svn commit: r151276 [2/3] - in xmlbeans/trunk: ./ docs/ docs/guide/
src/tools/org/apache/xmlbeans/impl/inst2xsd/ src/toolschema/
src/xmlpublic/org/apache/xmlbeans/
src/xpath_xquery/org/apache/xmlbeans/impl/xpath/saxon/
Modified: xmlbeans/trunk/docs/guide/conJavaTypesGeneratedFromUserDerived.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/conJavaTypesGeneratedFromUserDerived.html?view=diff&r1=151275&r2=151276
==============================================================================
--- xmlbeans/trunk/docs/guide/conJavaTypesGeneratedFromUserDerived.html (original)
+++ xmlbeans/trunk/docs/guide/conJavaTypesGeneratedFromUserDerived.html Thu Feb 3 16:39:39 2005
@@ -1,16 +1,29 @@
<!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" -->
+<!-- InstanceBeginEditable name="doctitle" -->
<title>Java Types Generated from Schema</title>
-<!-- InstanceEndEditable -->
+<!-- InstanceEndEditable -->
<!--(Meta)==========================================================-->
<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
-<!-- InstanceBeginEditable name="metatags" -->
+<!-- InstanceBeginEditable name="metatags" -->
<meta name="component" content="">
<!-- In the description metatag, please provide a BRIEF description of the topic contents. -->
@@ -23,7 +36,7 @@
<!-- InstanceBeginEditable name="head" -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
-
+
<!--(Meta)==========================================================-->
@@ -48,29 +61,29 @@
</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
+<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
+ <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
+ <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
+ <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">
@@ -88,33 +101,33 @@
<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:
+ <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>
+ <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
+ <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
+ <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
+public static float getStockPrice(java.io.File orderXML) throws Exception
{
PriceQuoteDocument docXML = PriceQuoteDocument.Factory.parse(orderXML);
PriceQuote quoteXML = docXML.getPriceQuote();
@@ -122,65 +135,65 @@
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
+ <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.
+<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
+ <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">
+ <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>
+ <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>
+ <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>
+ <tr>
<td>http://myco.com/sample.html</td>
<td width="155">SampleDocument</td>
<td>com.myco.sample.SampleDocument</td>
</tr>
- <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
+ <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)
+ <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"
+<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">
@@ -192,33 +205,33 @@
</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
+ <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
+ * 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
+ <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">
@@ -235,23 +248,23 @@
</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
+ <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.
*/
@@ -260,8 +273,8 @@
item.setAmount(12);
item.setPrice(560.00);
-/*
- * Use the new ItemType instance to set the value of the
+/*
+ * 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
@@ -270,12 +283,12 @@
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
+ <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
+ <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">
@@ -292,9 +305,9 @@
</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,
+ <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
{
@@ -305,40 +318,40 @@
// Methods omitted for this example
}
</pre>
- <p>You could create a new instance of the <span class="langinline">Gender</span>
+ <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
+ * 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
+ <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
+ <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>
+ <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.
@@ -348,12 +361,12 @@
System.out.println(intOrString.instanceType().getShortJavaName());
</pre>
<h3>Restrictions</h3>
- <p>XML schema restrictions on simple XMLBeans types are enforced. So, for
+ <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
+ <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">
@@ -365,31 +378,31 @@
</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>,
+ <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
+ <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
+ <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>
+ <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
+ <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>
@@ -397,19 +410,19 @@
<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
+ <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
+ <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"
+ <xs:element name="item" type="ps:itemType" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="threshold">
@@ -422,7 +435,7 @@
</xs:simpleType>
</xs:attribute>
</xs:complexType></pre>
- <p>Using types generated from the schema, you would be able to write the following
+ <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>
/*
@@ -431,7 +444,7 @@
*/
switch(priceElements[i].getThreshold().intValue())
{
- // Use the Threshold type's enumeration values to test for an attribute value.
+ // 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;
@@ -447,7 +460,7 @@
}</pre>
</div>
<p class="relatedtopics">Related Topics</p>
- <p><a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support for
+ <p><a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support for
Built-In Schema Types</a></p>
</div>
<!-- InstanceEndEditable -->
Modified: xmlbeans/trunk/docs/guide/conMethodsForGeneratedJavaTypes.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/conMethodsForGeneratedJavaTypes.html?view=diff&r1=151275&r2=151276
==============================================================================
--- xmlbeans/trunk/docs/guide/conMethodsForGeneratedJavaTypes.html (original)
+++ xmlbeans/trunk/docs/guide/conMethodsForGeneratedJavaTypes.html Thu Feb 3 16:39:39 2005
@@ -1,10 +1,23 @@
<!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 -->
+<!-- InstanceEndEditable -->
<!--(Meta)==========================================================-->
<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
@@ -34,160 +47,160 @@
<script language="JavaScript">
</script>
-<!-- InstanceBeginEditable name="body" -->
-<div id=topictitle>
+<!-- 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,
+ <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
+ <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
+ <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
+ <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
+ <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".
+ <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,
+ <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>
+ <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
+ <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>
+ <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
+ <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>
+ <div>
<pre><foo/></pre>
</div>
- <div>These methods are only generated when an element type is declared as
+ <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>
+ <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
+ <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>
+ <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>
+ <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>
+ <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
+ <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>
+ <blockquote>
<div>Returns or sets all of the Foo elements. </div>
- <div>
+ <div>
<pre>
// Get an array of the all of the purchase-order elements item children.
Item[] items = myPO.getItemArray();
</pre>
</div>
</blockquote>
- <div>
+ <div>
<hr size="1">
<pre>Type getFooArray(int index)
void setFooArray(Type newValue, int index)</pre>
</div>
- <blockquote>
+ <blockquote>
<div>Returns or sets the Foo child element at the specified index.</div>
- <div>
+ <div>
<pre>// Sets the value of the third item child element.
myPO.setItem(newItem, 2);</pre>
</div>
</blockquote>
- <div>
+ <div>
<hr size="1">
<pre>int sizeOfFooArray()</pre>
</div>
- <blockquote>
+ <blockquote>
<div>Returns the number of Foo child elements.</div>
- <div>
+ <div>
<pre>// Returns the number of item child elements.
int itemCount = myPO.sizeOfItemArray();</pre>
</div>
</blockquote>
- <div>
+ <div>
<hr size="1">
<pre>void removeFoo(int index)</pre>
</div>
- <blockquote>
+ <blockquote>
<div>Removes the Foo child element at the specified index.</div>
</blockquote>
- <div>
+ <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
+ <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>
+ <div>
<pre>/*
* Returns values of all the phone child elements of an employee element,
* where the phone element has been defined as xs:string.
@@ -196,62 +209,62 @@
</pre>
</div>
</blockquote>
- <div>
+ <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
+ <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>
+ <div>
<hr size="1">
<pre>void insertFoo(int index, FooType newValue)</pre>
</div>
- <blockquote>
+ <blockquote>
<div>Inserts the specified Foo child element at the specified index.</div>
</blockquote>
- <div>
+ <div>
<hr size="1">
<pre>void addFoo(FooType newValue)</pre>
</div>
- <blockquote>
+ <blockquote>
<div>Adds the specified Foo to the end of the list of Foo child elements.</div>
</blockquote>
- <div>
+ <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
+ <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>
+ <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,
+ <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>
+ <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
+ <blockquote>
+ <div>Determines or specifies whether the Foo element at the specified index
is nil.</div>
</blockquote>
- <div>
+ <div>
<hr size="1">
</div>
<div id="topictext"></div>
<p class=relatedtopics>Related Topics</p>
- <p><a href="conJavaTypesGeneratedFromUserDerived.html">Java Types Generated
+ <p><a href="conJavaTypesGeneratedFromUserDerived.html">Java Types Generated
from User-Derived Schema Types</a></p>
</div>
<!-- InstanceEndEditable -->
Modified: xmlbeans/trunk/docs/guide/conNavigatingXMLwithCursors.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/conNavigatingXMLwithCursors.html?view=diff&r1=151275&r2=151276
==============================================================================
--- xmlbeans/trunk/docs/guide/conNavigatingXMLwithCursors.html (original)
+++ xmlbeans/trunk/docs/guide/conNavigatingXMLwithCursors.html Thu Feb 3 16:39:39 2005
@@ -1,10 +1,23 @@
<!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 -->
+<!-- InstanceEndEditable -->
<!--(Meta)==========================================================-->
<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
@@ -19,7 +32,7 @@
<!-- InstanceEndEditable -->
<!--(Links)=========================================================-->
-<!-- InstanceBeginEditable name="head" -->
+<!-- InstanceBeginEditable name="head" -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
<!-- InstanceEndEditable -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
@@ -34,54 +47,54 @@
<script language="JavaScript">
</script>
-<!-- InstanceBeginEditable name="body" -->
+<!-- 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
+<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
+ <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>
+ <LI>
<DIV>Get and set values within the XML.</DIV>
- <LI>
- <DIV><a href="#adding_elements_attributes">Change the structure</a> of an
+ <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>
+ <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
+ <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>
+<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
+<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
+<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>
+<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
+<pre>public static void insertCursor(File orderFile) throws Exception
{
BatchWidgetOrderDocument xmlDoc = BatchWidgetOrderDocument.Factory.parse(orderFile);
XmlCursor orderCursor = xmlDoc.newCursor();
@@ -90,23 +103,23 @@
" / " + 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
+<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
+<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
+<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
+<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.
*/
@@ -124,15 +137,15 @@
<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
+<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
+ <p>For example, consider the following <employee> element, used in the
example below.</p>
<pre>
<employee>
@@ -154,8 +167,8 @@
<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
+ <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>
/**
@@ -164,8 +177,8 @@
*/
public void trySelectPath(XmlObject xml)
{
- /*
- * Inserts the cursor at the STARTDOC token (the very beginning,
+ /*
+ * Inserts the cursor at the STARTDOC token (the very beginning,
* before any elements).
*/
XmlCursor cursor = xml.newCursor();
@@ -173,7 +186,7 @@
cursor.toFirstChild();
// Pushes the cursor's current location onto the stack.
cursor.push();
- // Moves the cursor to just before the "work" <phone> element.
+ // 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();
@@ -181,27 +194,27 @@
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
+ <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
+ <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>
+ <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 -->
+<!-- InstanceEndEditable -->
<script language="JavaScript">
</script>
Modified: xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html?view=diff&r1=151275&r2=151276
==============================================================================
--- xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html (original)
+++ xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html Thu Feb 3 16:39:39 2005
@@ -1,10 +1,23 @@
<!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 -->
+<!-- InstanceEndEditable -->
<!--(Meta)==========================================================-->
<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
@@ -19,7 +32,7 @@
<!-- InstanceEndEditable -->
<!--(Links)=========================================================-->
-<!-- InstanceBeginEditable name="head" -->
+<!-- InstanceBeginEditable name="head" -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
<!-- InstanceEndEditable -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
@@ -34,34 +47,34 @@
<script language="JavaScript">
</script>
-<!-- InstanceBeginEditable name="body" -->
+<!-- InstanceBeginEditable name="body" -->
<h1> Selecting XML with XQuery and XPath</h1>
-<div id="topictext">
- <p>You can use XQuery and XPath 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 differing
- ways to use them. The methods are <span class="langinline">selectPath</span>
- and <span class="langinline">execQuery</span>, and you can call them from
- <a href="../reference/org/apache/xmlbeans/XmlObject.html"><span class="langinline">XmlObject</span></a>
- (or an object inheriting from it) or <a href="../reference/org/apache/xmlbeans/XmlCursor.html"><span class="langinline">XmlCursor</span></a>.
+<div id="topictext">
+ <p>You can use XQuery and XPath 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 differing
+ ways to use them. The methods are <span class="langinline">selectPath</span>
+ and <span class="langinline">execQuery</span>, and you can call them from
+ <a href="../reference/org/apache/xmlbeans/XmlObject.html"><span class="langinline">XmlObject</span></a>
+ (or an object inheriting from it) or <a href="../reference/org/apache/xmlbeans/XmlCursor.html"><span class="langinline">XmlCursor</span></a>.
The results for the methods differ somewhat. </p>
<h2>Using the selectPath Method</h2>
</div>
<div>
- <p>The <span class="langinline">selectPath</span> method is the most efficient
- way to execute XPath expressions. The <span class="langinline">selectPath</span>
- method is optimized for XPath. When you use XPath with the <span class="langinline">selectPath</span>
- method, the value returned is an array of values from the <em>current document</em>.
- In contrast, when you use <span class="langinline">execQuery</span>, the value
+ <p>The <span class="langinline">selectPath</span> method is the most efficient
+ way to execute XPath expressions. The <span class="langinline">selectPath</span>
+ method is optimized for XPath. When you use XPath with the <span class="langinline">selectPath</span>
+ method, the value returned is an array of values from the <em>current document</em>.
+ In contrast, when you use <span class="langinline">execQuery</span>, the value
returned is a <em>new document</em>.</p>
<h3>Calling from XmlObject</h3>
- <p>When called from <span class="langinline">XmlObject</span> (or a type that
- inherits from it), this method returns an array of objects. If the expression
- is executed against types generated from schema, then the type for the returned
+ <p>When called from <span class="langinline">XmlObject</span> (or a type that
+ inherits from it), this 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. </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
+ <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://openuri.org/selectPath">
@@ -85,20 +98,20 @@
</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:
+ 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://openuri.org/selectPath'" +
"$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
+ <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.
*/
@@ -112,74 +125,74 @@
} </pre>
<h3>Calling from XmlCursor</h3>
- <p>When called from an <span class="langinline">XmlCursor</span> instance, the
- <span class="langinline">selectPath</span> method retrieves a list of selections,
- or locations in the XML. The selections are remembered by the cursor instance.
- You can use methods such as <span class="langinline">toNextSelection</span>
+ <p>When called from an <span class="langinline">XmlCursor</span> instance, the
+ <span class="langinline">selectPath</span> method retrieves a list of selections,
+ 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>
+ <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 results 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
+ <p> For example, for a path such as <span class="langinline">$this/employees/employee</span>,
+ the results 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
+ <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
+ <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
+ <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
+ <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
+ <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>
+ <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 =
+ String xqNamespace =
"declare namespace xq='http://openuri.org/selectPath'";
// 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
+ /*
+ * 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
+ /*
+ * Loop through the list of selections, getting the value of
* each element.
*/
while (cursor.toNextSelection())
@@ -190,7 +203,7 @@
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, them print that element's
* value.
*/
@@ -200,56 +213,56 @@
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
+ <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>
+ <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>Using the execQuery Method</h2>
- <p>Use the <span class="langinline">execQuery</span> method to execute XQuery
- expressions that are more sophisticated than paths. These expressions include
- more sophisticated loops and FLWR (For, Let, Where, and Results) expressions.
+ <p>Use the <span class="langinline">execQuery</span> method to execute XQuery
+ expressions that are more sophisticated than paths. These expressions include
+ more sophisticated loops and FLWR (For, Let, Where, and Results) expressions.
</p>
- <p class="notepara"><strong>Note:</strong> Be sure to see the simpleExpressions
- sample in the SamplesApp application for a sampling of XQuery expressions
+ <p class="notepara"><strong>Note:</strong> Be sure to see the simpleExpressions
+ sample in the SamplesApp application for a sampling of XQuery expressions
in use.</p>
<h3>Calling from XmlObject</h3>
- <p>Unlike <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. If the <span class="langinline">XmlObject</span>
- instances resulting from the XQuery match a recognized XMLBeans type (the
- namespace and top level element name match up with an XMLBeans type) then
- the <span class="langinline">XmlObject</span> will be typed; otherwise the
+ <p>Unlike <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. If the <span class="langinline">XmlObject</span>
+ instances resulting from the XQuery match a recognized XMLBeans type (the
+ namespace and top level element name match up with an XMLBeans type) then
+ the <span class="langinline">XmlObject</span> will be typed; otherwise the
<span class="langinline">XmlObject</span> will be untyped.</p>
<h3>Calling from XmlCursor</h3>
</div>
-
-<div>
- <p>Calling <span class="langinline">execQuery</span> from an <span class="langinline">XmlCursor</span>
- instance returns a new <span class="langinline">XmlCursor</span> instance.
- The cursor returned is positioned at the beginning of a new xml document representing
- the query results, and you can use it to move through the results, cursor-style
- (for more information, see <a href="conNavigatingXMLwithCursors.html">Navigating
- XML with Cursors</a>). If the document resulting from the query execution
- represents a recognized XMLBeans type (the namespace and top level element
- name match up with an XMLBeans type) then the document resulting from the
- xquery will have that Java type; otherwise the resulting document will be
+
+<div>
+ <p>Calling <span class="langinline">execQuery</span> from an <span class="langinline">XmlCursor</span>
+ instance returns a new <span class="langinline">XmlCursor</span> instance.
+ The cursor returned is positioned at the beginning of a new xml document representing
+ the query results, and you can use it to move through the results, cursor-style
+ (for more information, see <a href="conNavigatingXMLwithCursors.html">Navigating
+ XML with Cursors</a>). If the document resulting from the query execution
+ represents a recognized XMLBeans type (the namespace and top level element
+ name match up with an XMLBeans type) then the document resulting from the
+ xquery will have that Java type; otherwise the resulting document will be
untyped.</p>
<h2>Related Topics</h2>
</div>
<p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p>
-<!-- InstanceEndEditable -->
+<!-- InstanceEndEditable -->
<script language="JavaScript">
</script>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlbeans.apache.org
For additional commands, e-mail: commits-help@xmlbeans.apache.org