Top Description Fields Constructors Methods
tools.jackson.dataformat.xml

public Class XmlFactory

extends TextualTSFactory
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.io.*, javax.xml.stream.*, org.codehaus.stax2.XMLInputFactory2, org.codehaus.stax2.io.Stax2ByteArraySource, .Stax2CharArraySource, tools.jackson.core.*, tools.jackson.core.base.TextualTSFactory, tools.jackson.core.exc.StreamReadException, .StreamWriteException, tools.jackson.core.io.IOContext, tools.jackson.dataformat.xml.deser.FromXmlParser, tools.jackson.dataformat.xml.ser.ToXmlGenerator, tools.jackson.dataformat.xml.util.StaxUtil

Factory used for constructing FromXmlParser and ToXmlGenerator instances.

Implements TokenStreamFactory since interface for constructing XML backed parsers and generators is quite similar to dealing with JSON.

Author
Tatu Saloranta ([email protected])

Field Summary

Modifier and TypeField and Description
protected final String
protected transient String
protected transient String
protected final XmlNameProcessor
protected final transient XMLInputFactory
protected final transient XMLOutputFactory
protected static final int
DEFAULT_XML_READ_FEATURE_FLAGS

Bitfield (set of flags) of all parser features that are enabled by default.

protected static final int
DEFAULT_XML_WRITE_FEATURE_FLAGS

Bitfield (set of flags) of all generator features that are enabled by default.

public static final String
FORMAT_NAME_XML

Name used to identify XML format (and returned by getFormatName()

private static final long

Constructor Summary

AccessConstructor and Description
public
XmlFactory()

Default constructor used to create factory instances.

public
public
protected
XmlFactory(int xpFeatures, int xgFeatures, XMLInputFactory xmlIn, XMLOutputFactory xmlOut, XmlNameProcessor nameProcessor, String nameForTextElem)

protected
XmlFactory(XmlFactoryBuilder b)

Constructor used by XmlFactoryBuilder for instantiation.

protected
XmlFactory(XmlFactory
Factory to make copy of
src
)

Constructor used by XmlFactory#copy()

protected
XmlFactory(XmlFactory src, String nameForTextElement)

Method Summary

Modifier and TypeMethod and Description
protected JsonGenerator
_createGenerator(ObjectWriteContext writeCtxt, IOContext ioCtxt, Writer out)

Implements abstract tools.jackson.core.base.TextualTSFactory._createGenerator.

Overridable factory method that actually instantiates generator for given Writer and context object.

protected JsonParser
protected FromXmlParser
protected FromXmlParser
protected FromXmlParser
_createParser(ObjectReadContext readCtxt, IOContext ioCtxt, char[] data, int offset, int len, boolean recycleBuffer)

Implements abstract tools.jackson.core.base.TextualTSFactory._createParser.

protected FromXmlParser
_createParser(ObjectReadContext readCtxt, IOContext ioCtxt, byte[] data, int offset, int len)

Implements abstract tools.jackson.core.base.TextualTSFactory._createParser.

protected JsonGenerator
_createUTF8Generator(ObjectWriteContext writeCtxt, IOContext ioCtxt, OutputStream out)

Implements abstract tools.jackson.core.base.TextualTSFactory._createUTF8Generator.

Overridable factory method that actually instantiates generator for given OutputStream and context object, using UTF-8 encoding.

protected XMLStreamWriter
protected XMLStreamWriter
protected FromXmlParser
_fromXmlParser(ObjectReadContext readCtxt, IOContext ioCtxt, XMLStreamReader sr)

Overridable method to allow using custom FromXmlParser sub-classes.

protected void
protected final XMLStreamReader
protected final XMLStreamWriter
protected ToXmlGenerator
_toXmlGenerator(ObjectWriteContext writeCtxt, IOContext ioCtxt, XMLStreamWriter sw)

Overridable method to allow using custom FromXmlParser sub-classes.

private final XmlPrettyPrinter
public static XmlFactoryBuilder
builder()

Main factory method to use for constructing XmlFactory instances with different configuration.

public static XmlFactoryBuilder
builderWithJackson2Defaults()

The builder returned uses default settings more closely matching the default configs used in Jackson 2.x versions.

public boolean
canParseAsync()

Implements abstract tools.jackson.core.TokenStreamFactory.canParseAsync.

Introspection method that can be used to check whether this factory can create non-blocking parsers: parsers that do not use blocking I/O abstractions but instead use a tools.jackson.core.async.NonBlockingInputFeeder.

public boolean
canUseCharArrays()

Overrides tools.jackson.core.base.TextualTSFactory.canUseCharArrays.

Since 2.4, we do have actual capability for passing char arrays efficiently, but unfortunately have no working mechanism for recycling buffers.

public boolean
canUseSchema(FormatSchema schema)

Implements abstract tools.jackson.core.TokenStreamFactory.canUseSchema.

Method that can be used to quickly check whether given schema is something that parsers and/or generators constructed by this factory could use.

public XmlFactory
copy()

Implements abstract tools.jackson.core.TokenStreamFactory.copy.

Note

compared to base implementation by TokenStreamFactory, here the copy will actually share underlying XML input and output factories, as there is no way to make copies of those.

public ToXmlGenerator
createGenerator(ObjectWriteContext writeCtxt, XMLStreamWriter sw)

Factory method that wraps given XMLStreamWriter, usually to allow incremental serialization to compose large output by serializing a sequence of individual objects.

public JsonParser
createParser(ObjectReadContext readCtxt, String content)

Overrides tools.jackson.core.base.TextualTSFactory.createParser.

Overridden just to prevent trying to optimize access via char array; while nice idea, problem is that we don't have proper hooks to ensure that temporary buffer gets recycled; so let's just use StringReader.

public FromXmlParser
createParser(ObjectReadContext readCtxt, XMLStreamReader sr)

Factory method that wraps given XMLStreamReader, usually to allow partial data-binding.

public String
getFormatName()

Implements abstract tools.jackson.core.TokenStreamFactory.getFormatName.

Method that returns short textual id identifying format this factory supports.

public int
public Class<XmlReadFeature>
getFormatReadFeatureType()

Overrides tools.jackson.core.TokenStreamFactory.getFormatReadFeatureType.

Method for accessing kind of FormatFeature that a parser JsonParser produced by this factory would accept, if any; null returned if none.

public int
public Class<XmlWriteFeature>
getFormatWriteFeatureType()

Overrides tools.jackson.core.TokenStreamFactory.getFormatWriteFeatureType.

Method for accessing kind of FormatFeature that a parser JsonGenerator produced by this factory would accept, if any; null returned if none.

public XMLInputFactory
public XMLOutputFactory
public String
private void
readObject(ObjectInputStream in)

In addition to default serialization, which mostly works, need to handle case of XML factories, hence override.

protected Object
readResolve()

Method that we need to override to actually make restoration go through constructors etc.

public XmlFactoryBuilder
rebuild()

Implements abstract tools.jackson.core.TokenStreamFactory.rebuild.

Method that can be used to create differently configured stream factories: it will create and return a Builder instance with exact settings of this stream factory.

public TokenStreamFactory
snapshot()

Implements abstract tools.jackson.core.TokenStreamFactory.snapshot.

Implements tools.jackson.core.util.Snapshottable.snapshot.

Instances are immutable so just return `this`

public Version
version()

Implements abstract tools.jackson.core.TokenStreamFactory.version.

Implements tools.jackson.core.Versioned.version.

Method called to detect version of the component that implements this interface; returned version should never be null, but may return specific "not available" instance (see Version for details).

public XmlFactory
withNameForTextElement(String name)

"Mutant factory" method used to allow XmlMapper.Builder to configure name used for text elements, instead of requiring defining it via XmlFactoryBuilder.

private void
writeObject(ObjectOutputStream out)

In addition to default serialization, which mostly works, need to handle case of XML factories, hence override.

Inherited from tools.jackson.core.base.TextualTSFactory:
_createContentReference_createContentReference_createWritercanHandleBinaryNativelycreateGeneratorcreateGeneratorcreateGeneratorcreateGeneratorcreateParsercreateParsercreateParsercreateParsercreateParsercreateParsercreateParser

Field Detail

_cfgNameForTextElementback to summary
protected final String _cfgNameForTextElement
_jdkXmlInFactoryback to summary
protected transient String _jdkXmlInFactory
_jdkXmlOutFactoryback to summary
protected transient String _jdkXmlOutFactory
_nameProcessorback to summary
protected final XmlNameProcessor _nameProcessor
_xmlInputFactoryback to summary
protected final transient XMLInputFactory _xmlInputFactory
_xmlOutputFactoryback to summary
protected final transient XMLOutputFactory _xmlOutputFactory
DEFAULT_XML_READ_FEATURE_FLAGSback to summary
protected static final int DEFAULT_XML_READ_FEATURE_FLAGS

Bitfield (set of flags) of all parser features that are enabled by default.

DEFAULT_XML_WRITE_FEATURE_FLAGSback to summary
protected static final int DEFAULT_XML_WRITE_FEATURE_FLAGS

Bitfield (set of flags) of all generator features that are enabled by default.

FORMAT_NAME_XMLback to summary
public static final String FORMAT_NAME_XML

Name used to identify XML format (and returned by getFormatName()

serialVersionUIDback to summary
private static final long serialVersionUID

Hides tools.jackson.core.base.TextualTSFactory.serialVersionUID.

Constructor Detail

XmlFactoryback to summary
public XmlFactory()

Default constructor used to create factory instances. Creation of a factory instance is a light-weight operation, but it is still a good idea to reuse limited number of factory instances (and quite often just a single instance): factories are used as context for storing some reused processing objects (such as symbol tables parsers use) and this reuse only works within context of a single factory instance.

XmlFactoryback to summary
public XmlFactory(XMLInputFactory xmlIn)
XmlFactoryback to summary
public XmlFactory(XMLInputFactory xmlIn, XMLOutputFactory xmlOut)
XmlFactoryback to summary
protected XmlFactory(int xpFeatures, int xgFeatures, XMLInputFactory xmlIn, XMLOutputFactory xmlOut, XmlNameProcessor nameProcessor, String nameForTextElem)
XmlFactoryback to summary
protected XmlFactory(XmlFactoryBuilder b)

Constructor used by XmlFactoryBuilder for instantiation.

XmlFactoryback to summary
protected XmlFactory(XmlFactory src)

Constructor used by XmlFactory#copy()

Parameters
src:XmlFactory

Factory to make copy of

XmlFactoryback to summary
protected XmlFactory(XmlFactory src, String nameForTextElement)

Method Detail

_createGeneratorback to summary
protected JsonGenerator _createGenerator(ObjectWriteContext writeCtxt, IOContext ioCtxt, Writer out)

Implements abstract tools.jackson.core.base.TextualTSFactory._createGenerator.

Doc from tools.jackson.core.base.TextualTSFactory._createGenerator.

Overridable factory method that actually instantiates generator for given Writer and context object.

This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.

Annotations
@Override
_createParserback to summary
protected JsonParser _createParser(ObjectReadContext readCtxt, IOContext ctxt, DataInput input)

Implements abstract tools.jackson.core.base.TextualTSFactory._createParser.

Annotations
@Override
_createParserback to summary
protected FromXmlParser _createParser(ObjectReadContext readCtxt, IOContext ioCtxt, InputStream in)

Implements abstract tools.jackson.core.base.TextualTSFactory._createParser.

Annotations
@Override
_createParserback to summary
protected FromXmlParser _createParser(ObjectReadContext readCtxt, IOContext ioCtxt, Reader r)

Implements abstract tools.jackson.core.base.TextualTSFactory._createParser.

Annotations
@Override
_createParserback to summary
protected FromXmlParser _createParser(ObjectReadContext readCtxt, IOContext ioCtxt, char[] data, int offset, int len, boolean recycleBuffer)

Implements abstract tools.jackson.core.base.TextualTSFactory._createParser.

Annotations
@Override
_createParserback to summary
protected FromXmlParser _createParser(ObjectReadContext readCtxt, IOContext ioCtxt, byte[] data, int offset, int len)

Implements abstract tools.jackson.core.base.TextualTSFactory._createParser.

Annotations
@Override
_createUTF8Generatorback to summary
protected JsonGenerator _createUTF8Generator(ObjectWriteContext writeCtxt, IOContext ioCtxt, OutputStream out)

Implements abstract tools.jackson.core.base.TextualTSFactory._createUTF8Generator.

Doc from tools.jackson.core.base.TextualTSFactory._createUTF8Generator.

Overridable factory method that actually instantiates generator for given OutputStream and context object, using UTF-8 encoding.

This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.

Annotations
@Override
_createXmlWriterback to summary
protected XMLStreamWriter _createXmlWriter(OutputStream out)
_createXmlWriterback to summary
protected XMLStreamWriter _createXmlWriter(Writer w)
_fromXmlParserback to summary
protected FromXmlParser _fromXmlParser(ObjectReadContext readCtxt, IOContext ioCtxt, XMLStreamReader sr)

Overridable method to allow using custom FromXmlParser sub-classes.

_initFactoriesback to summary
protected void _initFactories(XMLInputFactory xmlIn, XMLOutputFactory xmlOut)
_initializeXmlReaderback to summary
protected final XMLStreamReader _initializeXmlReader(XMLStreamReader sr)
_initializeXmlWriterback to summary
protected final XMLStreamWriter _initializeXmlWriter(XMLStreamWriter sw)
_toXmlGeneratorback to summary
protected ToXmlGenerator _toXmlGenerator(ObjectWriteContext writeCtxt, IOContext ioCtxt, XMLStreamWriter sw)

Overridable method to allow using custom FromXmlParser sub-classes.

_xmlPrettyPrinterback to summary
private final XmlPrettyPrinter _xmlPrettyPrinter(ObjectWriteContext writeCtxt)
builderback to summary
public static XmlFactoryBuilder builder()

Main factory method to use for constructing XmlFactory instances with different configuration.

builderWithJackson2Defaultsback to summary
public static XmlFactoryBuilder builderWithJackson2Defaults()

The builder returned uses default settings more closely matching the default configs used in Jackson 2.x versions.

This method is still a work in progress and may not yet fully replicate the default settings of Jackson 2.x.

canParseAsyncback to summary
public boolean canParseAsync()

Implements abstract tools.jackson.core.TokenStreamFactory.canParseAsync.

Doc from tools.jackson.core.TokenStreamFactory.canParseAsync.

Introspection method that can be used to check whether this factory can create non-blocking parsers: parsers that do not use blocking I/O abstractions but instead use a tools.jackson.core.async.NonBlockingInputFeeder.

Annotations
@Override
canUseCharArraysback to summary
public boolean canUseCharArrays()

Overrides tools.jackson.core.base.TextualTSFactory.canUseCharArrays.

Since 2.4, we do have actual capability for passing char arrays efficiently, but unfortunately have no working mechanism for recycling buffers. So we have to admit that can not make efficient use.

Annotations
@Override
canUseSchemaback to summary
public boolean canUseSchema(FormatSchema schema)

Implements abstract tools.jackson.core.TokenStreamFactory.canUseSchema.

Doc from tools.jackson.core.TokenStreamFactory.canUseSchema.

Method that can be used to quickly check whether given schema is something that parsers and/or generators constructed by this factory could use. Note that this means possible use, at the level of data format (i.e. schema is for same data format as parsers and generators this factory constructs); individual schema instances may have further usage restrictions.

Annotations
@Override
copyback to summary
public XmlFactory copy()

Implements abstract tools.jackson.core.TokenStreamFactory.copy.

Note

compared to base implementation by TokenStreamFactory, here the copy will actually share underlying XML input and output factories, as there is no way to make copies of those.

Annotations
@Override
createGeneratorback to summary
public ToXmlGenerator createGenerator(ObjectWriteContext writeCtxt, XMLStreamWriter sw) throws IOException

Factory method that wraps given XMLStreamWriter, usually to allow incremental serialization to compose large output by serializing a sequence of individual objects.

createParserback to summary
public JsonParser createParser(ObjectReadContext readCtxt, String content)

Overrides tools.jackson.core.base.TextualTSFactory.createParser.

Overridden just to prevent trying to optimize access via char array; while nice idea, problem is that we don't have proper hooks to ensure that temporary buffer gets recycled; so let's just use StringReader.

Annotations
@Override
createParserback to summary
public FromXmlParser createParser(ObjectReadContext readCtxt, XMLStreamReader sr) throws IOException

Factory method that wraps given XMLStreamReader, usually to allow partial data-binding.

getFormatNameback to summary
public String getFormatName()

Implements abstract tools.jackson.core.TokenStreamFactory.getFormatName.

Method that returns short textual id identifying format this factory supports.

Note

sub-classes should override this method; default implementation will return null for all sub-classes

Annotations
@Override
getFormatReadFeaturesback to summary
public int getFormatReadFeatures()

Overrides tools.jackson.core.TokenStreamFactory.getFormatReadFeatures.

Annotations
@Override
getFormatReadFeatureTypeback to summary
public Class<XmlReadFeature> getFormatReadFeatureType()

Overrides tools.jackson.core.TokenStreamFactory.getFormatReadFeatureType.

Doc from tools.jackson.core.TokenStreamFactory.getFormatReadFeatureType.

Method for accessing kind of FormatFeature that a parser JsonParser produced by this factory would accept, if any; null returned if none.

Annotations
@Override
getFormatWriteFeaturesback to summary
public int getFormatWriteFeatures()

Overrides tools.jackson.core.TokenStreamFactory.getFormatWriteFeatures.

Annotations
@Override
getFormatWriteFeatureTypeback to summary
public Class<XmlWriteFeature> getFormatWriteFeatureType()

Overrides tools.jackson.core.TokenStreamFactory.getFormatWriteFeatureType.

Doc from tools.jackson.core.TokenStreamFactory.getFormatWriteFeatureType.

Method for accessing kind of FormatFeature that a parser JsonGenerator produced by this factory would accept, if any; null returned if none.

Annotations
@Override
getXMLInputFactoryback to summary
public XMLInputFactory getXMLInputFactory()
getXMLOutputFactoryback to summary
public XMLOutputFactory getXMLOutputFactory()
getXMLTextElementNameback to summary
public String getXMLTextElementName()
readObjectback to summary
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException

In addition to default serialization, which mostly works, need to handle case of XML factories, hence override.

readResolveback to summary
protected Object readResolve()

Method that we need to override to actually make restoration go through constructors etc.

rebuildback to summary
public XmlFactoryBuilder rebuild()

Implements abstract tools.jackson.core.TokenStreamFactory.rebuild.

Doc from tools.jackson.core.TokenStreamFactory.rebuild.

Method that can be used to create differently configured stream factories: it will create and return a Builder instance with exact settings of this stream factory.

Annotations
@Override
snapshotback to summary
public TokenStreamFactory snapshot()

Implements abstract tools.jackson.core.TokenStreamFactory.snapshot.

Implements tools.jackson.core.util.Snapshottable.snapshot.

Instances are immutable so just return `this`

Annotations
@Override
versionback to summary
public Version version()

Implements abstract tools.jackson.core.TokenStreamFactory.version.

Implements tools.jackson.core.Versioned.version.

Doc from tools.jackson.core.Versioned.version.

Method called to detect version of the component that implements this interface; returned version should never be null, but may return specific "not available" instance (see Version for details).

Annotations
@Override
withNameForTextElementback to summary
public XmlFactory withNameForTextElement(String name)

"Mutant factory" method used to allow XmlMapper.Builder to configure name used for text elements, instead of requiring defining it via XmlFactoryBuilder.

writeObjectback to summary
private void writeObject(ObjectOutputStream out) throws IOException

In addition to default serialization, which mostly works, need to handle case of XML factories, hence override.