com.levigo.jadice.document
Class AbstractDocument

java.lang.Object
  com.levigo.jadice.document.AbstractDocument

All Implemented Interfaces:

Document, Item, MetadataProvider, MutableMetadataProvider, PermissionsProvider<Document>, PropertiesProvider

Direct Known Subclasses:

BasicDocument

public abstract class AbstractDocument
extends Object
implements Document, MutableMetadataProvider

A basic implementation of the Document interface. Not thread-safe!

Nested Class Summary

Nested classes/interfaces inherited from interface com.levigo.jadice.document.Document

Document.BasicState, Document.State

Field Summary

protected com.levigo.jadice.document.DocumentInterceptorSupport	interceptorSupport
protected com.levigo.jadice.document.DocumentListenerSupport	listenerSupport
protected static Logger	LOGGER

Fields inherited from interface com.levigo.jadice.document.Document

BASE_RESOLUTION, PROPERTY_KEY_DISPLAY_NAME, PROPERTY_KEY_DOCUMENT_ID, PROPERTY_KEY_FILE_NAME, PROPERTY_NAME, PROPERTY_PREFIX_PAGE, PROPERTY_PREFIX_USER_PROPERTY, PROPERTY_STATE

Constructor Summary

AbstractDocument()
Construct a new document.

AbstractDocument(String name)
Construct a new document with the given name.

Method Summary

void	addDocumentInterceptor(DocumentInterceptor interceptor) Register a DocumentInterceptor to this document instance.
void	addDocumentListener(DocumentListener listener) Register a DocumentListener to this document instance.
void	addPage(Page page) Adds a page to the document.
protected void	cleanUpResources() Performes the actual clean-up required for disposing of Documents.
boolean	close() Closes a Document.
void	dispose() Disposes of a Document performing necessary clean-up tasks.
protected void	exceptionIfDisposed()
Metadata	getMetadata() Return the exposed meta-data or null if no meta-data is available.
MutableMetadataNode	getMutableMetadataRoot() Return the mutable root node of the meta-data tree belonging to this metadata provider.
String	getName() Gets the document's name.
Page	getPage(int pageIndex) Convenience method: return the page at the given page index.
Page	getPage(int pageNumber, boolean create) Return the page at the given page index.
int	getPageCount() Convenience method: determine the number of pages in this document.
int	getPageIndex(Page page) Convenience method: determine the index of a page in this document.
abstract EventList<Page>	getPages() Returns a list of pages in the document.
Permissions<Document>	getPermissions() Provides an instance of Permissions.
Map<String,Object>	getProperties() Return a map of user properties.
Document.State	getState()
boolean	isDisposed() Return whether or not this Document has been disposed of.
void	removeDocumentInterceptor(DocumentInterceptor interceptor) Unregister a DocumentInterceptor from this document.
void	removeDocumentListener(DocumentListener listener) Unregister a DocumentListener from this document.
void	setName(String name) Sets the document's name.
boolean	setState(Document.State state) Sets the current state of the Document.
String	toString() The description of the document

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LOGGER

protected static final Logger LOGGER

listenerSupport

protected final com.levigo.jadice.document.DocumentListenerSupport listenerSupport

interceptorSupport

protected final com.levigo.jadice.document.DocumentInterceptorSupport interceptorSupport

Constructor Detail

AbstractDocument

public AbstractDocument()

Construct a new document.

AbstractDocument

public AbstractDocument(String name)

Construct a new document with the given name.

Parameters:

name - the name of the document

Method Detail

addDocumentListener

public void addDocumentListener(DocumentListener listener)

Description copied from interface: Document

Register a DocumentListener to this document instance.

Specified by:

addDocumentListener in interface Document

Parameters:

listener - the listener to register

addPage

public final void addPage(Page page)

Adds a page to the document.

Parameters:

page - the page to add

Throws:

IllegalStateException - if called on a Document which has been disposed of.

close

public final boolean close()

Description copied from interface: Document

Closes a Document. This includes performing a state transition to Document.BasicState.CLOSED and cleaning up resources. Both will only happen if all registered DocumentInterceptors agree with the state change. In usual cases, this method should be preferred to calling Document.dispose().

Specified by:

close in interface Document

Returns:

flag indicating whether the process passed successfully or not

See Also:

for details about resource clean-up, will be asked to accept or deny the state change. Implementations could ask the user for acknowledgment., gets the chance to perform save or clean-up actions when it receives the state change to new state {@link BasicState#CLOSED}.

dispose

public void dispose()

Description copied from interface: Document

Disposes of a Document performing necessary clean-up tasks. Disposed Documents will have Document.BasicState.CLOSED as their Document.State. This method is not expected to ask registered DocumentInterceptors for their consent about the state transition. DocumentListeners may or may not be informed about the state change. In most cases, Document.close() should be used instead of this method.

Since cleaning up releases any resources held by this Document, it will no longer be practically useful afterwards. A Document which has been disposed of will refuse further changes on itself and may throw Exceptions if methods are called.

Before calling dispose it is for this reason important to make sure that the Document to be disposed of is not registered with any other (GUI or non-GUI) component which might call methods later on.

Specified by:

dispose in interface Document

cleanUpResources

protected void cleanUpResources()

Performes the actual clean-up required for disposing of Documents.

isDisposed

public boolean isDisposed()

Description copied from interface: Document

Return whether or not this Document has been disposed of. Disposed Documents will refuse further changes on themselves. Method calls on them may result in Exceptions being thrown.

Specified by:

isDisposed in interface Document

Returns:

true if this Document has been disposed of and all of its resources have been cleaned up. false if this Document has not yet been disposed of and is therefore fully usable.

See Also:

Document.dispose()

getName

public String getName()

Description copied from interface: Document

Gets the document's name.

Specified by:

getName in interface Document

Specified by:

getName in interface Item

Returns:

Returns a String

getPage

public Page getPage(int pageIndex)

Description copied from interface: Document

Convenience method: return the page at the given page index. Equivalent to Document.getPages().get(pageNumber). As an added convenience, callers need not lock the page list in order to be thread-safe.

Specified by:

getPage in interface Document

Parameters:

pageIndex - the 0-based index of the page to be returned.

Returns:

a Page or null if the page doesn't exist.

getPageIndex

public int getPageIndex(Page page)

Description copied from interface: Document

Convenience method: determine the index of a page in this document. Equivalent to Document.getPages().indexOf(page). As an added convenience, callers need not lock the page list in order to be thread-safe.

Specified by:

getPageIndex in interface Document

Parameters:

page - to search for

Returns:

int the page number of the given page in this document, or -1 if this document does not contain the page

getPage

public Page getPage(int pageNumber,
                    boolean create)

Description copied from interface: Document

Return the page at the given page index. Create it, if there is no page at this index at this point. As an added convenience, callers need not lock the page list in order to be thread-safe.

Specified by:

getPage in interface Document

Parameters:

pageNumber - the 0-based index of the page to be returned.

create - flag indicating if the page should be created if it doesn't exist.

Returns:

a Pageor null if the page doesn't exist and create is false.

getPageCount

public int getPageCount()

Description copied from interface: Document

Convenience method: determine the number of pages in this document. Equivalent to Document.getPages().size(). As an added convenience, callers need not lock the page list in order to be thread-safe.

Specified by:

getPageCount in interface Document

Returns:

int the page number count

getPages

public abstract EventList<Page> getPages()

Description copied from interface: Document

Returns a list of pages in the document. Please note that, unless stated otherwise by implementors, this list is not thread-safe. Care must therefore be taken to manipulate the page list with appropriate locking as detailed in the documentation of EventList. As a convenience, a non-thread-safe page list may be wrapped using GlazedLists.threadSafeList(EventList) to obtain a thread-safe one.

Specified by:

getPages in interface Document

Returns:

List of pages

getState

public final Document.State getState()

Specified by:

getState in interface Document

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)

Description copied from interface: Document

Unregister a DocumentListener from this document.

Specified by:

removeDocumentListener in interface Document

Parameters:

listener - the listener to remove

setName

public void setName(String name)

Description copied from interface: Document

Sets the document's name.

Specified by:

setName in interface Document

Parameters:

name - The name to set

setState

public boolean setState(Document.State state)

Description copied from interface: Document

Sets the current state of the Document.

The document Document.State is not only a simple information about a document instance, but also it provides the decision base of the enabled state for many document functionalities. If the document state is not set or is set to a wrong state, these functionalities may become disabled or fail to execute. Registered interceptors may disapprove state changes. Therefore the requested state is not necessarily the actual next state.

Specified by:

setState in interface Document

Parameters:

state - the new state

Returns:

whether the state change was successful (true) or rejected ( false).

See Also:

Document.State, Document.BasicState, DocumentInterceptor

toString

public String toString()

The description of the document

Overrides:

toString in class Object

Returns:

String documents name description

getProperties

public Map<String,Object> getProperties()

Description copied from interface: PropertiesProvider

Return a map of user properties. What to store and which keys to use is largely up to the user of classes implementing this interface, since those classes will generally be oblivious to the map's contents. There are no guarantees regarding the thread-safety of the returned map, unless otherwise specified by implementors.

Specified by:

getProperties in interface PropertiesProvider

Returns:

a thread-safe map of user properties. If this document has been disposed of, the map will be empty.

See Also:

PropertiesProvider.getProperties()

addDocumentInterceptor

public void addDocumentInterceptor(DocumentInterceptor interceptor)

Description copied from interface: Document

Register a DocumentInterceptor to this document instance.

Specified by:

addDocumentInterceptor in interface Document

Parameters:

interceptor - the interceptor to register

removeDocumentInterceptor

public void removeDocumentInterceptor(DocumentInterceptor interceptor)

Description copied from interface: Document

Unregister a DocumentInterceptor from this document.

Specified by:

removeDocumentInterceptor in interface Document

Parameters:

interceptor - the interceptor to remove

getPermissions

public Permissions<Document> getPermissions()

Description copied from interface: PermissionsProvider

Provides an instance of Permissions. Must never return null.

Specified by:

getPermissions in interface PermissionsProvider<Document>

Returns:

a Permissions object.

getMetadata

public Metadata getMetadata()

Description copied from interface: MetadataProvider

Return the exposed meta-data or null if no meta-data is available. An object being a MetadataProvider is not required to provide a non-null meta-data.

Specified by:

getMetadata in interface MetadataProvider

Returns:

the metadata document or null

getMutableMetadataRoot

public MutableMetadataNode getMutableMetadataRoot()

Description copied from interface: MutableMetadataProvider

Return the mutable root node of the meta-data tree belonging to this metadata provider.

Specified by:

getMutableMetadataRoot in interface MutableMetadataProvider

Returns:

the mutable root node

exceptionIfDisposed

protected void exceptionIfDisposed()