com.qizx.api
Interface LibraryManager

public interface LibraryManager

Manages a group of XML Libraries.

A LibraryManager is a driver that manages a group of XML Libraries and federates resources likes memory caches. It is from a LibraryManager that User sessions (Library) are obtained, by calling the method openLibrary(String, User).

A LibraryManager instance is obtained through a LibraryManagerFactory, by opening or by creating a Library Group (methods openLibraryGroup and createLibraryGroup respectively).

A Library Group is physically located in a directory of a file-system and contains a XML file group.qlg that describes the structure of the group (essentially a list of XML Libraries with their name and location).

Note that there is no delete method for a group. To delete a group, simply delete its storage directory.

Method Summary

void	addLibraryObserver(LibraryMemberObserver observer) Adds an observer of access and update operations.
boolean	closeAllLibraries(int graceTimeMillis) Closes all the managed Libraries and release resources.
Library	createLibrary(String libraryName, User user) Creates a Library inside the storage directory of the Library group controlled by this LibraryManager.
boolean	deleteLibrary(String libraryName) Physically destroys a Library.
AccessControl	getAccessControl() Returns the current AccessControl object.
LibraryMemberObserver[]	getLibraryObservers() Returns a list of active LibraryMemberObserver's.
ModuleResolver	getModuleResolver() Returns the current ModuleResolver.
File	getStorageDirectory() Returns the top-level directory of the Library Group.
int	getTransientDocumentCacheSize() Gets the current maximum memory size for the document cache.
String[]	listLibraries() Returns the names of XML Libraries managed by this object.
Library	openLibrary(String libraryName, User user) Opens a new work session on a Library.
void	removeLibraryObserver(LibraryMemberObserver observer) Removes an observer of access and update operations.
void	setAccessControl(AccessControl accessControl) Specifies an AccessControl object.
void	setModuleResolver(ModuleResolver resolver) Sets the resolver used for resolving a module into actual locations.
int	setTransientDocumentCacheSize(int size) Sets the maximum memory size for the document cache.

Method Detail

getStorageDirectory

public File getStorageDirectory()

Returns the top-level directory of the Library Group. This directory contains one sub-directory for each contained Library.

Returns:

a File which is the directory containing the Library Group managed by this object.

setAccessControl

public void setAccessControl(AccessControl accessControl)

Specifies an AccessControl object.

This method should be called before opening sessions.

Parameters:

accessControl - an AccessControl object used for all managed Libraries. It can be null, in which case, no access control is performed (this is the default). This object is cloned for each new session.

getAccessControl

public AccessControl getAccessControl()

Returns the current AccessControl object. May return null.

Returns:

the master AccessControl of this LibraryManager, or null if access control was not enabled (the default).

addLibraryObserver

public void addLibraryObserver(LibraryMemberObserver observer)

Adds an observer of access and update operations.

Parameters:

observer - an object implementing this interface.

removeLibraryObserver

public void removeLibraryObserver(LibraryMemberObserver observer)

Removes an observer of access and update operations.

Parameters:

observer - an object implementing this interface.

getLibraryObservers

public LibraryMemberObserver[] getLibraryObservers()

Returns a list of active LibraryMemberObserver's.

Returns:

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

createLibrary

public Library createLibrary(String libraryName,
                             User user)
                      throws DataModelException

Creates a Library inside the storage directory of the Library group controlled by this LibraryManager.

Parameters:

libraryName - symbolic name of a Library

user - a User with security credentials. Can be null if there is no AccessControl set on the Library.

Returns:

a session opened on the newly created Library.

Throws:

DataModelException - if specified library already exists

openLibrary

public Library openLibrary(String libraryName,
                           User user)
                    throws DataModelException

Opens a new work session on a Library.

Notice that no authentication is performed at this level.

Parameters:

libraryName - symbolic name of a Library

user - a User with security credentials. Can be null if there is no AccessControl set on the Library.

Returns:

specified library or null if such 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.

listLibraries

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

deleteLibrary

public boolean deleteLibrary(String libraryName)
                      throws DataModelException

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.

closeAllLibraries

public boolean closeAllLibraries(int graceTimeMillis)
                          throws DataModelException

Closes all the managed Libraries and release 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 libraries have been closed without forced rollback

Throws:

DataModelException - if there is a system access problem.

setTransientDocumentCacheSize

public int setTransientDocumentCacheSize(int 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

public int getTransientDocumentCacheSize()

Gets the current maximum memory size for the document cache.

Returns:

a size in bytes

setModuleResolver

public 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

public ModuleResolver getModuleResolver()

Returns the current ModuleResolver.

Returns:

the current Module resolver