uk.org.ogsadai.dataresource
Interface XMLDBCollectionProvider

All Known Implementing Classes:

XMLDBDataResourceAccessor

public interface XMLDBCollectionProvider

Interface providing access to collections in XMLDB data resources.

Author:

The OGSA-DAI Project Team

Method Summary

java.lang.String	getBaseCollectionURI() Return the URI of the base collection.
org.xmldb.api.base.Collection	getXMLDBCollection(java.lang.String userCredentials) Returns an open collection for the base collection of a data resource.
org.xmldb.api.base.Collection	getXMLDBCollection(java.lang.String subCollection, java.lang.String userCredentials) Returns an open collection for the specified sub-collection of a data resource.
void	releaseXMLDBCollection(org.xmldb.api.base.Collection collection) Releases a previously obtained XMLB collection.

Method Detail

getBaseCollectionURI

public java.lang.String getBaseCollectionURI()

Return the URI of the base collection.

Returns:

collection URI.

getXMLDBCollection

public org.xmldb.api.base.Collection getXMLDBCollection(java.lang.String userCredentials)
                                                 throws DataResourceAuthorizationException,
                                                        XMLDBCollectionUseException,
                                                        AuthorizationExecutionException

Returns an open collection for the base collection of a data resource.

The specified user credential may be used to authorize access to the data resource.

Parameters:

userCredentials - Credentials specifing a user.

Returns:

an open collection for the base collection.

Throws:

DataResourceAuthorizationException - if the user is not authorized to access the collection.

XMLDBCollectionUseException - if there is a problem in using the data resource.

AuthorizationExecutionException - if there is a problem encountered during the authorization.

getXMLDBCollection

public org.xmldb.api.base.Collection getXMLDBCollection(java.lang.String subCollection,
                                                        java.lang.String userCredentials)
                                                 throws DataResourceAuthorizationException,
                                                        XMLDBUnknownSubCollectionException,
                                                        XMLDBCollectionUseException,
                                                        AuthorizationExecutionException

Returns an open collection for the specified sub-collection of a data resource.

The specified user credential may be used to authorize access to the data resource.

Parameters:

subCollection - The path to the sub-collection relative to the data resource's base collection. This should not begin with a "/". The "/" is added automatically to the base collection URI when the full collection URI is composed. For example, if the base collection is db and the sub-collection is test/addresses then an open collection for /db/test/addresses will be returned. If this is null then the base collection is returned.

userCredentials - Credentials specifing a user.

Returns:

an open collection for the sub-collection.

Throws:

DataResourceAuthorizationException - if the user is not authorized to access the collection or sub-collection.

XMLDBUnknownSubCollectionException - if the sub-collection is unknown.

XMLDBCollectionUseException - if there is a problem in using the data resource.

AuthorizationExecutionException - if there is a problem encountered during the authorization.

releaseXMLDBCollection

public void releaseXMLDBCollection(org.xmldb.api.base.Collection collection)
                            throws XMLDBCollectionUseException

Releases a previously obtained XMLB collection.

Once a collection is finished with it should be passed back to this method. This allows collection pooling to be performed under the surface.

Parameters:

collection - XMLDB collection to release. If the collection is null or already released then nothing is done.

Throws:

XMLDBCollectionUseException - if there is a problem in closing the collection.