Qizx fe-4.4p2 API

com.qizx.api
Interface Library

All Superinterfaces:
ItemFactory, XQuerySession

public interface Library
extends XQuerySession

Work session on a XML Library.

A Library is both:

This class is not thread-safe. As a connection, it is supposed to be used by only one thread at a time.

Common Exception causes: the Library is closed (LibraryException); Access is denied (AccessControlException); a library member does not exist (LibraryException with code LibraryException.MEMBER_NOT_FOUND).


Field Summary
 
Fields inherited from interface com.qizx.api.XQuerySession
ALLOWED_JAVA_CLASSES
 
Method Summary
 void backup(File backupDir)
          Makes a snapshot copy of the Library to a directory.
 XMLPushStream beginImportDocument(String documentPath)
          Document import primitive: returns a push-style interface allowing storing a document from a source other than a parser.
 void cancelImportDocument()
          Cancels a document import initiated by beginImportDocument.
 void close()
          Terminates a session.
 void commit()
          Commits the current transaction.
 Expression compileExpression(String xquery)
          Creates an executable Expression by compiling a XQuery script.
 LibraryMember copyMember(String srcPath, String dstPath)
          Copies the specified member of the Library (Document or Collection).
 Collection createCollection(String absolutePath)
          Creates a new Collection.
 boolean deleteMember(String path)
          Deletes the specified member of the Library.
 Document endImportDocument()
          Document import primitive: finishes a document import started with beginImportDocument() and returns a Document descriptor.
 AccessControl getAccessControl()
          Returns the Access Control associated with this Library.
 Collection getCollection(String absolutePath)
          Gets a Collection by its path inside the Library.
 XQueryContext getContext()
          Access to the default XQuery Context.
 Document getDocument(String absolutePath)
          Gets a Document by its path inside the Library.
 Indexing getIndexing()
          Gets the current indexing rules.
 LibraryMember getMember(String absolutePath)
          Returns the specified member (Document or Collection) or null if such member does not exist.
 String getName()
          Returns the name of the library.
 NonXMLDocument getNonXMLDocument(String absolutePath)
          Gets a non-XML Document by its path inside the Library.
 LibraryProgressObserver getProgressObserver()
          Returns the observer used for monitoring import, commit or backup.
 Collection getRootCollection()
          Returns the root collection of the Library.
 User getUser()
          Returns the user associated with this Library session.
 Document importDocument(String documentPath, ContentImporter importer)
          Imports a Document into the Library by using an implementation of ImportMethod.
 Document importDocument(String documentPath, File file)
          Imports a Document into the Library by parsing XML text from a File.
 Document importDocument(String documentPath, InputSource source)
          Imports a Document into the Library by parsing a SAX InputSource.
 Document importDocument(String documentPath, InputSource source, XMLReader xmlReader)
          Imports a Document into the Library by parsing a SAX InputSource, using a custom XML parser.
 Document importDocument(String documentPath, String data)
          Imports a Document into the Library by parsing a string representing a XML fragment.
 Document importDocument(String documentPath, URL url)
          Imports a Document into the Library by parsing XML text from an URL.
 NonXMLDocument importNonXMLDocument(String path, boolean compress, InputStream source)
          Imports a non-XML document into the Library by reading from an InputStream.
 void incrementalBackup(File backupDir)
          Makes a snapshot copy of the Library to a directory, transferring only the modified portions of the Library.
 boolean isAutoCommitting()
          Returns the auto-commit flag: if set to true, a commit is performed after the execution of each updating Expression (expression using XQuery Update instructions).
 boolean isClosed()
          Returns true if the session is closed.
 boolean isModified()
          Returns true if a transaction is in progress and library members have been created, modified or deleted.
 boolean isReadOnly()
          Returns true if the Library is in read-only mode.
 boolean lock(String[] memberPaths, int timeOutMillis)
          Locks one or several Collections or Documents to initiate a safe concurrent update.
 Collection lockCollection(String path, int timeOutMillis)
          Locks a Collection to initiate a safe concurrent update.
 Document lockDocument(String path, int timeOutMillis)
          Locks a Document to initiate a safe concurrent update.
 void optimize()
          Optimizes the underlying Library storage, in particular the indexes.
 void quickOptimize(int timeHint, boolean blocking)
          Performs an optimization of the underlying Library storage in limited time.
 void refresh()
          Refreshes the view of the Library.
 void reIndex()
          Completely rebuilds the indexes.
 LibraryMember renameMember(String srcPath, String dstPath)
          Renames the specified member of the Library (Document or Collection).
 void rollback()
          Cancels the current transaction.
 void setAutoCommitting(boolean autoCommitting)
          Sets the auto-commit flag: if set to true, a commit is performed after the execution of each updating Expression (expression using XQuery Update instructions).
 void setIndexing(Indexing specification)
          Defines the indexing rules used in this Library.
 void setProgressObserver(LibraryProgressObserver listener)
          Sets a listener used to monitor the progress of different operations on the Library.
 
Methods inherited from interface com.qizx.api.XQuerySession
enableJavaBinding, getFullTextFactory, getIdentifier, getModuleResolver, getWordSieve, listExpressions, setFullTextFactory, setModuleResolver, setWordSieve
 
Methods inherited from interface com.qizx.api.ItemFactory
copySequence, createItem, createItem, createItem, createItem, createItem, createItem, createItem, createSequence, getNodeType, getQName, getQName, getQName, getType
 

Method Detail

getName

String getName()
Returns the name of the library. This is a simple name relative to the Library Group, not a directory path.

Returns:
the name of the library

getUser

User getUser()
Returns the user associated with this Library session.

Returns:
the User specified when opening the session. If Access Control is not enabled, this value can be null.

getAccessControl

AccessControl getAccessControl()
Returns the Access Control associated with this Library.

Returns:
an instance of the AccessControl associated with the XML Library. If Access Control is not enabled, this value can be null.
Since:
3.2

getContext

XQueryContext getContext()
Access to the default XQuery Context. This context is inherited by expressions compiled from this session.

Specified by:
getContext in interface XQuerySession
Returns:
the XQuery context used as a basis for compiled expressions.

getRootCollection

Collection getRootCollection()
                             throws DataModelException
Returns the root collection of the Library. The root collection (whose path is "/") is created initially and cannot be deleted.

This is a convenience method, equivalent to getCollection("/").

Returns:
the handle of the root Collection
Throws:
DataModelException - common causes

getCollection

Collection getCollection(String absolutePath)
                         throws DataModelException
Gets a Collection by its path inside the Library.

Parameters:
absolutePath - path of the collection inside the Library.
Returns:
the collection, or null if no such collection exists.
Throws:
DataModelException - common causes

getMember

LibraryMember getMember(String absolutePath)
                        throws DataModelException
Returns the specified member (Document or Collection) or null if such member does not exist.

Parameters:
absolutePath - path of the member inside the Library.
Returns:
the library member, or null if no such member exists.
Throws:
DataModelException - common causes

getDocument

Document getDocument(String absolutePath)
                     throws DataModelException
Gets a Document by its path inside the Library.

Parameters:
absolutePath - path of the document inside the Library.
Returns:
the document, or null if no such document exists.
Throws:
DataModelException - common causes

getNonXMLDocument

NonXMLDocument getNonXMLDocument(String absolutePath)
                                 throws DataModelException
Gets a non-XML Document by its path inside the Library.

Parameters:
absolutePath - path of the document inside the Library.
Returns:
the document, or null if no such document exists.
Throws:
DataModelException - common causes

compileExpression

Expression compileExpression(String xquery)
                             throws CompilationException
Creates an executable Expression by compiling a XQuery script.

Specified by:
compileExpression in interface XQuerySession
Parameters:
xquery - a string containing a XQuery script.
Returns:
an executable Expression that can be used for several executions. Before an execution, the expression can be prepared by binding values with variables
Throws:
CompilationException - thrown after compilation if parsing or static analysis errors are detected. A CompilationException bears a list of Messages.

createCollection

Collection createCollection(String absolutePath)
                            throws DataModelException
Creates a new Collection. Also creates the parent collections if needed.

Parameters:
absolutePath - the path of the collection, starting from the root collection of the Library.
Returns:
a descriptor of the collection.
Throws:
DataModelException - common causes

importDocument

Document importDocument(String documentPath,
                        InputSource source)
                        throws DataModelException
Imports a Document into the Library by parsing a SAX InputSource.

This method simply calls importDocument(String, InputSource, XMLReader), passing a default parser (namespace aware).

Parameters:
documentPath - path in the Library assigned to the document.
source - a SAX InputSource
Returns:
a handle to the newly created document. This object can be used to set user-defined properties
Throws:
DataModelException - XML parsing error (wraps a SAX exception); common causes

importDocument

Document importDocument(String documentPath,
                        InputSource source,
                        XMLReader xmlReader)
                        throws DataModelException
Imports a Document into the Library by parsing a SAX InputSource, using a custom XML parser.

Parameters:
documentPath - path in the Library assigned to the document.
source - a SAX InputSource
xmlReader - a SAX XMLReader (parser) that can be setup before use.
Returns:
a handle to the newly created document. This object can be used to set user-defined properties
Throws:
DataModelException - XML parsing error (wraps a SAX exception); common causes

importDocument

Document importDocument(String documentPath,
                        ContentImporter importer)
                        throws DataModelException
Imports a Document into the Library by using an implementation of ImportMethod. The interface ImportMethod defines conversion filters from any structured or semi-structured

Parameters:
documentPath - path in the Library assigned to the document.
importer -
Returns:
a handle to the newly created document. This object can be used to set user-defined properties
Throws:
DataModelException - XML parsing error (wraps a SAX exception); common causes

importDocument

Document importDocument(String documentPath,
                        URL url)
                        throws DataModelException
Imports a Document into the Library by parsing XML text from an URL.

Parameters:
documentPath - path in the Library assigned to the document.
url - location of the document to import, must be a valid URL supported by the run-time environment. In particular, special characters should be correctly escaped, even if the URL actually points to a file.
Returns:
a handle to the newly created document. This object can be used to set user-defined properties
Throws:
DataModelException - XML parsing error (wraps a SAX exception); common causes

importDocument

Document importDocument(String documentPath,
                        File file)
                        throws DataModelException
Imports a Document into the Library by parsing XML text from a File.

Parameters:
documentPath - path in the Library assigned to the document.
file - location of the document to import, must contain a well-formed XML document.
Returns:
a handle to the newly created document. This object can be used to set user-defined properties
Throws:
DataModelException - XML parsing error (wraps a SAX exception); common causes

importDocument

Document importDocument(String documentPath,
                        String data)
                        throws DataModelException
Imports a Document into the Library by parsing a string representing a XML fragment.

Parameters:
documentPath - path in the Library assigned to the document.
data - XML fragment as a String. It must represent a well-formed XML document.
Returns:
a handle to the newly created document. This object can be used to set user-defined properties
Throws:
DataModelException - XML parsing error (wraps a SAX exception); common causes

beginImportDocument

XMLPushStream beginImportDocument(String documentPath)
                                  throws DataModelException
Document import primitive: returns a push-style interface allowing storing a document from a source other than a parser.

This source can be for example a SAX2 event generator (through adapter SAXToPushStream), a DOM document (through adapter DOMToPushStream), a XSLT engine (through a PushStreamResult).

Parameters:
documentPath - path in the Library assigned to the document.
Returns:
a push stream used to create the document content
Throws:
DataModelException - common causes
See Also:
endImportDocument(), cancelImportDocument()

endImportDocument

Document endImportDocument()
                           throws DataModelException
Document import primitive: finishes a document import started with beginImportDocument() and returns a Document descriptor. The document descriptor can be used to get or set properties.

Returns:
a handle to the newly created document. This object can be used to set user-defined properties
Throws:
DataModelException - common causes
See Also:
beginImportDocument, cancelImportDocument()

cancelImportDocument

void cancelImportDocument()
                          throws DataModelException
Cancels a document import initiated by beginImportDocument.

Can be used if for some reason a document has to be cancelled. This method is called automatically when a beginImportDocument is not followed by endImportDocument.

Throws:
DataModelException - common causes

importNonXMLDocument

NonXMLDocument importNonXMLDocument(String path,
                                    boolean compress,
                                    InputStream source)
                                    throws DataModelException
Imports a non-XML document into the Library by reading from an InputStream.

Parameters:
path - path in the Library assigned to the Blob.
compress - if true, compress contents. This is recommended for text-like data and not recommended for already compressed data such as images.
source - a binary InputStream that is read to get the data.
Returns:
a handle to the newly created lobdocument. This object can be used to set user-defined properties, in particular the mime-type.
Throws:
DataModelException - common causes

renameMember

LibraryMember renameMember(String srcPath,
                           String dstPath)
                           throws DataModelException
Renames the specified member of the Library (Document or Collection).

Parameters:
srcPath - path of the source member
dstPath - destination path. This path should not point to an existing member, but its parent collection should exist
Returns:
a handle to the renamed member
Throws:
DataModelException - if the source member does not exist; if the destination member does exist; if its parent is not an existing collection; common causes

copyMember

LibraryMember copyMember(String srcPath,
                         String dstPath)
                         throws DataModelException
Copies the specified member of the Library (Document or Collection).

If the specified member is a Collection, all its contained members - sub-collections and documents - are recursively copied.

Parameters:
srcPath - path of the source member
dstPath - destination path for the copy. This path should not point to an existing member, but its parent collection should exist
Returns:
a handle to the copied member
Throws:
DataModelException - if the source member does not exist; if the destination member does exist; if its parent is not an existing collection; common causes

deleteMember

boolean deleteMember(String path)
                     throws DataModelException
Deletes the specified member of the Library.

If the specified member is a Collection, all its contained members - sub-collections and documents - are recursively deleted.

Parameters:
path - of a library member
Returns:
true if specified member has been deleted; false otherwise (because such member does not exist)
Throws:
DataModelException - common causes

refresh

void refresh()
             throws LibraryException
Refreshes the view of the Library.

The view of the Library is stable as long as this method is not called (or lock, commit, rollback), i.e. changes performed by other sessions are not visible.

Conversely, after calling this method, deletions performed by other transactions become visible, so the programmer should re-acquire or check every library member used again (for example by using getDocument or getCollection), otherwise exceptions could be thrown when using a deleted object.

This method may not be called if a transaction has begun. In that case only commit() or rollback() may be used.

Throws:
DataModelException - common causes
LibraryException

lock

boolean lock(String[] memberPaths,
             int timeOutMillis)
             throws DataModelException
Locks one or several Collections or Documents to initiate a safe concurrent update.

Parameters:
memberPaths - a list of Documents or Collections. When a member is locked, another transaction cannot lock an enclosing (or ancestor) collection.

When a Collection is specified, then all enclosed documents and collections are also locked implicitly.

timeOutMillis - if strictly positive, specifies a time in milliseconds to wait for when one of the Library members is already locked. If this time is elapsed and one member is still locked, the function returns false and no lock is set.

If equal to 0, the method will not wait. This can be used as a "trylock" function.

If negative, wait indefinitely (this is not recommended).

Returns:
true if all members have been locked within the time imparted.
Throws:
DataModelException - common causes

lockCollection

Collection lockCollection(String path,
                          int timeOutMillis)
                          throws DataModelException
Locks a Collection to initiate a safe concurrent update. All the contents of the collection (documents and sub-collections) are locked at the same time.

Parameters:
path - path of the Collection.
timeOutMillis - if strictly positive, specifies a time in milliseconds to wait for when the collection or one of its descendants or ancestors is already locked. If this time is elapsed and one member is still locked, the function returns false and no lock is set.

If equal to 0, the method will not wait. This can be used as a "trylock" function.

If negative, wait indefinitely (this is not recommended).

Returns:
The collection if the lock is successful, i.e the collection exists and could be locked within the time imparted. Otherwise null is returned.
Throws:
DataModelException - common causes
See Also:
#lockDocument

lockDocument

Document lockDocument(String path,
                      int timeOutMillis)
                      throws DataModelException
Locks a Document to initiate a safe concurrent update.

Parameters:
path - path of the document.
timeOutMillis - if strictly positive, specifies a time in milliseconds to wait for when the collection or one of its descendants or ancestors is already locked. If this time is elapsed and one member is still locked, the function returns false and no lock is set.

If equal to 0, the method will not wait. This can be used as a "trylock" function.

If negative, wait indefinitely (this is not recommended).

Returns:
The document if the lock is successful, i.e the document exists and could be locked within the time imparted. Otherwise null is returned.
Throws:
DataModelException - common causes
See Also:
#lockDocument

commit

void commit()
            throws LibraryException
Commits the current transaction. If this method completes without error, updates performed in the transaction are guaranteed persistent, and become visible to other sessions (provided they do a refresh, lock, commit, or rollback).

Unlocks all Library members previously locked.

After completion, the state of the Library also reflects changes possibly performed by other transactions (i.e is "refreshed").

The progress of the

Throws:
LibraryException - common causes

isReadOnly

boolean isReadOnly()
Returns true if the Library is in read-only mode. This mode is set when the Library is actually opened by the related LibraryManager.

Attempts to modify the contents of a read-only Library raise AccessControlException.

Since:
3.1

isAutoCommitting

boolean isAutoCommitting()
Returns the auto-commit flag: if set to true, a commit is performed after the execution of each updating Expression (expression using XQuery Update instructions).

Returns:
true if a commit is performed after the execution of each updating Expression.

setAutoCommitting

void setAutoCommitting(boolean autoCommitting)
Sets the auto-commit flag: if set to true, a commit is performed after the execution of each updating Expression (expression using XQuery Update instructions).

Parameters:
autoCommitting - a boolean indicating whether a commit is performed after the execution of each updating Expression.

rollback

void rollback()
              throws LibraryException
Cancels the current transaction.

Unlocks all Library members previously locked.

After completion, the state of the Library is also "refreshed", i.e. reflects possible changes possibly performed by other transactions.

Throws:
DataModelException - common causes
LibraryException

isModified

boolean isModified()
Returns true if a transaction is in progress and library members have been created, modified or deleted.

Returns:
true if any modification is in progress for this session

close

void close()
           throws LibraryException
Terminates a session. No operation can be performed anymore once a session is closed.

This method may not be called if a transaction has begun. In that case only commit() or rollback() may be used.

Throws:
DataModelException - common causes
LibraryException

isClosed

boolean isClosed()
Returns true if the session is closed. No operation can be performed anymore once a session is closed.

Returns:
true if the session is closed

setIndexing

void setIndexing(Indexing specification)
                 throws DataModelException
Defines the indexing rules used in this Library.

Normally followed by a reindexing operation: see reIndex().

If Access Control is enforced, this operation requires the permission to modify the properties of the root collection.

Notice that the new configuration is immediately visible by all sessions opened on the Library, through the method getIndexing(): there is no isolation.

Parameters:
specification - a parsed Indexing specification
Throws:
DataModelException - common causes

getIndexing

Indexing getIndexing()
                     throws DataModelException
Gets the current indexing rules.

Returns:
the indexing specification used for document contents by this Library.
Throws:
DataModelException - common causes

reIndex

void reIndex()
             throws DataModelException
Completely rebuilds the indexes.

This is a synchronous (blocking) and potentially lengthy operation. The progress of the operation can be observed using a LibraryProgressObserver.
Note: this method was initially asynchronous (v2.0).

If Access Control is enforced, this operation requires the permission to modify the properties of the root collection.

Throws:
DataModelException - common causes
See Also:
setProgressObserver(com.qizx.api.LibraryProgressObserver)

optimize

void optimize()
              throws DataModelException
Optimizes the underlying Library storage, in particular the indexes. Nothing is done is the Library is already optimized.

This is a synchronous (blocking) and potentially lengthy operation. The progress of the operation can be observed using a LibraryProgressObserver.
Note: this operation was initially asynchronous (v2.0).

If Access Control is enforced, this operation requires the permission to modify the properties of the root collection.

Throws:
DataModelException - common causes
See Also:
setProgressObserver(com.qizx.api.LibraryProgressObserver)

quickOptimize

void quickOptimize(int timeHint,
                   boolean blocking)
                   throws DataModelException
Performs an optimization of the underlying Library storage in limited time. Nothing is done if the Library is already optimized.

This is a synchronous (blocking) operation. The progress of the operation can be observed using a LibraryProgressObserver.
If Access Control is enforced, this operation requires the permission to modify the properties of the root collection.

Parameters:
timeHint - a time in seconds granted for the operation. This is only a hint, actual time can be shorter or slightly longer and can depend on the hardware.
blocking - if set to true, then the operation is blocking, otherwise it is performed asynchronously
Throws:
DataModelException - common causes
See Also:
setProgressObserver(com.qizx.api.LibraryProgressObserver)

backup

void backup(File backupDir)
            throws DataModelException
Makes a snapshot copy of the Library to a directory.

If a LibraryProgressObserver is defined, its method LibraryProgressObserver.backupProgress(double) is called as the backup operation progresses.

Parameters:
backupDir - directory where the Library is copied. If this directory already exists, its contents are first erased.
Throws:
DataModelException - on IO error on the backup destination; common causes

incrementalBackup

void incrementalBackup(File backupDir)
                       throws DataModelException
Makes a snapshot copy of the Library to a directory, transferring only the modified portions of the Library.

This operation may revert to a full backup if the target Library is incompatible with the source Library (e.g different versions).

If a LibraryProgressObserver is defined, its method LibraryProgressObserver.backupProgress(double) is called as the backup operation progresses.

Parameters:
backupDir - directory where the Library is copied.
Throws:
DataModelException - on IO error on the backup destination; common causes

setProgressObserver

void setProgressObserver(LibraryProgressObserver listener)
Sets a listener used to monitor the progress of different operations on the Library.

Parameters:
listener - an implementation of LibraryProgressObserver used to monitor import, commit or backup.
See Also:
getProgressObserver()

getProgressObserver

LibraryProgressObserver getProgressObserver()
Returns the observer used for monitoring import, commit or backup.

Returns:
the observer set by setProgressObserver (null by default).
See Also:
setProgressObserver(com.qizx.api.LibraryProgressObserver)

© 2010 Axyana Software