biz.c24.io.api.presentation
Class XMLSource

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

public class XMLSource
extends Source

A source for generating data objects from XML.

A common usage of this class would be:

 FileInputStream in = new FileInputStream("myfile.xml"); // note: stream clean up code has been ommited for clarity
 XMLSource src = new XMLSource(in);
 ComplexDataObject myObj = src.readObject(myElement); // where my element is the element you are expecting to parse
 

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

See Also:
todo Revise this and possible super class for sypport the SYSTEM_ID!!!!, Serialized Form

Field Summary
static String DEFAULT_LOG_NAME
          Deprecated. Use SAXSource.DEFAULT_LOG_NAME instead.
 
Constructor Summary
XMLSource()
          Constructs a new instance.
XMLSource(InputStream stream)
          Constructs a new instance which will read from stream.
XMLSource(Reader reader)
          Constructs a new instance which will read from reader.
XMLSource(XMLSource clone)
          Constructs a new instance cloned from clone.
 
Method Summary
 void addAnyMapping(Element element)
          Deprecated. Use getWrappedSource().SAXSource.registerRemoteComponent(biz.c24.io.api.data.DataComponent) instead.
 Object clone()
           
 File getRootDir()
          Deprecated. Use equivalent method on getWrappedSource() instead.
 SAXSource getWrappedSource()
          Returns the wrapped SAX source on which this source is based.
 String getXmlReaderClassName()
          Returns the class name of the XMLReader that should be used.
 boolean isContinueAfterFatalError()
          Returns whether the parser will continue processing after encountering a fatal error.
 boolean isDynamicValidationEnabled()
          Returns whether the parser will validate the document only if a grammar is specified.
 boolean isExternalGeneralEntities()
          Returns whether the parser will include external general (text) entities.
 boolean isExternalParameterEntities()
          Returns whether the parser will include external parameter entities and the external DTD subset.
 boolean isLoadDTDGrammer()
          Returns whether the parser will load the DTD and use it to add default attributes and set attribute types when parsing.
 boolean isLoadExternalDTD()
          Returns whether the parser will load the DTD and use it to add default attributes and set attribute types when parsing.
 boolean isSchemaFullCheckingEnabled()
          Gets whether the parser will carry out full schema grammar constraint checking, including checking which may be time-consuming or memory intensive.
 boolean isSchemaValidationEnabled()
          Gets whether the parser will validate the schema as well as the instance document.
 boolean isStrictNamespaces()
          Deprecated. Use equivalent method on getWrappedSource() instead.
 boolean isValidationEnabled()
          Returns whether the parser is reporting all validity errors; if true, all external entities will be read.
 boolean isWarnOnDuplicateAttDef()
          Returns whether the parser will warn on duplicate attribute declarations.
 boolean isWarnOnUndeclaredElemDef()
          Returns whether the parser will warn if elements referenced in a content model are not declared.
 void readObject(ComplexDataObject object)
          Unsupported operation, use readObject(Element) instead.
 ComplexDataObject readObject(Element element)
          Reads an object from the the reader or input stream that has been set.
 void removeAnyMapping(Element element)
          Deprecated. Use getWrappedSource().SAXSource.unregisterRemoteComponent(biz.c24.io.api.data.DataComponent) instead.
 void setContinueAfterFatalError(boolean continueAfterFatalError)
          Sets whether the parser will continue processing after encountering a fatal error.
 void setDynamicValidationEnabled(boolean dynamicValidationEnabled)
          Sets whether the parser will validate the document only if a grammar is specified.
 void setExternalGeneralEntities(boolean externalGeneralEntities)
          Sets whether the parser will include external general (text) entities.
 void setExternalParameterEntities(boolean externalParameterEntities)
          Sets whether the parser will include external parameter entities and the external DTD subset.
 void setInputStream(InputStream stream, URI systemId)
          Sets the input stream and system ID (optional operation).
 void setLoadDTDGrammer(boolean loadDTDGrammer)
          Sets whether the parser will load the DTD and use it to add default attributes and set attribute types when parsing.
 void setLoadExternalDTD(boolean loadExternalDTD)
          Sets whether the parser will load the external DTD.
 void setReader(Reader reader, URI systemId)
          Sets the reader (optional operation).
 void setRootDir(File rootDir)
          Deprecated. Use equivalent method on getWrappedSource() instead.
 void setSchemaFullCheckingEnabled(boolean schemaFullCheckingEnabled)
          Sets whether the parser will carry out full schema grammar constraint checking, including checking which may be time-consuming or memory intensive.
 void setSchemaValidationEnabled(boolean schemaValidationEnabled)
          Sets whether the parser will validate the schema as well as the instance document.
 void setStrictNamespaces(boolean strictNamespaces)
          Deprecated. Use equivalent method on getWrappedSource() instead.
 void setValidationEnabled(boolean validationEnabled)
          Sets whether the parser is reporting all validity errors; if true, all external entities will be read.
 void setWarnOnDuplicateAttDef(boolean warnOnDuplicateAttDef)
          Sets whether the parser will warn on duplicate attribute declarations.
 void setWarnOnUndeclaredElemDef(boolean warnOnUndeclaredElemDef)
          Sets whether the parser will warn if elements referenced in a content model are not declared.
 void setXmlReaderClassName(String xmlReaderClassName)
          Sets the class name of the XMLReader that should be used.
 
Methods inherited from class biz.c24.io.api.presentation.Source
checkInit, getEncoding, getInputStream, getMarkableInputStream, getParseListener, getReader, getSystemId, reader, ready, setEncoding, setInputStream, setParseListener, 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
Deprecated. Use SAXSource.DEFAULT_LOG_NAME instead.
Default logger used when reading an object with no defining element.

See Also:
Constant Field Values
Constructor Detail

XMLSource

public XMLSource()
Constructs a new instance.


XMLSource

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

Parameters:
clone - The instance to clone.

XMLSource

public XMLSource(Reader reader)
Constructs a new instance which will read from reader.

Parameters:
reader - The reader to read the XML data from.

XMLSource

public XMLSource(InputStream stream)
Constructs a new instance which will read from stream.

Parameters:
stream - The stream to read the XML data from.
Method Detail

readObject

public void readObject(ComplexDataObject object)
                throws IOException
Unsupported operation, use readObject(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
Reads an object from the the reader or input stream that has been set.

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

Specified by:
readObject in class Source
Parameters:
element - The element declaration to which the input data is expected to adhere.
Returns:
The newly created object.
Throws:
IOException - If the complete object could not be read for any reason.
IllegalArgumentException - If neither a reader nor an input stream has been set.

getWrappedSource

public SAXSource getWrappedSource()
Returns the wrapped SAX source on which this source is based.

The wrapped source provides access to additional configuration properties.

Returns:
The SAX source.

getRootDir

public File getRootDir()
Deprecated. Use equivalent method on getWrappedSource() instead.

Returns the root directory to which all relative filenames will be resolved.

Returns:
The root directory.

setRootDir

public void setRootDir(File rootDir)
Deprecated. Use equivalent method on getWrappedSource() instead.

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.

getXmlReaderClassName

public String getXmlReaderClassName()
Returns the class name of the XMLReader that should be used.

Returns:
The class name.

setXmlReaderClassName

public void setXmlReaderClassName(String xmlReaderClassName)
Sets the class name of the XMLReader that should be used.
The default value if nothing has been set is "org.apache.xerces.parsers.SAXParser".

Parameters:
xmlReaderClassName - The new value.

isValidationEnabled

public boolean isValidationEnabled()
Returns whether the parser is reporting all validity errors; if true, all external entities will be read.

Returns:
The value.
See Also:
SAX Project, Apache Xerces

setValidationEnabled

public void setValidationEnabled(boolean validationEnabled)
Sets whether the parser is reporting all validity errors; if true, all external entities will be read. The default value is false.

Parameters:
validationEnabled - The new value.
See Also:
SAX Project, Apache Xerces

isSchemaValidationEnabled

public boolean isSchemaValidationEnabled()
Gets whether the parser will validate the schema as well as the instance document.

Returns:
The value.
See Also:
Apache Xerces

setSchemaValidationEnabled

public void setSchemaValidationEnabled(boolean schemaValidationEnabled)
Sets whether the parser will validate the schema as well as the instance document. The default value is false.

Parameters:
schemaValidationEnabled - The new value.
See Also:
Apache Xerces

isSchemaFullCheckingEnabled

public boolean isSchemaFullCheckingEnabled()
Gets whether the parser will carry out full schema grammar constraint checking, including checking which may be time-consuming or memory intensive. Currently, particle unique attribution constraint checking and particle derivation resriction checking are controlled by this option.

Returns:
The value.
See Also:
Apache Xerces

setSchemaFullCheckingEnabled

public void setSchemaFullCheckingEnabled(boolean schemaFullCheckingEnabled)
Sets whether the parser will carry out full schema grammar constraint checking, including checking which may be time-consuming or memory intensive. Currently, particle unique attribution constraint checking and particle derivation resriction checking are controlled by this option. The default value is false.

Parameters:
schemaFullCheckingEnabled - The new value.
See Also:
Apache Xerces

isDynamicValidationEnabled

public boolean isDynamicValidationEnabled()
Returns whether the parser will validate the document only if a grammar is specified.

Returns:
The value.
See Also:
Apache Xerces

setDynamicValidationEnabled

public void setDynamicValidationEnabled(boolean dynamicValidationEnabled)
Sets whether the parser will validate the document only if a grammar is specified. The default value is false.

Parameters:
dynamicValidationEnabled - The new value.
See Also:
Apache Xerces

isExternalGeneralEntities

public boolean isExternalGeneralEntities()
Returns whether the parser will include external general (text) entities.

Returns:
The value.

setExternalGeneralEntities

public void setExternalGeneralEntities(boolean externalGeneralEntities)
Sets whether the parser will include external general (text) entities. The default value is true.

Parameters:
externalGeneralEntities - The new value.

isExternalParameterEntities

public boolean isExternalParameterEntities()
Returns whether the parser will include external parameter entities and the external DTD subset.

Returns:
The value.

setExternalParameterEntities

public void setExternalParameterEntities(boolean externalParameterEntities)
Sets whether the parser will include external parameter entities and the external DTD subset. The default value is true.

Parameters:
externalParameterEntities - The new value.

isWarnOnDuplicateAttDef

public boolean isWarnOnDuplicateAttDef()
Returns whether the parser will warn on duplicate attribute declarations.

Returns:
The value.

setWarnOnDuplicateAttDef

public void setWarnOnDuplicateAttDef(boolean warnOnDuplicateAttDef)
Sets whether the parser will warn on duplicate attribute declarations. The default value is false.

Parameters:
warnOnDuplicateAttDef - The new value.

isWarnOnUndeclaredElemDef

public boolean isWarnOnUndeclaredElemDef()
Returns whether the parser will warn if elements referenced in a content model are not declared.

Returns:
The value.

setWarnOnUndeclaredElemDef

public void setWarnOnUndeclaredElemDef(boolean warnOnUndeclaredElemDef)
Sets whether the parser will warn if elements referenced in a content model are not declared. The default value is false.

Parameters:
warnOnUndeclaredElemDef - The new value.

isContinueAfterFatalError

public boolean isContinueAfterFatalError()
Returns whether the parser will continue processing after encountering a fatal error.

Returns:
The value.

setContinueAfterFatalError

public void setContinueAfterFatalError(boolean continueAfterFatalError)
Sets whether the parser will continue processing after encountering a fatal error. The default value is false.

Parameters:
continueAfterFatalError - The new value.

isLoadDTDGrammer

public boolean isLoadDTDGrammer()
Returns whether the parser will load the DTD and use it to add default attributes and set attribute types when parsing.

Returns:
The value.

setLoadDTDGrammer

public void setLoadDTDGrammer(boolean loadDTDGrammer)
Sets whether the parser will load the DTD and use it to add default attributes and set attribute types when parsing. The default value is true.

Parameters:
loadDTDGrammer - The new value.

isLoadExternalDTD

public boolean isLoadExternalDTD()
Returns whether the parser will load the DTD and use it to add default attributes and set attribute types when parsing.

Returns:
The value.

setLoadExternalDTD

public void setLoadExternalDTD(boolean loadExternalDTD)
Sets whether the parser will load the external DTD. The default value is true.

Parameters:
loadExternalDTD - The new value.

isStrictNamespaces

public boolean isStrictNamespaces()
Deprecated. Use equivalent method on getWrappedSource() instead.

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)
Deprecated. Use equivalent method on getWrappedSource() instead.

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.

addAnyMapping

public void addAnyMapping(Element element)
Deprecated. Use getWrappedSource().SAXSource.registerRemoteComponent(biz.c24.io.api.data.DataComponent) 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 element to register.

removeAnyMapping

public void removeAnyMapping(Element element)
Deprecated. Use getWrappedSource().SAXSource.unregisterRemoteComponent(biz.c24.io.api.data.DataComponent) instead.

Unregisters the specified element.

Parameters:
element - The element to unregister.

setReader

public void setReader(Reader reader,
                      URI systemId)
Description copied from class: Source
Sets the reader (optional operation).

Overrides:
setReader in class Source
Parameters:
reader - The new value.
systemId - The system ID identifying the reader.

setInputStream

public void setInputStream(InputStream stream,
                           URI systemId)
Description copied from class: Source
Sets the input stream and system ID (optional operation).

Overrides:
setInputStream in class Source
Parameters:
stream - The new value.
systemId - The system ID identifying the stream.

clone

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


C24 Technologies © 2002-2012: All Rights Reserved.