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 00:29:29 UTC
svn commit: r345361 [2/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/build/site/docs/2.1.0/guide/conHandlingAny.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/build/site/docs/2.1.0/guide/conHandlingAny.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/build/site/docs/2.1.0/guide/conHandlingAny.html (added)
+++ xmlbeans/site/build/site/docs/2.1.0/guide/conHandlingAny.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1 @@
+<!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>Handling xs:any with the XMLBeans API </title>
<!-- InstanceEndEditable -->
<!--(Meta)==========================================================-->
<meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
<!-- InstanceBe
ginEditable 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>
<!-- InstanceBeginEdi
table name="body" -->
<h1> Handling xs:any with the XMLBeans API </h1>
<p>Compiling schema for use with XMLBeans generates a kind of custom API specific to your schema. This API includes types with accessors designed to get and set parts of the XML defined by the schema. But if you've compiled schema that includes <code>xs:any</code> particles, you may have noticed that XMLBeans doesn't generate accessors for these these particles. </p>
<p>For example, imagine the accessors generated by compiling the following schema snippet: </p>
<div id="topictext"><pre><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlbeans.apache.org/samples/any"
targetNamespace="http://xmlbeans.apache.org/samples/any" elementFormDefault="qualified">
<xs:element name="root">
<xs:complexType>
<xs:sequence>
<xs:element ref="stringelement"/>
<xs:any processContents="lax"/>
<xs:element
name="arrayofany">
<xs:complexType>
<xs:sequence>
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="stringelement" type="xs:string"/>
<xs:complexType name="ListOfStrings">
<xs:sequence>
<xs:element ref="stringelement" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="id" type="xs:string"/>
</xs:complexType>
</xs:schema></pre>
<p>After compilation, you'd have the follow methods for <code>Root</code>, the type that gives you access to the <code><root></code> element:</p>
<p><code>addNewArrayofany()</code></p>
<p><code>getArrayofany()</c
ode></p>
<p><code>getStringelement()</code></p>
<p><code>setArrayofany(Arrayofany)</code></p>
<p><code>setStringelement(String)</code></p>
<p><code>xgetStringelement()</code></p>
<p><code>xsetStringelement(XmlString)</code></p>
<p>What's missing? There's no <code>getAny</code> or <code>setAny</code>. How do you get or set the <code><root></code> element's second child? As it turns out, you do this by leaving behind (at least for a moment) JavaBeans-style accessors, and picking up any of a number of tools the API provides. These tools include:</p>
<ul>
<li><a href="#using_cursors">Using <code>XmlCursor</code> instances</a> to "walk" the XML, handling elements cursor-style.</li>
<li><a href="#using_xpath">Using the <code>selectPath</code> method</a> to retrieve the XML you want via XPath.</li>
<li><a href="#using_selectchildren">Using the <code>selectChildren</code> method</a> to retrieve child elements by nam
e.</li>
<li> <a href="#using_dom">Using the DOM API</a> to "walk" the node tree, handling elements by name.</li>
</ul>
<h2><a name="using_cursors"></a>Using Cursors to Add XML </h2>
<p>As described in <a href="conNavigatingXMLwithCursors.html">Navigating XML with Cursors</a>, with an <code>XmlCursor</code> instance you can traverse your XML instance's full infoset. A cursor views XML as tokens, and you move a cursor from one token to another as if they were cars in a train.</p>
<p>The following example illustrates how you might, in the course of building out the <code><root></code> document, create a second child element <code><anyfoo></code> where schema specifies <code>xs:any</code>. You add the element by creating it with a cursor, then (in lieu of a setter) using the <code>XmlCursor.copyXml</code> or <code>XmlCursor.moveXml</code> method to put the element where it needs to go.</p>
<pre>// Start by creating a <root> e
lement that will contain
// the children built by this code.
RootDocument rootDoc = RootDocument.Factory.newInstance();
RootDocument.Root root = rootDoc.addNewRoot();
// Add the first element, <stringelement>.
root.setStringelement("some text");
// Create an XmlObject in which to build the second
// element in the sequence, <anyfoo>. Here, the
// XmlObject instance is simply a kind of incubator
// for the XML. Later the XML will be moved into the
// document this code is building.
XmlObject anyFoo = XmlObject.Factory.newInstance();
// Add a cursor to do the work of building the XML.
XmlCursor anyFooCursor = anyFoo.newCursor();
anyFooCursor.toNextToken();
// Add the element in the schema's namespace, then add
// element content.
anyFooCursor.beginElement(new QName(m_namespaceUri, "anyfoo"));
anyFooCursor.insertChars("some text");
// Move the cursor back to the new element's top, where
// it can grab all of the element's XML.
anyFooCursor.toStartDoc();
anyFooCurso
r.toNextToken();
// Finally, move the XML into the <root> document by moving it
// from a position at one cursor to a position at
// another.
XmlCursor rootCursor = root.newCursor();
rootCursor.toEndToken();
anyFooCursor.moveXml(rootCursor);</pre>
<p>You might find that this build-and-move-cursor-to-cursor pattern is common when you're creating or moving XML when accessors aren't available. For example, you could do the same sort of thing when your schema defines a type that you want to place into an <code>xs:any</code> space in an instance. The following code adds a <code><stringelement> </code>element as a child of the <code><arrayofany></code> element, which schema defines as containing a sequence of <code>xs:any</code> particles. The <code><stringlement></code> element is simple, but it could just as easily be a complex schema type.</p>
<pre>// Create a simple <stringelement>.
StringelementDocument stringElementDoc =
StringelementDoc
ument.Factory.newInstance();
stringElementDoc.setStringelement("some text");
XmlCursor stringElementCursor = stringElementDoc.newCursor();
stringElementCursor.toFirstContentToken();
// Add a cursor to mark the position to which the new child
// XML will be moved.
XmlCursor arrayCursor = arrayOfAny.newCursor();
arrayCursor.toNextToken();
// Move the new <stringelement> into place.
stringElementCursor.moveXml(arrayCursor);
stringElementCursor.dispose();</pre>
<h2><a name="using_xpath"></a>Using XPath and the selectPath Method to Find XML </h2>
<p>XPath is a convenient, direct way to get at specific chunks of XML. In the XMLBeans API, you execute XPath expressions with the <code>XmlObject.selectPath</code> or <code>XmlCursor.selectPath</code> methods. The example in Java below assumes the following instance conforming to the schema introduced at the beginning of this topic:</p>
<pre><root xmlns="http://xmlbeans.apache.org/samples/any">
<strin
gelement>some text</stringelement>
<anyfoo>some text</anyfoo>
<arrayofany>
<stringelement>some text</stringelement>
<someelement>
<stringlist id="001">
<stringelement>string1</stringelement>
<stringelement>string2</stringelement>
</stringlist>
</someelement>
</arrayofany>
</root></pre>
<p>The following code uses XPath to reach the <code><stringelement></code> element because there is no accessor available. It then shifts the XML around a little, moving <code><stringelement></code> up in the hierarchy to replace its parent, <code><someelement></code>. </p>
<pre>public boolean editExistingDocWithSelectPath(RootDocument rootDoc)
{
String namespaceUri = "http://xmlbeans.apache.org/samples/any";
// Put a cursor at the top of the <arrayofany> element.
XmlCursor selectionCursor = rootDoc.getRoot().getAr
rayofany().newCursor();
// Use XPath and cursor movement to position the cursor at
// the <stringlist> element.
String namespaceDecl = "declare namespace any='" + namespaceUri + "'; ";
selectionCursor.selectPath(namespaceDecl +
"$this//any:someelement/any:stringlist");
selectionCursor.toNextSelection();
// Create a new cursor at the same location and move it to
// <stringelement>'s <someelement> parent.
XmlCursor editCursor = selectionCursor.newCursor();
editCursor.toParent();
// Move the <stringelement> element to this position, displacing
// the <someelement> downward. Remove the <someelement> XML,
// effectively replacing <someelement> with <stringlist>.
selectionCursor.moveXml(editCursor);
editCursor.removeXml();
editCursor.dispose();
return rootDoc.validate();
}</pre>
<h2><a name="using_selectchildren"></a>Using the selectChildren Method to Find XML </h2>
<
p>The <code>XmlObject.selectChildren</code> method you can retrieve an array of the child elements of a specified name. The method is overloaded to take <code>java.xml.namespace.QName</code> instances or strings as parameters. The following code (based on the instance used in the preceding example) simply finds the <code><anyfoo></code> element, an <code>xs:any</code>, and replaces it with an <code><anybar></code> element. </p>
<pre>public boolean editExistingDocWithSelectChildren(RootDocument rootDoc)
{
String namespaceUri = "http://xmlbeans.apache.org/samples/any";
RootDocument.Root root = rootDoc.getRoot();
// Select the <anyfoo> children of <root>.
XmlObject[] stringElements =
root.selectChildren(new QName(m_namespaceUri, "anyfoo"));
// If the element is there, replace it with another element.
if (stringElements.length > 0)
{
XmlCursor editCursor = stringElements[0].newCursor();
editCurso
r.removeXml();
editCursor.beginElement(new QName(namespaceUri, "anybar"));
editCursor.insertChars("some other text");
editCursor.dispose();
}
return rootDoc.validate();
}</pre>
<h2><a name="using_dom"></a>Using the DOM API to Find XML </h2>
<p>Through the <code>getDomNode</code> method (exposed by <code>XmlObject</code> and types generated from schema), you can get a live DOM node representing your XML. For example, calling <code>myElement.getDomNode()</code> will return a <code>org.w3c.dom.Node</code> instance representing the XML bound to <code>myElement</code>. If you're already familiar with DOM-style access to XML, this can be a familiar alternative for handling <code>xs:any</code> instances.</p>
<p> Using the instance introduced earlier in this topic, the following example adds a new <code><bar></code> element between the first and second children of the <code><arrayofany></code> element. The code
also ensures that the first and second children are <code><stringelement></code> and <code><someelement></code>, respectively.</p>
<pre>public boolean editExistingDocWithDOM(RootDocument rootDoc)
{
RootDocument.Root root = rootDoc.getRoot();
// Get the DOM nodes for the <arrayofany> element's children.
Node arrayOfAnyNode = root.getArrayofany().getDomNode();
// You don't have get* accessors for any of the <arrayofany>
// element's children, so use DOM to identify the first
// and second elements while looping through the child list.
NodeList childList = arrayOfAnyNode.getChildNodes();
Element firstElementChild = null;
Element secondElementChild = null;
// Find the first child element and make sure it's
// <stringelement>.
for (int i = 0; i < childList.getLength(); i++)
{
Node node = childList.item(i);
if (node.getNodeType() == Node.ELEMENT_NODE)
{
if (
node.getLocalName().equals("stringelement"))
{
firstElementChild = (Element)node;
break;
}
}
}
if (firstElementChild == null) {return false;}
// Find the second child element and make sure it's
// <someelement>.
Node node = firstElementChild.getNextSibling();
do
{
if (node.getNodeType() == Node.ELEMENT_NODE)
{
if (node.getLocalName().equals("someelement"))
{
secondElementChild = (Element)node;
break;
}
}
node = node.getNextSibling();
} while (node != null);
if (secondElementChild == null) {return false;}
// Create and insert a new <bar> element.
Element fooElement =
secondElementChild.getOwnerDocument().createElementNS("http://openuri.org","bar");
Node valueNode =
fooElement.getOwnerDocument().createTextNode("some text");
fooElement.appendChild(valueNode);
arrayOfAnyNode.insertBefore(fooElement, secondElementChild);
return rootDoc.validate();
}</pre>
</div>
<div>
<h2>Related Topics</h2>
</div>
<p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p>
<!-- InstanceEndEditable -->
<script language="JavaScript">
</script>
</body>
</html>
\ No newline at end of file
Added: xmlbeans/site/build/site/docs/2.1.0/guide/conIntroToTheSchemaTypeSystem.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/build/site/docs/2.1.0/guide/conIntroToTheSchemaTypeSystem.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/build/site/docs/2.1.0/guide/conIntroToTheSchemaTypeSystem.html (added)
+++ xmlbeans/site/build/site/docs/2.1.0/guide/conIntroToTheSchemaTypeSystem.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,229 @@
+<!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>Introduction to Schema Type Signatures</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> Introduction to Schema Type Signatures</h1>
+<div id="topictext">
+ <p>When you compile schema, the API generated from your schema is integrated
+ with the XMLBeans type system that represents the underlying XML schema. All
+ together, these types make up the <em>schema type system</em> to which your
+ code has access. When handling XML based on the schema, you typically call
+ methods of the API generated when you compiled the schema. However, for the
+ cases when you want to get information about the schema itself, you use the
+ schema type system API.</p>
+ <p>In the XMLBeans API, you have access to the system itself through <a href="../reference/org/apache/xmlbeans/SchemaTypeSystem.html"><span class="langinline">SchemaTypeSystem</span></a>
+ and related classes. These make up a kind of "meta-API," or a view
+ on the schema. You can use the schema type system API to discover the type
+ system at run time. See the reference topic on that interface for an overview
+ of the schema type system.</p>
+ <h2>Schema Type "Signatures"</h2>
+ <p>A schema is made up of schema components. Schema components are the pieces
+ of a schema, such as a type definition, an element declaration, attribute
+ declaration, and so on. To mirror these in the schema type system, a <a href="../reference/org/apache/xmlbeans/SchemaComponent.html"><span class="langinline">SchemaComponent</span></a>
+ instance represents a component in the underlying schema; separate components
+ have corresponding types. For example you would have a <span class="langinline"><a href="../reference/org/apache/xmlbeans/SchemaType.html">SchemaType</a></span>
+ object for a <span class="langinline">CustomerType</span> your schema defined,
+ or a <a href="../reference/org/apache/xmlbeans/SchemaGlobalElement.html"><span class="langinline">SchemaGlobalElement</span></a>
+ object for a global <span class="langinline">PurchaseOrder</span> element.
+ You would also have a <span class="langinline">SchemaType</span> for built-in
+ schema types, such as <span class="langinline">xs:string</span> or <span class="langinline">xs:datetime</span>.
+ XMLBean provides a "signature" to describe each type. You can retrieve
+ this signature by calling the SchemaType class's <span class="langinline">toString</span>
+ method.</p>
+ <p>The <span class="langinline">toString</span> method returns XMLBeans' version
+ of a unique signature for a schema type. This string is useful for debugging
+ because it describes a given type even when the type doesn't have a name.
+ </p>
+ <p class="notepara"><strong>Note:</strong> It's important to remember that this
+ signature is an XMLBeans convention, rather than a standard from the schema
+ working group. The working group has not yet standardized a signature for
+ XML schema types. As a result the signature you'll see from XMLBeans is subject
+ to change — whatever the schema working group comes up with in the end
+ (if anything) is probably what will be used by this API. In other words, don't
+ write a program to decode the signature.</p>
+ <p>You can use the following description to understand how a signature is constructed.</p>
+</div>
+<ul>
+ <li>
+ <div><strong>Global types.</strong> If the type has a name, it's a global
+ type. The following form is used:</div>
+ <div>
+ <div>
+ <pre>T=<localname>@<targetNamespace></pre>
+ </div>
+ </div>
+ <p>The "T" is for "type," of course. "localname"
+ is a convention used by qnames (qualified names), which include a local
+ name and the namespace URI (if any). So an example might be:</p>
+ <pre>T=customer@openuri.org</pre>
+ </li>
+ <li><strong>Document types and global attribute types.</strong> These correspond
+ to a special anonymous type containing one global element or attribute. These
+ special types are generated by XMLBeans to represent global types declared
+ with the <element> or <attribute> tag in schema. Because such
+ types are types, but are declared as elements or attributes, they require
+ special treatment. The following signature form is used:
+ <div>
+ <pre>
+D=<document-element-name>@<targetNamespace>
+R=<attribute-type-name>@<targetNamespace>
+</pre>
+ <div></div>
+ </div>
+ <div>
+ <div>Note that these are also the signatures of a type returned by a FooDocument.type
+ or FooAttribute.type method call.</div>
+ </div>
+ </li>
+ <li><strong>Anonymous types.</strong> If the type is anonymous, it is defined
+ as an element or attribute, or within a further anonymous type. In this case,
+ the signature is built by establishing the local context (in order words,
+ what is the anonymous type nested in?). From the local context, the larger
+ context is built recursively. In other words, the signature is built by giving
+ not only the anonymous type itself, but also by describing its context.
+ <p> The following rules are used for building a signature for an anonymous
+ type. </p>
+ <ul>
+ <li> It might be an anonymous type defined inside a local element or attribute,
+ which in turn is defined within something else:
+ <p>If the element is <span class="langinline" style="langinline">form="qualified"</span>
+ (the usual default):</p>
+ </li>
+ </ul>
+ </li>
+ <blockquote>
+ <div>
+ <pre>E=<eltname>|<signature of the type within which the elt is defined></pre>
+ </div>
+ <div>If the element is <span class="langinline" style="langinline">form="unqualified"</span>:</div>
+ <div>
+ <pre>U=<eltname>|<signature of the type within which the elt is defined></pre>
+ </div>
+ <div>If the attribute is <span class="langinline" style="langline">form="unqualified"</span>
+ (the usual default):</div>
+ <div>
+ <pre>A=<attrname>|<signature of the type within the attr is defined></pre>
+ </div>
+ <div>if the attribute is <span class="langinline" style="langinline">form="qualified"</span>:</div>
+ <div>
+ <pre>Q=<attrname>|<signature of the type within the attr is defined></pre>
+ </div>
+ </blockquote>
+ <ul>
+ <li>It might be an anonymous type defined a simple restriction, union, or
+ list definition:</li>
+ </ul>
+ <blockquote>
+ <div>
+ <pre>M=#|<signature of the containing union type></pre>
+ <p>(The # is a number indicating which union member it is, by source order
+ — such as 0,1,2, etc.)</p>
+ <pre>B=|<signature of the containing base type for a restriction></pre>
+ <pre>I=|<signature of the containing list type></pre>
+ </div>
+ </blockquote>
+ <ul>
+ <li>
+ <div> In the future if anonymous types are allowed in some other context,
+ there may be more codes.</div>
+ </li>
+ </ul>
+</ul>
+<h2>An Example</h2>
+<p>So, for example, if you have a type that describes the list items within an
+ attribute of an instance that looks like this:</p>
+<blockquote>
+ <div>
+ <pre> <root mylist="432 999 143 123"/></pre>
+ </div>
+</blockquote>
+<div> The schema, if done with lots of nested types, could look something like
+ this:</div>
+<blockquote>
+ <div>
+ <pre>
+<schema targetNamespace="myNamespace" elementFormDefault="qualified">
+ <element name="root">
+ <complexType>
+ <attribute name="mylist">
+ <simpleType>
+ <list>
+ <simpleType> <!--This is the type that the signature is for -->
+ <restriction base="xs:nonNegativeInteger">
+ <totalDigits value="3"/>..
+</pre>
+ </div>
+</blockquote>
+<div> The signature for the simpleType indicated in the example would be:</div>
+<blockquote>
+ <pre>I=|A=mylist|E=root|D=root@myNamespace</pre>
+</blockquote>
+<div>
+ <p>You could read this as: </p>
+</div>
+<blockquote>
+ <div>"The type of the list item | within the type of the mylist attribute's
+ type | within the type of the root element | within the document type for
+ <root> documents | in the myNamespace namespace".</div>
+</blockquote>
+<div>
+ <p>Note that the signature structure mirrors the Java class structure generated
+ by XMLBeans when compiling the schema. In other words, if you were to compile
+ a schema that included the preceding snippet, you would be able to access
+ an instance of the schema with Java code like the following:</p>
+ <pre>SchemaType sType = RootDocument.Root.MyList.Item.type;</pre>
+</div>
+<p class="relatedtopics">Related Topics</p>
+<p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p>
+<!-- InstanceEndEditable -->
+<script language="JavaScript">
+
+</script>
+</body>
+</html>
Added: xmlbeans/site/build/site/docs/2.1.0/guide/conJavaTypesGeneratedFromUserDerived.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/build/site/docs/2.1.0/guide/conJavaTypesGeneratedFromUserDerived.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/build/site/docs/2.1.0/guide/conJavaTypesGeneratedFromUserDerived.html (added)
+++ xmlbeans/site/build/site/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/build/site/docs/2.1.0/guide/conMethodsForGeneratedJavaTypes.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/build/site/docs/2.1.0/guide/conMethodsForGeneratedJavaTypes.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/build/site/docs/2.1.0/guide/conMethodsForGeneratedJavaTypes.html (added)
+++ xmlbeans/site/build/site/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/build/site/docs/2.1.0/guide/conNavigatingXMLwithCursors.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/build/site/docs/2.1.0/guide/conNavigatingXMLwithCursors.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/build/site/docs/2.1.0/guide/conNavigatingXMLwithCursors.html (added)
+++ xmlbeans/site/build/site/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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlbeans.apache.org
For additional commands, e-mail: commits-help@xmlbeans.apache.org