Skip navigation links

com.essbase.eas.framework.defs.transfer
Class XMLTransferObject

java.lang.Object
com.essbase.eas.framework.defs.transfer.XMLTransferObject

Direct Known Subclasses:

StatementCommandsXML

public class XMLTransferObject

extends java.lang.Object

provides a generic mechanism for transporting Java objects via XML. It is intended to transport objects that primarily consist of properties implemented via get/set method pairs.

There are several guidelines to this transport method:

• Support for Date/Calendar objects will be implemented later.
• Objects must have publicly available no-argument constructors.
• Properties are defined by having publicly available method pairs such as: public Color getBackground() and public void setBackground(Color value). The get method must have 0 (zero) parameters, the set method must have 1 (one) argument, the return type of the get method must match the type of the single parameter in the set method. Note: it is permissable for the get method to be defined as an "is" method; normally this would be used only for boolean methods but the XMLTransferObject class doesn't enforce that semantic.
• Support is currently limited to properties of type String, Integer, Long, Short, Byte, Double, Float, BigDecimal, BigInteger, Boolean and their underlying native types (i.e., long, short, etc.
• Collections, as such, are not supported; i.e., a property defined by methods such as public List getACollection() and public void setACollection(List value) are not supported.
• Collections are supported by defining a property with methods like the following: public AliasTable[] getAliasTables() and public void SetAliasTables(AliasTable[] values).
• A class can prevent default values from being placed into the XML stream by adding two class functions: isDefaultValue(Object object) and isDefaultValue(String propertyName, [native type] value). The first instance is for properties that are Java objects; the second instance is for properties that are native Java types (int, short, long, boolean)

This class makes heavy use of Java introspection to generate and parse the XML.

When using this object to export XML, call the add(Object obj) method to add objects to the set of objects to be transported. Call get() to retrieve the set of objects that have been transported.

Since:

6.5.3

Version:

7.0.0

Author:

Hank Cox

Field Summary

protected java.util.ArrayList	data contains the objects to be transported or that have been parsed after transport
protected java.util.List	dtds contains a list of dtd objects for this transfer object.
protected java.util.List	messages contains the set of messages that were parsed after transport
protected com.essbase.eas.framework.defs.command.CommandStatus	status contains the command status object
protected java.util.Hashtable	substitutions contains a hashtable of possible substitution classes for importing.

Constructor Summary

XMLTransferObject()
default constructor

XMLTransferObject(java.util.Hashtable substitutions)
Creates a XMLTransferObject and initializes the table of substitutions classes to use for certain classes.

Method Summary

void	add(java.util.Collection coll) adds a collection of objects to the set of objects this instance will export
void	add(java.lang.Object obj) adds an object to the set of objects this instance will export.
void	addAll(java.lang.Object[] objects) adds an array of objects to the set of objects this instance will export.
void	addDTD(java.io.InputStream istream) adds a dtd to the set of dts for this transfer object
void	addDTD(java.lang.String name) Adds a dtd to the set of dtds for this transfer object
void	addMessage(java.lang.Object value) adds a message to the set of messages for this instance.
void	addMessages(java.util.Collection values) adds a collection of messages to the set of messages for this instance.
static java.lang.Class	classForName(java.lang.String className)
void	clearData() clears the internal data.
static XMLTransferObject	createInstance(java.lang.Class c, java.lang.String xmlDoc) creates an instance of an XMLTransferObject, using a specific class and imports an XML string into the internal data structures.
static XMLTransferObject	createInstance(java.lang.String xmlDoc) creates an instance of an XMLTransferObject and imports an XML string into the internal data structures.
void	dispose() This is called when you nolonger need this class
void	exportData(org.w3c.dom.Element root)
protected void	exportNonStandardData(org.w3c.dom.Element root)
static java.lang.String	exportObjectToXML(java.lang.Class c, java.lang.Object id) Exports the object to XML string
static java.lang.String	exportObjectToXML(java.lang.Object id) exports an object to XML so that it can be used as a parameter to an http request.
java.io.ByteArrayOutputStream	exportXml() builds and exports the Xml stream for the set of objects that need to be transported.
java.lang.String	exportXmlAsString() build and export the Xml stream for the set of objects that need to be transported.
void	exportXmlToFile(java.lang.String fname) exports the XML stream to a file.
void	extractData(java.lang.String xmlDoc) This methods extracts data from the XML Document.
java.io.ByteArrayOutputStream	generateXmlDocument(java.util.List dtdList)
com.essbase.eas.framework.defs.command.CommandStatus	getCommandStatus() returns the object considered to be the "command status".
java.lang.Object[]	getData() retrieves the set of data that this object represents.
java.lang.Object[]	getDataForClass(java.lang.Class c) retrieves the set of data by class type.
java.util.List	getDTDList() Retrieves the set of dtd documents that are to be embedded in the XML stream generated by this object.
XMLTransferMessage	getMessage() This method will always return the first XMLTransferMessage
java.util.Collection	getMessages()
java.lang.Object[]	getMessages(java.lang.Class c)
static java.util.Collection	getMessages(java.util.List messages)
static java.lang.Object	getObjectFromXML(java.lang.String xmlString, java.lang.Class c) Returns the first data object of the type Class c from the XML document
boolean	getValidating()
void	importData(org.w3c.dom.Document doc)
protected void	importNonStandardData(org.w3c.dom.Document doc) imports any non-standard data from the XML stream.
void	importXml(java.lang.String xmlDoc) parses an incoming XML string into a set of objects and a set of messages.
void	importXmlFromFile(java.lang.String fname)
void	importXmlFromURL(java.net.URL url) Parses an XML document from a URL source
static void	setClassFinder(ClassFinder classfinder)
void	setCommandStatus(com.essbase.eas.framework.defs.command.CommandStatus value) sets the command status for this transfer object.
void	setSchemaSources(java.io.InputStream[] inpStreams)
void	setValidating(boolean valid)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

data

protected java.util.ArrayList data

contains the objects to be transported or that have been parsed after transport

messages

protected java.util.List messages

contains the set of messages that were parsed after transport

status

protected com.essbase.eas.framework.defs.command.CommandStatus status

contains the command status object

substitutions

protected java.util.Hashtable substitutions

contains a hashtable of possible substitution classes for importing.

dtds

protected java.util.List dtds

contains a list of dtd objects for this transfer object.

Constructor Detail

XMLTransferObject

public XMLTransferObject()

default constructor

XMLTransferObject

public XMLTransferObject(java.util.Hashtable substitutions)

Creates a XMLTransferObject and initializes the table of substitutions classes to use for certain classes. The substitute class is used to instantiate object for requested class.

Parameters:

substitutions - the table of classes used for initialization

Method Detail

createInstance

public static XMLTransferObject createInstance(java.lang.String xmlDoc)

creates an instance of an XMLTransferObject and imports an XML string into the internal data structures.

Parameters:

xmlDoc - the text to be imported

Returns:

an instance of the requested class if everything works ok; null, otherwise.

createInstance

public static XMLTransferObject createInstance(java.lang.Class c,
                                               java.lang.String xmlDoc)

creates an instance of an XMLTransferObject, using a specific class and imports an XML string into the internal data structures.

Parameters:

c - a Class object the must be inherited from the XMLTransferObject class.

xmlDoc - the text to be imported

Returns:

an instance of the requested class if everything works ok; null, otherwise.

getDTDList

public final java.util.List getDTDList()

Retrieves the set of dtd documents that are to be embedded in the XML stream generated by this object. The items put into this list are strings representing locatable files with XML document definitions in them.

Returns:

a list collection of dtd names.

addDTD

public final void addDTD(java.lang.String name)

Adds a dtd to the set of dtds for this transfer object

Parameters:

name - the dtd name to add to the set of dtds

addDTD

public final void addDTD(java.io.InputStream istream)

adds a dtd to the set of dts for this transfer object

Parameters:

istream - the dtd to add

exportXml

public final java.io.ByteArrayOutputStream exportXml()
                                              throws java.lang.Exception

builds and exports the Xml stream for the set of objects that need to be transported.

Returns:

a ByteArrayOutputStream containing the XML stream to send.

Throws:

any - exception that occurs

java.lang.Exception

exportXmlAsString

public final java.lang.String exportXmlAsString()
                                         throws java.lang.Exception

build and export the Xml stream for the set of objects that need to be transported.

Returns:

a String object containing the XML stream.

Throws:

any - exception that occurs

java.lang.Exception

exportXmlToFile

public final void exportXmlToFile(java.lang.String fname)

exports the XML stream to a file.

Parameters:

fname - the file name to export to.

extractData

public final void extractData(java.lang.String xmlDoc)
                       throws java.lang.Exception

This methods extracts data from the XML Document. The data is added to the list data

Parameters:

xmlDoc - the string containing the XML data.

Throws:

java.lang.Exception - that occurs

importXml

public final void importXml(java.lang.String xmlDoc)
                     throws java.lang.Exception

parses an incoming XML string into a set of objects and a set of messages.

Parameters:

xmlDoc - the string containing the XML data.

Throws:

java.lang.Exception - that occurs

importXmlFromURL

public final void importXmlFromURL(java.net.URL url)

Parses an XML document from a URL source

Parameters:

url - xml URL

importXmlFromFile

public final void importXmlFromFile(java.lang.String fname)

exportData

public final void exportData(org.w3c.dom.Element root)
                      throws java.lang.Exception

Throws:

java.lang.Exception

exportNonStandardData

protected void exportNonStandardData(org.w3c.dom.Element root)
                              throws java.lang.Exception

Throws:

java.lang.Exception

importData

public final void importData(org.w3c.dom.Document doc)
                      throws java.lang.Exception

Throws:

java.lang.Exception

importNonStandardData

protected void importNonStandardData(org.w3c.dom.Document doc)

imports any non-standard data from the XML stream. This method must be overridden by any derived classes that wish to have special import values.

Parameters:

doc - the XML document for importing data

classForName

public static java.lang.Class classForName(java.lang.String className)
                                    throws java.lang.ClassNotFoundException

Throws:

java.lang.ClassNotFoundException

add

public final void add(java.lang.Object obj)

adds an object to the set of objects this instance will export.

Parameters:

obj - the object to eventually export for transport.

addAll

public final void addAll(java.lang.Object[] objects)

adds an array of objects to the set of objects this instance will export.

Parameters:

objects - the array of objects to add.

add

public final void add(java.util.Collection coll)

adds a collection of objects to the set of objects this instance will export

Parameters:

coll - the collection of objects to add.

addMessage

public final void addMessage(java.lang.Object value)

adds a message to the set of messages for this instance.

Parameters:

value - a message object

addMessages

public final void addMessages(java.util.Collection values)

adds a collection of messages to the set of messages for this instance.

Parameters:

values - a collection of message objects.

setCommandStatus

public final void setCommandStatus(com.essbase.eas.framework.defs.command.CommandStatus value)

sets the command status for this transfer object. This is used to indiacte success or failure.

Parameters:

value - the CommandStatus to be set for this object

clearData

public void clearData()

clears the internal data. This can be called so that the same XML object can be used to import/export multiple sets of data.

getCommandStatus

public final com.essbase.eas.framework.defs.command.CommandStatus getCommandStatus()

returns the object considered to be the "command status". Strictly speaking, a command status is not part of the XMLTransferObject class; however, since on of the primary uses is to move data between the client and mid-tier via command requests, this is a helper routine. Semantically, we would like to force a convention that every command contain exactly one instance of a command status object when it returns from the mid-tier. In versions of EAS numbered 6.5.3 and before we cannot do that; however, beginning with version 7.0 we will enforce this rule.

Returns:

the data representing the CommandStatus for this object

getMessage

public final XMLTransferMessage getMessage()

This method will always return the first XMLTransferMessage

Returns:

the first message that is an XMLTransferMessage object.

getMessages

public final java.util.Collection getMessages()

Returns:

the collection of messages.

getMessages

public static final java.util.Collection getMessages(java.util.List messages)

getMessages

public final java.lang.Object[] getMessages(java.lang.Class c)

Parameters:

c - the Class name for t

Returns:

an array containing all messages of a certain class. This array can be safely typecast by the calling method.

getData

public final java.lang.Object[] getData()

retrieves the set of data that this object represents.

Returns:

an array containing references to all of the objects.

getDataForClass

public final java.lang.Object[] getDataForClass(java.lang.Class c)

retrieves the set of data by class type. This method can be safely called in the following manner.

MyData[] results = (MyData[]) gxo.getDataForClass(MyData.class)

for (int i = 0; i < results.length; ++i)

doSomething ...

Parameters:

c - a class that represents the data we want.

Returns:

an Object array that can be safely cast to the type requested.

generateXmlDocument

public final java.io.ByteArrayOutputStream generateXmlDocument(java.util.List dtdList)
                                                        throws java.lang.Exception

Throws:

java.lang.Exception

setValidating

public void setValidating(boolean valid)

getValidating

public boolean getValidating()

setSchemaSources

public void setSchemaSources(java.io.InputStream[] inpStreams)

dispose

public void dispose()

This is called when you nolonger need this class

exportObjectToXML

public static java.lang.String exportObjectToXML(java.lang.Object id)
                                          throws java.lang.Exception

exports an object to XML so that it can be used as a parameter to an http request.

Throws:

java.lang.Exception

exportObjectToXML

public static java.lang.String exportObjectToXML(java.lang.Class c,
                                                 java.lang.Object id)
                                          throws java.lang.Exception

Exports the object to XML string

Parameters:

c - the class which is typically subclassed from the XMLTransferObject class

id - us the object to be transferred

Returns:

the object id exported as an XML document

Throws:

java.lang.Exception - that occurs

getObjectFromXML

public static java.lang.Object getObjectFromXML(java.lang.String xmlString,
                                                java.lang.Class c)

Returns the first data object of the type Class c from the XML document

Parameters:

xmlString - the xml document

c - the Class of which the data object is to be extracted

Returns:

the first data object of type Class c

setClassFinder

public static void setClassFinder(ClassFinder classfinder)

Skip navigation links