org.mitre.taxii.messages

Class TaxiiXml

java.lang.Object

org.mitre.taxii.messages.TaxiiXml

Direct Known Subclasses:

TaxiiXml, TaxiiXml

public abstract class TaxiiXml
extends java.lang.Object

JAXB utility class.

This class provides a JAXB environment for marshaling, unmarshaling, and validating TAXII messages. There are concrete subclasses to handle specific versions of TAXII. The factory class for a specific version of TAXII should be used to create a TaxiiXml object. There are a number of version specific parameters that must be set to create a useful TaxiiXml, the factories ensure the object is initialized properly.

Usage example

The following example demonstrates creating a TaxiiXml object and using it to validate, marshal, and unmarshal a simple TAXII message.

      ObjectFactory of = new ObjectFactory(); // JAXB factory for TAXII 
      TaxiiXmlFactory txf = new TaxiiXmlFactory(); // Create a factory with the default configuration.
      TaxiiXml taxiiXml = txf.createTaxiiXml(); // get a properly configured TaxiiXml
 
      DiscoveryMessage dm = of.createDiscoveryMessage()
                              .withMessageId(MessageHelper.generateMessageId());
 
      Validation results = taxiiXml.validateFast(dm, true); // Validate, failing on first error encountered, and perfoming Schematron validation.
 
      String xmlStr = taxiiXml.marshalToString(dm, true);
 
      DiscoveryMessage dm2 = taxiiXml.getJaxbContext().createUnmarshaller().unmarshal(new StringReader(xmlString));
 
 

Validation

Note that validateFast(Object, boolean) and validateAll(Object, boolean) perform validation checks beyond those done by the underlying XML schema; thus, these methods should be preferred over doing schema validation during JAXB marshalling and unmarshalling. Specifically, Marshaller.setSchema(Schema) and Unmarshaller.setSchema(Schema) should NOT be used for validation, as the additional code checks would not be performed; instead, validateFast(Object, boolean) or validateAll(Object, boolean) should be called before marshalling and after unmarshalling.

The following examples show how validation should be done before marshalling or after unmarshalling.

Fast Validation before Marshalling

 try {
   TaxiiXmlFactory txf = new TaxiiXmlFactory();
   TaxiiXml taxiiXml = txf.createTaxiiXml();
   Validation results = taxiiXml.validateFast(msg, true);
   if (results.hasWarnings()) {
     System.out.print("Validation warnings: ");
     System.out.println(results.getAllWarnings());
   }
   Marshaller m = taxiiXml.createMarshaller(true);
   m.marshal(msg, System.out);
 }
 catch (SAXParseException e) {
   System.err.print("Validation error: ");
   System.err.println(Validation.formatException(e));
 } 
 catch (SAXException e) {
   System.err.print("Validation error: ");
   e.printStackTrace();
 }
 

Fast Validation after Unmarshalling

 try {
   TaxiiXmlFactory txf = new TaxiiXmlFactory();
   TaxiiXml taxiiXml = txf.createTaxiiXml();
   Unmarshaller u = taxiiXML.getJaxbContext().createUnmarshaller();
   MessageType msg = (MessageType) u.unmarshal(input);
   Validation results = taxiiXml.validateFast(msg, true);
   if (results.hasWarnings()) {
     System.out.print("Validation warnings: ");
     System.out.println(results.getAllWarnings());
   }
   // do something with msg
 }
 catch (SAXParseException e) {
   System.err.print("Validation error: ");
   System.err.println(Validation.formatException(e));
 } 
 catch (SAXException e) {
   System.err.print("Validation error: ");
   e.printStackTrace();
 }
 

Comprehensive Validation before Marshalling

 try {
   TaxiiXmlFactory txf = new TaxiiXmlFactory();
   TaxiiXml taxiiXml = txf.createTaxiiXml();
   Validation results = taxiiXml.validateAll(msg, true);
   if (results.isSuccess()) {
     if (results.hasWarnings()) {
     System.out.print("Validation warnings: ");
       System.out.println(results.getAllWarnings());
     }
     Marshaller m = taxiiXml.createMarshaller(true);
     m.marshal(msg, System.out);
   }
   else {  // validation errors and warnings together
     System.err.print("Validation results: ");
     System.err.println(results.getAllErrorsAndWarnings());
   }
 }
 catch (SAXParseException e) {
   System.err.print("Fatal validation error: ");
   System.err.println(Validation.formatException(e));
 } 
 catch (SAXException e) {
   System.err.print("Fatal validation error: ");
   e.printStackTrace();
 }
 

Comprehensive Validation after Unmarshalling

 try {
   TaxiiXmlFactory txf = new TaxiiXmlFactory();
   TaxiiXml taxiiXml = txf.createTaxiiXml();
   Unmarshaller u = taxiiXML.getJaxbContext().createUnmarshaller();
   MessageType msg = (MessageType) u.unmarshal(input);
   Validation results = taxiiXml.validateAll(msg, true);
   if (results.isSuccess()) {
     if (results.hasWarnings()) {
       System.out.print("Validation warnings: ");
       System.out.println(results.getAllWarnings());
     }
     // do something with msg
   }
   else {  // validation errors and warnings together
     System.err.print("Validation results: ");
     System.err.println(results.getAllErrorsAndWarnings());
   }
 }
 catch (SAXParseException e) {
   System.err.print("Fatal validation error: ");
   System.err.println(Validation.formatException(e));
 } 
 catch (SAXException e) {
   System.err.print("Fatal validation error: ");
   e.printStackTrace();
 }
 

Constructor Summary

Constructors

Constructor and Description
TaxiiXml(java.lang.String taxiiVersion, java.lang.String serviceVersion, java.lang.String taxiiPackage, java.util.List<java.lang.String> otherPackages, java.lang.String schemaLocation, java.lang.String validatorLocation) Constructor that takes additional JAXB packages, used in initializing the JAXB Context.

Method Summary

Methods

Modifier and Type	Method and Description
javax.xml.bind.Marshaller	createMarshaller(boolean prettyPrint) Returns a marshaller for the TAXII XML Message Binding 1.0 classes.
javax.xml.bind.JAXBContext	getJaxbContext() Returns the JAXB Context.
java.util.List<java.lang.String>	getJaxbContextPath() Returns a read-only list of JAXB packages that the underlying JAXB Context knows about.
abstract HttpResponseErrorHandler	getResponseHandler()
java.lang.String	getServiceVersion()
java.lang.String	getTaxiiVersion()
abstract boolean	isRequestMessage(java.lang.Object message)
java.lang.String	marshalToString(javax.xml.bind.Marshaller m, java.lang.Object msg) Marshals a given TAXII Message to an XML String.
java.lang.String	marshalToString(java.lang.Object msg, boolean prettyPrint)
Validation	validateAll(java.lang.Object m, boolean checkSpecConformance) Validates the given message, returning all accumulated errors and warnings.
Validation	validateFast(java.lang.Object m, boolean checkSpecConformance) Validates the given message, throwing a SAXException on the first validation error encountered.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TaxiiXml

public TaxiiXml(java.lang.String taxiiVersion,
        java.lang.String serviceVersion,
        java.lang.String taxiiPackage,
        java.util.List<java.lang.String> otherPackages,
        java.lang.String schemaLocation,
        java.lang.String validatorLocation)

Constructor that takes additional JAXB packages, used in initializing the JAXB Context. For internal use. Use a TaxiiXmlFactory of the proper version to create a TaxiiXml instance.

Parameters:

taxiiVersion -

serviceVersion -

taxiiPackage -

otherPackages -

schemaLocation -

validatorLocation -

Throws:

java.lang.RuntimeException - if a deployment error prevents the underlying JAXBContext from being created, the Schema from being parsed, or the validating stylesheet from being compiled.

See Also:

TaxiiXmlFactory, TaxiiXmlFactory

Method Detail

createMarshaller

public javax.xml.bind.Marshaller createMarshaller(boolean prettyPrint)
                                           throws javax.xml.bind.JAXBException

Returns a marshaller for the TAXII XML Message Binding 1.0 classes.

Parameters:

prettyPrint - Returns a marshaller that indents the output if true.

Returns:

a marshaller to serialize TAXII XML objects.

Throws:

javax.xml.bind.JAXBException - if an error was encountered while creating the Marshaler

validateAll

public Validation validateAll(java.lang.Object m,
                     boolean checkSpecConformance)
                       throws javax.xml.bind.JAXBException,
                              org.xml.sax.SAXException,
                              java.io.IOException

Validates the given message, returning all accumulated errors and warnings.

Parameters:

m - The message to validate

checkSpecConformance - Check conformance to specification beyond what XML Schema provides.

Returns:

The validation results, including all errors and warnings.

Throws:

javax.xml.bind.JAXBException - If the message couldn't be validated because of an underlying JAXB error

java.io.IOException - If the underlying XMLReader throws an IOException.

org.xml.sax.SAXException - on any fatal validation error

validateFast

public Validation validateFast(java.lang.Object m,
                      boolean checkSpecConformance)
                        throws javax.xml.bind.JAXBException,
                               org.xml.sax.SAXException,
                               java.io.IOException

Validates the given message, throwing a SAXException on the first validation error encountered.

Parameters:

m - The message to validate

checkSpecConformance - Check conformance to specification beyond what XML Schema provides.

Returns:

The validation results, including any warnings. If this method returns successfully, then isSuccess() on the returned object will always return true.

Throws:

javax.xml.bind.JAXBException - If the message couldn't be validated because of an underlying JAXB error

java.io.IOException - If the underlying XMLReader throws an IOException.

org.xml.sax.SAXException - On the first validation error

marshalToString

public java.lang.String marshalToString(javax.xml.bind.Marshaller m,
                               java.lang.Object msg)
                                 throws javax.xml.bind.JAXBException

Marshals a given TAXII Message to an XML String.

Throws:

javax.xml.bind.JAXBException - if any unexpected problem occurs during marshalling

marshalToString

public java.lang.String marshalToString(java.lang.Object msg,
                               boolean prettyPrint)
                                 throws javax.xml.bind.JAXBException

Throws:

javax.xml.bind.JAXBException

getJaxbContext

public javax.xml.bind.JAXBContext getJaxbContext()

Returns the JAXB Context.

getJaxbContextPath

public java.util.List<java.lang.String> getJaxbContextPath()

Returns a read-only list of JAXB packages that the underlying JAXB Context knows about.

getTaxiiVersion

public java.lang.String getTaxiiVersion()

getServiceVersion

public java.lang.String getServiceVersion()

getResponseHandler

public abstract HttpResponseErrorHandler getResponseHandler()

isRequestMessage

public abstract boolean isRequestMessage(java.lang.Object message)