Fast Infoset modules description

Fast Infoset project contains several modules:

1. fastinfoset, the actual fastinfoset runtime implementation;

2. roundtrip-tests, the fastinfoset roundtrip test set;

3. utilities, the fastinfoset utilities, used for the element occurrences frequency analysis and other vocabulary tools;

4. samples, the fastinfoset samples.

Fast Infoset Maven 2 repository

We use Maven-Central repository

Fast Infoset runtime maven dependency

Here is FastInfoset runtime dependency you may want to add to your project's pom.xml:

        <dependency>
            <groupId>com.sun.xml.fastinfoset</groupId>
            <artifactId>FastInfoset</artifactId>
            <version>[version]</version>
        </dependency>
        

How to use the Fast Infoset parsers and serializers

The Fast Infoset project currently contains three types of implementations for the following APIs:

1. SAX, implementing the ContentHandler interface.

• Parser impl: com.sun.xml.fastinfoset.sax.SAXDocumentParser

• Serializer impl: com.sun.xml.fastinfoset.sax.SAXDocumentSerializer

2. StAX, implementing the XMLStreamReader and XMLStreamWriter interfaces.

• Parser impl: com.sun.xml.fastinfoset.stax.StAXDocumentParser

• Serializer impl: com.sun.xml.fastinfoset.stax.StAXDocumentSerializer

3. DOM, using the a conformant DOM implementation to construct or serialize a Document.

• Parser impl: com.sun.xml.fastinfoset.dom.DOMDocumentParser

• Serializer impl: com.sun.xml.fastinfoset.dom.DOMDocumentSerializer

There are no factory based mechanisms for instantiating the parsers and serializers, as is the case JAXP. It is necessary to instantiate the concrete classes (presented above) directly.

Using the Fast Infoset SAX parser and serializer

The following code shows how to parse a fast infoset document:

import java.io.*;
import org.xml.sax.*;
import com.sun.xml.fastinfoset.sax.*;

// Instantiate the FI SAX parser
XMLReader saxReader = new SAXDocumentParser();

// Set the content handler
ContentHandler ch = ...
saxReader.setContentHandler(ch);
// Parse the fast infoset document
InputStream in = new BufferedInputStream(new FileInputStream(<fast infoset document>));
saxReader.parse(new InputSource(in));

The following code shows how to translate an XML document to a fast infoset document using the Fast Infoset SAX serializer:

import java.io.*;
import javax.xml.parsers.*;
import com.sun.xml.fastinfoset.sax.*;

// Get the input stream for the XML document
InputStream xmlDocument = ...
// Set up output stream for fast infoset document
OutputStream fiDocument = ...

// Create Fast Infoset SAX serializer
SAXDocumentSerializer saxDocumentSerializer = new SAXDocumentSerializer();
// Set the output stream
saxDocumentSerializer.setOutputStream(fiDocument);

// Instantiate JAXP SAX parser factory
SAXParserFactory saxParserFactory = SAXParserFactory.newInstance();
/* Set parser to be namespace aware
 * Very important to do otherwise invalid FI documents will be
 * created by the SAXDocumentSerializer
 */
saxParserFactory.setNamespaceAware(true);
// Instantiate the JAXP SAX parser
SAXParser saxParser = saxParserFactory.newSAXParser();
// Set the lexical handler
saxParser.setProperty("http://xml.org/sax/properties/lexical-handler", documentSerializer);
// Parse the XML document and convert to a fast infoset document
saxParser.parse(xmlDocument, saxDocumentSerializer);

The following code shows how to translate a fast infoset document to an XML document using a FastInfosetSource and a StreamResult:

import java.io.*;
import javax.xml.transform.*;
import javax.xml.transform.stream.*;
import org.jvnet.fastinfoset.*;

// Get the input stream for the fast infoset document
InputStream fiDocument = ...
// Set up output stream for XML document
OutputStream xmlDocument = ...

// Create the transformer
Transformer tx = TransformerFactory.newInstance().newTransformer();
// Transform to convert the FI document to an XML document
tx.transform(new FastInfosetSource(fiDocument), new StreamResult(xmlDocument));

Using the Fast Infoset StAX parser and serializer

The following code shows how to parse a fast infoset document

import java.io.*;
import javax.xml.stream.*;
import com.sun.xml.fastinfoset.stax.*;

// Get the input stream for the fast infoset document
InputStream fiDocument = ...

// Create the StAX XMLStreamReader using the input stream
XMLStreamReader streamReader = new StAXDocumentParser(fiDocument);

The following code shows how to serialize to a fast infoset document:

import javax.xml.stream.*;
import com.sun.xml.fastinfoset.stax.*;

// Set up output stream for fast infoset document
OutputStream fiDocument = ...

// Create the StAX document serializer
StAXDocumentSerializer staxDocumentSerializer = new StAXDocumentSerializer();
staxDocumentSerializer.setOutputStream(fiDocument);

// Obtain XMLStreamWriter interface
XMLStreamWriter streamWriter = staxDocumentSerializer;

// Write out some simple infoset
streamWriter.writeStartDocument();
   streamWriter.writeStartElement(“foo”);
      streamWriter.writeCharacters(“bar”);
   streamWriter.writeEndElement();
streamWriter.writeEndDocument();
streamWriter.close();

Using the Fast Infoset StAX parser and serializer with JAXB

The following code shows how to unmarshall a fast infoset document using the FI StAX parser to an Object:

import java.io.*;
import javax.xml.bind.*;
import javax.xml.stream.*;
import com.sun.xml.fastinfoset.stax.*;

// Get the input stream for the fast infoset document
InputStream fiDocument = ...

// Create the StAX XMLStreamReader using the input stream
XMLStreamReader streamReader = new StAXDocumentParser(fiDocument);

// Create JAXB context
JAXBContext context = JAXBContext.newInstance(...);

// Create unmarshaller
Unmarshaller u = context.createUnmarshaller();
// Unmarshall from the stream to an object
Object jaxbObject = u.unmarshal(streamReader);

The following code shows how to marshall an Object using the FI StAX serializer to a fast infoset document:

import java.io.*;
import javax.xml.bind.*;
import javax.xml.stream.*;
import com.sun.xml.fastinfoset.stax.*;

// Set up output stream for fast infoset document
OutputStream fiDocument = ...

// Create the StAX document serializer
StAXDocumentSerializer staxDocumentSerializer = new StAXDocumentSerializer();
staxDocumentSerializer.setOutputStream(fiDocument);

// Obtain XMLStreamWriter interface
XMLStreamWriter streamWriter = staxDocumentSerializer;

// Create JAXB context
JAXBContext context = JAXBContext.newInstance(...);

// Create the marshaller
Marshaller m = context.createMarshaller();
// Marshall the object to the stream
m.marshal(jaxbObject, streamWriter);

When using the StAX parsers and serializers with the JAXB 2.0 java.net implementation there is an optimization to support the efficient marshalling and unmarshalling of byte[] that represents an xsd:base64Binary datatype for element content. When marshalling to XML documents such objects would be encoded to a string of characters that is the base64 encoding of the bytes. When marshalling to fast infoset documents using the FI StAX serializer such objects will be encoded as a sequence of octets that are the bytes of the object. When unmarshalling such octets will be directly assigned to the object. Thus no base64 encoding and decoding is required. This increases performance and reduces the size of fast infoset documents.