org.sixdml.xindice
Class xiSixdmlCollection

java.lang.Object
  |
  +--org.sixdml.xindice.xiSixdmlCollection

All Implemented Interfaces:

Collection, Configurable, SixdmlCollection, SixdmlConstants

public class xiSixdmlCollection

extends Object

implements SixdmlCollection, SixdmlConstants

 xiSixdmlCollection.java

 An implementation of the SixdmlCollection interface which maps to a collection in
 Xindice. This class is NOT thread safe.
 

Version:

1.0

Field Summary

(package private) Collection	collection The underlying Xindice collection that this class uses to interact with the database.
private String	indexFile The name of this Collection's index file.
private boolean	open Flag indicates whether the collection is open or not.
private HashMap	properties This is the table of properties for the needed by the Configurable interface.
private String	schemaName The name of this Collection's schema file.

Fields inherited from interface org.sixdml.SixdmlConstants

SIXDML_NS, SIXDML_VERSION

Constructor Summary

private	xiSixdmlCollection() Default constructor private because an instance of this class must always be instantiated with an underlying Xindice collection.
(package private)	xiSixdmlCollection(Collection collection) Initializes this Collection by mapping it to a Xindice collection.

Method Summary

void	addIndex(SixdmlIndex index) Adds an index to apply to the collection.
void	close() Releases all resources consumed by the Collection.
String	createId() Creates a new unique ID within the context of the Collection.
Resource	createResource(String id, String type) Creates a new empty Resource with the provided id.
private static URL	createURL(String fileName) Helper method to create a URL from a file name.
Collection	getChildCollection(String name) Returns a Collection instance for the requested child collection if it exists.
int	getChildCollectionCount() Returns the number of child collections under this Collection or 0 if no child collections exist.
static String	getContentsOfURL(URL source) Helper Method: Obtains the contents at a particular URL and returns them as a string.
SixdmlIndex[]	getIndices() Returns an array of SixdmlIndex objects that apply to this collection.
String	getName() Returns the name associated with the Collection instance.
Collection	getParentCollection() Returns the parent collection for this collection or null if no parent collection exists.
String	getProperty(String str) Returns the value of the property identified by name.
Resource	getResource(String id) Retrieves a Resource from the database.
int	getResourceCount() Returns the number of XML resources in this Collection or 0 if no child collections exist.
Service	getService(String name, String version) Returns a Service instance for the requested service name and version.
Service[]	getServices() Provides a list of all services known to the collection.
private static void	initializeParser(org.apache.xerces.parsers.DOMParser parser, String targetNS, String schemaLocation) Helper Method: Initializes properties related to schema validation in parser.
void	insertDocument(String name, String xmlString) Adds an XML document created from the string argument to the collection.
void	insertDocument(String name, URL documentSource) Adds an XML document loaded from the specified URL to the collection.
boolean	isOpen() Returns true if the Collection is open false otherwise.
String[]	listChildCollections() Returns a list of collection names naming all child collections of the current collection.
String[]	listResources() Returns a list of resource names naming all the resources in the current collection.
static void	main(String[] args) Main used for testing class.
void	removeDocument(String name) Removes an XML document from the collection.
void	removeIndex(String name) Removes a particular index from the collection.
void	removeResource(Resource res) Removes the Resource from the database.
void	setProperty(String name, String value) Sets the property name to have the value provided in value.
void	setSchema(URL schemaFile) Sets the XML schema or DTD that will be used to constrain the documents in this collection.
String	showSchema() Returns the contents of the schema for the collection as a string.
void	storeResource(Resource resource) Stores the provided resource into the database.
void	unsetSchema() Unsets the schema for this collection.
private void	validate(String xmlStr) Helper Method: Validates an XML document against the collection's schema.
private static File	writeToFile(String file, String contents, boolean append) Helper Method: Writes the contents of a string to a file.

Methods inherited from class java.lang.Object

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

Field Detail

indexFile

private String indexFile

The name of this Collection's index file. The index file is an XML document that creates mappings between names given to indexes and the actual index objects in eXcelon's DXE. An index file is needed because eXcelon DXE does not support naming indexes.

schemaName

private String schemaName

The name of this Collection's schema file.

properties

private HashMap properties

This is the table of properties for the needed by the Configurable interface.

See Also:

Configurable

open

private boolean open

Flag indicates whether the collection is open or not.

collection

Collection collection

The underlying Xindice collection that this class uses to interact with the database.

Constructor Detail

xiSixdmlCollection

private xiSixdmlCollection()

Default constructor private because an instance of this class must always be instantiated with an underlying Xindice collection.

xiSixdmlCollection

xiSixdmlCollection(Collection collection)
             throws XMLDBException

Initializes this Collection by mapping it to a Xindice collection.

Parameters:

col - the collection that will be this object's interface to the database.

Throws:

XMLDBException - if a call to the getName() function of the Collection passed in fails.

See Also:

Collection.getName()

Method Detail

addIndex

public void addIndex(SixdmlIndex index)
              throws UnsupportedIndexTypeException,
                     IndexAlreadyExistsException,
                     XMLDBException

Adds an index to apply to the collection.

Specified by:

addIndex in interface SixdmlCollection

Parameters:

index - the index to add

Throws:

UnsupportedIndexTypeException - if the index is of a type unsupported by the database.

IndexAlreadyExistsException - if an index with the same name already exists for the collection.

XMLDBException - if a database error occurs.

close

public void close()
           throws XMLDBException

Releases all resources consumed by the Collection. The close method must always be called when use of a Collection is complete. It is not safe to use a Collection after the close method has been called.
NOTE: This may close ALL connections to the database and thus must be used only when all database interaction is completed.

Specified by:

close in interface Collection

createId

public String createId()
                throws XMLDBException

Creates a new unique ID within the context of the Collection.

Specified by:

createId in interface Collection

Returns:

the created id as a string.

createResource

public Resource createResource(String id,
                               String type)
                        throws XMLDBException

Creates a new empty Resource with the provided id.

Specified by:

createResource in interface Collection

Parameters:

id - the unique id to associate with the created Resource.

type - the Resource type to create.

Throws:

XMLDBException - if the close method has been called on the Collection or the resource type is unknown.

See Also:

ErrorMessages.COLLECTION_CLOSED, ErrorMessages.UNKNOWN_RESOURCE_TYPE

getChildCollection

public Collection getChildCollection(String name)
                              throws XMLDBException

Returns a Collection instance for the requested child collection if it exists.

Specified by:

getChildCollection in interface Collection

Parameters:

name - the name of the child collection to retrieve.

Returns:

the requested child collection or null if it couldn't be found.

Throws:

XMLDBException - if the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED

getChildCollectionCount

public int getChildCollectionCount()
                            throws XMLDBException

Returns the number of child collections under this Collection or 0 if no child collections exist.

Specified by:

getChildCollectionCount in interface Collection

Returns:

the number of child collections

Throws:

XMLDBException - if the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED

getIndices

public SixdmlIndex[] getIndices()
                         throws XMLDBException

Returns an array of SixdmlIndex objects that apply to this collection. If no indexes exist in the collection then an empty array is returned.

Specified by:

getIndices in interface SixdmlCollection

Returns:

an array of SixdmlIndex objects.

Throws:

XMLDBException - if a database error occurs.

getName

public String getName()
               throws XMLDBException

Returns the name associated with the Collection instance.

Specified by:

getName in interface Collection

Returns:

the name of the object.

getParentCollection

public Collection getParentCollection()
                               throws XMLDBException

Returns the parent collection for this collection or null if no parent collection exists.

Specified by:

getParentCollection in interface Collection

Returns:

the parent Collection instance.

Throws:

XMLDBException - if the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED

getProperty

public String getProperty(String str)
                   throws XMLDBException

Returns the value of the property identified by name.

Specified by:

getProperty in interface Configurable

Returns:

the value of the property or null if there is no matching value for the key in hash table.

getResource

public Resource getResource(String id)
                     throws XMLDBException

Retrieves a Resource from the database. If the Resource could not be located a null value will be returned.

Specified by:

getResource in interface Collection

Parameters:

id - the unique id for the requested resource.

Returns:

The retrieved Resource instance.

Throws:

XMLDBException - if the close method has been called on the Collection or the user attempts to access the collection's schema.

See Also:

ErrorMessages.COLLECTION_CLOSED, ErrorMessages.PERMISSION_DENIED_SCHEMA, ErrorMessages.PERMISSION_DENIED_INDEX

getResourceCount

public int getResourceCount()
                     throws XMLDBException

Returns the number of XML resources in this Collection or 0 if no child collections exist.

Specified by:

getResourceCount in interface Collection

Returns:

the number of resources

Throws:

XMLDBException - if the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED

getService

public Service getService(String name,
                          String version)
                   throws XMLDBException

Returns a Service instance for the requested service name and version. If no Service exists for those parameters a null value is returned. The only valid name and version number for this implementation are "XSLT" and "1.0" respectively.

Specified by:

getService in interface Collection

Parameters:

name - the name of theservice to return.

version - the version number of the service to return.

getServices

public Service[] getServices()
                      throws XMLDBException

Provides a list of all services known to the collection. If no services are known an empty list is returned.

Specified by:

getServices in interface Collection

Returns:

An array of registered Service implementations.

insertDocument

public void insertDocument(String name,
                           String xmlString)
                    throws DocumentAlreadyExistsException,
                           InvalidCollectionDocumentException,
                           NonWellFormedXMLException,
                           XMLDBException

Adds an XML document created from the string argument to the collection.

Specified by:

insertDocument in interface SixdmlCollection

Parameters:

name - the name of the document.

xmlString - the string representation of a well-formed XML document

Throws:

DocumentAlreadyExistsException - if there already exists a document with the specified name in the database.

InvalidCollectionDocumentException - if the document fails to validate against the collection's schema.

NonWellFormedXMLException - if the XML is not well formed.

XMLDBException - if a database error occurs.

insertDocument

public void insertDocument(String name,
                           URL documentSource)
                    throws DocumentAlreadyExistsException,
                           IOException,
                           InvalidCollectionDocumentException,
                           NonWellFormedXMLException,
                           XMLDBException

Adds an XML document loaded from the specified URL to the collection.

Specified by:

insertDocument in interface SixdmlCollection

Parameters:

name - the name of the document.

xmlString - the string representation of a well-formed XML document

Throws:

DocumentAlreadyExistsException - if there already exists a document with the specified name in the database.

IOException - if an error occurs while trying to retrieve the file.

InvalidCollectionDocumentException - if the document fails to validate against the collection's schema.

NonWellFormedXMLException - if the XML is not well formed.

XMLDBException - if a database error occurs.

isOpen

public boolean isOpen()
               throws XMLDBException

Returns true if the Collection is open false otherwise. Calling the close method on Collection will result in isOpen returning false. It is not safe to use Collection instances that have been closed.

Specified by:

isOpen in interface Collection

Returns:

true if the Collection is open, false otherwise.

listChildCollections

public String[] listChildCollections()
                              throws XMLDBException

Returns a list of collection names naming all child collections of the current collection. If no child collections exist an empty list is returned.

Specified by:

listChildCollections in interface Collection

Returns:

an array containing collection names for all child collections.

Throws:

XMLDBException - if the close method has been called on the Collection

listResources

public String[] listResources()
                       throws XMLDBException

Returns a list of resource names naming all the resources in the current collection.

Specified by:

listResources in interface Collection

Returns:

an array containing collection names for all child collections.

Throws:

XMLDBException - if the close method has been called on the Collection

removeDocument

public void removeDocument(String name)
                    throws NonExistentDocumentException,
                           XMLDBException

Removes an XML document from the collection.

Specified by:

removeDocument in interface SixdmlCollection

Parameters:

name - the name of the document.

Throws:

NonExistentDocumentException - if the document does not exist in the collection.

XMLDBException - if a database error occurs.

removeIndex

public void removeIndex(String name)
                 throws NonExistentIndexException,
                        XMLDBException

Removes a particular index from the collection.

Specified by:

removeIndex in interface SixdmlCollection

Parameters:

index - the index to add

Throws:

XMLDBException - if a database error occurs.

removeResource

public void removeResource(Resource res)
                    throws XMLDBException

Removes the Resource from the database.

Specified by:

removeResource in interface Collection

Parameters:

res - the resource to remove.

Throws:

XMLDBException - if the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED, ErrorMessages.NO_SUCH_RESOURCE, ErrorMessages.PERMISSION_DENIED_SCHEMA, ErrorMessages.PERMISSION_DENIED_INDEX

setProperty

public void setProperty(String name,
                        String value)
                 throws XMLDBException

Sets the property name to have the value provided in value.

Specified by:

setProperty in interface Configurable

Parameters:

name - the name of the property to set.

value - the value to set for the property.

setSchema

public void setSchema(URL schemaFile)
               throws InvalidCollectionDocumentException,
                      IOException,
                      InvalidSchemaException,
                      XMLDBException

Sets the XML schema or DTD that will be used to constrain the documents in this collection. For this operation to succeed, all documents in the collection must pass schema validation. If a schema already exists for the collection then it is replaced by the new one if all documents pass validation.

Specified by:

setSchema in interface SixdmlCollection

Parameters:

schemaFile - the location of the schema file either on the local file system or over the internet.

Throws:

InvalidCollectionDocumentException - if an XML document in the collection fails to be validated by the schema.

IOException - if an error occurs while trying to retrieve the file.

InvalidSchemaException - if the schema is invalid.

XMLDBException - if a database error occurs.

showSchema

public String showSchema()
                  throws XMLDBException

Returns the contents of the schema for the collection as a string.

Specified by:

showSchema in interface SixdmlCollection

Returns:

the schema for the collection or null if none exists.

Throws:

XMLDBException - if a database error occurs.

storeResource

public void storeResource(Resource resource)
                   throws XMLDBException

Stores the provided resource into the database. If the resource does not already exist it will be created. If it does already exist it will be updated.

Specified by:

storeResource in interface Collection

Parameters:

res - the resource to store in the database.

Throws:

XMLDBException - if the close method has been called on the Collection or the document does validate against the collection's schema if any.

See Also:

ErrorMessages.COLLECTION_CLOSED, ErrorMessages.WRONG_CONTENT_TYPE_STORE, ErrorMessages.PERMISSION_DENIED_SCHEMA, ErrorMessages.PERMISSION_DENIED_INDEX

unsetSchema

public void unsetSchema()
                 throws XMLDBException

Unsets the schema for this collection. Does nothing if no schema exists for the collection.

Specified by:

unsetSchema in interface SixdmlCollection

Throws:

XMLDBException - if a database error occurs.

validate

private void validate(String xmlStr)
               throws Exception

Helper Method: Validates an XML document against the collection's schema. Does nothing if there is no schema for the collection.

Parameters:

xmlStr - the document to validate as a string.

Throws:

Exception - if anything goes wrong.

initializeParser

private static void initializeParser(org.apache.xerces.parsers.DOMParser parser,
                                     String targetNS,
                                     String schemaLocation)
                              throws SAXNotRecognizedException,
                                     SAXNotSupportedException

Helper Method: Initializes properties related to schema validation in parser.

Parameters:

parser - the DOM parser to initialize

targetNS - the targetNamespace of the schema to use.

schemaLocation - path to the schema. Only used if targetNS isn't null.

createURL

private static URL createURL(String fileName)
                      throws MalformedURLException

Helper method to create a URL from a file name.
NOTE:The code below was obtained from the modifying example programs in the Oracle XDK. I wonder if this is a violation of their EULA's?

Parameters:

fileName - file to convert.

Returns:

the URL version of the filename.

writeToFile

private static File writeToFile(String file,
                                String contents,
                                boolean append)
                         throws IOException

Helper Method: Writes the contents of a string to a file.

Parameters:

file - the file to write to.

contents - the string to write to the file.

append - boolean if true, then data will be written to the end of the file rather than the beginning.

Returns:

the File object that represents the file just modified.

Throws:

IOException - if an error occurs in writing the file.

getContentsOfURL

public static String getContentsOfURL(URL source)
                               throws IOException

Helper Method: Obtains the contents at a particular URL and returns them as a string.

Parameters:

source - the URL to obtaion the data from.

Returns:

the contents at the specified URL.

Throws:

IOException - if an error occurs while trying to retrieve the file.

main

public static void main(String[] args)
                 throws Exception

Main used for testing class.

Parameters:

args - IGNORED