XSOM User's Guide

Parsing a schema

Use the com.sun.xml.xsom.parser.XSOMParser class to parse schemas. There are a couple of overloaded versions of the parse method.

XSOMParser works like this; You create a new instance of XSOMParser, set it up, then call the parse method to parse a schema file. When a schema is parsed, all the schemas that are refered from it (<include>and <import>) will also be parsed. If you have multiple separate schema files that need to be compiled together, just call the parse method multiple times.

Once you parse all the schemas you want, call the getResult method to obtain the XSSchemaSet object, then use that object to obtain information about the schema.

import com.sun.xml.xsom.parser.XSOMParser;
import com.sun.xml.xsom.XSSchemaSet;

XSOMParser parser = new XSOMParser();
parser.setErrorHandler(...);
parser.setEntityResolver(...);

parser.parseSchema( new File("myschema.xsd"));
parser.parseSchema( new File("XHTML.xsd"));

XSSchemaSet sset = parser.getResult();

Now you can access schema information by using this SchemaSet.

Parsing from SAX events

For more sophisticated uses, you can feed SAX2 events to XSOM. This will be useful when the schema is not present as a stand-alone XML. For example, this can be used to:

• parse XML Schema inside another XML, such as WSDL
• generate XML on-the-fly and parse it

The following example shows how one can apply a XSLT transformation to produce XML Schema and parse it into XSOM:

import com.sun.xml.xsom.parser.XSOMParser;
import com.sun.xml.xsom.XSSchemaSet;

XSOMParser parser = new XSOMParser();
parser.setErrorHandler(...);
parser.setEntityResolver(...);

// set up XSLT
TransformerFactory tf = TransformerFactory.newInstance();
Transformer t = tf.newTransformer(new StreamSource(new File("wsdl2xsd.xsl"));

ContentHandler xsomHandler = parser.getParserHandler();

// run the transformation and feed the result to XSOM
t.transform(
    new StreamSource(new File("test.wsdl")),
    new SAXResult(xsomhandler));

XSSchemaSet sset = parser.getResult();

Error Handling

All the error messages will be sent to SAX ErrorHandler, which can be specified through the setErrorHandler method on XSOMParser.

Entity Resolution

By setting EntityResolver to XSOMParser, you can redirect <xs:include>s and <xs:import>s to different resources. For imports, the namespace URI of the target schema is passed as the public ID, and the absolutized value of the schemaLocation attribute will be passed as the system ID.

Parsing Annotations

There is a hook in XSOM that allows client applications to parse annotations in schema into an application specific data structure by using AnnotationParser. With this mechanism, the application-specified code can receive SAX events for every annotations found in the document.

AnnotationParser will be responsible for parsing these SAX events into an object, and that object will be attached to the appropriate "owner" schema component by XSOM automatically. The information can be later retrieved through the getAnnotation method.

By default, all the annotations are ignored, but you can easily parse them into a DOM tree or an application-specific data structure.

For details, see com.sun.xml.xsom.impl.parser.AnnotationParser and AnnotationParserFactory. An annotation parser can be attached to XSOMParser through the setAnnotationParser method. There's also a convenient utility class called DomAnnotationParserFactory that parses annotations into DOM.

Accessing Schema Information

The com.sun.xml.xsom package contains all the public interfaces available for client applications. It shouldn't be too hard to understand if you know well about schema components, which are defined in the XML Schema spec.

The interface is modeled after this document so this might help you understand XSOM.

For example, the following code lists all the global element declarations and whether they are abstract or not.

XSSchemaSet result = /* parse XML Schema */;

// iterate each XSSchema object. XSSchema is a per-namespace schema.
Iterator itr = result.iterateSchema();
while( itr.hasNext() ) {
  XSSchema s = (XSSchema)itr.next();
  
  System.out.println("Target namespace: "+s.getTargetNamespace());
  
  Iterator jtr = s.iterateElementDecls();
  while( jtr.hasNext() ) {
    XSElementDecl e = (XSElementDecl)jtr.next();
    
    System.out.print( e.getName() );
    if( e.isAbstract() )
      System.out.print(" (abstract)");
    System.out.println();
  }
}

Visitor pattern support

XSOM comes with a visitor pattern support, which simplifies the development of the client application. XSOM implements two different visitors. One is a visitor that returns void, and the other is a "functor" that returns Object. All the interfaces are available in com.sun.xml.xsom.visitor.

For more about the visitor pattern, see this summary or read this book.