Purchase Order Tutorial ^^^^^^^^^^^^^^^^^^^^^^^ This tutorial covers how to implement XML support for a particular schema. Prerequisites at the time of writing: * Maven 3 * Build GeoTools trunk locally; the ``gt2-xmlcodegen`` maven plugin is not published anywhere - you need to build it Create a New Project '''''''''''''''''''' Somewhere on your system: 1. Create a new directory called ``xml-po`` 2. Add the following ``pom.xml`` to the ``xml-po`` directory .. literalinclude:: /artifacts/xml/pom1.xml 3. Create the directories ``src/main/java and src/main/xsd``:: mkdir -p src/main/java mkdir -p src/main/resources mkdir -p src/test/java 4. Copy :download:`po.xsd <../../../artifacts/xml/po.xsd>` into ``src/main/resources`` .. literalinclude:: ../../../artifacts/xml/po.xsd Generate the Model '''''''''''''''''' The first step is to come up with an object model to work with. There are a number of technologies that will take an XML schema and generate Java code from it. To name a few: * Eclipse Modeling Framework * Java Architecture for XML Binding (JAXB) * XML Beans For this tutorial we will use JAXB. First we must configure the ``pom.xml`` file of our project to use the `maven-jaxb2-plugin `_ plugin, and also depend on JAXB as it will add some annotations. .. note:: We collected our :download:`po.xml ` schema from the sample projected available here: * http://confluence.highsource.org/display/MJIIP/Sample+projects You may wish to download a newer copy of the instructions if they seem out of date. 1. Add a dependency on ``jaxb api``: .. literalinclude:: /artifacts/xml/pom2.xml :start-after: :end-before: 2. Configure the JAXB maven plugin: .. literalinclude:: /artifacts/xml/pom2.xml :start-after: :end-before: The above configuration targets our project source directory; as we are only planning on running this generation code once. 3. At this point, your pom should look like this :download:`pom.xml ` . 4. Now we are ready to generate the model. Run the JAXB2 code generation:: [xml-po]$ mvn jaxb2:xjc [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Purchase Order XML Support 0.0.1-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- jaxb2-maven-plugin:2.3:xjc (default-cli) @ xml-po --- [INFO] Adding 'extension' flag to XJC arguments, since the 'generateEpisode' argument is given. (XJCs 'episode' argument requires that the 'extension' argument is provided). [INFO] Ignored given or default xjbSources [/Users/vickdw/Documents/workspace/xml-po/src/main/xjb], since it is not an existent file or directory. [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 0.998 s [INFO] Finished at: 2017-01-10T08:09:37-06:00 [INFO] Final Memory: 12M/303M [INFO] ------------------------------------------------------------------------ 5. Build the project:: [xml-po]% mvn install 6. At this point, the model should have been generated under ``src/main/java``. * ``Items.java`` * ``ObjectFactory.java`` * ``PurchaseOrderType.java`` * ``USAddress.java`` Generate the Bindings ''''''''''''''''''''' At this point, we have generated objects from the original schema. The next step will be to generate XML bindings from the original schema. To do this we will make use of the GeoTools XML generation plugin. 1. Add a dependency on the GeoTools XML module: .. literalinclude:: /artifacts/xml/pom3.xml :start-after: :end-before: 2. Configure the XML generation plugin: .. literalinclude:: /artifacts/xml/pom3.xml :start-after: :end-before: 3. A couple of things to note about the configuration: * The ``schemaLocation`` tag defines the target schema, in this case ``po.xsd``. * The ``destinationPackage`` defines which package we would like the generate code to end up in, in this case ``org.geotools.po.bindings`` * The ``constructorArguments`` tag defines the constructor arguments we want our XML bindings to take, in this case ``org.geotools.po.ObjectFactory`` which is a factory that was generated in our model in the previous section 4. At this point, your pom should look like this :download:`pom.xml ` . 5. Now we are ready to generate the bindings. Run the XML binding generator:: [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Purchase Order XML Support 0.0.1-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- xmlcodegen:17-SNAPSHOT:generate (default-cli) @ xml-po --- [INFO] org.apache.maven.artifact.factory.DefaultArtifactFactory@1ddae9b5 [INFO] Parsing schema: /Users/vickdw/Documents/workspace/xml-po/src/main/resources/po.xsd Downloading: https://repo.osgeo.org/repository/release/org/geotools/geotools/17-SNAPSHOT/maven-metadata.xml Downloaded: https://repo.osgeo.org/repository/release/org/geotools/geotools/17-SNAPSHOT/maven-metadata.xml (572 B at 0.5 KB/sec) Downloading: https://repo.osgeo.org/repository/release/geotools/geotools/17-SNAPSHOT/geotools-17-20170109.184824-56.pom Downloaded: https://repo.osgeo.org/repository/release/org/geotools/geotools/17-SNAPSHOT/geotools-17-20170109.184824-56.pom (71 KB at 182.0 KB/sec) [INFO] Generating bindings... Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate INFO: Generating binding for comment Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate INFO: Generating binding for purchaseOrder Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate INFO: Generating binding for Items Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate INFO: Generating binding for PurchaseOrderType Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate INFO: Generating binding for SKU Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate INFO: Generating binding for USAddress Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate INFO: Generating binding for Items_item Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.AbstractGenerator copy INFO: Copying /Users/vickdw/Documents/workspace/xml-po/src/main/resources/po.xsd to /Users/vickdw/Documents/workspace/xml-po/src/main/resources/org/geotools/po/bindings/po.xsd Jan 10, 2017 8:38:03 AM org.geotools.maven.xmlcodegen.BindingGenerator generate WARNING: Could not copy file /Users/vickdw/Documents/workspace/xml-po/src/main/resources/po.xsd java.io.FileNotFoundException: /Users/vickdw/Documents/workspace/xml-po/src/main/resources/org/geotools/po/bindings/po.xsd (No such file or directory) [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 4.092 s [INFO] Finished at: 2017-01-10T08:38:03-06:00 [INFO] Final Memory: 15M/291M [INFO] ------------------------------------------------------------------------ 5. At this point, the bindings should have been generated under ``src/main/java``:: [xml-po]% ls src/main/java/org/geotools/po/bindings ItemsBinding.java POSchemaLocationResolver.java Items_itemBinding.java po.xsd POBindingConfiguration.java PurchaseOrderTypeBinding.java POConfiguration.java SKUBinding.java PO.java USAddressBinding.java 6. Some explanation of the generated files is in order: * ``Binding.java`` These are the bindings themselves, there should be one for every type in the purchase order schema * ``PO.java`` An interface which contains constants for the qualified names of attributes, elements, and types defined in the schema * ``POConfiguration`` The parser configuration used to prepare the XML parser for parsing an instance of the schema * ``POSchemaLocationResolver.java`` Helper class used by the configuration to locate our schema file while parsing * ``POBindingConfiguration.java`` Helper class used by the configuration to register the generated bindings with the parser Implement the Bindings '''''''''''''''''''''' The next step is to implement the bindings, which are at this point contain stub methods. 1. At this time it will be useful to switch to your development environment. The following steps can be used by Eclipse users: Run the command:: [xml-po]% mvn eclipse:eclipse [INFO] Scanning for projects... [INFO] Searching repository for plugin with prefix: 'eclipse'. [INFO] ------------------------------------------------------------------------ [INFO] Building Purchase Order XML Support [INFO] task-segment: [eclipse:eclipse] [INFO] ------------------------------------------------------------------------ [INFO] Preparing eclipse:eclipse [INFO] No goals needed for project - skipping [INFO] [eclipse:eclipse {execution: default-cli}] [INFO] Using Eclipse Workspace: null [INFO] Adding default classpath container: org.eclipse.jdt.launching.JRE_CONTAINER [INFO] Wrote settings to /Users/jody/java/geotools/xml-po/.settings/org.eclipse.jdt.core.prefs [INFO] Wrote Eclipse project for "gt2-xml-po" to /Users/jody/java/geotools/xml-po. [INFO] 2. The command will produce a few warnings were it cannot find source or javadoc files but it will generate a ``.project`` and ``.classpath`` allowing you to import the project into eclipse. .. image:: /images/xml/eclipseImport.png .. note:: You may get a compile error from Eclipse noting ``The method parse(InstanceComponent, Object) in the type AbstractSimpleBinding is not applicable for the arguments (ElementInstance, Node, Object) PurchaseOrderBinding.java /xml-po/src/main/java/org/geotools/po/bindings line 60 Java Problem`` This is easily solved by changing PurchaseOrderBinding to extend AbstractComplexBinding instead of the generated ``AbstractSimpleBinding``. 3. We will take a bottom approach to implementation of the bindings, that is starting with bindings for types that are referenced by other types. SKU (Simple Type) ''''''''''''''''' 1. We will start by implementing the binding for the SKU type in our schema:: 2. From the schema definition, we see that the SKU type is a Simple Type, which extends ``xsd:string.`` In the realm of XML schema, the following diagram depicts the inheritance hierarchy of the SKU type: .. image:: /images/xml/skuHierachy.png 3. The parser takes this hierarchy into account when executing bindings. The bindings are executed in order from the top down. The output of each binding is passed on to the next binding in the chain. The following diagram depicts the binding execution chain: .. image:: /images/xml/skuExecutionChain.png 4. Implement the parse method So with that explanation, we can implement the ``SKUBinding.parse`` method:: Object parse( InstanceComponent instance, Object value ) { return null; } The value parameter is the parsed value that has been passed down from the parent ( ``xsd:string`` ), which is an instance of ``java.lang.String``, so we can cast accordingly.:: Object parse( InstanceComponent instance, Object value ) { String sku = (String) value; return sku; } At this point we could call it the end of the day, but the type definition for SKU constrains the value space with a pattern facet. So could also add a check for the pattern match:: Object parse( InstanceComponent instance, Object value ) { String sku = (String) value; if ( !sku.matches( "\\d{3}-[A-Z]{2}" ) ) { throw new IllegalArgumentException( "Illegal sku format: " + sku ); } return sku; } 5. Implement the ``getType`` method The last thing to do in implementing the SKU binding is to declare the type of the object that it returns. From the implementation parse it is clear that this is ``java.lang.String``.:: Class getType() [ return String.class; } 6. You can download completed :download:`SKUBinding.java ` . Comment (Simple Type) ''''''''''''''''''''' 1. We will start by implementing the binding for the ``Comment`` type in our schema:: 2. Implement the ``parse`` method:: Object parse(InstanceComponent instance, Object value) throws Exception { String comment = (String) value; return comment; } 3. Implement the ``getType`` method:: Class getType() { return String.class; } 4. You can download the completed code :download:`CommentBinding.java ` . USAddress (Complex Type) '''''''''''''''''''''''' 1. Next we will move on to implement a binding for the ``ComplexType`` ``USAddress``:: 2. Complex bindings follow the same execution chain as simple types in which a parsed value is passed down the chain into the parse method. The parse method for a complex binding is a little different then the parse method for a simple binding:: Object parse(ElementInstance instance, Node node, Object value) throws Exception { //TODO: implement return null; } 3. The difference is the addition of the node parameter. A ``Node`` instance contains the parsed values of all elements and attributes contained within the complex type. The node API is map like in which element and attribute values can be looked up by name:: interface Node { Object getChildValue( String name ); Object getAttributeValue( String name ): } So in implementing the binding for ``USAddress``, we will make use of the node to obtain the properties of the address. 4. Implement the parse method The first step is to create a new instance of ``USAddress``. To do so we make use of the ``org.geotools.po.ObjectFactory``. If you remember earlier when we configured the binding generator, we specified that each binding should take one of these factories in its constructor. Well know we will put it to use.:: Object parse(ElementInstance instance, Node node, Object value) throws Exception { USAddress address = factory.createUSAddress(); return address; } 5. Next, we must get the values for each of the elements and attributes defined in the XML schema type for ``USAddress`` from the node parameter:: Object parse(ElementInstance instance, Node node, Object value) throws Exception { USAddress address = factory.createUSAddress(); //elements address.setName( (String) node.getChildValue( "name" ) ); address.setStreet( (String) node.getChildValue( "street" ) ); address.setCity( (String) node.getChildValue( "city" ) ); address.setState( (String) node.getChildValue( "state" ) ); address.setZip( (BigDecimal) node.getChildValue( "zip" ) ); //attribute address.setCountry( (String) node.getAttributeValue( "country" ) ); return address; } 6. Implement the ``getType`` method Same as with simple types above, complex bindings must declare the type of object they create. And so:: Class getType() { return USAddress.class; } 7. You can download a complete :download:`USAddressBinding.java ` Item ( Anonymous Complex Type ) ''''''''''''''''''''''''''''''' Moving along we encounter the Items type. The schema for the type is relatively straight forward, it is an collection of item elements:: However, the element ``item`` itself provides a small wrinkle: it has an Anonymous Inline Type Definition. 1. The convention used for the binding append the element name to the name of the parent. In this case ``Items_item``.:: Class getType() { return Items.Item.class; } Object parse(ElementInstance instance, Node node, Object value) throws Exception { Items.Item item = factory.createItemsItem(); //elements item.setProductName( (String) node.getChildValue( "productName") ); item.setQuantity( (BigInteger) node.getChildValue( "quantity" ) ); item.setUSPrice( (BigDecimal) node.getChildValue( "USPrice" ) );item.setComment( (String) node.getChildValue( "comment" ) ); //attributes item.setPartNum( (String) node.getAttributeValue( "partNum" ) ); return item; } 2. You can download a complete :download:`Items_itemBinding.java ` Items ( Another Complex Type ) '''''''''''''''''''''''''''''' Items is just a container for multiple Item elements. 1. In implementing we make use of the ``getChildValues()`` method of Node, which returns a collection of child elements corresponding to a particular name.:: Class getType() { return Items.class; } Object parse(ElementInstance instance, Node node, Object value) throws Exception { //create the items collection Items items = factory.createItems(); //add each item items.getItem().addAll( node.getChildValues( "item" ) ); return items; } 2. You can download a complete :download:`ItemsBinding.java ` PurchaseOrder ( Another Complex Type ) '''''''''''''''''''''''''''''''''''''' 1. ``PurchaseOrder`` is a complex type based upon the complex type ``PurchaseOrderType``:: Class getType() { return PurchaseOrderType.class; } Object parse(ElementInstance instance, Node node, Object value) throws Exception { PurchaseOrderType po = new PurchaseOrderType(); po.setBillTo((USAddress) node.getChildValue("billTo")); po.setShipTo((USAddress) node.getChildValue("shipTo")); po.setItems((Items) node.getChildValue("items")); po.setComment((String) node.getChildValue("comment")); po.setOrderDate((XMLGregorianCalendar) node.getAttributeValue("orderDate")); return po; } 2. You can download a complete :download:`PurchaseOrderBinding.java ` PurchaseOrderType( The Last One ) ''''''''''''''''''''''''''''''''' Onto the final binding to implement ``PurchaseOrderType``. 1. Compared to the binding for Items it is simple:: Class getType() { return PurchaseOrderType.class; } Object parse(ElementInstance instance, Node node, Object value) throws Exception { PurchaseOrderType purchaseOrder = factory.createPurchaseOrderType(); purchaseOrder.setShipTo( (USAddress) node.getChildValue( "shipTo" ) ); purchaseOrder.setBillTo( (USAddress) node.getChildValue( "billTo" ) ); purchaseOrder.setComment( (String) node.getChildValue( "comment" ) ); purchaseOrder.setItems( (Items) node.getChildValue( "items") ); return purchaseOrder; } 2. You can download a complete :download:`PurchaseOrderTypeBinding.java ` All Done!! ... for now. And that's that for implementing the bindings. In the continuing sections we will focus on configuring the parser in order to hook up the bindings implemented in this section. Configure the Binding Context ''''''''''''''''''''''''''''' You should recall above our discussion about injecting all of our bindings with an instance of ``org.geotools.po.ObjectFactory``. But where does this come from? The answer is the Binding Context. The Binding Context is a container ( ``PicoContainer`` ) in which all the bindings are created in. The container uses Dependency Injection to satisfy binding dependencies. Therefore anytime a binding requires a factory or some other class to do work, it just has to declare one in its constructor. But, these dependencies have to be placed in the container at some point. This is done by the Configuration class. So in our case we would like to place an instance of ``org.geotools.po.ObjectFactory`` in the context. We do this by implementing the ``configureContext`` method in ``POConfiguration``.:: class POConfiguration { ... protected void configureContext(MutablePicoContainer context) { context.registerComponentImplementation( ObjectFactory.class ); } } The complete implementation of ``POConfiguration`` can be found here. Test the Bindings ''''''''''''''''' Now that the bindings are implemented, it is time to do some testing. 1. Add the ``junit`` dependency to the pom:: junit junit 4.11 test 2. Execute the following command once again: ( If you are using Eclipse ):: [xml-po]% mvn eclipse:eclipse 3. Switch to your IDE and create a new test class: ``POTest`` ( remember that test cases live under ``src/test/java`` in the project ):: class POTest extends TestCase { } 4. Next, create a test method called test, which will build up a DOM tree for an ``USAddress`` element.:: public void test() throws Exception { InputStream input = getClass().getResourceAsStream( "po.xml" ); POConfiguration configuration = new POConfiguration(); Parser parser = new Parser( configuration ); PurchaseOrderType po = (PurchaseOrderType) parser.parse( input ); assertNotNull( po ); } 5. The complete implementation of ``POTest`` can be found here. 6. To run the test we will create a test resource directory:: [xml-po]% mkdir -p src/test/resources/org/geotools/po 7. Copy ``po.xml`` into the new directory 8. Run the test from your IDE