com.actional.soapstation.plugin.inproc

Interface IXmlDocument

public interface IXmlDocument

Objects implementing this interface allow collecting and reusing expensive operations like converting an XML document from a byte[] into a DOM document.

Method Summary

Modifier and Type	Method and Description
IXpathResult	execute(IXPathEvaluator xpath, boolean writable) This method evaluates an XPATH using any available representation of the XML document.
boolean	fitsInMemory() indicates whether the documents fits in memory.
byte[]	getBytes() Returns the bytes of the message if they can all fit in memory.
byte[]	getBytes(boolean bytesMustMatchDOM) This method returns the text representation of the XML document as a byte array.
byte[]	getBytesIfAllInMemory(boolean throwEx) Returns the bytes of the message if they can all fit in memory.
byte[]	getBytesInMemory() Returns the bytes of the message that can fit in memory.
org.w3c.dom.Document	getDOM(boolean writable) This method returns XML document as a DOM representation.
java.lang.String	getEncoding() Returns the encoding of the document.
java.lang.Object	getMonitor() This method returns the object on which client code can synchronize to maintain the integrity of this IXmlDocument.
java.util.Map<java.lang.Object,java.lang.Object>	getScratchPad() This method returns a map that client code can use to cache information along with this IXmlDocument.
boolean	hasBytes() This method returns true if the byte array representation is already available without requiring extra computations.
boolean	hasData() This method returns true if this instance has data.
boolean	hasDOM() This method returns true if the DOM representation is already available without requiring extra computations.
boolean	hasDTM() This method returns true if the XPATH engine is already initialized and ready for computing XPATH expressions.
void	reset(byte[] bytes) This method flushes out the cache information of this XML document, and re-initializes itself using the passed array of bytes.
void	reset(org.w3c.dom.Document doc) This method flushes out the cache information of this XML document, and re-initializes itself using the passed document.

Method Detail

getEncoding

java.lang.String getEncoding()
                      throws java.lang.Exception

Returns the encoding of the document.

Returns:

the encoding (or charset) of the document. null if the document is not currently encoding as XML.

Throws:

java.lang.Exception

getBytesInMemory

byte[] getBytesInMemory()
                 throws java.lang.Exception

Returns the bytes of the message that can fit in memory.

Returns:

the bytes of the message that can fit in memory. It will not be the whole message if the message is too large to fit in memory.

Throws:

java.lang.Exception

getBytesIfAllInMemory

byte[] getBytesIfAllInMemory(boolean throwEx)
                      throws java.lang.Exception

Returns the bytes of the message if they can all fit in memory.

Parameters:

throwEx - whether to throw an exception if all the bytes of the message cannot be in memory.

Returns:

the bytes of the message. If the message is bigger that the in memory limit, return null if throwEx is false, otherwise throws an exception.

Throws:

java.lang.Exception

getBytes

byte[] getBytes()
         throws java.lang.Exception

Returns the bytes of the message if they can all fit in memory. This method is equivalent to calling getBytesIfAllInMemory(true).

Returns:

the bytes of the message. If the message is bigger that the in memory limit, throws an exception.

Throws:

java.lang.Exception

getBytes

byte[] getBytes(boolean bytesMustMatchDOM)
         throws java.lang.Exception

This method returns the text representation of the XML document as a byte array.
If the byte representation is unavailable, then it is built from using the DOM representation.
If the DOM representation is unavailable, an exception is thrown.
The bytesMustMatchDOM flag is used to determine whether it is mandatory that the available bytes must match the current DOM representation. This can be useful when formatting the bytes for display, even if there is a problem in the XML. This method will throw an exception if all the bytes of the message cannot fit in memory.

Throws:

java.lang.Exception

getDOM

org.w3c.dom.Document getDOM(boolean writable)
                     throws java.lang.Exception

This method returns XML document as a DOM representation.
If the DOM representation is unavailable, then it is built from using the byte array representation.
If the byte array representation is unavailable, an exception is thrown.

Parameters:

writable - true if the caller intends on making modifications to the DOM that is returned. If false, the DOM should be considered to be read-only (under some circumstances, this will be enforced). Calling getDOM(false) and then modifying the DOM can lead to unpredictable results.

Throws:

java.lang.Exception

execute

IXpathResult execute(IXPathEvaluator xpath,
                     boolean writable)
              throws java.lang.Exception

This method evaluates an XPATH using any available representation of the XML document.
If a DOM representation is available, then the XPATH is evaluated from it.
Otherwise if byte array is available, then the XPATH is evaluated from it.
Otherwise an exception is thrown.

Parameters:

writable - true if the caller wants to have back DOM nodes that it can modify. If you do not need to modify the DOM nodes returned by evaluating the XPATH, it is recommended to pass in false as building a read-only DOM is faster.

Throws:

java.lang.Exception

hasBytes

boolean hasBytes()

This method returns true if the byte array representation is already available without requiring extra computations.

hasDOM

boolean hasDOM()

This method returns true if the DOM representation is already available without requiring extra computations.

hasDTM

boolean hasDTM()

This method returns true if the XPATH engine is already initialized and ready for computing XPATH expressions.

hasData

boolean hasData()

This method returns true if this instance has data.

reset

void reset(byte[] bytes)

This method flushes out the cache information of this XML document, and re-initializes itself using the passed array of bytes.
After calling this method, calling:

• hasBytes() returns true
• hasDOM() returns false
• hasDTM() returns false
• getScratchPad() returns a brand new map

The reference count remains the same.

reset

void reset(org.w3c.dom.Document doc)

This method flushes out the cache information of this XML document, and re-initializes itself using the passed document.
After calling this method, calling:

• hasBytes() returns false
• hasDOM() returns true
• hasDTM() returns false
• getScratchPad() returns a brand new map

The reference count remains the same.

fitsInMemory

boolean fitsInMemory()

indicates whether the documents fits in memory. A document fits in memory if no limit has been fixed on its size or it the bytes of the document is smaller than the limit.

Returns:

true if the document fits im memory, false otherwise.

getScratchPad

java.util.Map<java.lang.Object,java.lang.Object> getScratchPad()

This method returns a map that client code can use to cache information along with this IXmlDocument.

getMonitor

java.lang.Object getMonitor()

This method returns the object on which client code can synchronize to maintain the integrity of this IXmlDocument. This method is of the utmost importance when you want operations made on this IXmlDocument to be atomic, especially when modifying the IXmlDocument with methods like reset(byte[]).