com.qizx.api
Interface Collection

All Superinterfaces:

LibraryMember

public interface Collection

extends LibraryMember

Collections can contain XML Documents and sub-Collections.

They are similar to folders in a disk file-system, and thus can be used to organize documents in hierarchies. It is possible to restrict XQuery queries to the documents contained within a particular Collection or set of Collections.

As a LibraryMember, a Collection can hold Metadata Properties.

A Collection can be used as the root of a XQuery Path Expression, either explicitly through the XQuery function fn:collection or the extension function xlib:collection, or implicitly in an Expression through the method Expression.bindImplicitCollection(LibraryMember).

See Also:

LibraryMember

Field Summary

Fields inherited from interface com.qizx.api.LibraryMember

COLLECTION, DOCUMENT, NATURE, PATH

Method Summary

Collection	createChildCollection(String name) Creates a Collection direct child of this collection.
LibraryMember	getChild(String name) Returns the direct child of this collection (Document or Collection) that bears this name.
LibraryMemberIterator	getChildren() Returns an iterator over members (Documents and Collections) directly contained in this Collection.
LibraryMemberIterator	getChildren(LibraryMemberFilter filter) Returns an iterator over members directly contained in this Collection and accepted by the specified filter.
LibraryMemberIterator	queryProperties(Expression query) Returns an iterator over descendant Documents and Collections whose properties match a boolean XQuery expression.

Methods inherited from interface com.qizx.api.LibraryMember

contains, copyTo, delete, exists, getIntegerProperty, getLibrary, getName, getParent, getParentPath, getPath, getProperty, getPropertyNames, hasProperty, isCollection, isDocument, lock, removeProperty, renameTo, setIntegerProperty, setProperty

Method Detail

getChild

public LibraryMember getChild(String name)
                       throws DataModelException

Returns the direct child of this collection (Document or Collection) that bears this name.

Parameters:

name - a simple name without slash.

Returns:

the handle of the child member, or null if does not exist

Throws:

DataModelException - common causes

getChildren

public LibraryMemberIterator getChildren()
                                  throws DataModelException

Returns an iterator over members (Documents and Collections) directly contained in this Collection.

Returns:

a forward only iterator

Throws:

DataModelException - common causes

getChildren

public LibraryMemberIterator getChildren(LibraryMemberFilter filter)
                                  throws DataModelException

Returns an iterator over members directly contained in this Collection and accepted by the specified filter.

Parameters:

filter - a LibraryMemberFilter implementation that accepts or rejects a member

Returns:

a forward only iterator

Throws:

DataModelException - common causes

queryProperties

public LibraryMemberIterator queryProperties(Expression query)
                                      throws EvaluationException,
                                             DataModelException

Returns an iterator over descendant Documents and Collections whose properties match a boolean XQuery expression.

Example:

    Expression exp = 
      library.compileExpression("type='document'  
                                 and import-date gt xs:date('2006-12-31')
                                 and dm.totalSize > 10000");
    LibraryMemberIterator result = collection.queryProperties(exp);
 

This metadata query would return all documents (property type) whose import-date property is greater than the value given and whose document size (property dm.totalSize) is greater than 10000 (bytes).

Metadata Property Query: the particular form of expression suitable for queryProperties is called a metadata query. It can be any boolean expression that could be used as a predicate in a Path expression (between square brackets).

• The properties (in this example: 'type', 'import-date', 'dm.totalSize') appear as simple names
• The value of properties can be either a typed atomic value (number, date, string) or an XML tree (element and children nodes). In fact everything happens as if each property was an XML element with a typed content which is the property value.
• In the latter case (property with a node value), a more complex path expression like a full-text query can be used for the property, e.g ft:contains('completed', taskinfo/status).

Parameters:

query - a metadata query about the properties of contained Documents or Collections.

Returns:

Library members, descendants of this collection, having properties matching the specified query.

Throws:

EvaluationException - on run-time error in the query expression

DataModelException - common causes

createChildCollection

public Collection createChildCollection(String name)
                                 throws DataModelException

Creates a Collection direct child of this collection. If the child collection already exists, it is simply returned.

Parameters:

name - a simple name without slash.

Returns:

a descriptor of the created Collection

Throws:

DataModelException - common causes