Class Encoder
The function of the encoder is to traverse a tree of objects serializing them out as xml as it goes. Navigation
and serialization of the tree is performed by instances of Binding
which are bound to types in the schema.
To execute the encoder, one must have 3 bits of information:
- The root object in the tree to be encoded
- The schema / configuration of the instance document being encoded.
- A name of the element defined in the schema which corresponds to the root object in the tree.
As an example, consider the encoding of a Filter
instance.
//instantiate the configuration for the filter schema
Configuration configuration = new OGCConfiguration();
//create the encoder
Encoder encoder = new Encoder( configuration );
//get a filter
Filter filter = ...;
//get the name of the 'filter' element in the schema
QName name = new QName( "http://www.opengis.net/ogc", "Filter" );
//encode
encoder.encode( filter, name );
- Author:
- Justin Deoliveira, The Open Planning Project
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionEncoder
(Configuration configuration) Creates an encoder from a configuration.Encoder
(Configuration configuration, XSDSchema schema) Creates an encoder from a configuration and a specific schema instance. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
closeIterator
(Iterator iterator, Object source) protected void
void
encode
(Object object, QName name, OutputStream out) Encodes an object.void
encode
(Object object, QName name, ContentHandler handler) protected Node
protected Node
encodeAsDOM
(Object object, QName name) Encodes an object directly to a dom.encodeAsString
(Object object, QName name) Encodes an object directly to a string.protected void
Returns the object used to load xml bindings in this encoderReturns the configuration used by the encoderPicoContainer
Returns the Pico context used by this encoderReturns the Charset defining the character encoding scheme this Encoder uses to encode XML content.int
Returns the indentation specified.int
Returns the line width for breaking up long lines.Returns the namespace mappings maintained by the encoder.XSDSchema
static XSDSchema
getSchema
(Configuration configuration) boolean
Returns whether this Encoder produces indented XML.boolean
Returns true if the XML document declaration should be omitted.void
setEncoding
(Charset charset) Sets the charset encoding scheme to be used in encoding XML content.void
setIndenting
(boolean doIndent) Sets the indentation on and off.void
setIndentSize
(int indentSize) Sets the indentation level in number of spaces used.void
setInline
(boolean inline) Sets the encoder to "inline" mode.void
setLineWidth
(int lineWidth) Sets the line width.void
setNamespaceAware
(boolean namespaceAware) Sets wether the encoder should be namespace aware.void
setOmitXMLDeclaration
(boolean ommitXmlDeclaration) Sets XML declaration omitting on and off.void
setRootElementType
(QName rootElementType) Informs the encoder of the type of the root element to be used in cases where it can not be inferred.void
setSchemaLocation
(String namespaceURI, String location) Sets the schema location for a particular namespace uri.protected void
-
Field Details
-
COMMENT
Special name recognized by the encoder as a comment.Bindings can return this name in
ComplexBinding.getProperties(Object, XSDElementDeclaration)
to provide comments to be encoded.
-
-
Constructor Details
-
Encoder
Creates an encoder from a configuration.This constructor calls through to
Encoder(Configuration, XSDSchema)
obtaining the schema instance from {@link Configuration#getXSD()#getSchema()}).- Parameters:
configuration
- The encoder configuration.
-
Encoder
Creates an encoder from a configuration and a specific schema instance.- Parameters:
configuration
- The encoder configuration.schema
- The schema instance.
-
-
Method Details
-
getSchema
-
setEncoding
Sets the charset encoding scheme to be used in encoding XML content.This encoding will determine the resulting character encoding for the XML content generated by this Encoder and will be reflected in the XML declaration tag.
- Parameters:
charset
- the (non null) charset to encode XML content accordingly to
-
getEncoding
Returns the Charset defining the character encoding scheme this Encoder uses to encode XML content.If not otherwise set through
setEncoding(Charset)
,UTF-8
is used.- Returns:
- the character set used for encoding
-
setOmitXMLDeclaration
public void setOmitXMLDeclaration(boolean ommitXmlDeclaration) Sets XML declaration omitting on and off.- Parameters:
ommitXmlDeclaration
-true
if XML declaration should be omitted
-
isOmitXMLDeclaration
public boolean isOmitXMLDeclaration()Returns true if the XML document declaration should be omitted. The default is false.- Returns:
- whether the xml declaration is omitted, defaults to false.
-
setIndenting
public void setIndenting(boolean doIndent) Sets the indentation on and off.When set on, the default indentation level and default line wrapping is used (see
getIndentSize()
andgetLineWidth()
). To specify a different indentation level or line wrapping, usesetIndentSize(int)
andsetLineWidth(int)
).- Parameters:
doIndent
-true
if indentation should be on
-
isIndenting
public boolean isIndenting()Returns whether this Encoder produces indented XML.Defaults to
false
.- Returns:
true
if indentation was specified- See Also:
-
setIndentSize
public void setIndentSize(int indentSize) Sets the indentation level in number of spaces used.The document will not be indented if the indentation is set to zero. Calling
setIndenting(false)
will reset this value to zero, calling it withtrue
will reset this value to the default.- Parameters:
indentSize
- the number, greater or equal than zero, of characters used to indent, zero for no indentation.
-
getIndentSize
public int getIndentSize()Returns the indentation specified.If no indentation was specified, zero is returned and the document should not be indented.
Defaults to
4
- Returns:
- zero if not indenting, the number of white space characters used for indentation otherwise.
- See Also:
-
setLineWidth
public void setLineWidth(int lineWidth) Sets the line width.If zero then no line wrapping will occur. Calling
setIndenting(false)
will reset this value to zero, callingsetIndenting(true)
will set this value to the default.- Parameters:
lineWidth
- a number >= 0 used to limit line widths
-
getLineWidth
public int getLineWidth()Returns the line width for breaking up long lines.When indenting, and only when indenting, long lines will be broken at space boundaries based on this line width. No line wrapping occurs if this value is zero.
Defaults to
72
characters per line.- Returns:
- the number of characters at which line wrapping happens, or zero for no line wrapping
- See Also:
-
setNamespaceAware
public void setNamespaceAware(boolean namespaceAware) Sets wether the encoder should be namespace aware.Warning that setting this to
false
will result in no namespace prefixes on encoded elements and attributes, and no schema declarations on the root element.document; -
getNamespaces
Returns the namespace mappings maintained by the encoder.Clients may register additional namespace mappings. This is useful when an application wishes to provide some "default" namespace mappings.
Clients should register namespace mappings in the current "context", ie do not call
NamespaceSupport.pushContext()
. Example:Encoder parser = new Encoder( ... ); encoder.getNamespaces().declarePrefix( "foo", "http://www.foo.com" ); ...
- Returns:
- The namespace support containing prefix to uri mappings.
- Since:
- 2.5
-
setInline
public void setInline(boolean inline) Sets the encoder to "inline" mode.When this flag is set
encode(Object, QName, ContentHandler)
should be used to encode. -
setRootElementType
Informs the encoder of the type of the root element to be used in cases where it can not be inferred.This method is used in cases where the element being encoded is not declared as global in the schema.
- Parameters:
rootElementType
- The type name of the root element.- Since:
- 8.0
-
setSchemaLocation
Sets the schema location for a particular namespace uri.Registering a schema location will include it on the "schemaLocation" attribute of the root element of the encoding.
- Parameters:
namespaceURI
- A namespace uri.location
- A schema location.
-
getBindingWalker
- Returns:
- The walker used to traverse bindings, this method is for internal use only.
-
getSchemaIndex
- Returns:
- The index of schema components, this method is for internal use only.
-
getSchema
public XSDSchema getSchema()- Returns:
- the schema.
-
getDocument
- Returns:
- The document used as a factory to create dom nodes.
-
encode
Encodes an object.An object is encoded as an object, name pair, where the name is the name of an element declaration in a schema.
- Parameters:
object
- The object being encoded.name
- The name of the element being encoded in the schema.out
- The output stream.- Throws:
IOException
-
encode
public void encode(Object object, QName name, ContentHandler handler) throws IOException, SAXException - Throws:
IOException
SAXException
-
encodeAsDOM
public Document encodeAsDOM(Object object, QName name) throws IOException, SAXException, TransformerException Encodes an object directly to a dom.Note that this method should be used for testing or convenience since it does not stream and loads the entire encoded result into memory.
-
encodeAsString
Encodes an object directly to a string.Note that this method should be used for testing or convenience since it does not stream and loads the entire encoded result into memory.
- Throws:
IOException
- Since:
- 8.0
-
closeIterator
-
encode
-
encode
-
start
- Throws:
SAXException
-
comment
- Throws:
SAXException
IOException
-
end
- Throws:
SAXException
-
getConfiguration
Returns the configuration used by the encoder- Returns:
- the configuration
-
getBindingLoader
Returns the object used to load xml bindings in this encoder -
getContext
public PicoContainer getContext()Returns the Pico context used by this encoder
-