com.qizx.api
Interface Library

All Superinterfaces:

ItemFactory, XQuerySession

public interface Library

extends XQuerySession

Work session on a XML Library.

A Library is both:

• The equivalent of a database for a DBMS or the equivalent of a volume in a file system. It contains a hierarchy of Collections and XML Documents.
• A connection to this database, supporting XQuery queries and updates with isolation and transactions. About isolation see refresh(). About transactions, see also commit(), rollback(), lock().

  A Library is also a factory for compiling XML Query Expressions, creating Items and obtaining XQuery ItemTypes and QNames. The XML Query context associated with a Library can be used as a predefined context for compiled Expressions.

  As a connection, a Library belongs to a given User and therefore is limited in the operations it can perform by the privileges of this user (see AccessControl). Access control is enabled at the level of the LibraryManager.

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

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.
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.
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, 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, 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.
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	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	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, getModuleResolver, setModuleResolver

Methods inherited from interface com.qizx.api.ItemFactory

copySequence, createItem, createItem, createItem, createItem, createItem, createItem, createItem, createSequence, getQName, getQName, getQName, getType

Method Detail

getName

public 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

public 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 User can be null.

getContext

public 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

public 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

public 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

public 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

public 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

compileExpression

public 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

public 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

public Document importDocument(String documentPath,
                               InputSource source)
                        throws DataModelException

Imports a Document into the Library by parsing a SAX InputSource.

• If a document with the same path already exists, it is replaced by the new contents; however existing user properties are kept (system properties are updated).
• If the enclosing Collection does not exist it is created automatically.

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

public Document importDocument(String documentPath,
                               URL url)
                        throws DataModelException

Imports a Document into the Library by parsing XML text from an URL.

• If a document with the same path already exists, it is replaced by the new contents; however existing user properties are kept (system properties are updated).
• If the enclosing Collection does not exist it is created automatically.

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

public Document importDocument(String documentPath,
                               File file)
                        throws DataModelException

Imports a Document into the Library by parsing XML text from a File.

• If a document with the same path already exists, it is replaced by the new contents; however existing user properties are kept (system properties are updated).
• If the enclosing Collection does not exist it is created automatically.

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

public Document importDocument(String documentPath,
                               String data)
                        throws DataModelException

Imports a Document into the Library by parsing a string representing a XML fragment.

• If a document with the same path already exists, it is replaced by the new contents; however existing user properties are kept (system properties are updated).
• If the enclosing Collection does not exist it is created automatically.

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

public 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

public 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

public void cancelImportDocument()

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.

renameMember

public 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

public 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

public 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

public void refresh()
             throws DataModelException

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

lock

public boolean lock(String[] memberPaths,
                    int timeOutMillis)
             throws DataModelException

Locks one or several Collections or Documents to initiate a safe concurrent update.

• This operation is optional: it is necessary only when a Library can updated concurrently by several threads.
• The lock set on members is advisory that is, if another thread updates one of these members without locking it, the result is unpredictable.
• Members are unlocked automatically by commit() or rollback().
• An implicit refresh is performed by this method, to ensure that the update is performed on the latest state of the Library. As a consequence, Document nodes and Properties read before the call to this method could become stale. So it is recommended to read or re-read this data afterwards.
• No other call to lock() can be made until the end of the transaction (commit or rollback). This prevents dead-locks and ensures consistency of the Library state. If several documents or collections need to be locked, they have to be passed in the first argument array.
• Members are locked atomically. If one of them is already locked, and if the timeOut argument is strictly positive, the method will wait until either all members are available, or the time-out is elapsed.
• If only one Collection or Document needs to be locked, the more convenient methods lockCollection(String, int) or lockDocument(String, int) can be used instead.

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

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

• This operation is optional: it is necessary only in applications where a Collection can be updated concurrently by several threads.
• The lock set on the collection is advisory that is, if another thread updates its contents without lock, then the result is unpredictable.
• The collection is unlocked automatically by commit() or rollback().
• An implicit refresh is performed by this method, to ensure that the update is performed on the latest state of the Library. In particular some library objects could have been deleted. This is why the method returns a new handle to the Collection: if a non-null value is returned, it is guaranteed that it still exists and has been successfully locked.
• No other call to lock() can be made until the end of the transaction (commit or rollback). If several objects need to be locked, either lock a common ancestor Collection (in extreme cases, the root collection), or use lock.

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

public Document lockDocument(String path,
                             int timeOutMillis)
                      throws DataModelException

Locks a Document to initiate a safe concurrent update.

• This operation is optional: it is necessary only in applications where a Document can be updated concurrently by several threads.
• The lock set on the document is advisory that is, if another thread updates its contents without lock, then the result is unpredictable.
• The document is unlocked automatically by commit() or rollback().
• An implicit refresh is performed by this method, to ensure that the update is performed on the latest state of the Library. In particular some library objects could have been deleted. This is why the method returns a new handle to the document: if a non-null value is returned, it is guaranteed that it still exists and has been successfully locked.
• No other call to lock() can be made until the end of the transaction (commit or rollback). If several objects need to be locked, either lock a common ancestor Collection (in extreme cases, the root collection), or use lock(String[], int).

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

public void commit()
            throws DataModelException

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:

DataModelException - common causes

isAutoCommitting

public 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

public 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

public void rollback()
              throws DataModelException

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

isModified

public 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

public void close()
           throws DataModelException

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

isClosed

public 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

public void setIndexing(Indexing specification)
                 throws DataModelException

Defines the indexing rules used in this Library.

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

With respect to access control, 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

public 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

public 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).

In terms of Access Control, 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

public 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).

In terms of Access Control, this operation requires the permission to modify the properties of the root collection.

Throws:

DataModelException - common causes

See Also:

setProgressObserver(com.qizx.api.LibraryProgressObserver)

backup

public 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

setProgressObserver

public 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

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