You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlbeans.apache.org by ce...@apache.org on 2005/06/17 22:04:27 UTC
svn commit: r191187 - in /xmlbeans/trunk/docs/guide: conHandlingAny.html
conSelectingXMLwithXQueryPathXPath.html conValidationWithXmlBeans.html
tools.html
Author: cezar
Date: Fri Jun 17 13:04:26 2005
New Revision: 191187
URL: http://svn.apache.org/viewcvs?rev=191187&view=rev
Log:
Adding topic on handling xs:any, topic on using the API to validate, topic on tools included with the release, and updating the XQuery/XPath topic with latest, more complete info. Contributed by Steve Traut
Added:
xmlbeans/trunk/docs/guide/conHandlingAny.html
xmlbeans/trunk/docs/guide/conValidationWithXmlBeans.html
xmlbeans/trunk/docs/guide/tools.html
Modified:
xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html
Added: xmlbeans/trunk/docs/guide/conHandlingAny.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/conHandlingAny.html?rev=191187&view=auto
==============================================================================
--- xmlbeans/trunk/docs/guide/conHandlingAny.html (added)
+++ xmlbeans/trunk/docs/guide/conHandlingAny.html Fri Jun 17 13:04: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;">
<!-- 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> 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()</code></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 name.</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> element 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();
anyFooCursor.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 =
StringelementDocument.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">
<stringelement>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().getArrayofany().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();
editCursor.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
Modified: xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html?rev=191187&r1=191186&r2=191187&view=diff
==============================================================================
--- xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html (original)
+++ xmlbeans/trunk/docs/guide/conSelectingXMLwithXQueryPathXPath.html Fri Jun 17 13:04:26 2005
@@ -50,34 +50,33 @@
<!-- 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>.
- The results for the methods differ somewhat. </p>
- <h2>Using the selectPath Method</h2>
+ <p>You can use XPath and XQuery to retrieve specific pieces of XML as you might
+ retrieve data from a database. XQuery and XPath provide a syntax for specifying
+ which elements and attributes you're interested in. The XMLBeans API provides
+ two methods for executing XQuery and XPath expressions, and two ways to use them. The methods are <span class="langinline">selectPath</span>
+ for XPath and <span class="langinline">execQuery</span> for XQuery. </p>
+ <p>You can call them from and <a href="../reference/org/apache/xmlbeans/XmlObject.html"><span class="langinline"> XmlObject</span></a> instance (or a generated type inheriting from it) or an <a href="../reference/org/apache/xmlbeans/XmlCursor.html"><span class="langinline">XmlCursor</span></a> instance.
+ As noted below, each of the four methods works slightly differently; be sure to keep these differences in mind when choosing your approach.</p>
+ <p class="notepara"><strong>Note:</strong> Both XQuery and complex XPath expressions require additional classes on the class path, as noted in the sections that follow. Also, be sure to see the XMLBeans <a href="../../../documentation/conInstallGuide.html">installation instructions</a>. </p>
+ <h2><a name="xpath_selectpath"></a>Using XPath with the selectPath Method</h2>
</div>
<div>
- <p>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>You can execute XPath expressions use the <span class="langinline">selectPath</span> method. When you use XPath with the <span class="langinline">selectPath</span>
+ method, the value returned is view of values from the <em>current document</em> — not a copy of those values. In other words, changes your code makes to XML returned by the selectPath method change the XML in the document queried against. In contrast, with XQuery executed using the <span class="langinline">execQuery</span> method, the value returned is a <em>copy of values in the XML queried against</em>.</p>
+ <p> Note that XPath itself does not provide syntax for declaring prefix to URI bindings. For user convenience, we allow XQuery syntax to be used for such purposes. You can consult the latest XQuery draft when using syntax for declaring namespaces.</p>
+ <blockquote>
+ <p><strong>Note:</strong> By default, XMLBeans supports only very simple XPath expressions. To execute complex expressions — such as those with predicates, function calls, and the like — you will need xbean_xpath.jar on your class path. This JAR is among those created when you build XMLBeans from source.</p>
+ </blockquote>
+ <h3>Calling XmlObject.selectPath</h3>
<p>When called from <span class="langinline">XmlObject</span> (or a type that
- inherits from it), this method returns an array of objects. If the expression
+ inherits from it), the <code>selectPath</code> method returns an array of objects. If the expression
is executed against types generated from schema, then the type for the returned
- array is one of the Java types corresponding to the schema. </p>
+ array is one of the Java types corresponding to the schema, and you can cast it accordingly. </p>
<p>For example, imagine you have the following XML containing employee information.
You've compiled the schema describing this XML and the types generated from
schema are available to your code.</p>
<pre>
-<xq:employees xmlns:xq="http://openuri.org/selectPath">
+<xq:employees xmlns:xq="http://xmlbeans.apache.org/samples/xquery/employees">
<xq:employee>
<xq:name>Fred Jones</xq:name>
<xq:address location="home">
@@ -102,31 +101,27 @@
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)')]"
+ "declare namespace xq='http://xmlbeans.apache.org/samples/xquery/employees';" +
+ "$this/xq:employees/xq:employee/xq:phone[contains(., '(206)')]";
</pre>
<p>Notice in the query expression that the variable <span class="langinline">$this</span>
represents the current context node (the <span class="langinline">XmlObject</span>
that you are querying from). In this example you are querying from the document
level <span class="langinline">XmlObject</span>.</p>
<p>You could then print the results with code such as the following:</p>
- <pre>
-/*
- * Retrieve the matching phone elements and assign the results to the corresponding
- * generated type.
- */
+ <pre>// Retrieve the matching phone elements and assign the results to the corresponding
+// generated type.
PhoneType[] phones = (PhoneType[])empDoc.selectPath(queryExpression);
-/*
- * Loop through the results, printing the value of the phone element.
- */
+
+// Loop through the results, printing the value of the phone element.
for (int i = 0; i < phones.length; i++)
{
System.out.println(phones[i].stringValue());
-} </pre>
+}</pre>
- <h3>Calling from XmlCursor</h3>
+ <h3>Calling XmlCursor.selectPath</h3>
<p>When called from an <span class="langinline">XmlCursor</span> instance, the
- <span class="langinline">selectPath</span> method retrieves a list of selections,
+ <span class="langinline">selectPath</span> method retrieves a list of <em>selections</em>,
or locations in the XML. The selections are remembered by the cursor instance.
You can use methods such as <span class="langinline">toNextSelection</span>
to navigate among them.</p>
@@ -137,7 +132,7 @@
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 cursor instance from which you called <code>selectPath</code> would include a selection for each employee element found by
the expression. Note that the variable <span class="langinline">$this</span>
is always bound to the current context node, which in this example is the
document. After calling the <span class="langinline">selectPath</span> method,
@@ -179,22 +174,20 @@
{
// Declare the namespace that will be used.
String xqNamespace =
- "declare namespace xq='http://openuri.org/selectPath'; ";
+ "declare namespace xq='http://xmlbeans.apache.org/samples/xquery/employees';";
// Insert a cursor and move it to the first element.
XmlCursor cursor = xml.newCursor();
cursor.toFirstChild();
- /*
- * Save the cursor's current location by pushing it
- * onto a stack of saved locations.
- */
+
+ // Save the cursor's current location by pushing it
+ // onto a stack of saved locations.
cursor.push();
// Query for zip elements.
cursor.selectPath(xqNamespace + "$this//xq:zip");
- /*
- * Loop through the list of selections, getting the value of
- * each element.
- */
+
+ // Loop through the list of selections, getting the value of
+ // each element.
while (cursor.toNextSelection())
{
System.out.println(cursor.getTextValue());
@@ -203,10 +196,9 @@
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.
- */
+
+ // Move the cursor to the first selection, then print that element's
+ // value.
cursor.toNextSelection();
System.out.println(cursor.getTextValue());
// Dispose of the cursor.
@@ -229,37 +221,113 @@
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>
- <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>
+ <h2><a name="xquery_execquery"></a>Using XQuery with the execQuery Method</h2>
+ <p>You use the <span class="langinline">execQuery</span> method to execute XQuery
+ expressions. With XQuery expressions, XML returned is a copy of XML in the document queried against. In other words, changes your code makes to the values returned by <code>execQuery</code> are not reflected in the document queried against.</p>
+ <blockquote>
+ <p><strong>Note:</strong> To execute XQuery expressions, you must have the Saxon 8.1.1 JAR on your class path. Look for the download at the <a href="http://sourceforge.net/project/showfiles.php?group_id=29872&package_id=21888">Saxon web site</a>. This JAR is also included in the lib directory when you build XMLBeans from source.</p>
+ </blockquote>
+ <h3>Calling XmlObject.execQuery</h3>
+ <p>As with <span class="langinline">selectPath</span>, calling <span class="langinline">execQuery</span>
from an <span class="langinline">XmlObject</span> instance will return an
- <span class="langinline">XmlObject</span> array. 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>
+ <span class="langinline">XmlObject</span> array.</p>
+ <p> The following example retrieves work <code><zip></code> elements from the incoming XML, adding the elements as children to a new <code><zip-list></code> element.</p>
+ <pre>public boolean collectZips(XmlObject empDoc)
+{
+ String namespaceDeclaration =
+ "declare namespace xq='http://xmlbeans.apache.org/samples/xquery/employees';";
+ // The query is designed to return results, so return
+ // true if it does.
+ boolean hasResults = false;
+
+ // The expression: Get the <zip> elements and return them as children
+ // of a new <zip-list> element.
+ String queryExpression =
+ "let $e := $this/xq:employees " +
+ "return " +
+ "<zip-list> " +
+ "{for $z in $e/xq:employee/xq:address/xq:zip " +
+ "return $z} " +
+ "</zip-list>";
+
+ // Execute the query. Results will be copies of the XML queried against,
+ // stored as members of an XmlObject array.
+ XmlObject[] results =
+ empDoc.execQuery(namespaceDeclaration + queryExpression);
+
+ // Print the results.
+ if (results.length > 0)
+ {
+ hasResults = true;
+ System.out.println("The query results: \n");
+ System.out.println(results[0].toString() + "\n");
+ }
+ return hasResults;
+}</pre>
+ <h3>Calling XmlCursor.execQuery</h3>
</div>
<div>
- <p>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>
+ <p>Unlike the <code>selectPath</code> method called from a cursor, the <span class="langinline">execQuery</span> method doesn't return <code>void</code>. Instead it returns an <span class="langinline">XmlCursor</span> instance positioned at the beginning of a new XML document representing
+ the query results. Rather than accessing results as selections, you use the cursor to move through the results in typical cursor fashion (for more information, see <a href="conNavigatingXMLwithCursors.html">Navigating
+ XML with Cursors</a>). The models are very different.</p>
+ <p>As always, you can cast the results to a type generated from schema if you know that the results conform to that type.</p>
+ <p>The following example retrieves work <code><phone></code> elements from the incoming XML, then changes the number in the results.</p>
+ <pre>public boolean updateWorkPhone(XmlObject empDoc)
+{
+ boolean hasResults = false;
+
+ // A cursor instance to query with.
+ XmlCursor empCursor = empDoc.newCursor();
+ empCursor.toNextToken();
+
+ // The expression: Get the <employee> elements with <state> elements whose
+ // value is "WA".
+ String queryExpression =
+ "for $e in $this/xq:employees/xq:employee " +
+ "let $s := $e/xq:address/xq:state " +
+ "where $s = 'WA' " +
+ "return $e//xq:phone[@location='work']";
+
+ // Execute the query. Results, if any, will be available at
+ // the position of the resultCursor in a new XML document.
+ XmlCursor resultCursor =
+ empCursor.execQuery(namespaceDeclaration + queryExpression);
+
+ System.out.println("The query results, element copies made " +
+ "from the received document: \n");
+ System.out.println(resultCursor.getObject().toString() + "\n");
+
+ // If there are results, the results will be children of the fragment root
+ // where the new cursor is positioned. This statement tests for children
+ // and moves the cursor if to the first if it exists.
+ if (resultCursor.toFirstChild())
+ {
+ hasResults = true;
+ // Use the cursor to loop through the results, printing each sibling
+ // <employee>element returned by the query.
+ int i = 0;
+ do
+ {
+ // Change the phone numbers.
+ XmlCursor editCursor = resultCursor.newCursor();
+ editCursor.toLastAttribute();
+ editCursor.toNextToken();
+ editCursor.removeXml();
+ editCursor.insertChars("(206)555-1234");
+ } while (resultCursor.toNextSibling());
+
+ resultCursor.toStartDoc();
+ System.out.println("The query results after changes: \n");
+ System.out.println(resultCursor.getObject().toString() + "\n");
+
+ System.out.println("The received document -- note that it is unchanged. " +
+ "Changes were made to the copy created by the execQuery method. \n");
+ System.out.println(empDoc + "\n");
+ }
+ return hasResults;
+}</pre>
+ <h2>Related Topics</h2>
</div>
<p><a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a></p>
<!-- InstanceEndEditable -->
Added: xmlbeans/trunk/docs/guide/conValidationWithXmlBeans.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/conValidationWithXmlBeans.html?rev=191187&view=auto
==============================================================================
--- xmlbeans/trunk/docs/guide/conValidationWithXmlBeans.html (added)
+++ xmlbeans/trunk/docs/guide/conValidationWithXmlBeans.html Fri Jun 17 13:04:26 2005
@@ -0,0 +1 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- 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 xmlns="http://www.w3.org/1999/xhtml">
<head>
<!-- InstanceBeginEditable name="doctitle" -->
<title>XMLBeans Tools</title>
<!-- InstanceEndEditable -->
<!--(Meta)==========================================================-->
<meta http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<!-- InstanceBeginEditable name="metatags" -->
<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" />
<!-- InstanceEndEditable -->
<!--(Links)=========================================================-->
<!-- InstanceBeginEditable name="head" -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css" />
<!-- InstanceEndEditable -->
<link href="../xmlbeans.css" rel="stylesheet" type="text/css">
<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> Validation with XMLBeans </h1>
<p>An essential part of schema-related work is validating instances based on the schema. XMLBeans provides a number of ways for you to ensure your instances are valid, both at the command line and programmatically at run time. </p>
<h2>Validation, XMLBeans-Style</h2>
<p>XMLBeans' schema-oriented approach to handling XML makes validation an important part of its work. However, XMLBeans has a specific approach to validation that's helpful to keep in mind when you're working.</p>
<p>Validation features include the following: </p>
<ul>
<li>Generally, XMLBeans validates when you ask it to. It <a href="#no_parsing_validation">doesn't validate while parsing</a> -- nor, by default, while your code is updating the bound instance along the way through, say, set* methods (although you can change this behavior).</li>
<li>You can <a href="#validation_apis">validate programmatically</a> or by using one of the <a href="#command_line_validation">command-line tools</a> provided by XMLBeans. </li>
<li>The <code>validate</code> methods return <code>true</code> or <code>false</code> to indicate whether the instance is valid. You can also <a href="#retrieving_error_messages">capture error information</a> if you want to when validating programmatically. To do this, you specify an error listener.</li>
<li>You can tell XMLBeans at parse time that it <a href="#validation_as_you_go">should validate during calls to set* methods</a>. Note that this means validation <em>after</em> parsing, not during, and that it can slow performance. Also note validation would not occur as changes are made by a cursor.</li>
<li>XMLBeans does validate <em>schema</em> when compiling the schema through scomp or the xmlbean Ant task. (When you're compiling schema programmatically, you can disable validation with the <code>XmlOptions.setCompileNoValidation</code> method.)</li>
</ul>
<h2>XMLBeans Validates Only When You Ask It To — Generally</h2>
<p>Given XMLBeans' focus on schema-oriented work, it's natural to assume that it might check up on you as your code is making changes to an instance — that it might prevent your code from doing something that would render the instance invalid along the way. But, by default, it doesn't. The design of XMLBeans assumes that an XML instance might go through multiple invalid states before changes are complete. As a result, generally speaking, XMLBeans keeps quiet while changes are occurring.</p>
<blockquote>
<p><span class="notepara"><strong>Note:</strong> The exception to this rule is that XMLBeans validates your schema when you're compiling it using scomp or the xmlbean Ant task.</span></p>
</blockquote>
<h3><a name="no_parsing_validation" id="no_parsing_validation"></a>XMLBeans Does Not Validate an Instance While Parsing It</h3>
<p>But it's not hard to get the impression that it does. For example, imagine that you're parsing an XML instance using a statement such as the following:</p>
<blockquote>
<pre>MyXmlSchemaType myXmlBean = MyXmlSchemaType.Factory.parse(myXml);</pre>
</blockquote>
<p>If the namespace declared in the myXml instance doesn't match the target namespace of the schema from which MyXmlSchemaType was generated, parsing will fail with an error message. Likewise, you'll get messages for other mismatches between the shape of myXml and the XML shape described by the schema.</p>
<p>But these failures and messages don't result from validation. Instead, all XMLBeans is doing is a not-very-deep check to see if the instance <em>shouldn't be bound</em> to the XMLBeans type generated from schema. In other words, the checking done at the parsing stage is simply a "low bar" effort to avoid trouble down the road.</p>
<p>Validation, on the other hand, is designed to verify that the instance conforms completely to the schema.</p>
<p>So you can validate in any of three ways:</p>
<ul>
<li>On request, using a validate method.</li>
<li>On the fly, using the "validate on set" option.</li>
<li>Using one of the command-line tools. </li>
</ul>
<h2>Tools for Validating</h2>
<p>XMLBeans tools for validation include command-line tools and APIs. </p>
<h3><a name="command_line_validation" id="command_line_validation"></a>Command-line Tools for Validation </h3>
<p>Among the many <a href="tools.html">command-line tools</a> XMLBeans provides, you'll find two that are specifically for validation. </p>
<ul>
<li><a href="tools.html#validate">validate</a> tool — A validation command-line tool
in which you specify the instance to validate and the schema to validate it against.
<p>You'll find the <code>validate</code> tool in the bin directory of your XMLBeans installation. </p>
</li>
<li><a href="tools.html#svalidate">svalidate</a> tool — Identical to the validate tool, except that svalidate uses a streaming model that supports validation against much larger schemas.
<p>You'll find the <code>svalidate</code> tool in the bin directory of your XMLBeans installation. </p>
</li>
</ul>
<h3><a name="validation_apis" id="validation_apis"></a>APIs for Validation </h3>
<p>XMLBeans APIs provide ways for you to <a href="#validation_when_you_ask">validate on request</a> — say, after your code has finished editing an instance and before it passes the instance elsewhere. You can also specify that your calls to set* methods should <a href="#validation_as_you_go">validate on-the-fly</a> the instance that is being edited; you do this as an option when your code creates the XMLBeans schema type instance.</p>
<h4><a name="validation_when_you_ask" id="validation_when_you_ask"></a>Validation When You Ask for It</h4>
<p>Both the <code>validate</code> methods described here are available from any XMLBeans type generated from schema during schema compilation (because all such types inherit from <code>XmlObject</code>). Both methods are designed to validate the instance that is bound to the type from which the method is called. For example, if your schema defines a <code><purchase-order></code> element with <code><item></code> children, calling the <code>myItem.validate()</code> method will validate the <code><item></code> instance bound to <code>Item</code>. This includes the <code><item></code> element's children, but not the <code><purchase-order></code> element or the <code><item></code> element's siblings.</p>
<p>Both methods return a <code>boolean</code> to indicate validity, and one of the methods lets you specify options for validation, such as capturing messages about why an invalid instance is invalid.</p>
<ul>
<li><code>XmlObject.validate()</code> — Returns <code>true</code> if the instance is valid.</li>
<li><code>XmlObject.validate(XmlOptions)</code> — Returns <code>true</code> if the instance is valid, using the specified <code>XmlOptions</code> instance to customize validation.
<p>In particular, you can use the <code>XmlOptions.setErrorListener</code> method to specify a <code>Collection</code> instance with which to capture messages pertaining to invalid instances. For an example, see the Javadoc for this method. </p>
<p>Through the <code>XmlOptions</code> class, you can specify options to use during validation. The options include the following: </p>
</li>
<li>XmlOptions.setErrorListener -- Specifies a Collection instance that XMLBeans should use to store errors that occur during validation (or, in other contexts, during parsing and compilation). </li>
<li>XmlOptions.setValidateTreatLaxAsSkip -- Tells XMLBeans that it should skip elements matching an particle with contentModel="lax" during validation. </li>
</ul>
<p>Also, see the <a href="#validation_as_you_go">section on validating as you go</a> for information about using the <code>XmlOptions.setValidateOnSet</code> method.</p>
<h3><a name="retrieving_error_messages" id="retrieving_error_messages"></a>Retrieving Error Messages About Invalid XML</h3>
<p>When you'll be validating with one of the <code>validate</code> methods, you can specify a <code>java.util.Collection</code> implementation as an error listener. As validation occurs, errors are added to the listener. After validation (and if the instance is found to be invalid) you can examine the errors. Here's an example:</p>
<pre>// Set up the validation error listener.
ArrayList validationErrors = new ArrayList();
XmlOptions validationOptions = new XmlOptions();
validationOptions.setErrorListener(validationErrors);
MyDocument myDoc = MyDocument.Factory.parse(pathToXml);
// Do some editing to myDoc.
// During validation, errors are added to the ArrayList for
// retrieval and printing by the printErrors method.
boolean isValid = myDoc.validate(validationOptions);
// Print the errors if the XML is invalid.
if (!isValid)
{
Iterator iter = validationErrors.iterator();
while (iter.hasNext())
{
System.out.println(">> " + iter.next() + "\n");
}
}</pre>
<h3><a name="validation_as_you_go" id="validation_as_you_go"></a>Validation As You Go</h3>
<p>By default, an XML instance will not be validated at run time as your code makes changes. However, you can change this behavior for limited on-the-fly validation. To do this, you specify the "validate on set" option when you create the XMLBeans type instance — you do this with the <code>XmlOptions.setValidateOnSet</code> method. </p>
<p>When you specify this option, XMLBeans with throw an exception when your code invalidates the XML through a set* method. Note that you can't specify an error listener for use in conjunction with this means of validating. Also, with "validate on set," only simple schema types will be validated. Schema types not validated by this approach include, for example, those defining elements with attributes or elements with children.</p>
<p>Because its functionality is limited to simple schema types and it validates for set* method calls, you should regard this validation approach as a debugging tool, rather than an alternative to using a <code>validate</code> method. For example, you might use it to determine which errant bit of code is creating an invalid chunk of XML.</p>
<p class="notepara"><strong>Note:</strong> This sort of validation is not supported during changes you make using an <code>XmlCursor</code> instance.</p>
<p>Among the methods you can use to create an XMLBeans instance — the <code>parse</code> methods and the <code>newInstance</code> method — you'll find versions that take an <code>XmlOptions</code> instance as a parameter. Specifying this option would look something like the following: </p>
<pre>XmlOptions validateOptions = new XmlOptions();
// Tell XMLBeans you want to validate on the fly.
validateOptions.setValidateOnSet();
// Create the new instance, specifying the option.
PurchaseOrder newPo = PurchaseOrder.Factory.newInstance(validateOptions);
// ... Code to edit the instance via get and set methods ... </pre>
<div>
<p class="relatedtopics"> Related Topics </p>
<p> <a href="conGettingStartedwithXMLBeans.html">Getting Started with XMLBeans</a> </p>
</div>
<!-- InstanceEndEditable -->
<script language="JavaScript">
</script>
</body>
</html>
\ No newline at end of file
Added: xmlbeans/trunk/docs/guide/tools.html
URL: http://svn.apache.org/viewcvs/xmlbeans/trunk/docs/guide/tools.html?rev=191187&view=auto
==============================================================================
--- xmlbeans/trunk/docs/guide/tools.html (added)
+++ xmlbeans/trunk/docs/guide/tools.html Fri Jun 17 13:04:26 2005
@@ -0,0 +1,542 @@
+<!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>
+ XMLBeans Tools
+ </title>
+ <!-- InstanceEndEditable --> <!--(Meta)==========================================================-->
+ <meta http-equiv=Content-Type content="text/html; charset=$CHARSET;">
+ <!-- InstanceBeginEditable name="metatags" -->
+ <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">
+ <!-- InstanceEndEditable --> <!--(Links)=========================================================--> <!-- InstanceBeginEditable name="head" --> <link href="../xmlbeans.css" rel="stylesheet" type="text/css"> <!-- InstanceEndEditable --> <link href="../xmlbeans.css" rel="stylesheet" type="text/css">
+ <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> XMLBeans Tools </h1>
+<p> XMLBeans includes several command-line tools you might find handy as shortcuts
+ for common tasks. You'll find these tools in the bin directory of the XMLBeans
+ installation or source tree.</p>
+<dl>
+ <dt> <a href="#dumpxsb">dumpxsb (XSB File Dumper)</a> </dt>
+ <dd> Prints the contents of an XSB file in human-readable form. </dd>
+ <dt> </dt>
+ <dt> <a href="#inst2xsd">inst2xsd (Instance to Schema Tool)</a> </dt>
+ <dd> Generates XML schema from XML instance files. </dd>
+ <dt> </dt>
+ <dt> <a href="#scomp">scomp (Schema Compiler)</a> </dt>
+ <dd> Compiles a schema into XMLBeans classes and metadata. </dd>
+ <dt> </dt>
+ <dt> <a href="#scopy">scopy (Schema Copier)</a> </dt>
+ <dd> Copies the XML schema at the specified URL to the specified file. </dd>
+ <dt> </dt>
+ <dt> <a href="#sdownload">sdownload (Schema Downloader)</a> </dt>
+ <dd> Maintains "xsdownload.xml," an index of locally downloaded XSD
+ files. URLs that are specified are downloaded if they aren't already cached.
+ If no files or URLs are specified, all indexed files are relevant. </dd>
+ <dt> </dt>
+ <dt> <a href="#sfactor">sfactor (Schema Factoring Tool)</a> </dt>
+ <dd> Factors redundant definitions out of a set of schemas and uses imports
+ instead. </dd>
+ <dt> </dt>
+ <dt> <a href="#svalidate">svalidate (Streaming Instance Validator)</a> </dt>
+ <dd> Validates a schema definition and instances within the schema. </dd>
+ <dt> </dt>
+ <dt> <a href="#validate">validate (Instance Validator)</a> </dt>
+ <dd> Validates an instance against a schema. </dd>
+ <dt> </dt>
+ <dt> <a href="#xpretty">xpretty (XML Pretty Printer)</a> </dt>
+ <dd> Pretty prints the specified XML to the console. </dd>
+ <dt> </dt>
+ <dt> <a href="#xsd2inst">xsd2inst (Schema to Instance Tool)</a> </dt>
+ <dd> Prints an XML instance from the specified global element using the specified
+ schema. </dd>
+ <dt> </dt>
+ <dt> <a href="#xsdtree">xsdtree (Schema Type Hierarchy Printer)</a> </dt>
+ <dd> Prints an inheritance hierarchy of the types defined in a schema. </dd>
+ <dt> </dt>
+ <dt> <a href="antXmlbean.html">xmlbean Ant task</a> </dt>
+ <dd> Compiles a set of XSD and/or WSDL files into XMLBeans types. </dd>
+</dl>
+<h2> <a name="dumpxsb"></a>dumpxsb (XSB File Dumper) </h2>
+<p> Prints the contents of an XSB file in human-readable form. An XSB file contains
+ schema meta information needed to perform tasks such as binding and validation.
+ "XSB" stands for XML Schema Binary.</p>
+<h3> Syntax </h3>
+<pre><strong>dumpxsb </strong><em>myfile.xsb</em></pre>
+<h4> Options </h4>
+<dl>
+ <dt> <em>myfile.xsb</em> </dt>
+ <dd> The name of an XSB file. </dd>
+</dl>
+<h3> Example </h3>
+<p> The following command and output example use an XSB file generated by compiling
+ the schema (in EasyPo.xsd) that accompanies the SubstitutionGroup sample. </p>
+<pre>dumpxsb PurchaseOrderDocument.xsb</pre>
+<p> Output: </p>
+<pre>PurchaseOrderDocument.xsb
+ Magic cookie: da7ababe
+ Major version: 2
+ Minor version: 22
+ Release number: 0
+ Filetype: FILETYPE_SCHEMAPOINTER
+ String pool (2):
+ 1 = "schema.system.s633ECC92E6CC0ACA137B11B7B38CA3A8"
+ Type system: schema.system.s633ECC92E6CC0ACA137B11B7B38CA3A8</pre>
+<h2> <a name="inst2xsd"></a>inst2xsd (Instance to Schema Tool) </h2>
+<p> Generates XML schema from XML instance files. </p>
+<h3> Syntax </h3>
+<pre><strong>inst2xsd </strong>[<em>options</em>] <em>instance.xml</em>*</pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-design </strong>[<strong>rd </strong>|<strong> ss </strong>|<strong>
+ vb</strong>] </dt>
+ <dd> The XML schema design type to use for the generated schema. </dd>
+ <dd> <strong>rd</strong> — Use russian doll design; local elements and
+ local types. </dd>
+ <dd> <strong>ss</strong> — Use salami slice design; global elements and
+ local types. </dd>
+ <dd> <strong>vb</strong> (default) — Use venetian blind design; local
+ elements and global complex types. </dd>
+</dl>
+<dt> <strong>-simple-content-types</strong> [<strong>smart</strong> | <strong>string</strong>]
+</dt>
+<dd> The manner for detecting content types (leaf text) </dd>
+<dd> <strong>smart</strong> (default) — Use a likely type, such as xs:byte
+ for a value of "123". </dd>
+<dd> <strong>string</strong> — Use xs:string as the type. </dd>
+<dt> </dt>
+<dt> <strong>-enumerations</strong> [<strong>never</strong> | <em>number</em>]
+</dt>
+<dd> Whether to use enumerations. </dd>
+<dd> <strong>never</strong> — Never use enumerations. </dd>
+<dd> <em>number</em> (default: 10) — Use <em>number</em> as the threshold
+ for enumerations. Specifying "2" will create enumerations for elements
+ with no more than two different values. </dd>
+<dt> </dt>
+<dt> <strong>-outDir</strong> [<em>dir</em>] </dt>
+<dd> The directory for output files. </dd>
+<dd> <em>dir</em> — Directory path. Default is '.' (the current directory).
+</dd>
+<dt> </dt>
+<dt> <strong>-outPrefix</strong> [<em>file_name_prefix</em>] </dt>
+<dd> The prefix for output file names. </dd>
+<dd> <em>file_name_prefix</em> — Prefix to use. Default is "schema".
+</dd>
+<dt> </dt>
+<dt> <strong>-validate</strong> </dt>
+<dd> Validate input instances against generated schemas. </dd>
+<dt> </dt>
+<dt> <strong>-verbose</strong> </dt>
+<dd> Print more informational messages. </dd>
+<dt> </dt>
+<dt> <strong>-license</strong> </dt>
+<dd> Print license information. </dd>
+<dt> </dt>
+<dt> <strong>-help</strong> </dt>
+<dd> Print help information. </dd>
+<h3> Example </h3>
+<p> The following example generates schema0.xsd from Purchase-Order.xml, with
+ salami slice schema design, simple content types detected where possible, and
+ enumerations limited to elements with four different values. </p>
+<pre>inst2xsd -design ss -simple-content-types smart -enumerations 4 Purchase-Order.xml</pre>
+<h2> <a name="scomp"></a>scomp (Schema Compiler) </h2>
+<p> Compiles schema into Java XMLBeans classes and metadata. Schema-related work
+ with XMLBeans begins by compiling schema to generated Java types. You can use
+ scomp to compile schema from the command line. XMLBeans also provides an Ant
+ task, <a href="antXmlbean.html">xmlbeans</a>, which you can use to compile schemas.
+ For run-time schema compilation that doesn't generate files, see the org.apache.xmlbeans.XmlBeans.compileXsd
+ methods.</p>
+<p>For more information about the types resulting from compiling schema, see <a href="conJavaTypesGeneratedFromUserDerived.html">Java
+ Types Generated from User-Derived Schema Types</a>, <a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans
+ Support for Built-In Schema Types</a>, and <a href="conMethodsForGeneratedJavaTypes.html">Methods
+ for Types Generated From Schema</a>. </p>
+<p>For more information on getting started with XMLBeans, see <a href="conGettingStartedwithXMLBeans.html">Getting
+ Started with XMLBeans</a>.</p>
+<h3> Syntax </h3>
+<pre><strong>scomp</strong> [<em>options</em>] [<em>dirs</em>]* [<em>schemaFile.xsd</em>]* [<em>service.wsdl</em>]* [<em>config.xsdconfig</em>]*</pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-cp</strong> [<em>pathA;pathB;pathC</em>] </dt>
+ <dd> Classpath specifying classes to include during compilation. </dd>
+ <dd> <em>pathA;pathB;pathC</em> — Class search path of directories and
+ JAR files. </dd>
+ <dt> </dt>
+ <dt> <strong>-d</strong> [<em>dir</em>] </dt>
+ <dd> Target directory for CLASS and XSB files. </dd>
+ <dd> <em>dir</em> — The directory path. </dd>
+ <dt> </dt>
+ <dt> <strong>-src</strong> [<em>dir</em>] </dt>
+ <dd> Target directory for generated JAVA files. </dd>
+ <dd> <em>dir</em> — The directory path. </dd>
+ <dt> </dt>
+ <dt> <strong>-srconly</strong> </dt>
+ <dd> Do not compile JAVA files or jar the output. </dd>
+ <dt> </dt>
+ <dd> Note that XSB files are needed in order for CLASS files compiled from the
+ sources to be useful as XMLBeans classes. To get <em>only JAVA files</em>,
+ use -src to specify a directory for the JAVA files. To get <em>JAVA and XSB
+ files in the same directory</em>, use -d to specify a directory that will
+ include both. To get <em>JAVA and XSB files in separate directories</em>,
+ use -src for the JAVA file destination and -d for the XSB file destination.
+ </dd>
+ <dt> </dt>
+ <dt> <strong>-out</strong> [<em>jarFileName</em>] </dt>
+ <dd> The name of the output JAR that will contain the result of compilation.
+ The default is "xmltypes.jar". </dd>
+ <dd> <em>jarFileName</em> — The name for the JAR containing generated
+ files. </dd>
+ <dt> </dt>
+ <dt> <strong>-dl</strong> </dt>
+ <dd> Permit network downloads for imports and includes (this permission is off
+ by default). </dd>
+ <dt> </dt>
+ <dt> <strong>-noupa</strong> </dt>
+ <dd> Do not enforce the unique particle attribution rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-nopvr</strong> </dt>
+ <dd> Do not enforce the particle valid (restriction) rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-noann</strong> </dt>
+ <dd> Ignore annotations. </dd>
+ <dt> </dt>
+ <dt> <strong>-novdoc</strong> </dt>
+ <dd> Do not validate contents of <documentation> elements. </dd>
+ <dt> </dt>
+ <dt> <strong>-compiler</strong> </dt>
+ <dd> Path to external Java compiler. </dd>
+ <dt> </dt>
+ <dt> <strong>-javasource</strong> [<em>version</em>] </dt>
+ <dd> Generate Java source compatible for the specified Java version (1.4 or
+ 1.5). </dd>
+ <dt> </dt>
+ <dt> <strong>-ms</strong> </dt>
+ <dd> Initial memory for external Java compiler; the default is "8m".
+ </dd>
+ <dt> </dt>
+ <dt> <strong>-mx</strong> </dt>
+ <dd> Maximum memory for external Java compiler; the default is "256m".
+ </dd>
+ <dt> </dt>
+ <dt> <strong>-debug</strong> </dt>
+ <dd> Compile with debug symbols. </dd>
+ <dt> </dt>
+ <dt> <strong>-quiet</strong> </dt>
+ <dd> Print fewer informational messages. </dd>
+ <dt> </dt>
+ <dt> <strong>-verbose</strong> </dt>
+ <dd> Print more informational messages. </dd>
+ <dt> </dt>
+ <dt> <strong>-version</strong> </dt>
+ <dd> Print version information. </dd>
+ <dt> </dt>
+ <dt> <strong>-license</strong> </dt>
+ <dd> Print license information. </dd>
+ <dt> </dt>
+ <dt> <strong>-allowmdef</strong> "[<em>namespace</em>] [<em>namespace</em>]
+ [<em>namespace</em>]" </dt>
+ <dd> Ignore multiple defs in given namespaces. Use <code> ##local </code> to
+ specify the no-namespace in that list. </dd>
+ <dt> </dt>
+ <dt> <strong>-catalog</strong> [<em>fileName</em>] </dt>
+ <dd> Catalog file to use for resolving external entities. With this option,
+ scomp uses <code> org.apache.xml.resolver.tools.CatalogResolver </code> for
+ resolving. Note that to use this option, your classpath must include resolver.jar
+ from http://xml.apache.org/commons/components/resolver/index.html). Copy resolver.jar
+ to the XMLBEANS_HOME/lib directory, so that the script can pick it up from
+ there. You can use the <a href="#sdownload">sdownload</a> tool to ensure that
+ required schemas are present for compilation. </dd>
+ <dd> <em>fileName — </em>A path to the catalog file. </dd>
+ <dt> </dt>
+ <dt> <em>dirs</em> </dt>
+ <dd> Directories containing XSD (and possibly XSDCONFIG) files that should be
+ compiled. </dd>
+ <dt> </dt>
+ <dt> <em>schemaFile.xsd</em> </dt>
+ <dd> The names of XSD files that should be compiled. </dd>
+ <dt> </dt>
+ <dt> <em>service.wsdl</em> </dt>
+ <dd> A WSDL file for which types should be generated. </dd>
+ <dt> </dt>
+ <dt> <em>config.xsdconfig</em> </dt>
+ <dd> The name of an XSDCONFIG file. Use an XSDCONFIG file to guide the naming
+ of generated classes and packages. Without an XSDCONFIG file, scomp uses the
+ schema's type names and URI for classes and packages. </dd>
+</dl>
+<h3> Example </h3>
+<p> In the following example, scomp compiles EasyPO.xsd, guiding type naming with
+ po.xsdconfig. scomp puts generated CLASS and XSB files into a classes directory
+ one level up, and JAVA source files into a src directory one level up. Source
+ files will be compatible with Java version 1.5. </p>
+<pre>scomp -d ..\classes -src ..\src -javasource 1.5 EasyPO.xsd po.xsdconfig</pre>
+<p> Here, scomp compiles all of the contents of the schemas directory and puts
+ the generated files into poschema.jar one level up. </p>
+<pre>scomp -out ..\poschema.jar schemas</pre>
+<p> The following example generates JAVA source and XSB files from the schema
+ in EasyPO.xsd. No CLASS files are generated, and the JAVA and XSB files are
+ put into src and xsb directories, respectively. </p>
+<pre>scomp -srconly -src ..\src -d ..\xsb EasyPO.xsd</pre>
+<p> When the schema features imports or includes and you want to use a catalog,
+ you can tell scomp to use the default catalog resolver (<code>org.apache.xml.resolver.tools.CatalogResolver</code>);
+ you specify a catalog file with the -catalog option, as in the example below.
+ (Note that this requires resolver.jar, as noted above for the -catalog option.)
+ In this example, scomp compiles schemaThatUsesRequiredSchema.xsd into myschemas.jar,
+ resolving imports from requiredSchema.xsd through xsdownload.xml. The <a href="#sdownload">sdownload</a>
+ tool is executed first — this ensures that requiredSchema.xsd is present
+ for compilation, but does not actually download requiredSchema.xsd unless the
+ URL at which it's found isn't already cached. This is more efficient than using
+ scomp's -dl option, which attempts to download every time.</p>
+<pre>sdownload "http://some.org/requiredSchema.xsd"
+scomp -out ..\myschemas.jar -catalog xsdownload.xml schemaThatUsesRequiredSchema.xsd</pre>
+<p> When a schema features multiple element declarations of the same qname, such
+ as multiple <xs:any> particles, you might want to disable to "unique
+ particle validation" rule, which would ordinarily invalidate the schema.
+ To do this, use the -noupa option, as in the following example. </p>
+<pre>scomp -out ..\myschemas.jar -noupa schemas</pre>
+<h2> <a name="scopy"></a>scopy (Schema Copier) </h2>
+<p> Copies the XML schema at the specified URL to the specified file. </p>
+<h3> Syntax </h3>
+<pre><strong>schemacopy</strong> <em>sourceurl</em> [<em>targetfile</em>]</pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>sourceurl</strong> </dt>
+ <dd> The URL at which the schema is located. </dd>
+ <dt> </dt>
+ <dt> <em>targetfile</em> </dt>
+ <dd> The file to which the schema should be copied. </dd>
+</dl>
+<h2> <a name="sdownload"></a>sdownload (Schema Downloader) </h2>
+<p> Maintains "xsdownload.xml," an index of locally downloaded XSD files.
+ URLs that are specified are downloaded if they aren't already cached. If no
+ files or URLs are specified, all indexed files are relevant. </p>
+<p> You can use this tool when using <a href="#scomp">scomp</a>, in conjunction
+ with scomp's -catalog option, to ensure the presence of schemas that are required
+ for compilation because they're imported or included. This is an alternative
+ to using scomp's -dl option, which would hit the Internet on every invocation
+ of scomp. When you use sdownload with -catalog, the download occurs only if
+ the URL is not already cached. See the scomp section for an example.</p>
+<h3> Syntax </h3>
+<pre><strong>sdownload</strong> [<strong>-dir</strong> <em>directory</em>] [<strong>-refresh</strong>] [<strong>-recurse</strong>] [<strong>-sync</strong>] [<em>url/file</em>]</pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-dir </strong><em>directory</em> </dt>
+ <dd> The directory for the xsdownload.xml file (the default is ".").
+ </dd>
+ <dd> <em>directory</em> — The directory path. </dd>
+ <dt> </dt>
+ <dt> <strong>-sync</strong> </dt>
+ <dd> Synchronize the index to any local XSD files in the tree. </dd>
+ <dt> </dt>
+ <dt> <strong>-recurse</strong> </dt>
+ <dd> Recursively download imported and included XSD files. </dd>
+ <dt> </dt>
+ <dt> <strong>-refresh</strong> </dt>
+ <dd> Re-download all indexed XSD files. </dd>
+</dl>
+<h2> <a name="sfactor"></a>sfactor (Schema Factoring Tool) </h2>
+<p> Factors redundant definitions out of a set of schemas and uses imports instead.
+</p>
+<h3> Syntax </h3>
+<pre><strong>sfactor</strong> [<strong>-import</strong> <em>common.xsd</em>] [<strong>-out</strong> <em>outputdir</em>] <em>inputdir [-license]</em></pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-import</strong> </dt>
+ <dd> The XSD file to contain redundant definitions for importing. </dd>
+ <dd> <em>common.xsd</em> — A path to the file. </dd>
+ <dt> <strong>-out</strong> <em>outputdir</em> </dt>
+ <dd> The directory into which to place XSD files resulting from refactoring,
+ plus a commonly imported common.xsd. </dd>
+ <dt> inputdir </dt>
+ <dd> The directory containing the XSD files with redundant definitions. </dd>
+ <dt> -license </dt>
+ <dd> Print license information. </dd>
+</dl>
+<h2> <a name="svalidate"></a>svalidate (Streaming Instance Validator) </h2>
+<p> Validates the specified instance against the specified schema. Unlike the
+ <a href="#validate">validate</a> tool, svalidate uses a streaming model through
+ which you can validate much larger instances with less memory (if the schema
+ permits it).</p>
+<h3> Syntax </h3>
+<pre><strong>svalidate</strong> [<em>options</em>] <em>schema.xsd</em> <em>instance.xml</em></pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-dl</strong> </dt>
+ <dd> Enable network downloads for imports and includes. </dd>
+ <dt> </dt>
+ <dt> <strong>-nopvr</strong> </dt>
+ <dd> Disable particle valid (restriction) rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-noupa</strong> </dt>
+ <dd> Disable unique particle attribution rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-license</strong> </dt>
+ <dd> Print license information. </dd>
+ <dt> </dt>
+ <dt> <em>schema.xsd</em> </dt>
+ <dd> The schema against which to validate. </dd>
+ <dt> </dt>
+ <dt> <em>instance.xm</em>l </dt>
+ <dd> The instance to validate. </dd>
+</dl>
+<h2> <a name="validate" id="validate"></a>validate (Instance Validator) </h2>
+<p> Validates a the specified instance against the specified schema. Compare this
+ tool with the <a href="#svalidate">svalidate</a> tool, which is useful for validating
+ very large documents. </p>
+<h3> Syntax </h3>
+<pre><strong>validate</strong> [<em>options</em>] <em>schema.xsd</em> <em>instance.xml</em></pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-dl</strong> </dt>
+ <dd> Enable network downloads for imports and includes. </dd>
+ <dt> </dt>
+ <dt> <strong>-nopvr</strong> </dt>
+ <dd> Disable particle valid (restriction) rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-noupa</strong> </dt>
+ <dd> Disable unique particle attribution rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-license</strong> </dt>
+ <dd> Print license information. </dd>
+ <dt> </dt>
+ <dt> <em>schema.xsd</em> </dt>
+ <dd> The schema against which to validate. </dd>
+ <dt> </dt>
+ <dt> <em>instance.xml</em> </dt>
+ <dd> The instance to validate. </dd>
+</dl>
+<h3> Example </h3>
+<p> The following simple example validates PurchaseOrder.xml against EasyPO.xsd.
+</p>
+<pre>validate ..\schemas\EasyPO.xsd PurchaseOrder.xml</pre>
+<p> In this example, MySchema imports types from another schema and also includes
+ multiple particles defined as <xsd:any> types. The validate command here
+ locates the external schemas for importing (providing there is network access
+ to the schemas) and ignores the validation rule whereby multiple particles of
+ the same qname render the schema invalid. </p>
+<pre>validate -dl -noupa ..\schemas\MySchema.xsd AnInstance.xml</pre>
+<h2> <a name="xpretty"></a>xpretty (XML Pretty Printer) </h2>
+<p> Pretty prints the specified XML to the console. </p>
+<h3> Syntax </h3>
+<pre><strong>xpretty</strong> [<em>options</em>] <em>file.xml</em></pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-indent</strong> <em>numberOfSpaces</em> </dt>
+ <dd> Indent the specified number of spaces. </dd>
+ <dd> <em>numberOfSpaces</em> — The number of spaces to indent. </dd>
+ <dt> </dt>
+ <dt> <strong>-license</strong> </dt>
+ <dd> Print license information. </dd>
+</dl>
+<h2> <a name="xsd2inst"></a>xsd2inst (Schema to Instance Tool) </h2>
+<p> Prints an XML instance from the specified global element using the specified
+ schema. </p>
+<h3> Syntax </h3>
+<pre><strong>xsd2inst</strong> <em>schemafile.xsd</em> <strong>-name</strong> <em>globalElementName</em></pre>
+<h4> Options </h4>
+<dl>
+ <dt> <em>schemafile.xsd</em> </dt>
+ <dd> The schema file defining the element to print. </dd>
+ <dt> </dt>
+ <dt> <strong>-name</strong> </dt>
+ <dd> The name of the global element </dd>
+ <dd> <em>globalElementName </em>— The local name of the global element
+ to use as the root of the printed instance. </dd>
+</dl>
+<h3> Example </h3>
+<p> The following command and output use the schema that accompanies the SubstitutionGroup
+ sample. </p>
+<pre>xsd2inst easypo.xsd -name invoice-header</pre>
+<p> Output </p>
+<pre><eas:invoice-header xmlns:eas="http://xmlbeans.apache.org/samples/substitutiongroup/easypo">
+ <eas:ship-to>
+ <eas:name>string</eas:name>
+ <eas:address>string</eas:address>
+ </eas:ship-to>
+ <eas:bill-to>
+ <eas:name>string</eas:name>
+ <eas:address>string</eas:address>
+ </eas:bill-to>
+ <!--Optional:-->
+ <eas:product id="3"/>
+ <!--Optional:-->
+ <eas:comment>string</eas:comment>
+</eas:invoice-header></pre>
+<h2> <a name="xsdtree"></a>xsdtree (Schema Type Hierarchy Printer) </h2>
+<p> Prints inheritance hierarchy of types defined in a schema. </p>
+<h3> Syntax </h3>
+<pre><strong>xsdtree</strong> [<strong>-noanon</strong>] [<strong>-nopvr</strong>] [<strong>-noupa</strong>] [<strong>-partial</strong>] [<strong>-license</strong>] <em>schemafile.xsd*</em></pre>
+<h4> Options </h4>
+<dl>
+ <dt> <strong>-noanon</strong> </dt>
+ <dd> Don't include anonymous types in the tree. </dd>
+ <dt> </dt>
+ <dt> <strong>-nopvr</strong> </dt>
+ <dd> Disable particle valid (restriction) rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-noupa</strong> </dt>
+ <dd> Disable unique particle attribution rule. </dd>
+ <dt> </dt>
+ <dt> <strong>-partial</strong> </dt>
+ <dd> Print only part of the hierarchy. </dd>
+ <dt> </dt>
+ <dt> <strong>-license</strong> </dt>
+ <dd> Print license information. </dd>
+ <dt> </dt>
+ <dt> <em>schemafile.xsd</em> </dt>
+ <dd> The file containing the schema whose hierarchy should be printed. </dd>
+</dl>
+<h3> Example </h3>
+<p> The following command and output use the schema that accompanies the SubstitutionGroup
+ sample. </p>
+<pre>xsdtree easypo.xsd</pre>
+<p> Output: </p>
+<pre>xmlns:xs="http://www.w3.org/2001/XMLSchema"
+xmlns:eas="http://xmlbeans.apache.org/samples/substitutiongroup/easypo"
++-xs:anyType (builtin)
+ +-xs:anySimpleType (builtin)
+ | +-xs:string (builtin)
+ | +-xs:normalizedString (builtin)
+ | +-xs:token (builtin)
+ | +-type of color element in eas:clothing-type (enumeration)
+ +-type of element eas:invoice-header
+ +-type of element eas:purchase-order
+ +-eas:product-type
+ | +-eas:clothing-type
+ | +-eas:book-type
+ +-eas:name-address</pre>
+<h2> <a name="xmlbeans_ant"></a>xmlbean Ant task </h2>
+<p> Compiles a set of XSD and/or WSDL files into XMLBeans types. See <a href="antXmlbean.html">xmlbean
+ Ant Task</a> for more complete documentation on the task. </p>
+<div>
+ <p class="relatedtopics"> Related Topics </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