edu.uky.rch.ept.data
Interface IConcurrentXMLAccessMethods

All Known Subinterfaces:

IDataAccessMethods, IDataSourceDriver

All Known Implementing Classes:

DataFactory, DataSourceDriver, Project, Repository

public interface IConcurrentXMLAccessMethods

This interface defines all the access methods for concurrent XML. 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

DTD Identifiers are of the form: 'root of project' + IDataConstants.SEP_MAJOR + 'ID'

For example: file:///home/ept/BEOWULF/cotlib.damage where "file:///home/ept/BEOWULF" is the root of the project and "cotlib.damage" is the specific identifier of the DTD. These methods are currently experimental and subject to change without notice. If you wish to use these methods, please speak with Neil <neil@s-z.org>.

Author:

Sandeep Bodapati <sbodapati@uky.edu>, Neil Moore <neil@s-z.org>

Method Summary

boolean	deleteCXML(String address, String dtdID, String location) Removes the node at the specified location in the resource.
String	getCXML(String address, String[] dtdIDs) Combine the specified hierarchies of the CXML content and return the result as a pseudo-XML string.
void	insertCXML(String address, String dtdID, String location, org.dom4j.Node newContent) Inserts the given XML node into the CXML resource at the indicated location.
Object	queryCXML(String xmlResourceAddress, String[] dtdIDs, String query, short returnType) Executes the given query on the CXML resource and returns the results as a list of org.dom4j.Nodes.
void	replaceCXML(String address, String dtdID, String location, org.dom4j.Node newContent) Replaces the node at the specified location in the resource with a new node at the same location.
void	replaceCXMLContent(String xmlResourceAddress, int beginIndex, int endIndex, String newContent) (unimplemented) Treats a CXML resource as text resource (all tags are treated as though they did not exist) and replaces the text from beginIndex to endIndex-1 with the new text content.
boolean	storeCXML(String address, String[] dtdIDs, String content, boolean force) Creates a new CXML resource.

Method Detail

getCXML

public String getCXML(String address,
                      String[] dtdIDs)
               throws MalformedAddressException,
                      ResourceNotFoundException,
                      IOException

Combine the specified hierarchies of the CXML content and return the result as a pseudo-XML string. If dtdIDs[] is null or an empty array, combine all the hierarchies. If dtdIDs contains a single DTD and the document is well-formed with respect to that DTD, the result will be proper XML.

Parameters:

address - address of the CXML resource.

dtdIDs - an array of DTD identifiers, specifying which hierarchies to combine. If this parameter is null or empty, all the hierarchies are combined.

Returns:

a String with the combined hierarchies.

Throws:

ResourceNotFoundException - if the resource doesn't exist

MalformedAddressException

IOException

storeCXML

public boolean storeCXML(String address,
                         String[] dtdIDs,
                         String content,
                         boolean force)
                  throws MalformedAddressException,
                         IOException

Creates a new CXML resource. This method parses the given content to handle the concurrent hierarchies and creates the required xml resource. The different hierarchies to be handled are specified by the identifiers referred to by the array of DTD identifiers. Note: currently, content should be the empty string; if not, that content will not be located properly with respect to other nodes. This will be fixed.

Parameters:

address - the address at which to store the CXML resource

dtdIDs - an array of DTD identifiers

content - the CXML data to be written (currently, the empty string)

force - flag indicating whether the resource should be overwritten if it already exists.

Returns:

true if the resource was created successfully, false otherwise.

Throws:

MalformedAddressException

IOException

insertCXML

public void insertCXML(String address,
                       String dtdID,
                       String location,
                       org.dom4j.Node newContent)
                throws MalformedAddressException,
                       ResourceNotFoundException,
                       InvalidNodePathException,
                       IOException

Inserts the given XML node into the CXML resource at the indicated location. The location takes the form "[[beg:end]]", where beg and end are the integer coordinates of the node, used to position it with respect to other nodes.

Parameters:

address - address of the resource.

dtdID - identifier of the corresponding DTD.

location - location for the new node, as specified above.

newContent - new node, which should be either an org.dom4j.Element or an org.dom4j.Text. The node's content is ignored; only the top-level node itself is used.

Throws:

ResourceNotFoundException - if the resource doesnt exist

InvalidNodePathException - if the given location is invalid.

MalformedAddressException

IOException

replaceCXML

public void replaceCXML(String address,
                        String dtdID,
                        String location,
                        org.dom4j.Node newContent)
                 throws MalformedAddressException,
                        ResourceNotFoundException,
                        InvalidNodePathException,
                        IOException

Replaces the node at the specified location in the resource with a new node at the same location. The location is of the same form as the similarly-named parameter to deleteCXML(java.lang.String, java.lang.String, java.lang.String).

Parameters:

address - address of the resource.

dtdID - identifier of the corresponding DTD.

location - location and tag name of an existing node, as specified by deleteCXML(java.lang.String, java.lang.String, java.lang.String).

newContent - the node to replace the deleted node; this should be as the argument to insertCXML(java.lang.String, java.lang.String, java.lang.String, org.dom4j.Node).

Throws:

ResourceNotFoundException - if the resource doesnt exist.

InvalidNodePathException - if the given location is invalid.

MalformedAddressException

IOException

deleteCXML

public boolean deleteCXML(String address,
                          String dtdID,
                          String location)
                   throws MalformedAddressException,
                          ResourceNotFoundException,
                          InvalidNodePathException,
                          IOException

Removes the node at the specified location in the resource. The location takes the form "[[beg:end]]|tag", where beg and end are the integer coordinates of the node (the coordinates passed to insertCXML(java.lang.String, java.lang.String, java.lang.String, org.dom4j.Node) when the node was originally inserted) and tag is the tag name of the node to be removed (or "st:string" to remove text content).

Parameters:

address - address of the resource

dtdID - identifier of the corresponding DTD.

location - location and tag name of an existing node, as specified above.

Returns:

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

Throws:

ResourceNotFoundException - if the resource doesnt exist

InvalidNodePathException - if the location is invalid.

MalformedAddressException

IOException

replaceCXMLContent

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

(unimplemented) Treats a CXML resource as text resource (all tags are treated as though they did not 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

queryCXML

public Object queryCXML(String xmlResourceAddress,
                        String[] dtdIDs,
                        String query,
                        short returnType)
                 throws MalformedAddressException,
                        ResourceNotFoundException,
                        MalformedQueryException,
                        IOException,
                        InvalidTypeException

Executes the given query on the CXML resource and returns the results as a list of org.dom4j.Nodes. Each such node is either an Element or a Text object. The query is of the form "op[[from:to]] where from and to are the coordinates of the context range (these are the same coordinates used by insertCXML(java.lang.String, java.lang.String, java.lang.String, org.dom4j.Node)). op indicates the type of query to perform, and may be one of:

• (empty): return all descendants (nodes contained in the context range). This is the only query type which returns nodes covering exactly the context range.
• children: return all children (strict descendants not strictly contained in other descendants). Does not return nodes which cover exactly the context range.
• ancestors: return all ancestors (nodes which strictly contain the context range).
• parents: return all parents (ancestors which do not strictly contain other ancestors).

Parameters:

xmlResourceAddress - address of the XML resource

dtdIDs - an array of DTD identifiers, specifying which of the hierarchies to consider for the query. If this parameter is null or empty, then all the hierarchies are considered.

query - the query, as specified above.

returnType - return type. This argument is currently ignored.

Returns:

an object containing the result of the query. The object is currently always a List of dom4j Element and Text nodes.

Throws:

ResourceNotFoundException - if the resource doesnt exist

MalformedQueryException - if the query is malformed

InvalidTypeException - if the return type specified is unrecognized (should never happen)

MalformedAddressException

IOException