com.levigo.jadice.document
Interface UIDocument<C>

Type Parameters:

C - the type of UI component used by the UI toolkit.

All Superinterfaces:

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

All Known Implementing Classes:

SwingUIDocument

public interface UIDocument<C>
extends Document

A UIDocument is a Document implementation which is particularly suitable for the use in graphical user interfaces. All GUI toolkits for Java mandate a single-thread rule, i.e. the rule that all GUI manipulation must only be done on the GUI thread (e.g. the Java AWT/Swing EDT). Since modifications of Documents frequently happen in the background (e.g. through a background loader) some complications arise from this restriction, as care must be taken to "lift" all changes onto the GUI thread.

UIDocuments alleviate developers from this burden by making all changes visible only on the respective GUI thread. In practical terms this means that all DocumentListeners will be notified and all DocumentInterceptor will be called only on the GUI thread. Furthermore, changes to the page list will only ever become visible on the GUI thread, so that activity on the GUI thread does not have to bother with locking read operations to ensure consistent state (write operations must still be properly guarded, however).

A application of UIDocuments is the tracking of "perceived ownership" of documents by UI components. Code dealing with a document, may, at times, need to determine which UI component(s) currently deal(s) with a given document instance. For example, a modal notification dialog presented to the used must be opened with the correct parent frame - the frame within which the document is currently being presented, in order for the window manager to correctly manage the frame relationships. By way of the assertOwnership(Object) and renounceOwnership(Object) methods a component can dis-/associate itself with/from a UIDocument. The last recent owner of the UIDocument can be determined using getCurrentOwner().

Nested Class Summary

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

Document.BasicState, Document.State

Field Summary

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

Method Summary

void	assertOwnership(C owner) Assert the given owner as the most recent UI component to own this document.
C	getCurrentOwner() Get the current owner, i.e.
Document	getSourceDocument() Return the source Document instance that this UIDocument is based on or null.
void	renounceOwnership(C owner) Renounce the ownership of this document by the given owner.

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

addDocumentInterceptor, addDocumentListener, close, dispose, getName, getPage, getPage, getPageCount, getPageIndex, getPages, getState, isDisposed, removeDocumentInterceptor, removeDocumentListener, setName, setState

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

Method Detail

assertOwnership

void assertOwnership(C owner)

Assert the given owner as the most recent UI component to own this document. The component becomes the current owner until it either withdraws the ownership (see renounceOwnership(Object)) or another component asserts the ownership.

Parameters:

owner -

Throws:

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

getCurrentOwner

C getCurrentOwner()

Get the current owner, i.e. the last UI component to assert ownership of this document. If there is no owner (no component has ever asserted ownership or all ownerships have been renounced) this method returns null.

Returns:

the current owner component or null

renounceOwnership

void renounceOwnership(C owner)

Renounce the ownership of this document by the given owner. If the given owner was the current owner, the next owner on the stack becomes the current owner. If the given owner was the only one left, the document becomes orphaned, i.e. it no longer has an owner and getCurrentOwner() will return null.

Parameters:

owner -

getSourceDocument

Document getSourceDocument()

Return the source Document instance that this UIDocument is based on or null. If a UIDocument has been created based on a existing Document instance the original instance can be obtained using this method. If the UIDocument is a standalone document, getSourceDocument() will return itself (using this).

Returns:

the source Document instance that this UIDocument is based on or null