edu.uky.rch.ept.data
Interface IXMLAccessMethods

All Known Subinterfaces:

IDataAccessMethods, IDataSourceDriver

All Known Implementing Classes:

DataFactory, DataSourceDriver, Project, Repository

public interface IXMLAccessMethods

This interface defines all the xml data access methods. Wherever addresses are involved in creating new resources, all non-existing collections in the specified path to the resource will be created automatically.

All the methods throw the following exceptions:

• NullAddressException - if the address specified is null
• MalformedAddressException - if the address specified is not a proper URI
• UnknownProtocolException - if there is no driver registered for the protocol specified in the address
• IOException - if a low level IO error occurs during processing

Author:

Sandeep Bodapati

Method Summary

boolean	deleteXML(String address, String xpath) Deletes the node pointed to by the xpath, from the xml resource.
String	getXML(String address) Retrieves the XML data from the specified address.
org.dom4j.Document	getXMLDocument(String address) Retrieves the XML data from the specified address.
void	insertXML(String address, String xpath, org.dom4j.Node newContent) Inserts the given xml node into the xml resource immediately after the node specified by the xpath.
Object	queryXML(String xmlResourceAddress, String query, short returnType) Executes the given query on the XML resource and returns the results in the format specified by the returnType parameter.
void	replaceXML(String address, String xpath, org.dom4j.Node newContent) Replaces the specified node in the resource with the new node.
void	replaceXMLContent(String xmlResourceAddress, int beginIndex, int endIndex, String newContent) Treats an xml resource as text resource (all tags are ignored as if they didnt exist) and replaces the text from beginIndex to endIndex-1 with the new text content.
boolean	storeXML(String address, org.dom4j.Document content, boolean force) Creates a new XML resource with the given content, reindented for readability.
boolean	storeXML(String address, org.dom4j.Document content, boolean force, boolean indent) Creates a new XML resource with the given content, possibly reindented.

Method Detail

getXMLDocument

public org.dom4j.Document getXMLDocument(String address)
                                  throws MalformedAddressException,
                                         ResourceNotFoundException,
                                         IOException

Retrieves the XML data from the specified address.

Parameters:

address - address of the xml resource

Returns:

a Document object built from the data in the resource

Throws:

ResourceNotFoundException - if the resource doesnt exist

MalformedAddressException

IOException

getXML

public String getXML(String address)
              throws MalformedAddressException,
                     ResourceNotFoundException,
                     IOException

Retrieves the XML data from the specified address.

Parameters:

address - address of the xml resource

Returns:

a String object containing the data from the resource

Throws:

ResourceNotFoundException - if the resource doesnt exist

MalformedAddressException

IOException

storeXML

public boolean storeXML(String address,
                        org.dom4j.Document content,
                        boolean force)
                 throws MalformedAddressException,
                        IOException

Creates a new XML resource with the given content, reindented for readability. Use storeXML(String, Document, boolean, boolean) instead to preserve whitespace. This method is to be used for XML resources that do not have concurrent hierarchies.

Parameters:

address - the address of the resource.

content - the Document to be written

force - if true then the resource is overwritten if it already exists

Returns:

true if the resource did not exist and was created successfully, false otherwise

Throws:

MalformedAddressException

IOException

storeXML

public boolean storeXML(String address,
                        org.dom4j.Document content,
                        boolean force,
                        boolean indent)
                 throws MalformedAddressException,
                        IOException

Creates a new XML resource with the given content, possibly reindented. This method is to be used for xml resources that do not have concurrent hierarchies.

Parameters:

address - the address of the resource

content - the Document to be written

force - if true then the resource is overwritten if it already exists

indent - if true reindent the document, compressing contiguous sequences of whitespace characters in content.

Returns:

true if the resource did not exist and was created successfully, false otherwise

Throws:

MalformedAddressException

IOException

insertXML

public void insertXML(String address,
                      String xpath,
                      org.dom4j.Node newContent)
               throws MalformedAddressException,
                      ResourceNotFoundException,
                      InvalidNodePathException,
                      IOException

Inserts the given xml node into the xml resource immediately after the node specified by the xpath.

Parameters:

address - address of the resource

xpath - valid path to a node

newContent - new node

Throws:

ResourceNotFoundException - if the resource doesnt exist

InvalidNodePathException - if the given xpath does not point to a node (valid location)

MalformedAddressException

IOException

replaceXML

public void replaceXML(String address,
                       String xpath,
                       org.dom4j.Node newContent)
                throws MalformedAddressException,
                       ResourceNotFoundException,
                       InvalidNodePathException,
                       IOException

Replaces the specified node in the resource with the new node.

Parameters:

address - address of the resource

xpath - valid path to an existing node in the resource

newContent - new node

Throws:

ResourceNotFoundException - if the resource doesnt exist

InvalidNodePathException - if the given xpath does not point to a node (valid location) in the resource

MalformedAddressException

IOException

replaceXMLContent

public void replaceXMLContent(String xmlResourceAddress,
                              int beginIndex,
                              int endIndex,
                              String newContent)
                       throws MalformedAddressException,
                              ResourceNotFoundException,
                              IndexOutOfBoundsException,
                              IOException

Treats an xml resource as text resource (all tags are ignored as if they didnt exist) and replaces the text from beginIndex to endIndex-1 with the new text content. If endIndex is EOF, the text till the end of the resource will be replaced.

Parameters:

xmlResourceAddress - address of the resource

beginIndex - beginIndex, inclusive

endIndex - endIndex, exclusive

newContent - new text content

Throws:

ResourceNotFoundException - if the resource doesnt exist

IndexOutOfBoundsException - if the beginIndex is negative, or beginIndex is larger than endIndex and endIndex is not EOF.

MalformedAddressException

IOException

deleteXML

public boolean deleteXML(String address,
                         String xpath)
                  throws MalformedAddressException,
                         ResourceNotFoundException,
                         InvalidNodePathException,
                         IOException

Deletes the node pointed to by the xpath, from the xml resource.

Parameters:

address - address of the resource

xpath - valid path to an existing node in the resource

Returns:

true if the node existed and was succesfully deleted, false otherwise

Throws:

ResourceNotFoundException - if the resource doesnt exist

InvalidNodePathException - if the given xpath does not point to a node (valid location) in the resource

MalformedAddressException

IOException

queryXML

public Object queryXML(String xmlResourceAddress,
                       String query,
                       short returnType)
                throws MalformedAddressException,
                       ResourceNotFoundException,
                       MalformedQueryException,
                       IOException,
                       InvalidTypeException

Executes the given query on the XML resource and returns the results in the format specified by the returnType parameter.

Parameters:

xmlResourceAddress - address of the XML resource

query - the query

returnType - return type.

The following values are valid for the return type:

• RT_DOCUMENT - Returns a Document object
• RT_NODELIST - Returns a list of Nodes
• RT_STRINGS - Returns a String array

Returns:

an object containing the result of the query. The type of object is decided by the returnType parameter.

Throws:

ResourceNotFoundException - if the resource doesnt exist

MalformedQueryException - if the query is malformed

InvalidTypeException - if the return type specified is unrecognized

MalformedAddressException

IOException