Xindice API
version 1.2m1

org.apache.xindice.core
Class Collection

java.lang.Object
  extended byorg.apache.xindice.core.CollectionManager
      extended byorg.apache.xindice.core.Collection
All Implemented Interfaces:
Configurable, DBObject, Named
Direct Known Subclasses:
Database, MetaSystemCollection, SystemCollection

public class Collection
extends CollectionManager
implements Named, DBObject, Configurable

Collection represents a collection of Documents maintains links to the Filer storage implementation, and the Indexes associated with the Collection.

Version:
$Revision: 594628 $, $Date: 2007-11-13 15:16:05 -0500 (Tue, 13 Nov 2007) $

Constructor Summary
protected Collection()
           
  Collection(Collection parent)
           
 
Method Summary
 boolean close()
          close closes the DBObject
 boolean create()
          create creates a new DBObject and any associated resources for the new DBObject, such as disk files, etc.
 Collection createCollection(String path, Configuration config)
          createCollection creates a new Collection object and any associated system resources that the Collection will need.
 Indexer createIndexer(Configuration config)
          createIndexer creates a new Indexer object and any associated system resources that the Indexer will need.
protected  Key createNewKey(Object key)
          createNewKey allocates a new key to be used as a key in the collection.
 Key createNewOID()
          createNewOID allocates a new Object ID to be used as a Key in the Collection.
 boolean drop()
          drop instructs the DBObjectimplementation to remove itself from existence.
 boolean dropCollection(Collection collection)
          dropCollection physically removes the specified Collection and any associated system resources that the Collection uses.
 boolean dropIndexer(Indexer index)
          dropIndexer physically removes the specified Indexer and any associated system resources that the Indexer uses.
 boolean exists()
          exists returns whether or not a physical representation of this DBObject actually exists.
 byte[] getBinary(Object key)
          Retrieve a binary database entry by key.
 String getCanonicalDocumentName(Key key)
          getCanonicalDocumentName returns the canonical name for the specified Key in relation to this Collection.
 String getCanonicalDocumentName(String key)
          From the document key and this collection canonical name, composes canonical document name.
 String getCanonicalName()
          getCanonicalName returns the canonical name of this Collection.
 MetaData getCollectionMeta()
          Return the MetaData for this collection.
 File getCollectionRoot()
           
 Container getContainer(Object docKey)
          getContainer retrieves a Container from the Collection.
 Database getDatabase()
          getDatabase returns the Database owner for this Collection.
 org.w3c.dom.Document getDocument(Object key)
          getDocument retrieves a Document by Key.
 long getDocumentCount()
          getDocumentCount returns the count of Documents being maintained by this Collection.
 MetaData getDocumentMeta(String id)
          Return the MetaData object for a document within this collection.
 DocumentSet getDocumentSet()
          getDocumentSet returns the set of Documents being maintained by this Collection.
 Entry getEntry(Object id)
          Retrieve a database entry by key.
 Entry getEntryMeta(Object id)
          Retrieve a database entry metadata by key.
 Filer getFiler()
          getFiler returns the low-level Filer instance underlying the Collection instance.
 Indexer getIndexer(String name)
          getIndexer retrieves an Indexer by name.
 IndexManager getIndexManager()
          return the IndexManager being used by this Collection.
 String getName()
          getName retrieves the contextually important name of the object
 XMLSerializable getObject(Object key)
          getObject instantiates and returns an XMLSerializable object based on the provided Key.
 Collection getParentCollection()
          getParentCollection returns the parent Collection of this Collection.
 QueryEngine getQueryEngine()
          getQueryEngine returns the Database's Query Engine
 SymbolTable getSymbols()
          getSymbols returns the SymbolTable in use by this Collection.
 SystemCollection getSystemCollection()
          getSystemCollection returns the System Collection.
 Key insertBinary(byte[] bytes)
          Insert a binary object into a Xindice Collection.
 Key insertBinary(Object docKey, byte[] bytes)
          insertBinary inserts a new binary object into a Xindice Collection.
 Key insertDocument(org.w3c.dom.Document document)
          insertDocument inserts a new Document into a Xindice Collection.
 Key insertDocument(Object docKey, org.w3c.dom.Document document)
          insertDocument inserts a new Document into a Xindice Collection.
 Key insertObject(String objKey, XMLSerializable obj)
          insertObject inserts an XMLSerializable object into the Collection based on the specified Key.
 Key insertObject(XMLSerializable obj)
          insertObject inserts an XMLSerializable object into the Collection and returns a newly generated Key.
 boolean isMetaEnabled()
          Returns whether or not meta data is enabled.
 boolean isOpened()
          isOpened returns whether or not the DBObject is opened for business.
 String[] listDocuments()
          listDocuments returns a list of all entry keys stored by this collection.
 String[] listIndexers()
          listIndexers returns a list of the currently registered Indexers as an array of String.
 boolean open()
          open opens the DBObject
 NodeSet queryCollection(String style, String query, NamespaceMap nsMap)
          queryCollection performs a query against the current collection using the specified style and query String.
 NodeSet queryDocument(String style, String query, NamespaceMap nsMap, Object key)
          queryDocument performs a query against a single Document using the specified style, query string, and Document ID.
 void remove(Object id)
          remove removes an object from the Collection based on its Key, regardless of it's type.
 boolean setBinary(Object docKey, byte[] bytes)
          setBinary inserts or updates binary object into a Xindice Collection.
protected  void setCanonicalName(String canonicalName)
           
 void setCollectionMeta(MetaData meta)
          Reset the metadata object for this collection.
protected  void setCollectionRoot(File collectionRoot)
           
 void setConfig(Configuration config)
          setConfig sets the configuration information for the Configurable object instance.
 boolean setDocument(Object docKey, org.w3c.dom.Document document)
          setDocument inserts or updates an existing Document in a Xindice Collection.
 void setDocumentMeta(String id, MetaData meta)
          Set the metadata associated with a document within this collection.
protected  void setName(String name)
           
 void setObject(Object key, XMLSerializable obj)
          setObject sets an XMLSerializable object in the Collection based on the provided Key.
protected  void updateCollectionMeta()
          update the modified time of this collection when appropriate
protected  void updateDocumentMeta(Record record)
          update the modified time of this document when appropriate
 
Methods inherited from class org.apache.xindice.core.CollectionManager
addCollection, countCollections, getCollection, getCollections, getConfig, listCollections
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.xindice.util.Configurable
getConfig
 

Constructor Detail

Collection

protected Collection()

Collection

public Collection(Collection parent)
Parameters:
parent - parent collection
Method Detail

setName

protected void setName(String name)
Parameters:
name - collection name

setCanonicalName

protected final void setCanonicalName(String canonicalName)

setCollectionRoot

protected final void setCollectionRoot(File collectionRoot)

createNewKey

protected final Key createNewKey(Object key)
createNewKey allocates a new key to be used as a key in the collection. Passed in key parameter string value used for the key. If passed key parameter is null, new OID is generated.

Parameters:
key - The Key hint, can be null
Returns:
The newly generated Key

isOpened

public boolean isOpened()
Description copied from interface: DBObject
isOpened returns whether or not the DBObject is opened for business.

Specified by:
isOpened in interface DBObject
Returns:
The open status of the DBObject

exists

public boolean exists()
               throws DBException
Description copied from interface: DBObject
exists returns whether or not a physical representation of this DBObject actually exists. In the case of a HashFiler, this would check for the file, and in the case of an FTPFiler, it might perform a connection check.

Specified by:
exists in interface DBObject
Returns:
Whether or not the physical resource exists
Throws:
DBException - if operation failed
See Also:
DBObject.exists()

create

public boolean create()
               throws DBException
Description copied from interface: DBObject
create creates a new DBObject and any associated resources for the new DBObject, such as disk files, etc.

Specified by:
create in interface DBObject
Returns:
Whether or not the DBObject was created
Throws:
DBException - if operation failed
See Also:
DBObject.create()

open

public final boolean open()
                   throws DBException
Description copied from interface: DBObject
open opens the DBObject

Specified by:
open in interface DBObject
Returns:
Whether or not the DBObject was opened
Throws:
DBException - if operation failed

drop

public boolean drop()
             throws DBException
Description copied from interface: DBObject
drop instructs the DBObjectimplementation to remove itself from existence. The DBObject's parent is responsible for removing any references to the DBObject in its own context.

Specified by:
drop in interface DBObject
Returns:
Whether or not the DBObject was dropped
Throws:
DBException - if operation failed
See Also:
DBObject.drop()

close

public boolean close()
              throws DBException
Description copied from interface: DBObject
close closes the DBObject

Specified by:
close in interface DBObject
Overrides:
close in class CollectionManager
Throws:
DBException
See Also:
DBObject.close()

setConfig

public void setConfig(Configuration config)
               throws XindiceException
Description copied from interface: Configurable
setConfig sets the configuration information for the Configurable object instance.

Specified by:
setConfig in interface Configurable
Overrides:
setConfig in class CollectionManager
Throws:
XindiceException
See Also:
Configurable.setConfig(org.apache.xindice.util.Configuration)

createCollection

public final Collection createCollection(String path,
                                         Configuration config)
                                  throws DBException
Description copied from class: CollectionManager
createCollection creates a new Collection object and any associated system resources that the Collection will need.

Overrides:
createCollection in class CollectionManager
Parameters:
path - The relative path of the Collection
config - The Collection's configuration
Returns:
The newly created Collection
Throws:
DBException - if operation failed
See Also:
CollectionManager.createCollection(String, Configuration)

dropCollection

public final boolean dropCollection(Collection collection)
                             throws DBException
Description copied from class: CollectionManager
dropCollection physically removes the specified Collection and any associated system resources that the Collection uses.

Overrides:
dropCollection in class CollectionManager
Parameters:
collection - The Collection to drop
Returns:
Whether or not the Collection was dropped
Throws:
DBException - if operation failed
See Also:
CollectionManager.dropCollection(Collection)

getDatabase

public Database getDatabase()
getDatabase returns the Database owner for this Collection.

Returns:
The Database

getParentCollection

public final Collection getParentCollection()
                                     throws DBException
getParentCollection returns the parent Collection of this Collection.

Returns:
The parent Collection (or null)
Throws:
DBException - if operation failed

getSystemCollection

public SystemCollection getSystemCollection()
getSystemCollection returns the System Collection.

Returns:
The System Collection

getName

public final String getName()
Description copied from interface: Named
getName retrieves the contextually important name of the object

Specified by:
getName in interface Named
Returns:
The object's name

getCanonicalName

public final String getCanonicalName()
getCanonicalName returns the canonical name of this Collection.
ex: /local/test/ocs

Returns:
The canonical name of the Collection

getCanonicalDocumentName

public final String getCanonicalDocumentName(Key key)
getCanonicalDocumentName returns the canonical name for the specified Key in relation to this Collection.
ex: /local/test/ocs/ytd

Parameters:
key - The Key
Returns:
The canonical name

getCanonicalDocumentName

public final String getCanonicalDocumentName(String key)
From the document key and this collection canonical name, composes canonical document name.

Parameters:
key - document key
Returns:
The canonical document name

getCollectionRoot

public final File getCollectionRoot()
Returns:
The collection root

getSymbols

public final SymbolTable getSymbols()
getSymbols returns the SymbolTable in use by this Collection.

Returns:
The Symbol Table

getFiler

public final Filer getFiler()
getFiler returns the low-level Filer instance underlying the Collection instance.

Returns:
The requested Filer

getQueryEngine

public QueryEngine getQueryEngine()
                           throws DBException
getQueryEngine returns the Database's Query Engine

Returns:
The Query Engine
Throws:
DBException - if operation failed

getIndexManager

public final IndexManager getIndexManager()
                                   throws DBException
return the IndexManager being used by this Collection.

Returns:
The IndexManager
Throws:
DBException - if operation failed

getIndexer

public final Indexer getIndexer(String name)
                         throws DBException
getIndexer retrieves an Indexer by name.

Parameters:
name - The Indexer name
Returns:
The Indexer (or null)
Throws:
DBException - if operation failed

listIndexers

public final String[] listIndexers()
                            throws DBException
listIndexers returns a list of the currently registered Indexers as an array of String.

Returns:
The Indexer list
Throws:
DBException - if operation failed

createIndexer

public final Indexer createIndexer(Configuration config)
                            throws DBException
createIndexer creates a new Indexer object and any associated system resources that the Indexer will need.

Parameters:
config - The Indexer's configuration
Returns:
The newly created Indexer
Throws:
DBException - if operation failed

dropIndexer

public final boolean dropIndexer(Indexer index)
                          throws DBException
dropIndexer physically removes the specified Indexer and any associated system resources that the Indexer uses.

Parameters:
index - The Indexer to drop
Returns:
Whether or not the Indexer was dropped
Throws:
DBException - if operation failed

createNewOID

public final Key createNewOID()
createNewOID allocates a new Object ID to be used as a Key in the Collection.

Returns:
The newly generated key

getEntry

public final Entry getEntry(Object id)
                     throws DBException
Retrieve a database entry by key. If no matching entry is found, null is returned, otherwise this method returns Entry that identifies resource type and holds its value and metadata.

Parameters:
id - identifying the desired database entry
Returns:
Entry containing the database entry and its metadata, or null if no matching entry is found
Throws:
DBException - in case of backing store error, and in case of header corruption

getDocument

public final org.w3c.dom.Document getDocument(Object key)
                                       throws DBException
getDocument retrieves a Document by Key.

Parameters:
key - The Document Key
Returns:
The Document
Throws:
DBException - if operation failed

getObject

public final XMLSerializable getObject(Object key)
                                throws DBException
getObject instantiates and returns an XMLSerializable object based on the provided Key. Xindice takes care of instantiating the correct class, but only if a class was registered with the Document in the first place.

Parameters:
key - The Document Key
Returns:
an Castable XMLSerializable Instance
Throws:
DBException - if operation failed

getBinary

public final byte[] getBinary(Object key)
                       throws DBException
Retrieve a binary database entry by key. This low-level method will not update non-inline metadata.

Parameters:
key - identifying the desired database entry
Returns:
byte[] containing the binary database entry
Throws:
DBException - if inline-metadata is not enabled (binary resource cannot be stored in a collection which does not have inline-metadata enabled), in case of backing store error, and in case of header corruption

insertDocument

public final Key insertDocument(org.w3c.dom.Document document)
                         throws DBException
insertDocument inserts a new Document into a Xindice Collection.

Parameters:
document - The Document
Returns:
The new Object Identifier
Throws:
DBException - if operation failed

insertDocument

public final Key insertDocument(Object docKey,
                                org.w3c.dom.Document document)
                         throws DBException
insertDocument inserts a new Document into a Xindice Collection.

Parameters:
docKey - The document Key
document - The document to insert
Returns:
key for inserted document
Throws:
DBException - if operation failed

insertObject

public final Key insertObject(XMLSerializable obj)
                       throws DBException
insertObject inserts an XMLSerializable object into the Collection and returns a newly generated Key. Xindice takes care of associating the implementation class with the XMLSerializable object.

Parameters:
obj - The Object to insert
Returns:
The newly generated Key
Throws:
DBException - if operation failed

insertObject

public final Key insertObject(String objKey,
                              XMLSerializable obj)
                       throws DBException
insertObject inserts an XMLSerializable object into the Collection based on the specified Key. Xindice takes care of associating the implementation class with the XMLSerializable object.

Parameters:
objKey - The Key to use
obj - The Object to insert
Returns:
key for the inserted object
Throws:
DBException - if operation failed

insertBinary

public Key insertBinary(byte[] bytes)
                 throws DBException
Insert a binary object into a Xindice Collection. A unique key is automatically generated. by which the binary object can be retrieved in the future. Note: because the key is automatically unique, this insert method will never cause a collision with an object already in the database.

Parameters:
bytes - The bytes making up the binary object to insert
Returns:
Key automatically generated for the binary object
Throws:
DBException - if inline-metadata is not enabled, or an error occurs while saving.

insertBinary

public Key insertBinary(Object docKey,
                        byte[] bytes)
                 throws DBException
insertBinary inserts a new binary object into a Xindice Collection.

Parameters:
docKey - The document Key
bytes - The document to insert
Returns:
key for the inserted binary
Throws:
DBException - if inline-metadata is not enabled, the key is already in the database, or an error occurs while saving.

setDocument

public final boolean setDocument(Object docKey,
                                 org.w3c.dom.Document document)
                          throws DBException
setDocument inserts or updates an existing Document in a Xindice Collection.

Parameters:
docKey - The Document Key
document - The Document
Returns:
True if new document entry was created, false otherwise
Throws:
DBException - if operation failed

setObject

public final void setObject(Object key,
                            XMLSerializable obj)
                     throws DBException
setObject sets an XMLSerializable object in the Collection based on the provided Key. Xindice takes care of associating the implementation class with the XMLSerializable object.

Parameters:
key - The Key to use
obj - The Object to set
Throws:
DBException - if operation failed

setBinary

public boolean setBinary(Object docKey,
                         byte[] bytes)
                  throws DBException
setBinary inserts or updates binary object into a Xindice Collection.

Parameters:
docKey - The document Key
bytes - The document to insert
Returns:
true if new binary was created, false otherwise
Throws:
DBException - if inline-metadata is not enabled, the key is already in the database, or an error occurs while saving.

remove

public final void remove(Object id)
                  throws DBException
remove removes an object from the Collection based on its Key, regardless of it's type.

Parameters:
id - The Object's Key
Throws:
DBException - if operation failed

isMetaEnabled

public boolean isMetaEnabled()
Returns whether or not meta data is enabled.

Returns:
boolean whether or not meta data is enabled.

getCollectionMeta

public MetaData getCollectionMeta()
                           throws DBException
Return the MetaData for this collection. If metadata is not enabled in the configuration, the MetaData object returned will be null.

Returns:
MetaData this collection's metadata.
Throws:
DBException - if operation failed

setCollectionMeta

public void setCollectionMeta(MetaData meta)
                       throws DBException
Reset the metadata object for this collection.

Parameters:
meta - the Metadata to use
Throws:
DBException - if operation failed

getEntryMeta

public final Entry getEntryMeta(Object id)
                         throws DBException
Retrieve a database entry metadata by key. If no matching entry is found, null is returned, otherwise this method return Entry that holds metadata only.

Parameters:
id - identifying the desired database entry
Returns:
Entry containing the metadata of the database entry, or null if no matching entry is found
Throws:
DBException - in case of backing store error, and in case of header corruption

getDocumentMeta

public MetaData getDocumentMeta(String id)
                         throws DBException
Return the MetaData object for a document within this collection. If metadata is not enabled, the MetaData object returned will be null.

Parameters:
id - the document whose metadata you want
Returns:
meta data for requested resource
Throws:
DBException - if operation failed

setDocumentMeta

public void setDocumentMeta(String id,
                            MetaData meta)
                     throws DBException
Set the metadata associated with a document within this collection.

Parameters:
id - the document name
meta - the metadata object to be used.
Throws:
DBException - if operation failed

updateCollectionMeta

protected void updateCollectionMeta()
update the modified time of this collection when appropriate


updateDocumentMeta

protected void updateDocumentMeta(Record record)
                           throws DBException
update the modified time of this document when appropriate

Parameters:
record - database record for which metadata should be updated
Throws:
DBException - if operation failed

getContainer

public final Container getContainer(Object docKey)
                             throws DBException
getContainer retrieves a Container from the Collection. The Container encapsulates all information needed in dealing with a Document outside of the context of a Collection (ex: DocumentContext).

Parameters:
docKey - The Document Key
Returns:
The Container
Throws:
DBException - if operation failed

getDocumentCount

public final long getDocumentCount()
                            throws DBException
getDocumentCount returns the count of Documents being maintained by this Collection.

Returns:
The Document count
Throws:
DBException - if operation failed

getDocumentSet

public final DocumentSet getDocumentSet()
                                 throws DBException
getDocumentSet returns the set of Documents being maintained by this Collection.

Returns:
The DocumentSet
Throws:
DBException - if operation failed

listDocuments

public final String[] listDocuments()
                             throws DBException
listDocuments returns a list of all entry keys stored by this collection.

Returns:
the list of entry keys
Throws:
DBException - if operation failed

queryCollection

public final NodeSet queryCollection(String style,
                                     String query,
                                     NamespaceMap nsMap)
                              throws DBException
queryCollection performs a query against the current collection using the specified style and query String.

Parameters:
style - The query style to use (ex: XPath)
query - The query to execute
nsMap - The namespace Map (if any)
Returns:
The resulting NodeSet
Throws:
DBException - if operation failed

queryDocument

public final NodeSet queryDocument(String style,
                                   String query,
                                   NamespaceMap nsMap,
                                   Object key)
                            throws DBException
queryDocument performs a query against a single Document using the specified style, query string, and Document ID.

Parameters:
style - The query style to use (ex: XPath)
query - The query to execute
nsMap - The namespace Map (if any)
key - The Document to query
Returns:
The resulting NodeSet
Throws:
DBException - if operation failed

Xindice API
version 1.2m1

Copyright (c) 1999-2007 The Apache Software Foundation. All Rights Reserved.