mirror of https://github.com/apache/poi.git
254 lines
9.3 KiB
Plaintext
254 lines
9.3 KiB
Plaintext
/* 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 2.5.0
|
|
|
|
|
|
Welcome to XMLBeans!
|
|
|
|
|
|
Kit contents:
|
|
|
|
(1) One copy of xbean.jar, which contains XMLBeans.
|
|
Should work on any JDK 1.4.x or 1.5.x.
|
|
./lib/xbean.jar
|
|
|
|
(2) One copy of jsr173_1.0_api.jar, which contains classes
|
|
needed to parse XML files for use with XMLBeans.
|
|
./lib/jsr173_1.0_api.jar
|
|
|
|
(3) One copy of resolver.jar from Apache xml-commons. See scomp
|
|
documentation for when it is needed.
|
|
./lib/resolver.jar
|
|
|
|
(4) One copy of xbean_xpath jar. Contains the XPath and XQuery
|
|
"glue" code, only needed if XPath-XQuery functionality is
|
|
required.
|
|
./lib/xbean_xpath.jar
|
|
|
|
(5) One copy of xmlpublic.jar, containing all the public interfaces of
|
|
XMLBeans. (Classes included here are a subset of those included
|
|
in xbean.jar.)
|
|
./lib/xmlpublic.jar
|
|
|
|
(6) One copy of xmlbeans-qname.jar, contains javax.xml.namespace
|
|
QName.class and NamespaceContext.class. These classes were
|
|
introduced in the jdk since 1.5. This jar is necesary on classpath
|
|
only if using jdk 1.4.
|
|
./lib/xmlbeans-qname.jar
|
|
|
|
(7) License information for XML Beans and included libraries
|
|
./LICENSE.txt
|
|
./NOTICE.txt
|
|
|
|
(8) One folder full of command-line scripts, pointing to the
|
|
useful main() functions in the JAR.
|
|
./bin
|
|
|
|
(9) A copy of the plain javadoc tree for org.apache.xmlbeans.*
|
|
./docs/reference
|
|
|
|
(10) A preliminary collection of nicely formatted user-level
|
|
documentation HTML (includes reformatted and nicely
|
|
organized javadoc as well)
|
|
./docs/guide
|
|
|
|
(11) A few sample schemas
|
|
./schemas
|
|
|
|
(12) 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.4.x installed (or 1.5.x); 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 files
|
|
for .java.
|
|
|
|
* "inst2xsd mydoc.xml" will generate a [set of] XmlSchema
|
|
file based on the instance document provided. This is
|
|
useful as a starting point in authoring an XmlSchema
|
|
document.
|
|
|
|
* "xsd2inst schema.xsd -name root" will generate a
|
|
sample xml document with root "root", based on the
|
|
schema definitions from the provided file.
|
|
|
|
The code is in (available via source SVN access)
|
|
org.apache.xmlbeans.impl.xsd2inst.SampleXmlUtil and is
|
|
a great example of how to combine the XmlCursor and
|
|
SchemaType APIs to create a full [sub]document
|
|
that includes required children, default values, etc.
|
|
|