XMLBeans Schema Generation

Overview

This document is meant to be a brief overview of using the powerful XMLBeans functionality with the Gateway to easily build and validate XML documents using Java code.

Generation of classes

XMLBeans is able to generate Java classes from a supplied .xsd schema file. We use generated classes of this type for our SSTP implementation to build acknowledgments, test transmissions, and receipts among other things. Our current build system, Maven, contains a plugin to generate these classes for use in our code.

Developers who wish to add new functionality to the Gateway for other XML schemas can do so with a few simple steps. First, the XMLBeans Maven plugin must be configured in the desired module's pom.xml. The following code is taken from the pom.xml of our sstp-base module. It specifies the location of the SSTP XML schema to be converted into Java classes and is run with the Maven build goal.

        <project>
        ...     
                <build>
                ...
                        <plugins>
                        ...
                                <plugin>
                                        <groupId>org.codehaus.mojo</groupId>
                                        <artifactId>xmlbeans-maven-plugin</artifactId>
                                        <executions>
                                                <execution>
                                                        <goals>
                                                                <goal>xmlbeans</goal>
                                                        </goals>
                                                </execution>
                                        </executions>
                                        <inherited>true</inherited>
                                        <configuration>
                                                <schemaDirectory>src/main/xsd</schemaDirectory>
                                        </configuration>
                                </plugin>
                        ...
                        </plugins>
                ...
                </build>
        ...
        </project>

The generated classes are imported by their namespace and XML tag name as actual Java classes. An SSTPTransmission type would be imported with the code:

    import noNamespace.SSTPTransmissionType;

Usage of generated classes

There is a wide range of functionality provided with the generated Java classes. The use of these classes within the Gateway is described in this section.

  • Construction of an XML document

    Below is a snippet of code from TransmissionGenerator.java

    The objects created here are named after the types defined in the XML schema. Manipulation of their fields is as simple as using .getXXX() and .setXXX() where XXX is a sub-type. In this code an SSTPDocument object is being created to be added to an SSTP transmission. This is a rough example of usage and by looking over the methods in TransmissionGenerator you can get a more complete view of the usage. Simple types can be set with simple objects such as int, String, long, etc. Complex XML types are represented as objects you must also create using the .addXXX() method.

      ...
            SSTPDocumentDocument1 doc = SSTPDocumentDocument1.Factory.newInstance();

        // SSTPDocument
        SSTPDocument document = doc.addNewSSTPDocument();

        document.setDocumentId(generateId());
        document.setDocumentType(SSTPDocumentDocument1.SSTPDocument.DocumentType.PAYMENT_ONLY);

        // SSTPDocument/SSTPFilingHeader
        SSTPFilingHeaderType header = document.addNewSSTPFilingHeader();

        // SSTPDocument/SSTPFilingHeader/FIPSCode
        header.setFIPSCode(Constants.FIPS_CODE);

        // SSTPDocument/SSTPFilingHeader/SSTPID
        header.setSSTPID(user);

        // SSTPDocument/SSTPFilingHeader/ElectronicPostmark
        SSTPFilingHeaderType.ElectronicPostmark postMark = header.addNewElectronicPostmark();
        postMark.setCalendarValue(today);
        postMark.setDateSupplier(SSTPFilingHeaderType.ElectronicPostmark.DateSupplier.TRANSMITTER);

        // SSTPDocument/SSTPFilingHeader/TaxPeriodStartDate
        header.setTaxPeriodStartDate(taxPeriodStart);
  ...

    There is much more documentation explaining usage of these generated XML classes on the XMLBeans site .

  • Validation of an XML document

    Validating XML documents is very simple when they are loaded in as instances of an XMLBeans generated class. The following code shows a method from ValidationUtils.java . 

      public static boolean validateAcknowledgement(ArrayList errorList, String xml)
            throws Exception {

        XmlOptions validationOptions = new XmlOptions();

        validationOptions.setLoadLineNumbers();

        SSTPAcknowledgementDocument validateThis = SSTPAcknowledgementDocument.Factory.parse(xml, validationOptions);

        // run XMLBeans validation with schema
        validationOptions.setErrorListener(errorList);

        // set up and run transmission level rules
        boolean validateResult = validateThis.validate(validationOptions);

                //...
        //non-XMLBeans Gateway-specific validation code omitted
        //...
        
        }
        return validateResult;
        
  }

    This method makes use of the ability of XMLBeans to build a list of errors and include their line number. A String containing XML and a List are passed in. The String is parsed into an XMLBeans object and validation is as simple as calling .validate() with or without arguments to get a boolean value stating weather or not the XML is valid.