xmlbeans-bin-3.1.0.tgz

/* 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. */ XMLBeans Development Kit Version 3.1.0 Welcome to XMLBeans! Kit contents: (1) One copy of xbean.jar, which contains XMLBeans. Should work on any JDK 1.6.x or newer. ./lib/xbean.jar (2) One copy of resolver.jar from Apache xml-commons. See scomp documentation for when it is needed. ./lib/resolver.jar (3) License information for XML Beans and included libraries ./LICENSE.txt ./NOTICE.txt (4) One folder full of command-line scripts, pointing to the useful main() functions in the JAR. ./bin (5) A copy of the plain javadoc tree for org.apache.xmlbeans.* ./docs/javadocs (6) A preliminary collection of nicely formatted user-level documentation HTML ./docs/guide (7) Samples that show the use of the XMLBeans API. (You'll also find more samples at the XMLBeans web site.) ./samples Where to start? (1) Setup. 1. Make sure you have a JDK 1.6.x or later installed; that java[.exe] is on your path and that JAVA_HOME/bin contains java[.exe], javac[.exe], and jar[.exe]. 2. Set your XMLBEANS_HOME env variable to point to the directory in which you installed XmlBeans (i.e., /home/user/xmlbeans). 3. Put the scripts in ./bin on your path. 4. To test your setup, run "scomp" with no arguments. You should get a "usage" message. (2) Get to know XMLBeans basics. 1. Use the tutorial located at the XMLBeans web site: http://xmlbeans.apache.org/documentation/tutorial_getstarted.html. This provides a hands-on introduction to the most commonly used technologies in XMLBeans. 2. For an even shorter introduction, see the Getting Started topic included with the release (./docs/guide/conGettingStartedwithXMLBeans.html) or at the web site (http://xmlbeans.apache.org/docs/2.2.0/guide/conGettingStartedwithXMLBeans.html). 3. Explore the samples provided with the release (./samples) or at the XMLBeans web site (http://xmlbeans.apache.org/samples/index.html). (3) Get more XMLBeans depth by compiling other schemas to understand and use generate Java types. * In the ./schemas directory you'll find some collections of schemas you can try out. - easypo: a contrived simple starter "purchase order" - nameworld: another simple schema - numerals: schema illustrating the use of various flavors of XmlSchema simple types - s4s: the Schema for Schema and Schema for XML To compile them, you can just send the whole directory to scomp, "scomp samples", or compile each file individually, "cd samples"; then "scomp easypo.xsd". You will get an "xmltypes.jar" out that contains all the compiled XMLBeans. To pick your own JAR filename just say scomp -out myeasypo.jar easypo.xsd * Especially as you get started, you will want to see the .java source code for the generated code. To get that, use a command-line like scomp -src mysrcdir -out myeasypo.jar easypo.xsd The "mysrcdir" will contain all the .java source code for the generated XMLBeans. * You can also use the XMLBean Ant task to compile your schemas during your build process: <taskdef name="xmlbean" classname="org.apache.xmlbeans.impl.tool.XMLBean" classpath="path/to/xbean.jar:path/to/jsr173_1.0_api.jar" /> <xmlbean schemas="easypo.xsd" destfile="myeasypo.jar" classpath="path/to/xbean.jar:path/to/jsr173_1.0_api.jar" /> For more information, see docs/guide/antXmlbean.html. (4) Learn more about code generated from your schema and about the XMLBeans API. Armed with the XMLBeans source code and the basic docs, you're ready to program. Things you need to know: * The org.apache.xmlbeans package has all the public classes for XMLBeans. Programs should not need to call anything else in xbean.jar directly. * XmlObject is the base class for all XMLBeans. It corresponds to xs:anyType. * Every schema type corresponds to an XMLBean interface, e.g., XmlAnySimpleType corresponds to xs:anySimpleType, and XmlInt corresponds to xs:int, etc.. And of course this extends to the XMLBean classes compiled from user-defined schemas. * Every XMLBean interface has an inner Factory class for creating or parsing instances, e.g., to load a file of generic type, use XmlObject.Factory.parse(myfile); to parse a string you expect to be a purchase-order, use PurchaseOrderDocument.Factory.parse("<ep:purchase-o..."); * XmlCursor is the API for full XML infoset treewalking. It is obtained via xmlobject.newCursor(). Using it is less convenient, but faster than using XML Objects, because it does not create objects as it traverses the XML tree. * SchemaType is the basic "schema reflection" API (just like Class, but for Schema). Get the actual schema type of any instance by saying "xobj.schemaType();" get the static constant schema type corresponding to any XMLBean class by saying "MyPurchaseOrder.type" or "XmlInt.type". (Analogous to "obj.getClass()" and "Object.class".) * A number of utility methods are available on org.apache.xmlbeans.XmlBeans, including a function that can be used to determine whether a Java class is an XmlBean and functions to manage runtime-loading of schema type systems or programmatically compiling Schema files. With that, you're ready to navigate the Javadoc and play with the code. Also, try reading some of our docs that are included in ./docs, as well as samples included in ./samples (5) Try some of the other utilities included in the ./bin directory; you can also see a few examples of XMLBean techniques in their source code. * "xpretty instance.xml" pretty-prints an XML instance document. The code is in (available via source SVN access) org.apache.xmlbeans.impl.tool.PrettyPrinter and is a reasonable example of how to load and save out an arbitrary XML document. XmlOptions are used to produce the pretty-printing. * "validate instance.xml schema.xsd" will validate the instance against the schema. XMLBeans is intended to be a very accurate XML schema validator. The code is in (available via source SVN access) org.apache.xmlbeans.impl.tool.InstanceValidator. It is an excellent example of how to load a schema type system dynamically at runtime, load and validate an instance within that type system, and how to obtain lists of and locations for validation errors. * "xsdtree easypo" will show the inheritance hierarchy of the schema types in that directory. The code is in xml.apache.org.tool.TypeHierarchyPrinter and is a good introduction to how to traverse the metadata in a schema type system. * "dumpxsb xbean.jar" or "dumpxsb myfile.xsb" will dump the contents of "xsb" (binary schema metadata) files in a human-readable form. These .xsb files contain the compiled metadata resulting from the .xsd files of a type system. They are analogous to .class fil