You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlbeans.apache.org by ra...@apache.org on 2005/11/18 21:09:47 UTC
svn commit: r345361 [91/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/xmlbeans.css
URL: http://svn.apache.org/viewcvs/xmlbeans/site/build/site/docs/2.1.0/xmlbeans.css?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/build/site/docs/2.1.0/xmlbeans.css (added)
+++ xmlbeans/site/build/site/docs/2.1.0/xmlbeans.css Thu Nov 17 15:28:26 2005
@@ -0,0 +1,496 @@
+/* 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.
+ */
+/* The styles most likely to be used are:
+ - Title: The title of the topic
+ - h1, h2, h3: First, second, and third-level headings within the body of a topic
+ - relatedTopics: Related Topics
+ - procTitle: Within How Do I:... topics, for headings within the body of a topic that are followed by
+ bulleted procedures ("To do this").
+ - pre: For code blocks
+ - langinline: For code fragments within a (non-code) regular section.
+ - notepara: Notes
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+p,
+proctitle,
+relatedtopics {
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ color: #000000;
+}
+
+/* Use h1 for all first-level headings within the body of a topic.
+ For the topic title, use the Title style. */
+h1 {
+ font-size: 135%;
+ margin-top: .5em;
+ margin-bottom: .5em;
+}
+
+/* Use h2 for all second-level headings. */
+h2 {
+ font-size: 125%;
+ margin-top: 1em;
+ margin-bottom: .6em;
+}
+
+/* Use h3 for all third-level headings. */
+h3 {
+ font-size: 110%;
+ margin-top: 1em;
+ margin-bottom: .6em;
+}
+
+/* Use h4 for all fourth-level headings.
+ Note: this style looks identical to the relatedtopics and proctitle styles. */
+h4 {
+ font-size: 105%;
+ margin-top: 1em;
+ margin-bottom: .6em;
+}
+
+/* Use h5 for all fifth-level heading.
+ Currently, there are no h5s in use in the document.*/
+h5 {
+ font-size: 100%;
+ margin-top: 1em;
+ margin-bottom: .6em;
+}
+
+/* Use the Title style for the title of a topic. */
+p.Title {
+ font-weight: bold;
+ font-style: normal;
+ font-family: Verdana, sans-serif;
+ font-size: 142%;
+}
+
+/* This deprated tag creates a div that designates the title. */
+#topictitle {
+}
+
+/* This deprecated tag creates a dive that designates all body text. */
+#topictext {
+}
+
+/* Used for figure captions.*/
+p.arttitle {
+ font-weight: Bold;
+}
+
+/* The attribute style resembles the navtitle and partdesc styles in that it keeps the next paragraph
+ flush with it. Use it when you list the attributes of syntax in a reference topic.
+ The argument style should always be followed by the partdesc style. */
+p.attribute {
+ margin-top: .6em;
+ margin-bottom: 0px;
+ font-weight: Bold;
+
+}
+
+/* Standard HTML tag. */
+body {
+ padding: 0px 0px 0px 15px;
+ background: #ffffff;
+ color: #00000;
+ font-size: 80%;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+}
+
+/* Standard HTML tag. */
+span.bold {
+ font-weight: Bold;
+}
+
+/* Standard HTML tag. */
+blockquote {
+ margin: 0em 0em 0em 2em;
+ padding: 0px;
+}
+
+/* Use the filepath style to designate file paths. It is currently a monospace file. */
+span.filepath {
+ font: 100% Courier New Courier mono;
+ font-family: "Courier New", monospace;
+}
+
+/* The langinline style, like userinput and filepath, also renders text monospace. Use this
+ to denote any individual instance of code in the context of non-coded text. For example,
+ you would use this to denote the name of a class when you're describing it in the paragraph that
+ precedes a code sample. To denote a code sample, however, use the <pre> tag. */
+span.langinline {
+ font: 100% Courier New Courier mono;
+ font-family: "Courier New", monospace;
+}
+
+/* The listplain style narrows the margin between the formatted line and the one before it.
+ It is to be used when creating a second paragraph in a list item, along with the indent and
+ unindent buttons in Dreamweaver. */
+p.listplain {
+ margin-top: 0.7em;
+ margin-bottom: 0;
+ padding: 0em;
+}
+
+/* All text in the navtitle style should include a link to another topic.
+ The navtitle style is used in navigational node topics, in Class reference
+ topics, and in Method reference topics. For example, in the "Topics
+ Included in this Section" section of a navigation topic, you include the links to all of
+ the topics in that chapter, along with a brief description of what you'll find in each. Use the
+ navtitle style for the linked text. It differs from a normal paragraph style in that it does not
+ include an extra paragraph break between the link and the descriptive text. */
+p.navtitle {
+ margin-top: .6em;
+ margin-bottom: 0em;
+}
+
+/* The navdesc style is used in navigational node topics, in Class reference
+ topics, and in Method reference topics. For example, in the "Topics Included in this Section"
+ section of a navigation topic, you include the links to all of the topics in that chapter,
+ along with a brief description of what you'll find in each. Use this style for the descriptive text.
+ It indents the text one tab stop and keeps the margin between this style and the navtitle style small. */
+p.navdesc {
+ margin-bottom: 1em;
+ margin-left: 1.9em;
+ margin-top: 0em;
+}
+
+/* The notepara style indents your text to the tab stop for note
+ text. You should always begin Note text with the word "Note:" in
+ boldface. */
+p.notepara {
+ margin-left: 2em;
+ margin-right: 2em;
+ margin-bottom: 1.5em;
+}
+
+/* The partname style resembles the navtitle style in that it keeps the next paragraph flush with it.
+ You use it when you list the parameters in a reference topic. It is also used currently in the
+ glossary to designate glossary entries. It renders text italic.
+ The partname style should always be followed by the partdesc style.*/
+p.partname {
+ margin-top: .6em;
+ margin-bottom: 0px;
+ font-style: italic;
+}
+
+/* Use the partdesc style when you describe the function of the properties, parameters, or exceptions
+ listed in a reference topic. It is also used currently in the glossary to designate glossary
+ definitions. The style indents the description slightly.
+ The partdesc style should always follow the partname or attribute style.*/
+p.partdesc {
+ margin-bottom: 1em;
+ margin-left: 1.9em;
+ margin-top: 0em;
+
+}
+
+/* The point of the proctitle style is the same as the point of the relatedtopics style.
+ It applies to all headings that begin with "To [do something]". It looks identical to the h4 style. */
+p.proctitle {
+ font-size: 110%;
+ margin-top: 1em;
+ margin-bottom: .6em;
+ font-weight: Bold;
+
+}
+
+/* Use the relatedtopics style, for the words "Related Topics" at the end of a topic.
+ It looks identical to the h4 style. */
+p.relatedtopics {
+ font-size: 120%;
+ margin-top: 1em;
+ margin-bottom: .6em;
+ font-weight: Bold;
+}
+
+/* The syntax style renders text bold. Use it to style all syntax lines under the
+ Syntax heading of reference topics. */
+p.syntax {
+ font-family: monospace;
+ line-height: normal;
+ font-weight: Bold;
+}
+
+/* Use the syntaxindent style to indent sub-properties of syntax declarations. */
+p.syntaxindent {
+ font-family: monospace;
+ line-height: normal;
+ font-weight: Bold;
+ margin-left: 1.5em;
+ margin-top: 0em;
+ margin-bottom: 0px;
+}
+
+
+p.fileurl {
+ font-size: 8pt;
+}
+
+p.modifieddate {
+ font-size: 8pt;
+}
+
+/* The syntaxpartname character style renders text italic. Use it to designate
+ syntax elements in reference topics.*/
+span.syntaxpartname {
+ font-style: italic;
+ font-weight: normal;
+}
+
+/* These specifications dictate the margins and width of tables. */
+table {
+ width: 90%;
+ margin-top: .6em;
+ margin-bottom: .3em;
+}
+
+/* The background of header cells is grey, and the text is bottom-aligned. */
+th {
+ padding-left: 8px;
+ padding-right: 8px;
+ background: #cccccc;
+ text-align: left;
+ font-size: 80%;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ vertical-align: bottom;
+}
+
+/* The text in normal table cells is top-aligned. */
+td {
+ padding-left: 8px;
+ padding-right: 8px;
+ background: #ffffff;
+ vertical-align: top;
+ font-size: 80%;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+}
+
+/* This style creates space above and below table text between paragraph and the table borders. */
+p.tabletext {
+ margin-top: .6em;
+ margin-bottom: .6em;
+}
+
+/* The editor uses this style when creating template guides to designate a style annotation.
+ You probably won't want to use it anywhere else in the guide. */
+span.template {
+ color: #FF00FF;
+}
+
+a.toc-node {
+ font-size:11px;
+ color:000000;
+ margin-left: 0px;
+ margin-top: 0px;
+ margin-bottom: 0px;
+ white-space: nowrap;
+ font-family: Tahoma;
+ background-color:#FFFFFF;
+ text-decoration:none;
+}
+
+/* The userinput style renders text monospace.Use this style to highlight text that a user
+ types into a text field. */
+span.userinput {
+ font: 100% Courier New Courier mono;
+ font-family: "Courier New", monospace;
+}
+
+/* Standard HTML tags. */
+ul,
+ol {
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ list-style-position: outside;
+ list-style-image: none;
+ margin-top: 0em;
+ margin-bottom: 0em;
+}
+
+/* Standard HTML tag. */
+ol {
+ list-style-type: 1;
+ margin-left: 2em;
+}
+
+/* Standard HTML tag. */
+ul {
+ list-style-type: disc;
+ margin-left: 1.5em;
+}
+
+/* Standard HTML tag. */
+li {
+ margin-top: 1.3em;
+ margin-bottom: 0em;
+}
+
+a:link {
+ color: #3366CC;
+}
+a:hover {
+ x-text-underline: normal;
+ /*begin!kadov{{*/ text-decoration: underline; /*}}end!kadov*/
+}
+
+a:active {
+ x-text-underline: normal;
+ /*begin!kadov{{*/ text-decoration: underline; /*}}end!kadov*/
+}
+
+a:visited {
+ color: #803380;
+}
+
+a {
+ x-text-underline: off;
+ x-text-overline: off;
+ x-text-line-through: off;
+ /*begin!kadov{{*/ text-decoration: none none none; /*}}end!kadov*/
+}
+a:link {
+ color: #3366CC;
+}
+
+a:hover {
+ x-text-underline: normal;
+ /*begin!kadov{{*/ text-decoration: underline; /*}}end!kadov*/
+}
+
+a:active {
+ x-text-underline: normal;
+ /*begin!kadov{{*/ text-decoration: underline; /*}}end!kadov*/
+}
+
+a:visited {
+ color: #000066;
+}
+
+div.footer {
+}
+
+.buttonclass
+{
+ font-size:10px;
+ height:20px;
+}
+
+.formclass
+{
+ font-size:10px;
+ height:17px;
+}
+
+
+
+
+/*DEPRECATED*/
+p.codeblock {
+ font-size: 100%;
+ font-family: monospace;
+ line-height: 1em;
+ x-text-tab-stops: repeat 1in;
+ white-space: nowrap;
+ color: #000000;
+ cursor: text;
+ padding-right: 1em;
+ padding-left: 1em;
+ padding-top: 0em;
+ padding-bottom: 0em;
+ margin-bottom: 0em;
+ margin-top: 0em;
+ x-text-underline: Off;
+ /*begin!kadov{{*/ text-decoration: none; /*}}end!kadov*/
+}
+
+/* DEPRECATED */
+p.bulletindent1 {
+ margin-left: 1.5em;
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+/* DEPRECATED */
+p.bulletindent2 {
+ margin-left: 5.1em;
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+/* DEPRECATED */
+p.bulletindent3 {
+ margin-left: 4.3em;
+}
+
+/* DEPRECATED */
+p.indent1 {
+ margin-left: 1.5em;
+ margin-right: 1.9em;
+}
+
+/* DEPRECATED */
+p.indent2 {
+ margin-left: 2.9em;
+ margin-right: 1.9em;
+}
+
+/* DEPRECATED */
+p.indent3 {
+ margin-left: 4.3em;
+ margin-right: 1.9em;
+}
+
+/* DEPRECATED */
+p.numberedindent1 {
+ margin-left: 2.2em;
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+/* DEPRECATED */
+p.numberedindent2 {
+ margin-left: 6.3em;
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+/* DEPRECATED */
+p.numberedindent3 {
+ margin-left: 10.5em;
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+/* DEPRECATED */
+p.tabletitle {
+ margin-left: 0;
+ font-weight: Bold;
+}
+
+
+/* These styles are used by the search results page */
+
+.search-node {
+ font-size:10px;
+ color:000000;
+}
+
+a.search-node {
+ font-size:10px;
+ color:000000;
+}
Modified: xmlbeans/site/build/site/documentation/index.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/build/site/documentation/index.html?rev=345361&r1=345360&r2=345361&view=diff
==============================================================================
--- xmlbeans/site/build/site/documentation/index.html (original)
+++ xmlbeans/site/build/site/documentation/index.html Thu Nov 17 15:28:26 2005
@@ -240,11 +240,17 @@
<a href="../docs/2.0.0/reference/index.html">XMLBeans 2.0.0 Java Doc</a>
</li>
+
+<li>
+
+<a href="../docs/2.1.0/reference/index.html">XMLBeans 2.1.0 Java Doc</a>
+
+</li>
</ul>
</div>
-<a name="N100B3"></a><a name="Wiki+Pages"></a>
+<a name="N100BA"></a><a name="Wiki+Pages"></a>
<h2 class="h3">Wiki Pages</h2>
<div class="section">
<p>Have an idea for a sample you'd like to see? Looking for ideas for a sample you'd
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/antXmlbean.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/antXmlbean.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/antXmlbean.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/antXmlbean.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,346 @@
+<!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><!-- InstanceBegin template="file:///C|/p4/main/help/ide/en/Templates/Command.dwt" codeOutsideHTMLIsLocked="false" -->
+<head>
+<!-- InstanceBeginEditable name="doctitle" -->
+<title>xmlbean Ant Task</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">
+</head>
+
+<!--(Body)==========================================================-->
+<body>
+<!-- InstanceBeginEditable name="body" -->
+<div id=topictitle>
+ <H1 class=Title>xmlbean Ant Task</h1>
+</div>
+<div id=topictext>
+ <p>Compiles a set of XSD and/or WSDL files into XMLBeans. This is useful for
+ building an XMLBean JAR from XSD and WSDL files. If desired, the task can
+ also generate the source code that makes up the XMLBean type system specified
+ by the schema files.</p>
+ <p class="notepara"><b>Note:</b> This task depends on two external libraries not
+ included in the Ant distribution: one called xbean.jar, one called jsr173_1.0_api.jar.
+ Both can be found in the XMLBeans developer kit at <a
+ href="http://xmlbeans.apache.org/" target="_blank">http://xmlbeans.apache.org/</a>.
+ The build script will need to include a taskdef for xmlbean, which could look
+ like this:</p>
+</div>
+<blockquote>
+ <div class="notepara">
+ <pre><taskdef name="xmlbean"<br> classname="org.apache.xmlbeans.impl.tool.XMLBean"<br> classpath="path/to/xbean.jar:path/to/jsr173_1.0_api.jar" /></pre>
+ </div>
+</blockquote>
+<div>
+<p>It is possible to refine the set of files that are being processed. This
+ can be done with the <span class="langinline">includes</span>, <span class="langinline">includesfile</span>,
+ <span class="langinline">excludes</span>, <span class="langinline">excludesfile</span>
+ and <span class="langinline">defaultexcludes</span> attributes. With the <span class="langinline">includes</span>
+ or <span class="langinline">includesfile</span> attribute you specify the
+ files you want to have included by using patterns. The <span class="langinline">exclude</span>
+ or <span class="langinline">excludesfile</span> attributes are used to specify
+ the files you want to have excluded. This is also done with patterns. And
+ finally with the <span class="langinline">defaultexcludes</span> attribute,
+ you can specify whether you want to use default exclusions or not. See the
+ section on <a
+ href="http://ant.apache.org/manual/dirtasks.html#directorybasedtasks" target="_blank">directory
+ based tasks</a> in the <a href="http://ant.apache.org/manual/" target="_blank">Ant
+ documentation</a>, on how the inclusion/exclusion of files works, and how
+ to write patterns.</p>
+ <p>This task forms an implicit <a
+ href="http://ant.apache.org/manual/CoreTypes/fileset.html" target="_blank">FileSet</a>
+ and supports all attributes of <code><fileset></code> (<code>dir</code>
+ becomes <code>basedir</code>) as well as the nested <code><include></code>,
+ <code><exclude></code> and <code><patternset></code> elements.</p>
+ <h3>Parameters</h3>
+ <table border="1" cellpadding="2" cellspacing="0">
+ <tbody>
+ <tr>
+ <td valign="top"><b>Attribute</b></td>
+ <td valign="top"><b>Description</b></td>
+ <td align="center" valign="top"><b>Required</b></td>
+ </tr>
+ <tr>
+ <td valign="top">schema</td>
+ <td valign="top">A file that points to either an individual schema file
+ or a directory of files. Not a path reference. If multiple
+ schema files need to be built together, use a nested fileset instead
+ of setting schema.</td>
+ <td align="center" valign="top">Yes, unless a fileset element is nested.</td>
+ </tr>
+ <tr>
+ <td valign="top">destfile</td>
+ <td valign="top">Define the name of the jar file created. For instance,
+ "myXMLBean.jar" will output the results of this task into a jar with
+ the same name.</td>
+ <td align="center" valign="top">No, default is "xmltypes.jar".</td>
+ </tr>
+ <tr>
+ <td valign="top">download</td>
+ <td valign="top">Set to true to permit the compiler to download URLs for
+ imports and includes. Defaults to false, meaning all imports and
+ includes must be copied locally.<br> </td>
+ <td align="center" valign="top">No, default is false.</td>
+ </tr>
+ <tr>
+ <td valign="top">classgendir<br> </td>
+ <td valign="top">Set a location to generate CLASS files into.<br> </td>
+ <td valign="top" align="center">No<br> </td>
+ </tr>
+ <tr>
+ <td valign="top">srconly<br> </td>
+ <td valign="top">A value of true means that only source will be generated.<br>
+ </td>
+ <td valign="top" align="center">No, default is false.</td>
+ </tr>
+ <tr>
+ <td valign="top">srcgendir<br> </td>
+ <td valign="top">Set a location to generate JAVA files into.<br> </td>
+ <td valign="top" align="center">No<br> </td>
+ </tr>
+ <tr>
+ <td valign="top">javasource<br> </td>
+ <td valign="top">Generate java source compatible with the given
+ version. Currently only "1.4" and "1.5" are supported. <br> </td>
+ <td valign="top" align="center">No, Default is "1.4"</td>
+ </tr>
+ <tr>
+ <td valign="top">classpath</td>
+ <td valign="top">The classpath to use if schemas in the fileset import
+ definitions that are supplied by other compiled XMLBeans JAR files,
+ or if JAVA files are in the schema fileset. Also supports a nested classpath.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">classpathref</td>
+ <td valign="top">Adds a classpath, given as <a
+ href="http://ant.apache.org/manual/using.html#references" target="_blank">reference</a>
+ to a path defined elsewhere.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">includes</td>
+ <td valign="top">Comma- or space-separated list of patterns of files that
+ must be included. All files are included when omitted.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">includesfile</td>
+ <td valign="top">The name of a file. Each line of this file is taken to
+ be an include pattern.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">excludes</td>
+ <td valign="top">Comma- or space-separated list of patterns of files that
+ must be excluded. No files (except default excludes) are excluded when
+ omitted.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">excludesfile</td>
+ <td valign="top">The name of a file. Each line of this file is taken to
+ be an exclude pattern.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">defaultexcludes</td>
+ <td valign="top">Indicates whether default excludes should be used or
+ not ("yes"/"no"). Default excludes are used when omitted.</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
+ <td valign="top">debug</td>
+ <td valign="top">Indicates whether source should be compiled with debug
+ information; defaults to <code>off</code>. If set to <code>off</code>,
+ <code>-g:none</code> will be passed on the command line for compilers
+ that support it (for other compilers, no command line argument will
+ be used). If set to <code>true</code>, the value of the <code>debuglevel</code>
+ attribute determines the command line argument.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">debuglevel</td>
+ <td valign="top">Keyword list to be appended to the <code>-g</code> command-line
+ switch. This will be ignored by all implementations except <code>modern</code>
+ and <code>classic(ver >= 1.2)</code>. Legal values are <code>none</code>
+ or a comma-separated list of the following keywords: <code>lines</code>,
+ <code>vars</code>, and <code>source</code>. If <code>debuglevel</code>
+ is not specified, by default, nothing will be appended to <code>-g</code>.
+ If <code>debug</code> is not turned on, this attribute will be ignored.
+ </td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">optimize</td>
+ <td valign="top">Indicates whether source should be compiled with optimization;
+ defaults to <code>off</code>.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">includeAntRuntime</td>
+ <td valign="top">Whether to include the Ant run-time libraries in the
+ classpath; defaults to <code>yes</code>.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">includeJavaRuntime</td>
+ <td valign="top">Whether to include the default run-time libraries from
+ the executing VM in the classpath; defaults to <code>no</code>.</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">fork</td>
+ <td valign="top">Whether to execute <code>javac</code> using the JDK compiler
+ externally; defaults to <code>yes</code>.</td>
+ <td align="center" valign="top">No, default is true</td>
+ </tr>
+ <tr>
+ <td valign="top">executable</td>
+ <td valign="top">Complete path to the <code>javac</code> executable to
+ use in case of <code>fork="yes"</code>. Defaults to the compiler
+ of the Java version that is currently running Ant. Ignored if <code>fork="no"</code></td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">memoryInitialSize</td>
+ <td valign="top">The initial size of the memory for the underlying VM,
+ if <code>javac</code> is run externally; ignored otherwise. Defaults
+ to the standard VM memory setting. (Examples: <code>83886080</code>,
+ <code>81920k</code>, or <code>80m</code>)</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">memoryMaximumSize</td>
+ <td valign="top">The maximum size of the memory for the underlying VM,
+ if <code>javac</code> is run externally; ignored otherwise. Defaults
+ to the standard VM memory setting. (Examples: <code>83886080</code>,
+ <code>81920k</code>, or <code>80m</code>)</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">compiler</td>
+ <td valign="top">The compiler implementation to use. If this attribute
+ is not set, the value of the <code>build.compiler</code> property, if
+ set, will be used. Otherwise, the default compiler for the current VM
+ will be used.
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">failonerror</td>
+ <td valign="top"> Determines whether or not the ant target will continue
+ if the XMLBean creation encounters a build error.<br> </td>
+ <td align="center" valign="top">No, default is true.</td>
+ </tr>
+ <tr>
+ <td valign="top">verbose<br> </td>
+ <td valign="top">Controls the amount of build message output.<br> </td>
+ <td valign="top" align="center">No, default is true.</td>
+ </tr>
+ <tr>
+ <td valign="top">quiet<br> </td>
+ <td valign="top">Controls the amount of build message output.<br> </td>
+ <td valign="top" align="center">No, default is false.</td>
+ </tr>
+ <tr>
+ <td valign="top">typesystemname<br> </td>
+ <td valign="top">The name of the package that the TypeSystemHolder class
+ should be generated in. Normally this should be left unspecified.
+ None of the XMLBeans are generated in this package. Use .xsdconfig files
+ to modify XMLBean package or class names.<br> </td>
+ <td valign="top" align="center">No<br> </td>
+ </tr>
+ <tr>
+ <td valign="top">noupa</td>
+ <td valign="top">Do not enforce the unique particle attribution rule.<br> </td>
+ <td align="center" valign="top">No, default is false.</td>
+ </tr>
+ <td valign="top">nopvr</td>
+ <td valign="top">Do not enforce the particle valid (restriction) rule.<br> </td>
+ <td align="center" valign="top">No, default is false.</td>
+ </tr>
+ <tr>
+ <td valign="top">noann</td>
+ <td valign="top">Skip over schema <annotation> elements<br> </td>
+ <td align="center" valign="top">No, default is false.</td>
+ </tr>
+ <tr>
+ <td valign="top">nopvr</td>
+ <td valign="top">Do not validate the contents of schema <documentation> elements.<br> </td>
+ <td align="center" valign="top">No, default is false.</td>
+ </tr>
+ <tr>
+ <td valign="top">ignoreDuplicatesInNamespaces</td>
+ <td valign="top">Comma separated list of one or more namespaces
+ in which duplicate definitions are to be ignored.
+ </td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ </tbody>
+ </table>
+ <h3>Example</h3>
+</div>
+<div id=topictext> Be sure to define the task in your script, like this:</div>
+<div>
+ <pre><taskdef name="xmlbean"<br> classname="org.apache.xmlbeans.impl.tool.XMLBean"<br> classpath="path/to/xbean.jar:path/to/jsr173_1.0_api.jar" /></pre>
+ <p>The following builds all the schemas in the schemas directory and creates
+ a jar called "Schemas.jar". (Note: both xbean.jar and
+ jsr173_1.0_api.jar must be on the classpath when the task executes).</p>
+</div>
+<div>
+ <pre>
+<xmlbean schema="schemas" destfile="Schemas.jar"
+ classpath="path/to/xbean.jar:path/to/jsr173_1.0_api.jar" /></pre>
+ The following compiles the schema "ourSchema.xsd" into the default
+ jar "xmltypes.jar". If any imports and includes are defined
+ by remote URLs, they are downloaded during the build.
+ <div>
+ <pre><xmlbean schema="schemas/ourSchema.xsd" download="true"<br> classpath="path/to/xbean.jar:path/to/jsr173_1.0_api.jar" /></pre>
+ </div>
+ <div>
+ <h4>Using a fileset</h4>
+ </div>
+ <div>
+ <pre><xmlbean classgendir="${build.dir}" classpath="${class.path}"<br> failonerror="true"><br> <fileset basedir="src" excludes="**/*.xsd"/><br> <fileset basedir="schemas" includes="**/*.*"/><br></xmlbean></pre>
+ </div>
+ <div> Gathers all the files in the src directory except XSD files, along with
+ every file in the schemas directory, and compiles them. The fileset can include
+ schema files that refer to previously compiled schema components. The
+ fileset can also contain JAVA files. The classpath parameter defines
+ the classpath necessary to resolve compiled schema and java references (and must include xbean.jar and jsr173_1.0_api.jar).<br>
+ <br>
+ The built classes will go into ${build.dir}.</div>
+ <div>
+ <p class=relatedtopics>Related Topics</p>
+ <p>None.</p>
+ </div>
+</div>
+<!-- InstanceEndEditable -->
+</body>
+<!-- InstanceEnd --></html>
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conGettingStartedwithXMLBeans.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conGettingStartedwithXMLBeans.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conGettingStartedwithXMLBeans.html (added)
+++ xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conGettingStartedwithXMLBeans.html Thu Nov 17 15:28:26 2005
@@ -0,0 +1,531 @@
+<!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>Getting Started with XMLBeans</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">
+<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> Getting Started with XMLBeans</h1>
+<div id="topictext">
+ <p>XMLBeans provides intuitive ways to handle XML that make it easier for you
+ to access and manipulate XML data and documents in Java. </p>
+ <p>Characteristics of XMLBeans approach to XML:</p>
+</div>
+<ul>
+ <li>
+ <div>It provides a familiar Java object-based view of XML data without losing
+ access to the original, native XML structure.</div>
+ </li>
+ <li>
+ <div>The XML's integrity as a document is not lost with XMLBeans. XML-oriented
+ APIs commonly take the XML apart in order to bind to its parts. With XMLBeans,
+ the entire XML instance document is handled as a whole. The XML data is
+ stored in memory as XML. This means that the document order is preserved
+ as well as the original element content with whitespace.</div>
+ </li>
+ <li>
+ <div>With types generated from schema, access to XML instances is through
+ JavaBean-like accessors, with get and set methods.</div>
+ </li>
+ <li>
+ <div>It is designed with XML schema in mind from the beginning — XMLBeans
+ supports all XML schema definitions.</div>
+ </li>
+ <li>Access to XML is fast.</li>
+</ul>
+<div>
+ <p>The starting point for XMLBeans is XML schema. A schema (contained in an
+ XSD file) is an XML document that defines a set of rules to which other XML
+ documents must conform. The XML Schema specification provides a rich data
+ model that allows you to express sophisticated structure and constraints on
+ your data. For example, an XML schema can enforce control over how data is
+ ordered in a document, or constraints on particular values (for example, a
+ birth date that must be later than 1900). Unfortunately, the ability to enforce
+ rules like this is typically not available in Java without writing custom
+ code. XMLBeans honors schema constraints.</p>
+ <p class="notepara"><strong>Note:</strong> Where an XML schema defines rules
+ for an XML document, an XML <em>instance</em> is an XML document that conforms
+ to the schema.</p>
+ <p>You compile a schema (XSD) file to generate a set of Java interfaces that
+ mirror the schema. With these types, you process XML instance documents that
+ conform to the schema. You bind an XML instance document to these types; changes
+ made through the Java interface change the underlying XML representation.</p>
+ <p>Previous options for handling XML include using XML programming interfaces
+ (such as DOM or SAX) or an XML marshalling/binding tool (such as JAXB). Because
+ it lacks strong schema-oriented typing, navigation in a DOM-oriented model
+ is more tedious and requires an understanding of the complete object model.
+ JAXB provides support for the XML schema specification, but handles only a
+ subset of it; XMLBeans supports all of it. Also, by storing the data in memory
+ as XML, XMLBeans is able to reduce the overhead of marshalling and demarshalling.</p>
+ <h1>Accessing XML Using Its Schema</h1>
+ <p>To get a glimpse of the kinds of things you can do with XMLBeans, take a
+ look at an example using XML for a purchase order. The purchase order XML
+ contains data exchanged by two parties, such as two companies. Both parties
+ need to be able to rely on a consistent message shape, and a schema specifies
+ the common ground. </p>
+ <p>Here's what a purchase order XML instance might look like.</p>
+ <pre>
+<po:purchase-order xmlns:po="http://openuri.org/easypo">
+ <po:customer>
+ <po:name>Gladys Kravitz</po:name>
+ <po:address>Anytown, PA</po:address>
+ </po:customer>
+ <po:date>2003-01-07T14:16:00-05:00</po:date>
+ <po:line-item>
+ <po:description>Burnham's Celestial Handbook, Vol 1</po:description>
+ <po:per-unit-ounces>5</po:per-unit-ounces>
+ <po:price>21.79</po:price>
+ <po:quantity>2</po:quantity>
+ </po:line-item>
+ <po:line-item>
+ <po:description>Burnham's Celestial Handbook, Vol 2</po:description>
+ <po:per-unit-ounces>5</po:per-unit-ounces>
+ <po:price>19.89</po:price>
+ <po:quantity>2</po:quantity>
+ </po:line-item>
+<po:shipper>
+ <po:name>ZipShip</po:name>
+ <po:per-ounce-rate>0.74</po:per-ounce-rate>
+ </po:shipper>
+</po:purchase-order></pre>
+ <p>This XML includes a root element, <span class="langinline">purchase-order</span>,
+ that has three kinds of child elements: <span class="langinline">customer</span>,
+ <span class="langinline">date</span>, <span class="langinline">line-item</span>,
+ and <span class="langinline">shipper</span>. An intuitive, object-based view
+ of this XML would provide an object representing the <span class="langinline">purchase-order</span>
+ element, and it would have methods for getting the date and for getting subordinate
+ objects for <span class="langinline">customer</span>, <span class="langinline">line-item</span>,
+ and <span class="langinline">shipper</span> elements. Each of the last three
+ would have its own methods for getting the data inside them as well.</p>
+ <h2>Looking at the Schema</h2>
+ <p>The following XML is the the schema for the preceding purchase order XML.
+ It defines the XML's "shape" — what its elements are, what
+ order they appear in, which are children of which, and so on.</p>
+</div>
+<div>
+ <pre>
+<xs:schema targetNamespace="http://openuri.org/easypo"
+ xmlns:po="http://openuri.org/easypo"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ elementFormDefault="qualified">
+
+ <xs:element name="purchase-order">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="customer" type="po:customer"/>
+ <xs:element name="date" type="xs:dateTime"/>
+ <xs:element name="line-item" type="po:line-item" minOccurs="0" maxOccurs="unbounded"/>
+ <xs:element name="shipper" type="po:shipper" minOccurs="0"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ <xs:complexType name="customer">
+ <xs:sequence>
+ <xs:element name="name" type="xs:string"/>
+ <xs:element name="address" type="xs:string"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="line-item">
+ <xs:sequence>
+ <xs:element name="description" type="xs:string"/>
+ <xs:element name="per-unit-ounces" type="xs:decimal"/>
+ <xs:element name="price" type="xs:double"/>
+ <xs:element name="quantity" type="xs:int"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="shipper">
+ <xs:sequence>
+ <xs:element name="name" type="xs:string"/>
+ <xs:element name="per-ounce-rate" type="xs:decimal"/>
+ </xs:sequence>
+ </xs:complexType>
+</xs:schema></pre>
+ <div>
+ <p>This schema describes the purchase order XML instance by defining the following:</p>
+ </div>
+ <ul>
+ <li>
+ <div>Definitions for three complex types — customer, line-item, and
+ shipper. These are the types used for the children of the purchase-order
+ element. In schema, a complex type is one that defines an element that
+ may have child elements and attributes. The sequence element nested in
+ the complex type lists its child elements.</div>
+ <p>These are also <em>global</em> types. They are global because they are
+ at the top level of the schema (in other words, just beneath the <span class="langinline">schema</span>
+ root element). This means that they may be referenced from anywhere else
+ in the schema.</p>
+ </li>
+ </ul>
+</div>
+<div>
+ <ul>
+ <li>Use of simple types within the complex types. The name, address, and description
+ elements (among others) are typed as simple types. As it happens, these
+ are also <em>built-in</em> types. A built-in type (here, one with the "xs"
+ prefix) is part of the schema specification. (The specification defines
+ 46 built-in types.)</li>
+ <li>A global element called purchase-order. This element definition includes
+ a nested complex type definition that specifies the child elements for a
+ purchase-order element. Notice that the complex type includes references
+ to the other complex types defined in this schema.</li>
+ </ul>
+ <div></div>
+ <p>In other words, the schema defines types for the child elements and describes
+ their position as subordinate to the root element, <span class="langinline">purchase-order</span>.</p>
+ <p>When you use the XMLBean compiler with an XSD file such as this one, you
+ generate a JAR file containing the interfaces generated from the schema.</p>
+ <h2>Writing Java Code That Uses the Interfaces</h2>
+ <p>With the XMLBeans interfaces in your application, you can write code that
+ uses the new types to handle XML based on the schema. Here's an example that
+ extracts information about each of the ordered items in the purchase order
+ XML, counts the items, and calculates a total of their prices. In particular,
+ look at the use of types generated from the schema and imported as part of
+ the <span class="langinline">org.openuri.easypo</span> package. </p>
+ <p>The <span class="langinline">printItems</span> method receives a <span class="langinline">File</span>
+ object containing the purchase order XML file.</p>
+ <pre>
+package docs.xmlbeans;
+
+import java.io.File;
+import org.apache.xmlbeans.*;
+import org.openuri.easypo.PurchaseOrderDocument;
+import org.openuri.easypo.PurchaseOrder;
+import org.openuri.easypo.LineItem;
+
+public class POHandler
+{
+ public static void printItems(File po) throws Exception
+ {
+ /*
+ * All XMLBeans schema types provide a nested Factory class you can
+ * use to bind XML to the type, or to create new instances of the type.
+ * Note that a "Document" type such as this one is an XMLBeans
+ * construct for representing a global element. It provides a way
+ * for you to get and set the contents of the entire element.
+ *
+ * Also, note that the parse method will only succeed if the
+ * XML you're parsing appears to conform to the schema.
+ */
+ PurchaseOrderDocument poDoc =
+ PurchaseOrderDocument.Factory.parse(po);
+
+ /*
+ * The PurchaseOrder type represents the purchase-order element's
+ * complex type.
+ */
+ PurchaseOrder po = poDoc.getPurchaseOrder();
+
+ /*
+ * When an element may occur more than once as a child element,
+ * the schema compiler will generate methods that refer to an
+ * array of that element. The line-item element is defined with
+ * a maxOccurs attribute value of "unbounded", meaning that
+ * it may occur as many times in an instance document as needed.
+ * So there are methods such as getLineItemArray and setLineItemArray.
+ */
+ LineItem[] lineitems = po.getLineItemArray();
+ System.out.println("Purchase order has " + lineitems.length + " line items.");
+
+ double totalAmount = 0.0;
+ int numberOfItems = 0;
+
+ /*
+ * Loop through the line-item elements, using generated accessors to
+ * get values for child elements such a description, quantity, and
+ * price.
+ */
+ for (int j = 0; j < lineitems.length; j++)
+ {
+ System.out.println(" Line item: " + j);
+ System.out.println(
+ " Description: " + lineitems[j].getDescription());
+ System.out.println(" Quantity: " + lineitems[j].getQuantity());
+ System.out.println(" Price: " + lineitems[j].getPrice());
+ numberOfItems += lineitems[j].getQuantity();
+ totalAmount += lineitems[j].getPrice() * lineitems[j].getQuantity();
+ }
+ System.out.println("Total items: " + numberOfItems);
+ System.out.println("Total amount: " + totalAmount);
+ }
+}
+</pre>
+ <p>Notice that types generated from the schema reflect what's in the XML:</p>
+</div>
+<ul>
+ <li>
+ <div>A <span class="langinline">PurchaseOrderDocument</span> represents the
+ global root element.</div>
+ </li>
+ <li>
+ <div>A <span class="langinline">getPurchaseOrder</span> method returns a <span class="langinline">PurchaseOrderDocument.PurchaseOrder</span>
+ type that contains child elements, including <span class="langinline">line-item</span>.
+ A <span class="langinline">getLineItemArray</span> method returns a <span class="langinline">LineItem</span>
+ array containing the <span class="langinline">line-item</span> elements.</div>
+ </li>
+ <li>Other methods, such as <span class="langinline">getQuantity</span>, <span class="langinline">getPrice</span>,
+ and so on, follow naturally from what the schema describes, returning corresponding
+ children of the <span class="langinline">line-item</span> element.</li>
+ <li>The name of the package containing these types is derived from the schema's
+ target namespace.</li>
+</ul>
+<div>
+ <p>Capitalization and punctuation for generated type names follow Java convention.
+ Also, while this example parses the XML from a file, other <span class="langinline">parse</span>
+ methods support a Java <span class="langinline">InputStream</span> object,
+ a <span class="langinline">Reader</span> object, and so on.</p>
+ <p>The preceding Java code prints the following to the console:</p>
+</div>
+<div>
+ <pre>
+Purchase order has 3 line items.
+ Line item 0
+ Description: Burnham's Celestial Handbook, Vol 1
+ Quantity: 2
+ Price: 21.79
+ Line item 1
+ Description: Burnham's Celestial Handbook, Vol 2
+ Quantity: 2
+ Price: 19.89
+Total items: 4
+Total amount: 41.68</pre>
+ <h2>Creating New XML Instances from Schema</h2>
+ <p>As you've seen XMLBeans provides a "factory" class you can use
+ to create new instances. The following example creates a new <span class="langinline">purchase-order</span>
+ element and adds a <span class="langinline">customer</span> child element.
+ It then inserts <span class="langinline">name</span> and <span class="langinline">address</span>
+ child elements, creating the elements and setting their values with a single
+ call to their <span class="langinline">set</span> methods.</p>
+ <pre>
+public PurchaseOrderDocument createPO()
+{
+ PurchaseOrderDocument newPODoc = PurchaseOrderDocument.Factory.newInstance();
+ PurchaseOrder newPO = newPODoc.addNewPurchaseOrder();
+ Customer newCustomer = newPO.addNewCustomer();
+ newCustomer.setName("Doris Kravitz");
+ newCustomer.setAddress("Bellflower, CA");
+ return newPODoc;
+}
+</pre>
+ <p>The following is the XML that results. Note that XMLBeans assigns the correct
+ namespace based on the schema, using an "ns1" (or, "namespace
+ 1") prefix. For practical purposes, the prefix itself doesn't really
+ matter — it's the namespace URI (http://openuri.org/easypo) that defines
+ the namespace. The prefix is merely a marker that represents it.</p>
+ <pre><ns1:purchase-order xmlns:ns1="http://openuri.org/easypo">
+ <ns1:customer>
+ <ns1:name>Doris Kravitz</ns1:name>
+ <ns1:address>Bellflower, CA</ns1:address>
+ </ns1:customer>
+</ns1:purchase-order>
+</pre>
+ <p>Note that all types (including those generated from schema) inherit from
+ <span class="langinline">XmlObject</span>, and so provide a <span class="langinline">Factory</span>
+ class. For an overview of the type system in which <span class="langinline">XmlObject</span>
+ fits, see <a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support
+ for Built-In Schema Types</a>. For reference information, see <a href="../reference/org/apache/xmlbeans/XmlObject.html">XmlObject
+ Interface</a>.</p>
+ <h1>XMLBeans Hierarchy</h1>
+ <p>The generated types you saw used in the preceding example are actually part
+ of a hierarchy of XMLBeans types. This hierarchy is one of the ways in which
+ XMLBeans presents an intuitive view of schema. At the top of the hierarchy
+ is <span class="langinline">XmlObject</span>, the base interface for XMLBeans
+ types. Beneath this level, there are two main type categories: generated types
+ that represent user-derived schema types, and included types that represent
+ built-in schema types.</p>
+ This topic has already introduced generated types. For more information, see
+ <a href="conJavaTypesGeneratedFromUserDerived.html">Java Types Generated from
+ User-Derived Schema Types.</a>
+ <h2>Built-In Type Support</h2>
+ <p>In addition to types generated from a given schema, XMLBeans provides 46
+ Java types that mirror the 46 built-in types defined by the XML schema specification.
+ Where schema defines <span class="langinline">xs:string</span>, <span class="langinline">xs:decimal</span>,
+ and <span class="langinline">xs:int</span>, for example, XMLBeans provides
+ <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlString.html">XmlString</a></span>,
+ <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlDecimal.html">XmlDecimal</a></span>,
+ and <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlInt.html">XmlInt</a></span>.
+ Each of these also inherits from <span class="langinline">XmlObject</span>,
+ which corresponds to the built-in schema type <span class="langinline">xs:anyType</span>.</p>
+ <p>XMLBeans provides a way for you to handle XML data as these built-in types.
+ Where your schema includes an element whose type is, for example, <span class="langinline">xs:int</span>,
+ XMLBeans will provide a generated method designed to return an <span class="langinline">XmlInt</span>.
+ In addition, as you saw in the preceding example, for most types there will
+ also be a method that returns a natural Java type such as <span class="langinline">int</span>.
+ The following two lines of code return the <span class="langinline">quantity</span>
+ element's value, but return it as different types.</p>
+ <pre>
+// Methods that return simple types begin with an "x".
+XmlInt xmlQuantity = lineitems[j].xgetQuantity();
+// Methods that return a natural Java type are unadorned.
+int javaQuantity = lineitems[j].getQuantity();
+</pre>
+ <p>In a sense both get methods navigate to the <span class="langinline">quantity</span>
+ element; the <span class="langinline">getQuantity</span> method goes a step
+ further and converts the elements value to the most appropriate natural Java
+ type before returning it. (XMLBeans also provides a means for validating the
+ XML as you work with it.)</p>
+ <p>If you know a bit about XML schema, XMLBeans types should seem fairly intuitive.
+ If you don't, you'll learn a lot by experimenting with XMLBeans using your
+ own schemas and XML instances based on them. </p>
+ <p>For more information on the methods of types generated from schema, see <a href="conMethodsForGeneratedJavaTypes.html">Methods
+ for Types Generated From Schema</a>. For more about the how XMLBeans represents
+ built-in schema types, see <a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans
+ Support for Built-In Schema Types</a>.</p>
+ <h1>Using XQuery Expressions</h1>
+ <p>With XMLBeans you can use XQuery to query XML for specific pieces of data.
+ XQuery is sometimes referred to as "SQL for XML" because it provides
+ a mechanism to access data directly from XML documents, much as SQL provides
+ a mechanism for accessing data in traditional databases.</p>
+ <p>XQuery borrows some of its syntax from XPath, a syntax for specifying nested
+ data in XML. The following example returns all of the <span class="langinline">line-item</span>
+ elements whose <span class="langinline">price</span> child elements have values
+ less than or equal to 20.00:</p>
+ <pre>
+PurchaseOrderDocument doc = PurchaseOrderDocument.Factory.parse(po);
+
+/*
+ * The XQuery expression is the following two strings combined. They're
+ * declared separately here for convenience. The first string declares
+ * the namespace prefix that's used in the query expression; the second
+ * declares the expression itself.
+ */
+String nsText = "declare namespace po = 'http://openuri.org/easypo'; ";
+String pathText = "$this/po:purchase-order/po:line-item[po:price <= 20.00]";
+String queryText = nsText + pathText;
+
+XmlCursor itemCursor = doc.newCursor().execQuery(queryText);
+System.out.println(itemCursor.xmlText());
+</pre>
+ <p>This code creates a new cursor at the start of the document. From there,
+ it uses the <span class="langinline">XmlCursor</span> interface's <span class="langinline">execQuery</span>
+ method to execute the query expression. In this example, the method's parameter
+ is an XQuery expression that simply says, "From my current location,
+ navigate through the <span class="langinline">purchase-order</span> element
+ and retrieve those <span class="langinline">line-item</span> elements whose
+ value is less than or equal to 20.00." The <span class="langinline">$this</span>
+ variable means "the current position."</p>
+ <p>For more information about XQuery, see <a href="http://www.w3.org/TR/xquery/" target="_blank">XQuery
+ 1.0: An XML Query Language</a> at the W3C web site.</p>
+ <h2>Using XML Cursors</h2>
+ <p>In the preceding example you may have noticed the <span class="langinline"><a href="../reference/org/apache/xmlbeans/XmlCursor.html">XmlCursor</a></span>
+ interface. In addition to providing a way to execute XQuery expression, an
+ XML cursors offers a fine-grained model for manipulating data. The XML cursor
+ API, analogous to the DOM's object API, is simply a way to point at a particular
+ piece of data. So, just like a cursor helps navigate through a word processing
+ document, the XML cursor defines a location in XML where you can perform actions
+ on the selected XML.</p>
+ <p>Cursors are ideal for moving through an XML document when there's no schema
+ available. Once you've got the cursor at the location you're interested in,
+ you can perform a variety of operations with it. For example, you can set
+ and get values, insert and remove fragments of XML, copy fragments of XML
+ to other parts of the document, and make other fine-grained changes to the
+ XML document.</p>
+ <p>The following example uses an XML cursor to navigate to the <span class="langinline">customer</span>
+ element's <span class="langinline">name</span> child element.</p>
+ <pre>
+PurchaseOrderDocument doc =
+ PurchaseOrderDocument.Factory.parse(po);
+
+XmlCursor cursor = doc.newCursor();
+cursor.toFirstContentToken();
+cursor.toFirstChildElement();
+cursor.toFirstChildElement();
+System.out.println(cursor.getText());
+
+cursor.dispose();
+</pre>
+ <p>What's happening here? As with the earlier example, the code loads the XML
+ from a <span class="langinline">File</span> object. After loading the document,
+ the code creates a cursor at its beginning. Moving the cursor a few times
+ takes it to the nested <span class="langinline">name </span> element. Once
+ there, the getText method retrieves the element's value.</p>
+ <p>This is just an introduction to XML cursors. For more information about using
+ cursors, see <a href="conNavigatingXMLwithCursors.html">Navigating XML with
+ Cursors</a>.</p>
+ <h2>Where to Go Next</h2>
+</div>
+<ul>
+ <li>
+ <div>XMLBeans provides intuitive ways to handle XML, particularly if you're
+ starting with schema. If you're accessing XML that's based on a schema,
+ you'll probably find it most efficient to access the XML through generated
+ types specific to the schema. To do this, you begin by compiling the schema
+ to generate interfaces. For more information on using XMLBeans types generated
+ by compiling schema, see <a href="conJavaTypesGeneratedFromUserDerived.html">Java
+ Types Generated From User-Derived Schema Types</a> and <a href="conMethodsForGeneratedJavaTypes.html">Methods
+ for Types Generated From Schema</a>.</div>
+ </li>
+ <li>
+ <div>You might be interested in reading more about the type system on which
+ XMLBeans is based, particularly if you're using types generated from schema.
+ XMLBeans provides a hierarchical system of types that mirror what you find
+ in the XML schema specification itself. If you're working with schema, you
+ might find it helps to understand how these types work. For more information,
+ see <a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support
+ for Built-In Schema Types</a> and <a href="conIntroToTheSchemaTypeSystem.html">Introduction
+ to Schema Type Signatures</a>.</div>
+ </li>
+ <li>
+ <div>XMLBeans provides access to XML through XQuery, which borrows path syntax
+ from XPath. With XQuery, you can specify specific fragments of XML data
+ with or without schema. To learn more about using XQuery and XPath in XMLBeans,
+ see <a href="conSelectingXMLwithXQueryPathXPath.html">Selecting XML with
+ XQuery and XPath</a>.</div>
+ </li>
+ <li>You can use the <span class="langinline">XmlCursor</span> interface for
+ fine-grained navigation and manipulation of XML. For more information, see
+ <a href="conNavigatingXMLwithCursors.html">Navigating XML with Cursors</a>.</li>
+</ul>
+<div>
+ <p class="notepara"><strong>Note:</strong> The xbean.jar file that contains
+ the XMLBeans library is fully functional as a standalone library.</p>
+ <h1>Related Topics</h1>
+ <p><a href="../../samples/navXMLBeansSamples.html">XMLBeans Samples</a></p>
+</div>
+<!-- InstanceEndEditable -->
+<script language="JavaScript">
+
+</script>
+</body>
+</html>
Added: xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conHandlingAny.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conHandlingAny.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conHandlingAny.html (added)
+++ xmlbeans/site/src/documentation/content/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/src/documentation/content/docs/2.1.0/guide/conIntroToTheSchemaTypeSystem.html
URL: http://svn.apache.org/viewcvs/xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conIntroToTheSchemaTypeSystem.html?rev=345361&view=auto
==============================================================================
--- xmlbeans/site/src/documentation/content/docs/2.1.0/guide/conIntroToTheSchemaTypeSystem.html (added)
+++ xmlbeans/site/src/documentation/content/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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlbeans.apache.org
For additional commands, e-mail: commits-help@xmlbeans.apache.org