| <!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN"> |
| |
| <!-- Copyright 2004 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. --> |
| <html> |
| <head> |
| <!-- InstanceBeginEditable name="doctitle" --> |
| <title>Java Types Generated from Schema</title> |
| <!-- InstanceEndEditable --> |
| |
| <!--(Meta)==========================================================--> |
| <meta http-equiv=Content-Type content="text/html; charset=$CHARSET;"> |
| |
| |
| <!-- InstanceBeginEditable name="metatags" --> |
| |
| <meta name="component" content=""> |
| <!-- In the description metatag, please provide a BRIEF description of the topic contents. --> |
| <meta name="description" content=""> |
| <!-- In the component metatag, please list keywords that will help a user search for this topic. --> |
| <meta name="keywords" content=""> |
| <!-- InstanceEndEditable --> |
| |
| <!--(Links)=========================================================--> |
| <!-- InstanceBeginEditable name="head" --> |
| |
| <link href="../xmlbeans.css" rel="stylesheet" type="text/css"> |
| |
| <!--(Meta)==========================================================--> |
| |
| |
| |
| <meta name="author" content="your name"> |
| <meta name="description" content="A description of the topic contents."> |
| <meta name="keywords" content="keywords to help in searches"> |
| <meta name="date last modified" content="10/25/02"> |
| <!--(Links)=========================================================--> |
| <!--(Body)==========================================================--><!-- InstanceEndEditable --> |
| <link href="../xmlbeans.css" rel="stylesheet" type="text/css"> |
| <a href="../../../core/index.html" id="index"></a> |
| <script language="JavaScript" src="../../../core/topicInfo.js"></script> |
| <script language="JavaScript" src="../../../core/CookieClass.js"></script> |
| <script language="JavaScript" src="../../../core/displayContent.js"></script> |
| </head> |
| |
| <!--(Body)==========================================================--> |
| <body> |
| <script language="JavaScript"> |
| |
| </script> |
| <!-- InstanceBeginEditable name="body" --> |
| <h1> Java Types Generated from User-Derived Schema Types</h1> |
| <div id="topictext"> |
| <p>When you compile XML schema, the resulting API is made up of two categories |
| of types: built-in types that mirror those in the schema specification and |
| others that are generated from user-derived schema types. This topic provides |
| an overview of the Java types generated for user-derived types, describing |
| the methods the Java types provide. For more information about built-in types, |
| see <a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support for |
| Built-In Schema Types</a>. For specific information about the methods exposed |
| by generated types, see <a href="conMethodsForGeneratedJavaTypes.html">Methods |
| for Generated Java Types</a>.</p> |
| <p>In general, an API generated from schema is an intuitive means to access |
| XML instances based on the schema. You'll probably find that for most uses |
| it's unnecessary to know the rules for generating it in order to use it. However, |
| for those cases when it's unclear what's going on behind the scenes (or if |
| you're just curious), this topic describes the rules.</p> |
| <p class="notepara"><strong>Note:</strong> The XMLBeans API also provides a |
| way for you to get information <em>about </em>the type system itself — |
| in other words, about the API and the underlying schema. For more information, |
| see <a href="conIntroToTheSchemaTypeSystem.html">Introduction to Schema Type |
| Signatures</a>.</p> |
| <p>Each of the types generated when you compile a schema is designed specifically |
| for access to XML instances conforming to that part of the schema. Start by |
| taking a look at a simple XML and schema example. The following schema describes |
| an XML document to contain a stock price quote.</p> |
| <pre><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> |
| <xs:element name="price-quote"> |
| <xs:complexType> |
| <xs:sequence> |
| <xs:element name="stock-symbol" type="xs:string"/> |
| <xs:element name="stock-price" type="xs:float"/> |
| </xs:sequence> |
| </xs:complexType> |
| </xs:element> |
| </xs:schema> |
| </pre> |
| <p>The following is an example of XML that conforms to this schema.</p> |
| <pre><price-quote> |
| <stock-symbol>BEAS</stock-symbol> |
| <stock-price>59.21</stock-price> |
| </price-quote></pre> |
| <p>When you compile this schema, you get two generated XMLBeans interfaces: |
| <span class="langinline"> PriceQuoteDocument</span> and <span class="langinline">PriceQuoteDocument.PriceQuote</span>.</p> |
| <p>From the schema point of view, the generated <span class="langinline">PriceQuote</span> |
| interface represents the <em>complex type</em> you see inside the schema's |
| <span class="langinline">price-quote</span> element declaration. Looking at |
| the XML instance, you can see that this complex type translates into a sequence |
| of two elements, <span class="langinline">stock-symbol</span> and <span class="langinline">stock-price</span>. |
| So it's not surprising that the <span class="langinline">PriceQuote</span> |
| interface exposes methods such as <span class="langinline">getStockPrice</span> |
| and <span class="langinline">setStockPrice</span> to set the value <span class="langinline">stock-price</span> |
| element.</p> |
| <p>The <span class="langinline">PriceQuoteDocument</span> interface, on the |
| other hand, represents the <span class="langinline">price-quote</span> <em>document</em> |
| that contains the root <span class="langinline">price-quote</span> element. |
| XMLBeans creates a special "document" type for global element types. |
| A document type provides a way for you to get and set the value of the underlying |
| type, here represented by <span class="langinline">PriceQuote</span>. The |
| <span class="langinline">price-quote</span> element is considered a <em>global</em> |
| element because it can be referenced from anywhere else in the schema. For |
| global elements, the XMLBeans schema compiler generates an interface whose |
| name ends with "Document." This is because an XML schema has no |
| way of defining a "root" element; any global element can be the |
| root.</p> |
| <p>The following bit of Java code illustrates how you might use these interfaces |
| to get the stock price contained in the XML.</p> |
| <pre> |
| public static float getStockPrice(java.io.File orderXML) throws Exception |
| { |
| PriceQuoteDocument docXML = PriceQuoteDocument.Factory.parse(orderXML); |
| PriceQuote quoteXML = docXML.getPriceQuote(); |
| float stockPrice = quoteXML.getStockPrice(); |
| return stockPrice; |
| } |
| </pre> |
| <p>This code loads the XML from a <span class="langinline">File</span> object, |
| converting the <span class="langinline">parse</span> method's return value |
| to a <span class="langinline">PriceQuoteDocument</span> instance. It then |
| uses this instance to get an instance of <span class="langinline">PriceQuote</span>. |
| With <span class="langinline">PriceQuote</span>, the code extracts the stock |
| price. </p> |
| </div> |
| <div> |
| <div id="topictext"> |
| <p>The XML schema specification provides a rich set of rules through which |
| you can derive new types. When you generate interfaces from your schema, |
| XMLBeans uses the schema's rules to determine how to generate interfaces. |
| The following describes some of the guidelines by which this is done.</p> |
| <h2>Names for Interfaces</h2> |
| <p>Interfaces are generated for schema types (both simple and complex). Anonymous |
| schema types result in inner interfaces inside the type interface in which |
| they are defined. Their name comes from the element or attribute in which |
| they is defined.</p> |
| <p>Names for schema types become Java-friendly names when the schema is compiled. |
| In other words, names such as "price-quote" become "PriceQuote." In addition, |
| a schema's XML namespace URIs become package names for XMLBean types generated |
| from the schema. The way this name translation is done is described by section |
| C of the Java API for XML Binding (JAXB) specification at <a href="http://java.sun.com/xml/downloads/jaxb.html" target="_blank"> |
| http://java.sun.com/xml/jaxb.html.</a> </p> |
| <p>Here are a few examples:</p> |
| <table> |
| <tr> |
| <td><strong>Schema Target Namespace</strong></td> |
| <td width="155"><strong>XML Localname</strong></td> |
| <td><strong>Fully-Qualified XMLBean Type Name</strong></td> |
| </tr> |
| <tr> |
| <td>http://www.mycompany.com/2002/buyer</td> |
| <td width="155">purchase-order-4</td> |
| <td>com.mycompany.x2002.buyer.PurchaseOrder4</td> |
| </tr> |
| <tr> |
| <td>http://myco.com/sample.html</td> |
| <td width="155">SampleDocument</td> |
| <td>com.myco.sample.SampleDocument</td> |
| </tr> |
| <tr> |
| <td>http://openuri.org/test_case_1</td> |
| <td width="155">test_type</td> |
| <td>org.openuri.testCase1.TestType</td> |
| </tr> |
| </table> |
| <p>When there are name collisions, the generated types will have names with |
| numerals appended for example, "TestType2".</p> |
| <h2>Global Elements and Attributes</h2> |
| <p>In schema, global element and attribute definitions are those that are |
| declared at the top level of the schema (that is, immediately within the |
| <span class="langinline">schema</span> root element). Because they are global, |
| they may be referenced from inside the schema by name. The <span class="langinline">creditReport</span> |
| (not the <span class="langinline">creditReportType</span> complex type) |
| element defined in the following schema is an example.</p> |
| <pre> |
| <xs:schema targetNamespace="http://openuri.org/samples/creditReport" |
| xmlns:cr="http://openuri.org/samples/creditReport" |
| xmlns:xs="http://www.w3.org/2001/XMLSchema" |
| elementFormDefault="qualified" |
| attributeFormDefault="unqualified"> |
| <xs:complexType name="creditReportType"> |
| <xs:sequence> |
| <xs:element name="bankReport" type="xs:string"/> |
| <xs:element name="taxReport" type="xs:string"/> |
| </xs:sequence> |
| </xs:complexType> |
| <xs:element name="creditReport" type="cr:creditReportType"/> |
| </xs:schema></pre> |
| <p>XMLBeans generates a separate interface for each of these. Also, global |
| element and attribute types are somewhat unique in that the schema compiler |
| will create special types to hold the globally defined element or attribute. |
| The names of these types will be appended with "Document" (for |
| elements) or "Attribute" (for attributes). You can retrieve the |
| element or attribute itself (or create a new one) by calling the accessor |
| methods that the special types provide. The following example would create |
| a new instance of the creditReport element.</p> |
| <pre> |
| // Create an instance of the special document type. |
| CreditReportDocument reportDoc = CreditReportDocument.Factory.newInstance(); |
| /* |
| * Use the document type to add a new creditReport element to the XML instance. |
| * Note that the type returned by the addNewCreditReport method is the |
| * creditReportType complex type defined for it in schema. |
| */ |
| CreditReportType report = reportDoc.addNewCreditReport(); |
| </pre> |
| <h2>Global User-Derived Types</h2> |
| <p>A <em>user-derived</em> type is one defined with a <span class="langinline">complexType</span> |
| or <span class="langinline">simpleType</span> element in schema. User-derived |
| types at the top level of a schema are global. XMLBeans generates an interface |
| for each of these, as it does with global elements and attributes. These |
| interfaces include methods through which you can get and set the type's |
| values, including any nested derived types it may contain. The following |
| schema snippet defines a user-derived complex type called <span class="langinline">itemType</span>, |
| along with a <span class="langinline">priceType</span> that uses it as the |
| type for an <span class="langinline">item</span> child element.</p> |
| <pre> |
| <xs:complexType name="itemType"> |
| <xs:sequence> |
| <xs:element name="name" type="xs:string"/> |
| <xs:element name="amount" type="xs:int"/> |
| <xs:element name="price" type="xs:double"/> |
| </xs:sequence> |
| </xs:complexType> |
| <xs:complexType name="priceType"> |
| <xs:sequence> |
| <xs:element name="item" type="ps:itemType" minOccurs="0" maxOccurs="unbounded"/> |
| </xs:sequence> |
| </xs:complexType> |
| <xs:element name="price" type="ps:priceType"/> |
| </pre> |
| <p>By default, the generated Java type for <span class="langinline">itemType</span> |
| would be an interface called <span class="langinline">ItemType</span>. With |
| this type, you would be able to get and set the values of its <span class="langinline">name</span>, |
| <span class="langinline">amount</span>, and <span class="langinline">price</span> |
| child elements. However, a user-derived type (as opposed to an element or |
| attribute) is always intended for use as the type to which an element or |
| attribute is bound. In other words, it's contained by an element or attribute. |
| While you can create a new instance of a user-derived type, the new instance's |
| underlying XML is a fragment. As the generated API would make clear, the |
| <span class="langinline">itemType</span> becomes the return type of a get |
| method, or the parameter of a set method.</p> |
| <pre> |
| // Create a new price document. |
| PriceDocument priceDoc = PriceDocument.Factory.newInstance(); |
| PriceType price = priceDoc.getPrice(); |
| |
| /* |
| * Create a new instance of ItemType and set the values of its |
| * child elements. |
| */ |
| ItemType item = ItemType.Factory.newInstance(); |
| item.setName("bicycle"); |
| item.setAmount(12); |
| item.setPrice(560.00); |
| |
| /* |
| * Use the new ItemType instance to set the value of the |
| * price element's first item child element. Notice that the set method |
| * here is an "Array" method. This is because the item element |
| * is defined with a maxOccurs="unbounded" attribute. It can occur |
| * many times as a child of price. |
| */ |
| price.setItemArray(0, item); |
| </pre> |
| <h2>Nested Elements and Derived Types</h2> |
| <p>When your schema includes named types that are declared locallywithin |
| the declaration of another element or typethe schema type's generated Java |
| interface will be an inner interface within the type it's nested in.</p> |
| <p>For example, the following schema snippet defines <span class="langinline">name</span> |
| and <span class="langinline">gender</span> elements nested within a <span class="langinline">person</span> |
| complex type. In particular, note that the gender element is defined as |
| deriving from the xs:NMTOKEN built-in type.</p> |
| <pre> |
| <xs:complexType name="person"> |
| <xs:sequence> |
| <xs:element name="name" type="xs:string"/> |
| <xs:element name="gender"> |
| <xs:simpleType> |
| <xs:restriction base="xs:NMTOKEN"> |
| <xs:enumeration value="male"/> |
| <xs:enumeration value="female"/> |
| </xs:restriction> |
| </xs:simpleType> |
| </xs:element> |
| </xs:sequence> |
| </xs:complexType> |
| </pre> |
| <p>The generated interfaces for person and gender would be organized in source |
| something like the following. Of course, you wouldn't see the source, but |
| you can see here that the Gender interface is nested with Person. Also, |
| notice that it extends XmlNMTOKEN, mirroring the schema.</p> |
| <pre>public interface Person extends XmlObject |
| { |
| public interface Gender extends XmlNMTOKEN |
| { |
| // Methods omitted for this example |
| } |
| // Methods omitted for this example |
| } |
| </pre> |
| <p>You could create a new instance of the <span class="langinline">Gender</span> |
| type in this way (there are also various alternatives to this):</p> |
| <pre> |
| // Create a new Person instance. |
| Person person = Person.Factory.newInstance(); |
| /* |
| * Set the gender element's value using the |
| * enumeration generated from the schema. |
| */ |
| person.setGender(Gender.FEMALE);</pre> |
| <h2>User-Derived Simple Types</h2> |
| <p>In addition to the 46 built-in simple types in XML schema, a schema can |
| include its own custom simple types using <span class="langinline">xs:simpleType</span> |
| declarations. These user-derived simple types are always based on the built-in |
| XML schema types. The built-in types can be modified by <em>restricting</em> |
| them, taking <em>unions</em> of them, or making space-separated <em>lists</em> |
| of them. Each XML simple type is translated into a Java type that provides |
| access to the underlying data.</p> |
| <h3>Unions</h3> |
| <p>In schema, you can use <span class="langinline">xs:union</span> to specify |
| a simple type that is allowed to contain values of a number of other simple |
| types. XMLBeans generates a type for a union, just as it generates a type |
| for any other schema type. At run time, you can discover the underlying |
| type of an instance of a union type by calling the <span class="langinline">XmlObject</span> |
| interface's <span class="langinline">instanceType</span> method. Once you |
| have determined the type, you can cast an instance of a union type to the |
| actual underlying instance type.</p> |
| <pre> |
| <xs:simpleType name="intOrString"> |
| <xs:union memberTypes="xs:int xs:string"> |
| </xs:simpleType> |
| </pre> |
| <p>Given the preceding schema snippet, you could set the intOrString value |
| to, say, 6 or "six". The union of <span class="langinline">xs:int</span> |
| and <span class="langinline">xs:string</span> makes both allowable.</p> |
| <pre> |
| // Create a new instance of the type. |
| IntOrString intOrString = IntOrString.Factory.newInstance(); |
| intOrString.set("5"); |
| // This code prints "XmlInt" to the console. |
| System.out.println(intOrString.instanceType().getShortJavaName()); |
| </pre> |
| <h3>Restrictions</h3> |
| <p>XML schema restrictions on simple XMLBeans types are enforced. So, for |
| example, it is illegal to set a number outside its restricted range. </p> |
| <h4>Numeric Type Restrictions</h4> |
| <p>In schema, you can restrict numeric types to allow, for example, only a |
| particular range of values. For such a restriction, XMLBeans tailors the |
| resulting natural Java alternative. For example, suppose you have the following |
| element defined in schema:</p> |
| <pre> |
| <xs:element name="number"> |
| <xs:simpleType> |
| <xs:restriction base="xs:integer"> |
| <xs:minInclusive value="1"/> |
| <xs:maxInclusive value="1000000"/> |
| </xs:restriction> |
| </xs:simpleType> |
| </xs:element> |
| </pre> |
| <p>The type is restricted from <span class="langinline">xs:integer</span>, |
| but because the number's range is limited to between 1 and 1000000, it will |
| fit into a Java <span class="langinline">int</span>. A <span class="langinline">long</span> |
| or <span class="langinline">java.math.BigInteger</span> would be too big |
| for the need. In other words, the <span class="langinline">getNumber</span> |
| method generated for this type will return an <span class="langinline">int</span>, |
| rather than a <span class="langinline">BigInteger</span> or a <span class="langinline">long</span>.</p> |
| <p>By the same token, an long can be compiled to an int if the totalDigits |
| attribute is <=9, or the min and max attribute values are within 32-bit |
| 2s complement range.</p> |
| <p>The single primitive XML type xs:decimal can be restricted in several ways |
| that influence the resulting natural Java type. For example, it can be:</p> |
| </div> |
| </div> |
| <ul> |
| <li> |
| <div> |
| <div>Compiled to a <span class="langinline">BigInteger</span> if its <span class="langinline">fractionDigit</span> |
| attribute is set to 0. </div> |
| </div> |
| </li> |
| <li> |
| <div> |
| <div>Compiled to a <span class="langinline">long</span> if its totalDigits |
| attribute is <=18, or the min and max are within 64-bit 2s complement |
| range.</div> |
| </div> |
| </li> |
| </ul> |
| <div> |
| <div> |
| <h3>Enumerations</h3> |
| <p>In schema, you can derive a new type by restricting a built-in type so |
| that only a finite set of values are allowable. Where schema does this by |
| restricting <span class="langinline">xs:string</span>, XMLBeans generates |
| a special <span class="langinline">Enum</span> type. With an <span class="langinline">Enum</span>, |
| you can select the enumerated value either by its <span class="langinline">String</span> |
| value or by a numeric index. The index's value is determined based on the |
| <span class="langinline">String</span> value's order in the schema. Having |
| an index can be useful in Java switch statements.</p> |
| <p>For example, suppose you had a document containing price elements whose |
| type was the priceType defined in the following schema snippet:</p> |
| <pre><xs:complexType name="priceType"> |
| <xs:sequence> |
| <xs:element name="item" type="ps:itemType" minOccurs="0" |
| maxOccurs="unbounded"/> |
| </xs:sequence> |
| <xs:attribute name="threshold"> |
| <xs:simpleType> |
| <xs:restriction base="xs:string"> |
| <xs:enumeration value="Below10Dollars"/> |
| <xs:enumeration value="Between10And20Dollars"/> |
| <xs:enumeration value="Above20Dollars"/> |
| </xs:restriction> |
| </xs:simpleType> |
| </xs:attribute> |
| </xs:complexType></pre> |
| <p>Using types generated from the schema, you would be able to write the following |
| Java code to "switch" on the threshold attribute's enumeration:</p> |
| <pre> |
| /* |
| * Use the intValue method provided by the Enum type to determine the threshold |
| * attribute's current enumeration value. |
| */ |
| switch(priceElements[i].getThreshold().intValue()) |
| { |
| // Use the Threshold type's enumeration values to test for an attribute value. |
| case PriceType.Threshold.INT_BELOW_10_DOLLARS: |
| zeroBuffer.append(item.getTitle() + "\n"); |
| break; |
| case PriceType.Threshold.INT_BETWEEN_10_AND_20_DOLLARS: |
| tenBuffer.append(item.getTitle() + "\n"); |
| break; |
| case PriceType.Threshold.INT_ABOVE_20_DOLLARS: |
| twentyBuffer.append(item.getTitle() + "\n"); |
| break; |
| default: |
| System.out.println("Yo! Something unexpected happened!"); |
| break; |
| }</pre> |
| </div> |
| <p class="relatedtopics">Related Topics</p> |
| <p><a href="conXMLBeansSupportBuiltInSchemaTypes.html">XMLBeans Support for |
| Built-In Schema Types</a></p> |
| </div> |
| <!-- InstanceEndEditable --> |
| <script language="JavaScript"> |
| |
| </script> |
| </body> |
| </html> |
