org.geotools.xml
Class Encoder

Object
  extended by Encoder

public class Encoder
extends Object

Encodes objects as xml based on a schema.

The function of the encoder is to traverse a tree of objects seializing 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:

  1. The root object in the tree to be encoded
  2. The schema / configuration of the intsance document being encoded.
  3. A name of the element defined in the schema which corresponds to the root object in the tree.


As an exmaple, consider the encoding of a Filter instance.

         
  //instantiate hte configuration for the filter schmea
  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
Module:
modules/extension/xsd-core (gt-xsd-core.jar)

Field Summary
static QName COMMENT
          Special name recognized by the encoder as a comment.
 
Constructor Summary
Encoder(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
protected  void closeIterator(Iterator itr, Object source)
           
protected  void comment(Element element)
           
 void encode(Object object, QName name, ContentHandler handler)
           
 void encode(Object object, QName name, OutputStream out)
          Encodes an object.
protected  Node encode(Object object, XSDNamedComponent component)
           
protected  Node encode(Object object, XSDNamedComponent component, XSDTypeDefinition container)
           
 Document encodeAsDOM(Object object, QName name)
          Encodes an object directly to a dom.
protected  void end(Element element)
           
 BindingWalker getBindingWalker()
           
 Document getDocument()
           
 Charset getEncoding()
          Returns the Charset defining the character encoding scheme this Encoder uses to encode XML content.
 int getIndentSize()
          Returns the indentation specified.
 int getLineWidth()
          Returns the line width for breaking up long lines.
 NamespaceSupport getNamespaces()
          Returns the namespace mappings maintained by the encoder.
 XSDSchema getSchema()
           
 SchemaIndex getSchemaIndex()
           
 boolean isIndenting()
          Returns whether this Encoder produces indented XML.
 boolean isOmitXMLDeclaration()
          Returns true if the XML document declaration should be omitted.
 void setEncodeFullDocument(boolean encodeFullDocument)
          Deprecated. use setInline(boolean).
 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 setOutputFormat(OutputFormat outputFormat)
          Deprecated. use the various setters instead (setEncoding, setIndentation, etc)
 void setSchemaLocation(String namespaceURI, String location)
          Sets the schema location for a particular namespace uri.
protected  void start(Element element)
           
 void write(Object object, QName name, OutputStream out)
          Deprecated. use encode(Object, QName, OutputStream).
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COMMENT

public static final QName COMMENT
Special name recognized by the encoder as a comment.

Bindings can return this name in ComplexBinding.getProperties(Object) to provide comments to be encoded.

Constructor Detail

Encoder

public Encoder(Configuration configuration)
Creates an encoder from a configuration.

This constructor calls through to Encoder(Configuration, XSDSchema) obtaining the schema instance from Configuration.schema().

Parameters:
configuration - The encoder configuration.

Encoder

public Encoder(Configuration configuration,
               XSDSchema schema)
Creates an encoder from a configuration and a specific schema instance.

Parameters:
configuration - The encoder configuration.
schema - The schema instance.
Method Detail

setEncoding

public void setEncoding(Charset charset)
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

public Charset 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() and getLineWidth()). To specify a different indentation level or line wrapping, use #setIndent(int) and setLineWidth(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(int)

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 with true 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:
setIndenting(boolean)

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, calling setIndenting(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:
isIndenting()

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;

Parameters:
namespaces -

getNamespaces

public NamespaceSupport getNamespaces()
Returns the namespace mappings maintained by the encoder.

Clients may register additional namespace mappings. This is useful when an application whishes 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

setEncodeFullDocument

public void setEncodeFullDocument(boolean encodeFullDocument)
Deprecated. use setInline(boolean).

True if we are encoding a full document, false if the xml headers should be omitted (the encoder is used to generate part of a large document)

Parameters:
encodeFullDocument -

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.


setSchemaLocation

public void setSchemaLocation(String namespaceURI,
                              String location)
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.

setOutputFormat

public void setOutputFormat(OutputFormat outputFormat)
Deprecated. use the various setters instead (setEncoding, setIndentation, etc)

Sets hte output format to be used by the encoder.

Parameters:
outputFormat - The output format.

getBindingWalker

public BindingWalker getBindingWalker()
Returns:
The walker used to traverse bindings, this method is for internal use only.

getSchemaIndex

public SchemaIndex getSchemaIndex()
Returns:
The index of schema components, this method is for internal use only.

getSchema

public XSDSchema getSchema()
Returns:
the schema.

write

public void write(Object object,
                  QName name,
                  OutputStream out)
           throws IOException,
                  SAXException
Deprecated. use encode(Object, QName, OutputStream).

Throws:
IOException
SAXException

getDocument

public Document getDocument()
Returns:
The document used as a factory to create dom nodes.

encode

public void encode(Object object,
                   QName name,
                   OutputStream out)
            throws IOException
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.

Throws:
IOException
SAXException
TransformerException

closeIterator

protected void closeIterator(Iterator itr,
                             Object source)

encode

protected Node encode(Object object,
                      XSDNamedComponent component)

encode

protected Node encode(Object object,
                      XSDNamedComponent component,
                      XSDTypeDefinition container)

start

protected void start(Element element)
              throws SAXException
Throws:
SAXException

comment

protected void comment(Element element)
                throws SAXException,
                       IOException
Throws:
SAXException
IOException

end

protected void end(Element element)
            throws SAXException
Throws:
SAXException


Copyright © 1996-2009 Geotools. All Rights Reserved.