public abstract class TXMLObject extends TDataObject implements TXMLStreamable
A TXMLObject instance can either be obtained from Tamino or can be instantiated via one of the newInstance factory methods.
The object model of a TXMLObject instance obtained from Tamino is identical to the object model of the accessor used. Such a TXMLObject instance has XML content and a unique id with respect to its collection and schema.
The object model of a TXMLObject instance created via a factory method is by definition the stream object model, unless the object model was specified explicitly or the XML document provided as input for the factory method conformed to a specific object model.
The getDocument and getElement methods can be used to access the XML content. The type of object these methods return depends on the object model asssociated with the TXMLOBject instance. The actual XML content returned depends in turn on the method by which the TXMLObject instance was created or the method by by which the instance was obtained from Tamino.
Modifier | Constructor and Description |
---|---|
protected |
TXMLObject()
Initializes the instance.
|
protected |
TXMLObject(java.util.Locale locale)
Initializes the instance.
|
protected |
TXMLObject(java.lang.String collection,
java.lang.String doctype)
Initializes the instance with the given collection and doctype.
|
protected |
TXMLObject(java.lang.String collection,
java.lang.String doctype,
java.util.Locale locale)
Initializes the instance with the given collection and doctype.
|
Modifier and Type | Method and Description |
---|---|
java.lang.String |
getDocname()
Gets the ino:docname attribute for this TXMLObject instance.
|
abstract java.lang.Object |
getDocument()
Gets the document instance.
|
abstract java.lang.Object |
getElement()
Gets the element instance.
|
java.lang.String |
getEncoding()
Gets the encoding for this TXMLObject instance.
|
java.lang.String |
getId()
Gets the ino:id attribute for this TXMLObject instance.
|
java.lang.String |
getSystemId()
Gets the systemId for this TXMLObject instance.
|
static TXMLObject |
newInstance(java.io.File file)
Factory method, creates a TXMLObject instance from the given File instance.
|
static TXMLObject |
newInstance(java.io.File file,
java.util.Locale locale)
Factory method, creates a TXMLObject instance from the given File instance.
|
static TXMLObject |
newInstance(java.io.File file,
java.lang.String systemId)
Factory method, creates a TXMLObject instance from the given File instance.
|
static TXMLObject |
newInstance(java.io.File file,
java.lang.String systemId,
java.util.Locale locale)
Factory method, creates a TXMLObject instance from the given File instance.
|
static TXMLObject |
newInstance(java.io.InputStream inputStream)
Factory method, creates a TXMLObject from the given byte input
stream.
|
static TXMLObject |
newInstance(java.io.InputStream inputStream,
java.util.Locale locale)
Factory method, creates a TXMLObject from the given byte input
stream.
|
static TXMLObject |
newInstance(java.io.InputStream inputStream,
java.lang.String systemId)
Factory method, creates a TXMLObject from the given byte input
stream.
|
static TXMLObject |
newInstance(java.io.InputStream inputStream,
java.lang.String systemId,
java.util.Locale locale)
Factory method, creates a TXMLObject from the given byte input
stream.
|
static TXMLObject |
newInstance(java.lang.Object object)
Factory method, creates a TXMLObject instance from the given object
instance.
|
static TXMLObject |
newInstance(java.lang.Object object,
java.util.Locale locale)
Factory method, creates a TXMLObject instance from the given object
instance.
|
static TXMLObject |
newInstance(java.io.Reader reader)
Factory method, creates a TXMLObject from the given character input
stream.
|
static TXMLObject |
newInstance(java.io.Reader reader,
java.util.Locale locale)
Factory method, creates a TXMLObject from the given character input
stream.
|
static TXMLObject |
newInstance(java.io.Reader reader,
java.lang.String systemId)
Factory method, creates a TXMLObject from the given character input
stream.
|
static TXMLObject |
newInstance(java.io.Reader reader,
java.lang.String systemId,
java.util.Locale locale)
Factory method, creates a TXMLObject from the given character input
stream.
|
static TXMLObject |
newInstance(java.lang.String xml)
Factory method, creates a TXMLObject instance from the given
string.
|
static TXMLObject |
newInstance(java.lang.String xml,
java.util.Locale locale)
Factory method, creates a TXMLObject instance from the given
string.
|
static TXMLObject |
newInstance(java.lang.String xml,
java.lang.String systemId)
Factory method, creates a TXMLObject instance from the given
string.
|
static TXMLObject |
newInstance(java.lang.String xml,
java.lang.String systemId,
java.util.Locale locale)
Factory method, creates a TXMLObject instance from the given
string.
|
static TXMLObject |
newInstance(TXMLObjectModel xmlObjectModel)
Factory method specifying a TXMLObjectModel.
|
static TXMLObject |
newInstance(TXMLObjectModel xmlObjectModel,
java.util.Locale locale)
Factory method specifying a TXMLObjectModel.
|
static TXMLObject |
newInstance(java.net.URL url)
Factory method, creates a TXMLObject instance by reading an XML
document from the given URL.
|
static TXMLObject |
newInstance(java.net.URL url,
java.util.Locale locale)
Factory method, creates a TXMLObject instance by reading an XML
document from the given URL.
|
static TXMLObject |
newInstance(java.net.URL url,
java.lang.String systemId)
Factory method, creates a TXMLObject instance by reading an XML
document from the given URL.
|
static TXMLObject |
newInstance(java.net.URL url,
java.lang.String systemId,
java.util.Locale locale)
Factory method, creates a TXMLObject instance by reading an XML
document from the given URL.
|
void |
setContentType(java.lang.String contentType)
Overrides base class method to ensure that text/xml is the only contentType.
|
void |
setDocname(java.lang.String docname)
Sets the ino:docname for the TXMLObject instance.
|
void |
setEncoding(java.lang.String encoding)
Sets the encoding for this TXMLObject instance.
|
void |
setId(java.lang.String id)
Sets the ino:id for the TXMLObject instance.
|
protected void |
setProperty(java.lang.String key,
java.lang.Object value)
Sets a property for the specific implementation of TXMLObject.
|
void |
setSystemId(java.lang.String systemId)
Sets the systemId for this TXMLObject instance.
|
void |
writeTo(java.io.OutputStream outputStream)
Writes the XML document represented by this TXMLObject instance to the outputStream
passed as parameter.
|
void |
writeTo(java.io.OutputStream outputStream,
java.lang.String encoding)
Writes the XML document represented by this TXMLObject instance to the outputStream
passed as parameter.
|
void |
writeTo(java.io.Writer writer)
Writes the XML document represented by this TXMLObject instance to the Writer
passed as parameter.
|
void |
writeTo(java.io.Writer writer,
java.lang.String encoding)
Writes the XML document represented by this TXMLObject instance to the Writer
passed as parameter.
|
canWriteToOutputStream, getCollection, getContentType, getDoctype, getLastModified, getLocale, hasCollection, hasDocname, hasDoctype, hasId, readDocumentStateFrom, readStateFrom, setCollection, setDoctype, setLastModified, setLocale, writeDocumentStateTo, writeStateTo
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
readFrom, readFrom
getContentType, readFrom, readFrom
protected TXMLObject()
protected TXMLObject(java.util.Locale locale)
protected TXMLObject(java.lang.String collection, java.lang.String doctype)
protected TXMLObject(java.lang.String collection, java.lang.String doctype, java.util.Locale locale)
public static TXMLObject newInstance(TXMLObjectModel xmlObjectModel)
Example:
TXMLObject xmlObject = TXMLObject.newInstance( TDOMObjectModel.getInstance() , null , null ); xmlObject.readFrom( inputStream ); org.w3c.dom.Element rootElement = (org.w3c.dom.Element)xmlObject.getElement();
xmlObjectModel
- the object model to be used.public static TXMLObject newInstance(java.lang.Object object)
object
- an object representing the XML document.public static TXMLObject newInstance(java.io.InputStream inputStream)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
inputStream
- a byte input stream from which the
TXMLObject instance is built.public static TXMLObject newInstance(java.io.InputStream inputStream, java.lang.String systemId)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
inputStream
- a byte input stream from which the
TXMLObject instance is built.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.io.Reader reader)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
reader
- a character input stream from which the
TXMLObject instance is built.public static TXMLObject newInstance(java.io.Reader reader, java.lang.String systemId)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
reader
- a character input stream from which the
TXMLObject instance is built.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.lang.String xml)
xml
- a String containing wellformed XML.public static TXMLObject newInstance(java.lang.String xml, java.lang.String systemId)
xml
- a String containing wellformed XML.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.net.URL url)
url
- a URL providing a byte input stream containing an XML
document.public static TXMLObject newInstance(java.net.URL url, java.lang.String systemId)
url
- a URL providing a byte input stream containing an XML
document.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.io.File file)
file
- a file providing a byte input stream containing an XML document.public static TXMLObject newInstance(java.io.File file, java.lang.String systemId)
file
- a file providing a byte input stream containing an XML document.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(TXMLObjectModel xmlObjectModel, java.util.Locale locale)
Example:
TXMLObject xmlObject = TXMLObject.newInstance( TDOMObjectModel.getInstance() , null , null ); xmlObject.readFrom( inputStream ); org.w3c.dom.Element rootElement = (org.w3c.dom.Element)xmlObject.getElement();
xmlObjectModel
- the object model to be used.public static TXMLObject newInstance(java.lang.Object object, java.util.Locale locale)
object
- an object representing the XML document.public static TXMLObject newInstance(java.io.InputStream inputStream, java.util.Locale locale)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
inputStream
- a byte input stream from which the
TXMLObject instance is built.public static TXMLObject newInstance(java.io.InputStream inputStream, java.lang.String systemId, java.util.Locale locale)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
inputStream
- a byte input stream from which the
TXMLObject instance is built.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.io.Reader reader, java.util.Locale locale)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
reader
- a character input stream from which the
TXMLObject instance is built.public static TXMLObject newInstance(java.io.Reader reader, java.lang.String systemId, java.util.Locale locale)
Note that a stream can only be processed once; for example after an insert or update operation in Tamino, the stream is consumed and can not be used again.
reader
- a character input stream from which the
TXMLObject instance is built.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.lang.String xml, java.util.Locale locale)
xml
- a String containing wellformed XML.public static TXMLObject newInstance(java.lang.String xml, java.lang.String systemId, java.util.Locale locale)
xml
- a String containing wellformed XML.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.net.URL url, java.util.Locale locale)
url
- a URL providing a byte input stream containing an XML
document.public static TXMLObject newInstance(java.net.URL url, java.lang.String systemId, java.util.Locale locale)
url
- a URL providing a byte input stream containing an XML
document.systemId
- the base URI of the data to resolve relative references.public static TXMLObject newInstance(java.io.File file, java.util.Locale locale)
file
- a file providing a byte input stream containing an XML document.public static TXMLObject newInstance(java.io.File file, java.lang.String systemId, java.util.Locale locale)
file
- a file providing a byte input stream containing an XML document.systemId
- the base URI of the data to resolve relative references.public abstract java.lang.Object getDocument()
Type.
For the DOM object model, an org.w3c.dom.Document instance is returned.
For the JDOM object model, an org.jdom.Document instance is returned.
For the stream object model, an org.xml.sax.InputSource instance is returned.
For a SAX object model, an instance of the class implementing the TSAXDocument
interface is returned. The class is the class specified when the SAX object model
was instantiated.
Content.
There are 3 ways to create a TXMLObject instance: via any of the factory methods newInstance of the TXMLObject class; via a retrieve method of an accessor; as a member of the result of a query.
For newInstance and retrieve, the complete document is returned according to the object model in use. In case of the stream object model, the document is returned as a byte stream and can be accessed via the getByteStream method of the InputSource instance.
For query, the document returned depends on the object model used. For the stream object model, an InputSource instance is returned, which does not contain any relevant information (both getByteStream and getCharacterStream return null). For other object models, the document returned represents the complete response document as returned by Tamino. For more information on the structure of a Tamino response document, see the Tamino documentation. Normally, it is not necessary to process the Tamino response document itself. All relevant information is accessible through the TResponse instance resturned by the query. You can access the individual members of the result set of a query via the getElement method.
Note that when iterating through a result set the Tamino response document returned by the getDocument method does not change unless the query was invoked to be performed in steps. In that case, the response document changes every time the next step is performed.
public abstract java.lang.Object getElement()
Type.
For the DOM object model, an org.w3c.dom.Element instance is returned.
For the JDOM object model, an org.jdom.Element instance is returned.
For the stream object model, an org.xml.sax.InputSource instance is returned.
For a SAX object model, an instance of the class implementing the TSAXElement
interface is returned. The class is the class specified when the SAX object model
was instantiated.
Content.
There are 3 ways to create a TXMLObject instance: via any of the factory methods newInstance of the TXMLObject class; via a retrieve method of an accessor; as a member of the result of a query.
For newInstance and retrieve, the complete root element is returned according to the object model in use. In case of the stream object model, an InputSource instance is returned, which does not contain any relevant information (both getByteStream and getCharacterStream return null).
For query, the element returned depends on the object model used. For the stream object model, the element is delivered as a charactezr stream and can be accessed via the getCharacterStream method of the InputSource instance. For other object models, the element returned represents a single member of the query result set.
public void setDocname(java.lang.String docname)
Sets the ino:docname for the TXMLObject instance. The ino:docname is an optional identification for an XML document stored in Tamino. Other than the ino:id, the ino:docname can be set by the user. The ino:id is automatically set by Tamino. Once the ino:docname is set it can not be changed. If an XML document is inserted without an ino:docname, the ino:docname can not added. The ino:docname can therefore only be set when an XML document is inserted in a Tamino database. If the setDocname method is called on a TXMLObject instance that was read from Tamino, and this document is subsequently updated the set ino:docname value is ignored by Tamino. The original setting of ino:docname remains unchanged.
The setDocname method can also be used to completely remove the ino:docname attribute from the XML document by passing a null or an empty String as docname. This may be necessary when the XML document should not contain any ino: namespace specific elements.
setDocname
in class TDataObject
docname
- the ino:docname attribute. If null or an empty String, the ino:docname attribute
is completely removed from the underlying XML document, e.g. in case of a DOM object model,
the Node representing the ino:docname attribute is removed from the DOM tree.public void setId(java.lang.String id)
Sets the ino:id for the TXMLObject instance. The ino:id is a unique identification of an XML document stored in Tamino. The ino:id is automatically set by Tamino when a new XML document is inserted in a Tamino database. The ino:id can not be set by the user nor can it be changed. The main purpose of the setId method is for retrieval. If the ino:id of an XML document stored in Tamino is known, it can be retrieved directly by creating an instance of TXMLObject and setting the ino:id. The retrieve method of an accessor instance can then be used to retrieve the XML document from Tamino.
The setId method can also be used to completely remove the ino:id attribute from the XML document by passing a null or an empty String as id. This may be necessary when the XML document should not contain any ino: namespace specific elements.
setId
in class TDataObject
id
- the ino:id attribute. If null or an empty String, the ino:id attribute is completely removed
from the underlying XML document, e.g. in case of a DOM object model, the Node representing
the ino:id attribute is removed from the DOM tree.public void setContentType(java.lang.String contentType)
setContentType
in class TDataObject
contentType
- has to be text/xml.public java.lang.String getDocname()
getDocname
in class TDataObject
public java.lang.String getId()
getId
in class TDataObject
public void setSystemId(java.lang.String systemId)
systemId
- the systemId.public java.lang.String getSystemId()
public void setEncoding(java.lang.String encoding)
encoding
- the encoding, if null or empty the default encoding (utf-8) will be used.public java.lang.String getEncoding()
public void writeTo(java.io.OutputStream outputStream) throws TStreamWriteException
This method uses the encoding specified with setEncoding(). The encoding is always set in the prologue of the stream, i.e. the prologue always looks like this: <?xml ... encoding="..." ...?> and the byte stream representing the XML document is encoded in this encoding.
If there is no encoding set, the default encoding "utf-8" is used.
writeTo
in interface TStreamable
outputStream
- the byte output stream.TStreamWriteException
- signals an error while attempting to write the stream.public void writeTo(java.io.Writer writer) throws TStreamWriteException
This method uses the encoding specified with setEncoding(). The encoding is always set in the prologue of the character stream, i.e. the prologue always looks like this: <?xml ... encoding="..." ...?>. The character stream representing the XML document is normally not concerned with a particular encoding, unless an OutputStreamWriter is used. An OutputStreamWriter is a converter between a character stream and a byte stream. That conversion is done based on a specific encoding. If an OutputStreamWriter is used with any other encoding than the specified (setEncoding()), there will be a mismatch between the encoding set in the prologue and the encoding of the byte stream. It is therefore recommended to only use an OutputStreamWriter in conjunction with UTF-8.
writeTo
in interface TStreamable
writer
- the character output stream writer.TStreamWriteException
- signals an error while attempting to write the stream.public void writeTo(java.io.OutputStream outputStream, java.lang.String encoding) throws TStreamWriteException
This method uses the given encoding. The given encoding is always set in the prologue of the stream, i.e. the prologue always looks like this: <?xml ... encoding="..." ...?> and the byte stream representing the XML document is always encoded with the given encoding.
Note: This is currently only supported by DOM-, JDOM- and StreamObjectModel.
writeTo
in interface TXMLStreamable
outputStream
- the byte output stream.encoding
- the encoding used for serializing the XML document.TStreamWriteException
- signals an error while attempting to write the stream.public void writeTo(java.io.Writer writer, java.lang.String encoding) throws TStreamWriteException
This method uses the given encoding. The given encoding is always set in the prologue of the stream, i.e. the prologue always looks like this: <?xml ... encoding="..." ...?>. The character stream representing the XML document is normally not concerned with a particular encoding, unless an OutputStreamWriter is used. An OutputStreamWriter is a converter between a character stream and a byte stream. That conversion is done based on a specific encoding. If an OutputStreamWriter is used with any other encoding than given encoding, there will be a mismatch between the encoding set in the prologue and the encoding of the byte stream. It is therefore recommended to only use an OutputStreamWriter in conjunction with given encoding. Note: This is currently only supported by DOM-, JDOM- and StreamObjectModel.
writeTo
in interface TXMLStreamable
writer
- the character output stream writer.encoding
- the encoding used for serializing the XML document.TStreamWriteException
- signals an error while attempting to write the stream.protected void setProperty(java.lang.String key, java.lang.Object value)
key
- the values key.value
- the key's value.Copyright (c) 2017 Software AG. All Rights Reserved.