com.levigo.jadice.document
Interface Document

All Superinterfaces:

Item, MetadataProvider, PermissionsProvider<Document>, PropertiesProvider

All Known Subinterfaces:

UIDocument<C>

All Known Implementing Classes:

AbstractDocument, BasicDocument, SwingUIDocument

public interface Document
extends PermissionsProvider<Document>, Item, MetadataProvider

Represents a logical document. A logical document consists of a two-dimensional structure:

• The first dimension are the Pages. Pages are mere containers for data which can be displayed or manipulated. Each page consists of 1-n AbstractPageSegments, which occupy the document's layers for a page (see below).
• The second dimension are the layers. Layers are virtual slots in the stack of data which represents a page. Layers are defined for the document as a whole, but pages are not required to have a page segment for each defined layer.

Furthermore a document can handle user or document related properties, stored as key value pairs.

Nested Class Summary

static class	Document.BasicState An enum consisting of the default document states.
static interface	Document.State This is a marker interface to be implemented by objects serving as state designators for documents.

Field Summary

static int	BASE_RESOLUTION The base resolution.
static String	PROPERTY_KEY_DISPLAY_NAME A user property key for the name of the document to be presented to users such as in a window title bar etc..
static String	PROPERTY_KEY_DOCUMENT_ID A user property key for the ID of an item in an archive with which the document is associated.
static String	PROPERTY_KEY_FILE_NAME A user property key for the name of the file from which the document originated.
static String	PROPERTY_NAME Property change key for the 'name' property.
static String	PROPERTY_PREFIX_PAGE A property name prefix used for bridged property changes from pages.
static String	PROPERTY_PREFIX_USER_PROPERTY A property name prefix used for bridged property changes from user properties.
static String	PROPERTY_STATE Property change key for the 'state' property.

Method Summary

void	addDocumentInterceptor(DocumentInterceptor interceptor) Register a DocumentInterceptor to this document instance.
void	addDocumentListener(DocumentListener listener) Register a DocumentListener to this document instance.
boolean	close() Closes a Document.
void	dispose() Disposes of a Document performing necessary clean-up tasks.
String	getName() Gets the document's name.
Page	getPage(int pageIndex) Convenience method: return the page at the given page index.
Page	getPage(int pageIndex, 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.
EventList<Page>	getPages() Returns a list of pages in the document.
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.

Methods inherited from interface com.levigo.jadice.document.PermissionsProvider

getPermissions

Methods inherited from interface com.levigo.jadice.document.util.PropertiesProvider

getProperties

Methods inherited from interface com.levigo.jadice.document.metadata.MetadataProvider

getMetadata

Field Detail

PROPERTY_STATE

static final String PROPERTY_STATE

Property change key for the 'state' property.

See Also:

getState(), setState(State), Constant Field Values

PROPERTY_NAME

static final String PROPERTY_NAME

Property change key for the 'name' property.

See Also:

getName(), setName(String), Constant Field Values

PROPERTY_PREFIX_PAGE

static final String PROPERTY_PREFIX_PAGE

A property name prefix used for bridged property changes from pages.

See Also:

Constant Field Values

PROPERTY_PREFIX_USER_PROPERTY

static final String PROPERTY_PREFIX_USER_PROPERTY

A property name prefix used for bridged property changes from user properties.

See Also:

Constant Field Values

PROPERTY_KEY_FILE_NAME

static final String PROPERTY_KEY_FILE_NAME

A user property key for the name of the file from which the document originated.

See Also:

Constant Field Values

PROPERTY_KEY_DISPLAY_NAME

static final String PROPERTY_KEY_DISPLAY_NAME

A user property key for the name of the document to be presented to users such as in a window title bar etc..

See Also:

Constant Field Values

PROPERTY_KEY_DOCUMENT_ID

static final String PROPERTY_KEY_DOCUMENT_ID

A user property key for the ID of an item in an archive with which the document is associated.

See Also:

Constant Field Values

BASE_RESOLUTION

static final int BASE_RESOLUTION

The base resolution. All calculations are based on this resolution. The base resolution is currently a 7200'th of an inch.

See Also:

Constant Field Values

Method Detail

addDocumentListener

void addDocumentListener(DocumentListener listener)

Register a DocumentListener to this document instance.

Parameters:

listener - the listener to register

Throws:

IllegalArgumentException - if parameter is null

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

addDocumentInterceptor

void addDocumentInterceptor(DocumentInterceptor interceptor)

Register a DocumentInterceptor to this document instance.

Parameters:

interceptor - the interceptor to register

Throws:

IllegalArgumentException - if parameter is null

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

close

boolean close()

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

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

void dispose()

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

isDisposed

boolean isDisposed()

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.

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:

dispose()

getName

String getName()

Gets the document's name.

Specified by:

getName in interface Item

Returns:

Returns a String

getPage

Page getPage(int pageIndex)

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

Parameters:

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

Returns:

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

getPage

Page getPage(int pageIndex,
             boolean create)

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.

Parameters:

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

Throws:

IndexOutOfBoundsException - if pageIndex < 0

IllegalStateException - if called with parameter create==true on a Document which has been disposed of

getPageCount

int getPageCount()

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

Returns:

int the page number count

getPageIndex

int getPageIndex(Page page)

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

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

Throws:

NullPointerException - if the page is null

getPages

EventList<Page> getPages()

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.

Returns:

List of pages

Throws:

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

removeDocumentListener

void removeDocumentListener(DocumentListener listener)

Unregister a DocumentListener from this document.

Parameters:

listener - the listener to remove

removeDocumentInterceptor

void removeDocumentInterceptor(DocumentInterceptor interceptor)

Unregister a DocumentInterceptor from this document.

Parameters:

interceptor - the interceptor to remove

setName

void setName(String name)

Sets the document's name.

Parameters:

name - The name to set

Throws:

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

getState

Document.State getState()

setState

boolean setState(Document.State state)

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.

Parameters:

state - the new state

Returns:

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

Throws:

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

See Also:

Document.State, Document.BasicState, DocumentInterceptor