org.sixdml.excelon
Class xlnSixdmlCollection

java.lang.Object
  |
  +--org.sixdml.excelon.xlnSixdmlCollection

All Implemented Interfaces:

Collection, Configurable, SixdmlCollection, SixdmlConstants

class xlnSixdmlCollection

extends Object

implements SixdmlCollection, SixdmlConstants

  
 xlnSixdmlCollection.java

 An implementation of the SixdmlCollection interface which maps to a directory in 
 the eXcelon's Dynamic XML Server (DXE). This class is NOT thread safe. 
 
 Created: Fri Jan 11 21:56:01 2002

 

Version:

1.0

Author:

Dare Obasanjo

Field Summary

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.
private com.exln.dxe.Session	session A session provides the context in which an application can access XMLStores.
private com.exln.dxe.filesystem.Directory	xlnDir The underlying DXE directory that this class uses to interact with the database.

Fields inherited from interface org.sixdml.SixdmlConstants

SIXDML_NS, SIXDML_VERSION

Constructor Summary

private	xlnSixdmlCollection() Default constructor private because an instance of this class must always be instantiated with an underlying DXE Directory object.
(package private)	xlnSixdmlCollection(com.exln.dxe.filesystem.Directory dir, com.exln.dxe.Session session) Initializes this Collection by mapping it to a DXE directory.

Method Summary

void	addIndex(org.sixdml.dbmanagement.SixdmlIndex index) Adds an index to apply to the collection.
void	close() Releases all resources consumed by the Collection.
(package private) org.sixdml.excelon.xlnSixdmlCollection	createDescendantCollection(String name) Used to create a descendant collection of this 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.
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) Obtains the contents at a particular URL and returns them as a string.
org.sixdml.dbmanagement.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 name) 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.
(package private) com.exln.dxe.XMLStore	getXMLStore() Returns the eXcelon DXE XMLStore this collection's underlying Directory object belongs to.
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 res) 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, 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.

xlnDir

private com.exln.dxe.filesystem.Directory xlnDir

The underlying DXE directory that this class uses to interact with the database.

session

private com.exln.dxe.Session session

A session provides the context in which an application can access XMLStores. An application needs a session to do anything with DXE

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.

Constructor Detail

xlnSixdmlCollection

private xlnSixdmlCollection()

Default constructor private because an instance of this class must always be instantiated with an underlying DXE Directory object.

xlnSixdmlCollection

xlnSixdmlCollection(com.exln.dxe.filesystem.Directory dir,
                    com.exln.dxe.Session session)

Initializes this Collection by mapping it to a DXE directory.

Parameters:

dir - the Directory that will be this object's interface to the database.

session - the DXE session associated with the underlying directory.

Method Detail

getXMLStore

com.exln.dxe.XMLStore getXMLStore()

Returns the eXcelon DXE XMLStore this collection's underlying Directory object belongs to.

Returns:

an eXcelon DXE XMLStore.

createDescendantCollection

org.sixdml.excelon.xlnSixdmlCollection createDescendantCollection(String name)
                                                            throws XMLDBException

Used to create a descendant collection of this collection.

Parameters:

name - the name or path of the new collection.

Returns:

the new collection.

Throws:

XMLDBException - if the collection already exists or if one of the collections in the path given does not exist.

See Also:

ErrorCodes.NO_SUCH_COLLECTION, ErrorMessages.DUPLICATE_COLLECTION

addIndex

public void addIndex(org.sixdml.dbmanagement.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 the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED

removeIndex

public void removeIndex(String name)
                 throws NonExistentIndexException,
                        XMLDBException

Removes a particular index from the collection.

Specified by:

removeIndex in interface SixdmlCollection

Throws:

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

NonExistentIndexException

See Also:

ErrorMessages.COLLECTION_CLOSED

getIndices

public org.sixdml.dbmanagement.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 the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED

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.

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.

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 the close method has been called on the Collection

See Also:

ErrorMessages.COLLECTION_CLOSED, ErrorMessages.PERMISSION_DENIED_SCHEMA, ErrorMessages.PERMISSION_DENIED_INDEX

insertDocument

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

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.

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.

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

NonWellFormedXMLException - if the XML is not well formed.

See Also:

ErrorMessages.COLLECTION_CLOSED, ErrorMessages.PERMISSION_DENIED_SCHEMA, ErrorMessages.PERMISSION_DENIED_INDEX

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 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.PERMISSION_DENIED_SCHEMA, ErrorMessages.PERMISSION_DENIED_INDEX

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 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

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 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

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 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

storeResource

public void storeResource(Resource res)
                   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

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

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

See Also:

ErrorMessages.COLLECTION_CLOSED

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

See Also:

ErrorMessages.COLLECTION_CLOSED

getService

public Service getService(String name,
                          String version)

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()

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.

getName

public String getName()

Returns the name associated with the Collection instance.

Specified by:

getName in interface Collection

Returns:

the name of the object.

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

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

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

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

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

createId

public String createId()

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

Specified by:

createId in interface Collection

Returns:

the created id as a string.

getProperty

public String getProperty(String name)

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.

setProperty

public void setProperty(String name,
                        String value)

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.

isOpen

public boolean isOpen()

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.

close

public void close()

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

getContentsOfURL

public static String getContentsOfURL(URL source)
                               throws IOException

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)

Main used for testing class.

Parameters:

args - IGNORED