|
Qizx fe-4.4p2 API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Library
Work session on a XML Library.
A Library is both:
Collection
s and XML
Document
s.
refresh()
. About transactions, see also commit()
,
rollback()
, lock()
.
A Library is also a factory for compiling XML Query Expression
s,
creating Item
s and obtaining XQuery ItemType
s and
QName
s. 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
).
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 |
---|
String getName()
User getUser()
AccessControl getAccessControl()
XQueryContext getContext()
getContext
in interface XQuerySession
Collection getRootCollection() throws DataModelException
This is a convenience method, equivalent to
getCollection("/")
.
DataModelException
- common causesCollection getCollection(String absolutePath) throws DataModelException
absolutePath
- path of the collection inside the Library.
DataModelException
- common causesLibraryMember getMember(String absolutePath) throws DataModelException
null
if such member does not exist.
absolutePath
- path of the member inside the Library.
DataModelException
- common causesDocument getDocument(String absolutePath) throws DataModelException
absolutePath
- path of the document inside the Library.
DataModelException
- common causesNonXMLDocument getNonXMLDocument(String absolutePath) throws DataModelException
absolutePath
- path of the document inside the Library.
DataModelException
- common causesExpression compileExpression(String xquery) throws CompilationException
compileExpression
in interface XQuerySession
xquery
- a string containing a XQuery script.
CompilationException
- thrown after compilation if parsing or
static analysis errors are detected. A CompilationException bears a list
of Message
s.Collection createCollection(String absolutePath) throws DataModelException
absolutePath
- the path of the collection, starting from the root
collection of the Library.
DataModelException
- common causesDocument importDocument(String documentPath, InputSource source) throws DataModelException
This method simply calls importDocument(String, InputSource, XMLReader)
,
passing a default parser (namespace aware).
documentPath
- path in the Library assigned to the document.source
- a SAX InputSource
DataModelException
- XML parsing error (wraps a SAX exception);
common causesDocument importDocument(String documentPath, InputSource source, XMLReader xmlReader) throws DataModelException
documentPath
- path in the Library assigned to the document.source
- a SAX InputSourcexmlReader
- a SAX XMLReader (parser) that can be setup before use.
DataModelException
- XML parsing error (wraps a SAX exception);
common causesDocument importDocument(String documentPath, ContentImporter importer) throws DataModelException
documentPath
- path in the Library assigned to the document.importer
-
DataModelException
- XML parsing error (wraps a SAX exception); common causesDocument importDocument(String documentPath, URL url) throws DataModelException
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.
DataModelException
- XML parsing error (wraps a SAX exception);
common causesDocument importDocument(String documentPath, File file) throws DataModelException
documentPath
- path in the Library assigned to the document.file
- location of the document to import, must contain a
well-formed XML document.
DataModelException
- XML parsing error (wraps a SAX exception);
common causesDocument importDocument(String documentPath, String data) throws DataModelException
documentPath
- path in the Library assigned to the document.data
- XML fragment as a String. It must represent a well-formed
XML document.
DataModelException
- XML parsing error (wraps a SAX exception);
common causesXMLPushStream beginImportDocument(String documentPath) throws DataModelException
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
).
documentPath
- path in the Library assigned to the document.
DataModelException
- common causesendImportDocument()
,
cancelImportDocument()
Document endImportDocument() throws DataModelException
DataModelException
- common causesbeginImportDocument
,
cancelImportDocument()
void cancelImportDocument() throws DataModelException
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.
DataModelException
- common causesNonXMLDocument importNonXMLDocument(String path, boolean compress, InputStream source) throws DataModelException
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.
DataModelException
- common causesLibraryMember renameMember(String srcPath, String dstPath) throws DataModelException
srcPath
- path of the source memberdstPath
- destination path. This path should not point to an existing
member, but its parent collection should exist
DataModelException
- if the source member does not exist; if the
destination member does exist; if its parent is not an existing
collection; common causesLibraryMember copyMember(String srcPath, String dstPath) throws DataModelException
If the specified member is a Collection, all its contained members - sub-collections and documents - are recursively copied.
srcPath
- path of the source memberdstPath
- destination path for the copy. This path should not point
to an existing member, but its parent collection should exist
DataModelException
- if the source member does not exist; if the
destination member does exist; if its parent is not an existing
collection; common causesboolean deleteMember(String path) throws DataModelException
If the specified member is a Collection, all its contained members - sub-collections and documents - are recursively deleted.
path
- of a library member
true
if specified member has been deleted;
false
otherwise (because such member does not
exist)
DataModelException
- common causesvoid refresh() throws LibraryException
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.
DataModelException
- common causes
LibraryException
boolean lock(String[] memberPaths, int timeOutMillis) throws DataModelException
lockCollection(String, int)
or
lockDocument(String, int)
can be used instead.
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).
DataModelException
- common causesCollection lockCollection(String path, int timeOutMillis) throws DataModelException
lock
.
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).
DataModelException
- common causes#lockDocument
Document lockDocument(String path, int timeOutMillis) throws DataModelException
lock(String[], int)
.
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).
DataModelException
- common causes#lockDocument
void commit() throws LibraryException
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
LibraryException
- common causesboolean isReadOnly()
Attempts to modify the contents of a read-only Library raise AccessControlException.
boolean isAutoCommitting()
void setAutoCommitting(boolean autoCommitting)
autoCommitting
- a boolean indicating whether a commit is performed
after the execution of each updating Expression.void rollback() throws LibraryException
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.
DataModelException
- common causes
LibraryException
boolean isModified()
void close() throws LibraryException
This method may not be called if a transaction has begun. In that case only commit() or rollback() may be used.
DataModelException
- common causes
LibraryException
boolean isClosed()
void setIndexing(Indexing specification) throws DataModelException
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.
specification
- a parsed Indexing specification
DataModelException
- common causesIndexing getIndexing() throws DataModelException
DataModelException
- common causesvoid reIndex() throws DataModelException
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.
DataModelException
- common causessetProgressObserver(com.qizx.api.LibraryProgressObserver)
void optimize() throws DataModelException
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.
DataModelException
- common causessetProgressObserver(com.qizx.api.LibraryProgressObserver)
void quickOptimize(int timeHint, boolean blocking) throws DataModelException
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.
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
DataModelException
- common causessetProgressObserver(com.qizx.api.LibraryProgressObserver)
void backup(File backupDir) throws DataModelException
If a LibraryProgressObserver
is defined, its method
LibraryProgressObserver.backupProgress(double)
is called as
the backup operation progresses.
backupDir
- directory where the Library is copied. If this
directory already exists, its contents are first erased.
DataModelException
- on IO error on the backup destination; common causesvoid incrementalBackup(File backupDir) throws DataModelException
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.
backupDir
- directory where the Library is copied.
DataModelException
- on IO error on the backup destination; common causesvoid setProgressObserver(LibraryProgressObserver listener)
listener
- an implementation of LibraryProgressObserver used to
monitor import, commit or backup.getProgressObserver()
LibraryProgressObserver getProgressObserver()
setProgressObserver(com.qizx.api.LibraryProgressObserver)
|
© 2010 Axyana Software | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |