Qizx fe-4.4p2 API

com.qizx.api
Interface LibraryManager


public interface LibraryManager

Manages a group of XML Libraries.

A LibraryManager manages a bundle of XML Libraries and federates resources like memory caches. It can be seen as the core of a server.

User sessions (Library) are obtained from a LibraryManager, by calling the openLibrary(String) methods.

A LibraryManager instance can be obtained through the bootstrap class Configuration:

A Library Group is merely a directory that contains a sub-directory for each XML Library belonging to the group. Note that there is no delete method for a group: to delete it, simply delete its storage directory.


Field Summary
static int CHECK_CONTENTS
          Mask for sanityCheck(com.qizx.api.util.logging.Log, boolean, boolean): fully check the document contents
static int CHECK_INDEXES
          Mask for sanityCheck(com.qizx.api.util.logging.Log, boolean, boolean): check the indexes for integrity & consistency
static int CHECK_STORAGE
          Mask for sanityCheck(com.qizx.api.util.logging.Log, boolean, boolean): fully check the document storage
 
Method Summary
 void addLibraryObserver(LibraryMemberObserver observer)
          Adds an observer for access and update operations.
 void addLogHandler(Handler handler)
          Adds a Logger handler which is used both by the Library Manager and all the managed Libraries.
 void addPostCommitTrigger(String libraryName, PostCommitTrigger trigger)
          Adds a post-commit Trigger.
 boolean closeAllLibraries(int graceTimeMillis)
          Shuts down the manager by unmanaging all the Libraries and releasing resources.
 void collectStatistics(com.qizx.api.util.logging.Statistic.Map targetMap)
          Returns a list of statistics collected from the managed XML Libraries and from shared resources (caches, disk I/O etc).
 boolean configure(Configuration.Property property, Object value)
          Configures a XQuerySessionManager with a Configuration.Property.
 boolean configure(Properties properties)
          Configures a LibraryManager with a set of properties.
 com.qizx.api.util.backup.BackupTarget createBackup(File location, String libraryName, int version, boolean incremental)
          Opens or creates a Library used as backup output.
 void createLibrary(String libraryName, File libraryDirectory)
          Creates a new XML Library and manages it in this LibraryManager.
 boolean deleteLibrary(String libraryName)
          Physically destroys a Library.
 XQuerySession findSession(int id)
          Finds a session (Library) by its public identifier.
 Map<Configuration.Property,Object> getConfiguration()
          Gets the current configuration properties of the LibraryManager.
 FullTextFactory getFullTextFactory()
          Returns the FullTextFactory specified by setFullTextFactory(FullTextFactory).
 File getGroupDirectory()
          Returns the top-level directory of the Library Group.
 Logger getLibraryLogger(String libraryName)
          Returns the logger associated with a Library.
 LibraryMemberObserver[] getLibraryObservers()
          Returns a list of active LibraryMemberObserver's.
 Logger getLogger()
          Returns the logger associated with the LibraryManager.
 long getMemoryLimit()
          Defines the maximum memory size the generated LibraryManager can use.
 ModuleResolver getModuleResolver()
          Returns the current ModuleResolver.
 PostCommitTrigger[] getPostCommitTriggers(String libraryName)
          Returns a list of post-commit Triggers.
 com.qizx.xdm.DocumentPool getTransientDocumentCache()
          Gets the document cache.
 long getTransientDocumentCacheSize()
          Gets the current maximum memory size for the document cache.
 List<BackgroundTask> listBackgroundTasks(int timeline)
          Returns a list of past- or current maintenance tasks.
 String[] listLibraries()
          Returns the names of XML Libraries managed by this object.
 List<Library> listSessions()
          Returns a list of active (non closed) sessions.
 void manageLibrary(String libraryName, File libraryDirectory)
          Starts managing an existing XML Library in this LibraryManager.
 com.qizx.api.util.backup.BackupSession openForBackup(String libraryName)
          Opens a backup session on a Library: a BackupSession is the source of a backup operation and allows comparison of contents with a BackupTarget in order to perform incremental backup or Replication.
 Library openLibrary(String libraryName)
          Opens a new session on a Library.
 Library openLibrary(String libraryName, AccessControl accessControl, User user)
          Opens a new session on a Library.
 void removeLibraryObserver(LibraryMemberObserver observer)
          Removes an observer of access and update operations.
 void removePostCommitTrigger(String libraryName, PostCommitTrigger trigger)
          Removes a post-commit Trigger.
 void sanityCheck(com.qizx.api.util.logging.Log log, boolean deep, boolean allowFixing)
          Performs a validity check of all managed Libraries.
 void sanityCheck(com.qizx.api.util.logging.Log log, int modeMask, boolean allowFixing)
          Performs a validity check of all managed Libraries.
 void saveConfiguration()
          Saves the current configuration properties of the LibraryManager onto a file attached to the Library Group (named group.conf).
 void setFullTextFactory(FullTextFactory factory)
          Defines a default FullTextFactory for all the XML Libraries opened or created from this Library Manager.
 void setGroupDirectory(File directory)
          Sets the top-level directory of the Library Group.
 void setMemoryLimit(long size)
          Defines the maximum memory size the generated LibraryManager can use.
 void setModuleResolver(ModuleResolver resolver)
          Sets the resolver used for resolving a module into actual locations.
 long setTransientDocumentCacheSize(long size)
          Sets the maximum memory size for the document cache.
 boolean unmanageLibrary(String libraryName, int graceTimeMillis)
          Closes and detaches a XML Library from this LibraryManager.
 

Field Detail

CHECK_STORAGE

static final int CHECK_STORAGE
Mask for sanityCheck(com.qizx.api.util.logging.Log, boolean, boolean): fully check the document storage

See Also:
Constant Field Values

CHECK_CONTENTS

static final int CHECK_CONTENTS
Mask for sanityCheck(com.qizx.api.util.logging.Log, boolean, boolean): fully check the document contents

See Also:
Constant Field Values

CHECK_INDEXES

static final int CHECK_INDEXES
Mask for sanityCheck(com.qizx.api.util.logging.Log, boolean, boolean): check the indexes for integrity & consistency

See Also:
Constant Field Values
Method Detail

listLibraries

String[] listLibraries()
                       throws DataModelException
Returns the names of XML Libraries managed by this object.

Returns:
a sorted array of Library names
Throws:
DataModelException - if there is a system access problem.

createLibrary

void createLibrary(String libraryName,
                   File libraryDirectory)
                   throws LibraryException
Creates a new XML Library and manages it in this LibraryManager.

Parameters:
libraryName - symbolic name of a Library.
libraryDirectory - the location of the new Library. It represents a directory. If the directory exists, it must be empty. If value is null, the Library will be created as a sub-directory of the 'group directory' of this LibraryManager, which must be defined (see setGroupDirectory(java.io.File). The sub-directory will have the name of the Library (parameter libraryName).
Throws:
DataModelException - if specified library already exists, if specified library name already used.
LibraryException
Since:
4.0 This method has been changed in 4.0, it has different parameters and no more opens a session.

deleteLibrary

boolean deleteLibrary(String libraryName)
                      throws LibraryException
Physically destroys a Library.

Parameters:
libraryName - symbolic name of the Library to destroy
Returns:
true if specified library has been deleted; false otherwise (because such library does not exist)
Throws:
DataModelException - if there is a system access problem, if no managed Library has the specified name.
LibraryException

manageLibrary

void manageLibrary(String libraryName,
                   File libraryDirectory)
                   throws LibraryException
Starts managing an existing XML Library in this LibraryManager. Sessions on the Library can then be opened by openLibrary(java.lang.String, com.qizx.api.AccessControl, com.qizx.api.User).

Parameters:
libraryName - symbolic name of a Library. Must not clash with an already managed Library.
libraryDirectory - the location of the Library. If value is null and if the Group directory is defined (see setGroupDirectory(java.io.File)), the LibraryManager will look for a Library located at group-directory/library-name.
Throws:
DataModelException - if specified library name already used, if Library cannot be located.
LibraryException
Since:
4.0

unmanageLibrary

boolean unmanageLibrary(String libraryName,
                        int graceTimeMillis)
                        throws LibraryException
Closes and detaches a XML Library from this LibraryManager. The Library is then no more accessible by openLibrary(java.lang.String, com.qizx.api.AccessControl, com.qizx.api.User). All sessions if any are automatically closed after a delay.

Parameters:
libraryName - symbolic name of a managed Library.
graceTimeMillis - a time in milliseconds for which the method will wait if there are Library sessions with unfinished transactions. After that time a rollback will be forced on all uncommitted transactions.
Returns:
true if all sessions have been closed without forced rollback.
Throws:
DataModelException - if there is a system access problem.
LibraryException
Since:
4.0

closeAllLibraries

boolean closeAllLibraries(int graceTimeMillis)
                          throws DataModelException
Shuts down the manager by unmanaging all the Libraries and releasing resources.

Parameters:
graceTimeMillis - a time in milliseconds for which the method will wait if there are Library sessions with unfinished transactions. After that time a rollback will be forced on all uncommitted transactions.
Returns:
true if all sessions have been closed without forced rollback.
Throws:
DataModelException - if there is a system access problem.

openLibrary

Library openLibrary(String libraryName,
                    AccessControl accessControl,
                    User user)
                    throws DataModelException
Opens a new session on a Library.

Notice that no authentication is performed at this level. The user name is used by the AccessControl to check the permissions of the user.

Parameters:
libraryName - symbolic name of a Library
accessControl - an implementation of AccessControlException. this instance can be specific to this session, or specific to the concerned Library: this is under the control of the implementation.
user - represents an authentified User. If null, then the AccessControl must be null too (corresponds to the simplified version without access control).
Returns:
a session on the specified Library or null if such a Library does not exist.
Throws:
DataModelException - if there is a system access problem. This happens normally only when the XML Library is already locked by another application.
Since:
4.0 modified to add AccessControl parameter

openLibrary

Library openLibrary(String libraryName)
                    throws DataModelException
Opens a new session on a Library.

Simplified version used when there is no Access Control.

Parameters:
libraryName - symbolic name of a Library
Returns:
a session on the specified Library or null if such a Library does not exist
Throws:
DataModelException - if there is a system access problem. This happens normally only when the XML Library is already used by another application.
Since:
4.0

listSessions

List<Library> listSessions()
Returns a list of active (non closed) sessions.

Since:
4.4

findSession

XQuerySession findSession(int id)
Finds a session (Library) by its public identifier.

Parameters:
id - a public identifier returned by XQuerySession.getIdentifier().
Returns:
a session, or null if not found.
Since:
4.4

openForBackup

com.qizx.api.util.backup.BackupSession openForBackup(String libraryName)
                                                     throws DataModelException
Opens a backup session on a Library: a BackupSession is the source of a backup operation and allows comparison of contents with a BackupTarget in order to perform incremental backup or Replication.

Parameters:
libraryName - symbolic name of a Library
Returns:
a low-level session that is used as source.
Throws:
DataModelException

createBackup

com.qizx.api.util.backup.BackupTarget createBackup(File location,
                                                   String libraryName,
                                                   int version,
                                                   boolean incremental)
                                                   throws DataModelException,
                                                          IOException
Opens or creates a Library used as backup output.

Used for implementing backup. Advanced use, not for usual applications.

Parameters:
location - physical location of the XML Library
incremental - true if the backup is incremental. If not incremental, or if the storage versions differ, then a previously existing backup Library is erased and recreated.
version - storage version number
Returns:
an interface used as low-level output of
Throws:
DataModelException
IOException

getGroupDirectory

File getGroupDirectory()
Returns the top-level directory of the Library Group. This directory in general contains one sub-directory for each contained Library. It is non null if this LibraryManager was open with Configuration.openLibraryGroup(java.io.File).

Returns:
a File which is the directory containing the Library Group managed by this object.
Since:
4.0

setGroupDirectory

void setGroupDirectory(File directory)
Sets the top-level directory of the Library Group. This directory in general contains one sub-directory for each contained Library.

Parameters:
directory - a File which is the root location of the Library Group managed by this object.
Since:
4.0

configure

boolean configure(Properties properties)
                  throws Exception
Configures a LibraryManager with a set of properties.

Parameters:
properties - a set of properties. Properties are defined by Configuration.Property.

Unknown properties are silently ignored.

Returns:
true if any configuration property has actually been changed.
Throws:
QizxException -

When one or several invalid property values are specified. An invalid value does not prevent valid properties to be taken into account.

Exception
Since:
4.2

configure

boolean configure(Configuration.Property property,
                  Object value)
                  throws Exception
Configures a XQuerySessionManager with a Configuration.Property.

Parameters:
property - a Property.
value - see each Property
Returns:
true if Property is recognized and its value actually changes.
Throws:
Exception

getConfiguration

Map<Configuration.Property,Object> getConfiguration()
Gets the current configuration properties of the LibraryManager.

The configuration is loaded from the property file group.conf located in the main directory of the XML Library Group (this file is normally created by saveConfiguration()). It is loaded only if the LibraryManager has a root directory and if this file exists.

The returned values reflect the changes made with the configure() methods.

Returns:
a mapping of configuration Property descriptors to values.

saveConfiguration

void saveConfiguration()
                       throws DataModelException
Saves the current configuration properties of the LibraryManager onto a file attached to the Library Group (named group.conf).

The LibraryManager must have a defined root directory.

Throws:
DataModelException

collectStatistics

void collectStatistics(com.qizx.api.util.logging.Statistic.Map targetMap)
Returns a list of statistics collected from the managed XML Libraries and from shared resources (caches, disk I/O etc).

Parameters:
targetMap - a map that can aggregate or discard some queries

setMemoryLimit

void setMemoryLimit(long size)
Defines the maximum memory size the generated LibraryManager can use.

Parameters:
size - maximum size in bytes of memory allocated to the LibraryManager.
See Also:
getMemoryLimit()

getMemoryLimit

long getMemoryLimit()
Defines the maximum memory size the generated LibraryManager can use.

Returns:
maximum size in bytes of memory allocated to the LibraryManager.
See Also:
setMemoryLimit(long)

getTransientDocumentCache

com.qizx.xdm.DocumentPool getTransientDocumentCache()
Gets the document cache.


setTransientDocumentCacheSize

long setTransientDocumentCacheSize(long size)
Sets the maximum memory size for the document cache. The document cache stores transient documents which are parsed in memory but not stored in a XML Library.

Parameters:
size - maximum memory size in bytes. Decreasing this size will flush the cache accordingly.
Returns:
the former maximum memory size in bytes

getTransientDocumentCacheSize

long getTransientDocumentCacheSize()
Gets the current maximum memory size for the document cache.

Returns:
a size in bytes

setModuleResolver

void setModuleResolver(ModuleResolver resolver)
Sets the resolver used for resolving a module into actual locations. By default, a LibraryManager uses a DefaultModuleResolver.

Parameters:
resolver - replacement for the current resolver

getModuleResolver

ModuleResolver getModuleResolver()
Returns the current ModuleResolver.

Returns:
the current Module resolver

setFullTextFactory

void setFullTextFactory(FullTextFactory factory)
Defines a default FullTextFactory for all the XML Libraries opened or created from this Library Manager.

A FullTextFactory provides access to- or allows redefining full-text resources such as text tokenizer, stemming, thesaurus and scoring method.

Parameters:
factory - an implementation of FullTextFactory. A new instance is cloned for each Library. A factory can also be defined for a specific Library.

getFullTextFactory

FullTextFactory getFullTextFactory()
Returns the FullTextFactory specified by setFullTextFactory(FullTextFactory).

Returns:
the FullTextFactory specified by setFullTextFactory(FullTextFactory) or null if none has been defined.

getLogger

Logger getLogger()
Returns the logger associated with the LibraryManager. This object can be used by applications to change its configuration.

This logger logs starts and shutdowns, and incidents on managed Libraries. It is created with level INFO.

Since:
4.0

getLibraryLogger

Logger getLibraryLogger(String libraryName)
Returns the logger associated with a Library. This object can be used by applications to change its configuration.

This logger logs internal events of each XML Library.

It is created with a daily rolling file output in library/logs/lib.log at level WARNING.

Since:
4.0

addLogHandler

void addLogHandler(Handler handler)
Adds a Logger handler which is used both by the Library Manager and all the managed Libraries.

Parameters:
handler -

addLibraryObserver

void addLibraryObserver(LibraryMemberObserver observer)
Adds an observer for access and update operations.

A LibraryMemberObserver is a pre-commit trigger whose actions are part of a transaction.

Parameters:
observer - an object implementing the LibraryMemberObserver interface.

removeLibraryObserver

void removeLibraryObserver(LibraryMemberObserver observer)
Removes an observer of access and update operations.

Parameters:
observer - an object implementing the LibraryMemberObserver interface.

getLibraryObservers

LibraryMemberObserver[] getLibraryObservers()
Returns a list of active LibraryMemberObserver's.

Returns:
a non-null (but possibly empty) array of observers

addPostCommitTrigger

void addPostCommitTrigger(String libraryName,
                          PostCommitTrigger trigger)
Adds a post-commit Trigger.

Parameters:
libraryName - the name of a managed Library, or null. A null value acts as a wildcard: the trigger is added to all currently managed Libraries.
trigger - an object implementing the PostCommitTrigger interface.

removePostCommitTrigger

void removePostCommitTrigger(String libraryName,
                             PostCommitTrigger trigger)
Removes a post-commit Trigger.

Parameters:
libraryName - the name of a managed Library, or null. A null value acts as a wildcard: the trigger is removed from all currently managed Libraries.
trigger - an object implementing the PostCommitTrigger interface.

getPostCommitTriggers

PostCommitTrigger[] getPostCommitTriggers(String libraryName)
Returns a list of post-commit Triggers.

Parameters:
libraryName - the name of a managed Library. A null value is not allowed here.
Returns:
a non-null (but possibly empty) array of Triggers.

sanityCheck

void sanityCheck(com.qizx.api.util.logging.Log log,
                 boolean deep,
                 boolean allowFixing)
Performs a validity check of all managed Libraries.

Parameters:
log - interface reporting errors and messages
deep - perform deep inspection if true
allowFixing - if true and errors are detected, perform fixes if possible. Requires the Libraries to be writable.

sanityCheck

void sanityCheck(com.qizx.api.util.logging.Log log,
                 int modeMask,
                 boolean allowFixing)
Performs a validity check of all managed Libraries.

Parameters:
log - interface reporting errors and messages
modeMask - a bit combination of CHECK_STORAGE (for a full check of the contents storage), CHECK_CONTENTS CHECK_INDEXES. .
allowFixing - if true and errors are detected, perform fixes if possible. Requires the Libraries to be writable.

listBackgroundTasks

List<BackgroundTask> listBackgroundTasks(int timeline)
Returns a list of past- or current maintenance tasks.

Parameters:
timeline - timeline=0 for "current tasks". if timeline > 0 list all tasks that started within this number of hours in the past. For example timeline=24 returns all tasks that started in the past 24 hours.

© 2010 Axyana Software