biz.c24.io.api.presentation
Class SAXSource

java.lang.Object
  extended by biz.c24.io.api.presentation.Source
      extended by biz.c24.io.api.presentation.SAXSource
All Implemented Interfaces:
Serializable, Cloneable

public class SAXSource
extends Source

A source for generating data objects from a series of SAX events.

Since the generation of SAX events is an asynchronous process the readObject(biz.c24.io.api.data.Element) method of this class will always immediatley return null without blocking for the incoming events. After calling this method, and once the events have been sent to this object you should call getRootObject() to return the parsed object. Thus a common usage of this class would be:

 SAXSource src = new SAXSource();
 src.readObject(myElement); // should still call this method to initialise the src

 // The following is dependent on the actual SAX event source in use
 saxEvenntSource = // initialize the source of the SAX events
 saxEventSource.setContentHandler(src.getContentHandler());
 saxEventSource.setLexicalHandler(src.getLexicalHandler());
 saxEventSource.setEntityResolver(src.getEntityResolver());
 saxEventSource.setErrorHandler(src.getErrorHandler());
 saxEventSource.start(); // dependent on the actual SAX event source in use

 ComplexDataObject myObj = src.getRootObject();
 

Please note this class does not use the inherited Source.getInputStream() or Source.getReader() methods.

Note that this implementation is not synchronized. If multiple threads use an instance concurrently, it must be synchronized externally.

Note. Internal parts of this built up on the "Thread Local pattern". So, before processing of XML is stopped is not allowed the using of other SAXSource instances in scope of one thread. But there is options, for details see the binding context.

See Also:
Source, DefaultContext, Serialized Form

Field Summary
static String DEFAULT_LOG_NAME
          Default logger used when reading an object with no defining element.
 
Constructor Summary
SAXSource()
          Constructs a new instance.
SAXSource(SAXSource clone)
          Constructs a new instance cloned from clone.
 
Method Summary
 Object clone()
           
 ContentHandler getContentHandler()
          Returns the content handler from which SAX events will be read.
 EntityResolver getEntityResolver()
          Returns the entity resolver.
 ErrorHandler getErrorHandler()
          Returns the error handler.
 LexicalHandler getLexicalHandler()
          Returns the lexical handler from which SAX events will be read.
 String[] getRegisteredRemoteComponents()
          Deprecated. please use Document Root instead
 File getRootDir()
          Returns the root directory to which all relative filenames will be resolved.
 Element getRootElement()
          Returns the root element set up via the readObject(biz.c24.io.api.data.Element) method.
 Logger getRootLogger()
          Returns the logger for the root element is one has been specified, otherwise the logger called DEFAULT_LOG_NAME.
 ComplexDataObject getRootObject()
          Returns the parsed object or null if insufficent SAX events have been received to create the object.
 boolean isElementOrderValidationEnabled()
          Returns whether element order validation are allowed in the incoming XML.
 boolean isPopulateOptionalDefaultValues()
          Returns wether the default values be populated to the elements/attributes if they are empty/absent respectively.
 boolean isPopulateOptionalFixedValues()
          Returns wether the fixed values be populated to the elements/attributes if they are empty/absent respectively.
 boolean isSkipWrongData()
          Returns wether skipping of non-bindable elements are allowed in the incoming XML.
 boolean isStrictNamespaces()
          Returns whether instance documents in namespaces (including the default namespace) other than that defined by the argument supplied to the readObject(biz.c24.io.api.data.Element) method will be accepted.
 boolean isUnknownComponentsAllowed()
          Returns whether unknown components are allowed to appear in the incoming XML.
 void readObject(ComplexDataObject object)
          Unsupported operation, use readObject(biz.c24.io.api.data.Element) instead.
 ComplexDataObject readObject(Element element)
          Initialises this source to read data against the specified element declaration.
 void registerRemoteComponent(DataComponent element)
          Deprecated. please use Document Root instead
 void setElementOrderValidationEnabled(boolean enable)
          Sets whether element order validation are allowed.
 void setPopulateOptionalDefaultValues(boolean enable)
          Sets whether the default values be populated to the elements/attributes.
 void setPopulateOptionalFixedValues(boolean enable)
          Sets whether the fixed values be populated to the elements/attributes.
 void setRootDir(File rootDir)
          Sets the root directory to which all relative filenames will be resolved.
 void setSkipWrongData(boolean enable)
          Sets whether skipping of non-bindable elements are allowed.
 void setStrictNamespaces(boolean strictNamespaces)
          Sets whether instance documents in namespaces (including the default namespace) other than that defined by the argument supplied to the readObject(biz.c24.io.api.data.Element) method will be accepted.
 void setUnknownComponentsAllowed(boolean unknownComponentsAllowed)
          Sets whether unknown components are allowed to appear in the incoming XML.
 void unregisterRemoteComponent(DataComponent element)
          Deprecated. please use Document Root instead
 
Methods inherited from class biz.c24.io.api.presentation.Source
checkInit, getEncoding, getInputStream, getMarkableInputStream, getParseListener, getReader, getSystemId, reader, ready, setEncoding, setInputStream, setInputStream, setParseListener, setReader, setReader, setSystemId, stream
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_LOG_NAME

public static final String DEFAULT_LOG_NAME
Default logger used when reading an object with no defining element.

See Also:
Constant Field Values
Constructor Detail

SAXSource

public SAXSource()
Constructs a new instance.


SAXSource

public SAXSource(SAXSource clone)
Constructs a new instance cloned from clone.

Parameters:
clone - The instance to clone.
Method Detail

getContentHandler

public ContentHandler getContentHandler()
Returns the content handler from which SAX events will be read.

The handler can be used with a SAX event source - a producer of SAX events (or possibly a SAXSink).

Returns:
The content handler.

getLexicalHandler

public LexicalHandler getLexicalHandler()
Returns the lexical handler from which SAX events will be read.

The handler can be used with a SAX event source - a producer of SAX events (or possibly a SAXSink).

Returns:
The lexical handler.

getEntityResolver

public EntityResolver getEntityResolver()
Returns the entity resolver.

Returns:
The entiry resolver.

getErrorHandler

public ErrorHandler getErrorHandler()
Returns the error handler.

Returns:
The error handler.

readObject

public void readObject(ComplexDataObject object)
                throws IOException
Unsupported operation, use readObject(biz.c24.io.api.data.Element) instead.

XML instance documents often consist of a root element whose name is different from it's type or which use the xsi:type attribute. In both these cases the object which is to be produced by the parse process may not be compatible with that which is passed in. A pointer to the root element is required so that the correct instance can be created, populated and returned, it is therefore neccesary to use the alternative readObject method.

Specified by:
readObject in class Source
Parameters:
object - The object into which the input data should be parsed.
Throws:
IOException - If the complete object could not be read for any reason.

readObject

public ComplexDataObject readObject(Element element)
                             throws IOException
Initialises this source to read data against the specified element declaration.

If element == null, a new object will be created on the fly from the SAX event data, in a similar fashion to a DOM. In this case, logging output will be sent to DEFAULT_LOG_NAME.

This method will always return null since parsing the incoming SAX events is an asynchronous process. To get access to the parsed object call getRootObject() after firing all SAX events.

Specified by:
readObject in class Source
Parameters:
element - The element declaration to which the input data is expected to adhere.
Returns:
null - the parsed object can be retrieved via getRootObject() after the events have been fired.
Throws:
IOException - If an error occours reading the data.

getRootElement

public Element getRootElement()
Returns the root element set up via the readObject(biz.c24.io.api.data.Element) method.

Returns:
The root element.

getRootObject

public ComplexDataObject getRootObject()
Returns the parsed object or null if insufficent SAX events have been received to create the object.

This method should be called synchronously after all SAX events have been fired.

Returns:
The parsed object or null.

getRootLogger

public Logger getRootLogger()
Returns the logger for the root element is one has been specified, otherwise the logger called DEFAULT_LOG_NAME.

Returns:
The logger.

getRootDir

public File getRootDir()
Returns the root directory to which all relative filenames will be resolved.

Returns:
The root directory.

setRootDir

public void setRootDir(File rootDir)
Sets the root directory to which all relative filenames will be resolved. The default value if nothing has been set is the working directory of the JVM.

Parameters:
rootDir - The new value.

isStrictNamespaces

public boolean isStrictNamespaces()
Returns whether instance documents in namespaces (including the default namespace) other than that defined by the argument supplied to the readObject(biz.c24.io.api.data.Element) method will be accepted.

Returns:
The value.

setStrictNamespaces

public void setStrictNamespaces(boolean strictNamespaces)
Sets whether instance documents in namespaces (including the default namespace) other than that defined by the argument supplied to the readObject(biz.c24.io.api.data.Element) method will be accepted.

Parameters:
strictNamespaces - The new value.

isUnknownComponentsAllowed

public boolean isUnknownComponentsAllowed()
Returns whether unknown components are allowed to appear in the incoming XML.

Unknown components are remote to the structure being parsed, e.g. those that might appear in place of an 'any'. This property is set to true by default to give maximum flexibility..

Returns:
Whether unknown components will be allowed.

setUnknownComponentsAllowed

public void setUnknownComponentsAllowed(boolean unknownComponentsAllowed)
Sets whether unknown components are allowed to appear in the incoming XML.

Unknown components are remote to the structure being parsed, e.g. those that might appear in place of an 'any'. You should consider setting this property to false if you have registered remote components via the registerRemoteComponent(biz.c24.io.api.data.DataComponent) method and want to be alerted when an XML document contains an unregistered component.

Parameters:
unknownComponentsAllowed - The new value.

isElementOrderValidationEnabled

public boolean isElementOrderValidationEnabled()
Returns whether element order validation are allowed in the incoming XML.

This property is set to true by default to give maximum flexibility..

Returns:
Whether element order validation will be allowed.

setElementOrderValidationEnabled

public void setElementOrderValidationEnabled(boolean enable)
Sets whether element order validation are allowed.

Parameters:
enable - The new value.

isSkipWrongData

public boolean isSkipWrongData()
Returns wether skipping of non-bindable elements are allowed in the incoming XML.

This property is set to false by default to give the working the batch processing. If this property is true, batch processing has the unexpected results.

Returns:
Wether skipping of non-bindable elements will be allowed.

setSkipWrongData

public void setSkipWrongData(boolean enable)
Sets whether skipping of non-bindable elements are allowed.

Parameters:
enable - The new value.
See Also:
isSkipWrongData()

isPopulateOptionalDefaultValues

public boolean isPopulateOptionalDefaultValues()
Returns wether the default values be populated to the elements/attributes if they are empty/absent respectively.

According to XML spec the default values for element/attributes should be populated if they are empty (for an element) or absent (for an attribute). For details please see part 2.2.1. "Occurrence Constraints".

This property is true by default.

Returns:
Wether the default values be populated to the elements/attributes.

setPopulateOptionalDefaultValues

public void setPopulateOptionalDefaultValues(boolean enable)
Sets whether the default values be populated to the elements/attributes.

Parameters:
enable - The new value.
See Also:
isPopulateOptionalDefaultValues()

isPopulateOptionalFixedValues

public boolean isPopulateOptionalFixedValues()
Returns wether the fixed values be populated to the elements/attributes if they are empty/absent respectively.

According to XML spec the fixed values for element/attributes should be populated if they are empty (for an element) or absent (for an optional attribute only). For details please see part 2.2.1. "Occurrence Constraints".

This property is true by default.

Returns:
Wether the fixed values be populated to the elements/attributes.

setPopulateOptionalFixedValues

public void setPopulateOptionalFixedValues(boolean enable)
Sets whether the fixed values be populated to the elements/attributes.

Parameters:
enable - The new value.
See Also:
isPopulateOptionalFixedValues()

registerRemoteComponent

public void registerRemoteComponent(DataComponent element)
Deprecated. please use Document Root instead

Registers an element which may occur in the incoming XML stream but which is not referenced by the data structure to be parsed.

This method provides the parser with possible elements which can be parsed against, e.g. those that might appear in place of an 'any' or as part of a model which is loaded without a defining element declaration, i.e. as a result of a call to readObject(biz.c24.io.api.data.Element) with a null argument.

Parameters:
element - The data component (element or attribute) to register.

unregisterRemoteComponent

public void unregisterRemoteComponent(DataComponent element)
Deprecated. please use Document Root instead

Unregisters the specified data component.

Parameters:
element - The (element or attribute) to unregister.

getRegisteredRemoteComponents

public String[] getRegisteredRemoteComponents()
Deprecated. please use Document Root instead

Return a new array containing all registered remote components.

Returns:
The class names.

clone

public Object clone()
Specified by:
clone in class Source


C24 Technologies © 2002-2012: All Rights Reserved.