Skip to content

Factory Configuration

Jump to bottom
Christoph Beck edited this page Feb 6, 2014 · 11 revisions

StAXON comes with JSON-specific implementations of StAX' javax.xml.XMLInputFactory and javax.xml.XMLOutputFactory, which provide various methods for reader and writer creation. When using StAXON, it is not unlikely, that these are the only classes from StAXON you will reference directly:

  • JsonXMLInputFactory extends XMLInputFactory - factory to create instances of XMLStreamReader and XMLEventReader
  • JsonXMLOutputFactory extends XMLOutputFactory - factory to create instances of XMLStreamWriter and XMLEventWriter

These factories are configured with their setProperty(String, Object) method. Beyond the standard properties defined by XMLInputFactory and XMLOutputFactory, StAXON's factories accept some additional, JSON-specific properties.

Input Properties

The JsonXMLInputFactory class supports the following properties, defined by static string constants:

  • PROP_MULTIPLE_PI (boolean) - whether to report the <? xml-multiple ... ?> processing instruction (default is true)
  • PROP_VIRTUAL_ROOT (QName) - if set, insert root element with the given name (default is null)
  • PROP_NAMESPACE_SEPARATOR (char) - character used as namespace prefix separator (default is ':')
  • PROP_NAMESPACE_MAPPINGS (Map) - associate namespace URIs with prefixes (default is null)

Output Properties

The JsonXMLOutputFactory class supports the following properties, defined by static string constants:

  • PROP_AUTO_ARRAY (boolean) - whether to automatically add JSON array boundaries (default is false)
  • PROP_AUTO_PRIMITIVE (boolean) - whether to automatically convert element text to JSON primitives (default is false)
  • PROP_MULTIPLE_PI (boolean) - whether to honor the <? xml-multiple ... ?> processing instruction (default is true)
  • PROP_VIRTUAL_ROOT (QName) - if set, remove root element with the given name (default is null)
  • PROP_PRETTY_PRINT (boolean) - whether to format output for better readability (default is false)
  • PROP_NAMESPACE_SEPARATOR (char) - character used as namespace prefix separator (default is ':')
  • PROP_NAMESPACE_DECLARATIONS (boolean) - whether to write namespace declarations (default is true)
  • PROP_NAMESPACE_MAPPINGS (Map) - associate namespace URIs with prefixes (default is null)

Unified Configuration

Some of the properties are shared by input and output factories. For convenience, the JsonXMLConfig interface provides a unified way to configure both - input and output factories - with a single configuration object. The JsonXMLConfigBuilder class provides a "fluid" API to create such a configuration:

JsonXMLConfig config = new JsonXMLConfigBuilder()
	.virtualRoot("customer")
	.prettyPrint(true)
	.build();
XMLInputFactory inputFactory = new JsonXMLInputFactory(config);
...
XMLOutputFactory outputFactory = new JsonXMLOutputFactory(config);
...

Stream Factory

StAXON's input/output factories use an instance of JsonStreamFactory as their JSON "backend", i.e. to create objects that do the actual JSON reading/writing.

Apart from the ability to implement your own, StAXON provides the following stream factory implementations:

  • StreamFactoryImpl - StAXON's default JSON I/O implementation, contained in requires staxon-<version>.jar
  • JsonProcessingStreamFactory - delegate JSON I/O to JSON Processing API (JSR-353), requires staxon-jsr353-<version>.jar
  • GsonStreamFactory - delegate JSON I/O to Gson, requires staxon-gson-<version>.jar
  • JacksonStreamFactory - delegate JSON I/O to Jackson, requires staxon-jackson-<version>.jar

Unless you want to avoid a dependency to an external JSON processor, it is recommended to choose one of those as backend.

If you use the default input/output factory constructors, StAXON performs the following lookup procedure to determine the stream factory class to instantiate:

  1. Use the Services API (as detailed in the JAR specification). If a resource with the name of META-INF/services/de.odysseus.staxon.json.stream.JsonStreamFactory exists, then its first line, if present, is used as the UTF-8 encoded name of the implementation class.
  2. Use the properties file lib/staxon.properties in the JRE directory. If this file exists and is readable by the java.util.Properties.load(InputStream) method, and it contains an entry whose key is de.odysseus.staxon.json.stream.JsonStreamFactory, then the value of that entry is used as the name of the implementation class.
  3. Use the de.odysseus.staxon.json.stream.JsonStreamFactory system property. If a system property with this name is defined, then its value is used as the name of the implementation class.
  4. Use platform default: de.odysseus.staxon.json.stream.impl.JsonStreamFactoryImpl.

The staxon-jsr353-<version>.jar, staxon-gson-<version>.jar and staxon-jackson-<version>.jar modules use the Services API to register their stream factory class. That is, if you have one of those on your classpath, StAXON will automatically use the corresponding stream factory implementation.

As an alternative, you may always explicitly pass a stream factory instance to your input/output factory at construction time.

Clone this wiki locally