v1/xkit/README.txt

XMLBeans Development Kit


Welcome to XMLBeans!

Apache XMLBeans is an effort undergoing incubation at the 
Apache Software Foundation (ASF), sponsored by the XML project. 
Incubation is required of all newly accepted projects until a 
further review indicates that the infrastructure, communications, 
and decision making process have stabilized in a manner consistent 
with other successful ASF projects. While incubation status is not 
necessarily a reflection of the completeness or stability of the 
code, it does indicate that the project has yet to be fully 
endorsed by the ASF. 


Kit contents:

(1) One copy of xbean.jar, which contains XMLBeans.
    Should work on any JDK 1.4.x.
    ./lib/xbean.jar

(2) License information for XML Beans and included libraries
    ./license.txt

(3) One folder full of command-line scripts, pointing to the
    useful main() functions in the JAR.
    ./bin

(4) One bit of ant task documentation.
    ./anttask.html

(5) A copy of the plain javadoc tree for com.bea.xml.*
    ./docs/reference

(6) A preliminary collection of nicely formatted user-level
    documentation HTML (includes reformatted and nicely
    organized javadoc as well)
    ./docs/guide

(7) A few sample schemas
    ./schemas


Where to start?

(1) Setup.

    1. make sure you have a JDK 1.4.x installed; that java[.exe]
       is on your path and that JAVA_HOME/bin contains java[.exe],
       javac[.exe], and jar[.exe].

    2. set your XMLBEANDIR env variable to point to the directory
       containing xbean.jar (i.e., ./lib).

    3. put the scripts in ./bin on your path.

    4. run "scomp" with no arguments.  You should get a "usage"
       message.

(2) Try some schema compilation

    1. In the ./schemas directory you'll find some collections of
       schemas you can try out.

         - easypo: a contrived simple starter "purchase order"
         - cyclone: an actual customer schema (cyclonecommerce.com)
         - s4s: the Schema for Schema
         - j2ee: j2ee descriptor schemas

       To compile them, you can just send the whole directory to
       scomp, for example, "cd samples"; then "scomp easypo".
       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


    2. 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

       The "mysrcdir" will contain all the .java source code
       for the generated XMLBeans.

(3) Try using your compiled XMLBeans

    Now, 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 purcahse-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 avaliable on
      com.bea.xml.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.

    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

(3) Try some of the other utilities; you can also see a few
    examples of XMLBean techniques in their source code.

    1. "xpretty instance.xml" pretty-prints an XML instance
       document.

       The code is in xml.apache.org.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.

    2. "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 xml.apache.org.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.

    3. "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.

    4. "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.