com.levigo.jadice.swing
Class SwingUIDocument

java.lang.Object
  extended by com.levigo.jadice.swing.SwingUIDocument
All Implemented Interfaces:
Document, Item, MetadataProvider, PermissionsProvider<Document>, UIDocument<Component>, PropertiesProvider

public class SwingUIDocument
extends Object
implements UIDocument<Component>

A UIDocument for the use with Java AWT/Swing components. All calls to DocumentListeners and DocumentInterceptors registered with this document will happen on the the event dispatch thread.


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
 
Constructor Summary
protected SwingUIDocument(Document doc)
           
 
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 assertOwnership(Component owner)
          Assert the given owner as the most recent UI component to own this document.
 boolean close()
          Closes a Document.
protected  EventList<Page> createThreadProxyList(Document doc)
           
 void dispose()
           Disposes of a Document performing necessary clean-up tasks.
protected  void exceptionIfDisposed()
           
static UIDocument<Component> get(Document doc)
          Return a UIDocument suitable for use with the Java AWT/Swing GUI toolkit based on the given Document.
 Component getCurrentOwner()
          Get the current owner, i.e.
 Metadata getMetadata()
          Return the exposed meta-data or null if no meta-data is available.
 String getName()
          Gets the document's name.
 Page getPage(int pageNumber)
          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.
 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 getSourceDocument()
          Return the source Document instance that this UIDocument is based on or null.
 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 renounceOwnership(Component owner)
          Renounce the ownership of this document by the given owner.
 void setName(String name)
          Sets the document's name.
 boolean setState(Document.State docState)
           Sets the current state of the Document.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SwingUIDocument

protected SwingUIDocument(Document doc)
Method Detail

get

public static UIDocument<Component> get(Document doc)
Return a UIDocument suitable for use with the Java AWT/Swing GUI toolkit based on the given Document. If the given document is already a SwingUIDocument, it is returned unchanged. Otherwise a SwingUIDocument wrapper to the given document is returned. For a any given document, only one wrapper is created. If a wrapper as already been created earlier, this existing instance is returned from this call.

Parameters:
doc - the document for which to return the SwingUIDocument wrapper.
Returns:
the wrapper
Throws:
IllegalStateException - if called with a document that has been disposed of.

createThreadProxyList

protected EventList<Page> createThreadProxyList(Document doc)

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

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 -
See Also:
Document.addDocumentListener(com.levigo.jadice.document.DocumentListener)

assertOwnership

public void assertOwnership(Component owner)
Description copied from interface: UIDocument
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 UIDocument.renounceOwnership(Object)) or another component asserts the ownership.

Specified by:
assertOwnership in interface UIDocument<Component>

close

public 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:
Document.close()

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

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

getCurrentOwner

public Component getCurrentOwner()
Description copied from interface: UIDocument
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.

Specified by:
getCurrentOwner in interface UIDocument<Component>
Returns:
the current owner component or null

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
See Also:
Document.getName()

getPage

public Page getPage(int pageNumber)
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:
pageNumber - the 0-based index of the page to be returned.
Returns:
a Page or null if the page doesn't exist.
See Also:
Document.getPage(int)

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
See Also:
Document.getPageIndex(com.levigo.jadice.document.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.
See Also:
Document.getPage(int, boolean)

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
See Also:
Document.getPageCount()

getPages

public 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
See Also:
Document.getPages()

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.

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:
the map of user properties

getState

public Document.State getState()
Specified by:
getState in interface Document
See Also:
Document.getState()

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

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
See Also:
Document.removeDocumentListener(com.levigo.jadice.document.DocumentListener)

renounceOwnership

public void renounceOwnership(Component owner)
Description copied from interface: UIDocument
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 UIDocument.getCurrentOwner() will return null.

Specified by:
renounceOwnership in interface UIDocument<Component>

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
See Also:
Document.setName(java.lang.String)

setState

public boolean setState(Document.State docState)
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:
docState - the new state
Returns:
whether the state change was successful (true) or rejected ( false).
See Also:
Document.State, Document.BasicState, DocumentInterceptor

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

exceptionIfDisposed

protected void exceptionIfDisposed()

getSourceDocument

public Document getSourceDocument()
Description copied from interface: UIDocument
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, UIDocument.getSourceDocument() will return itself (using this).

Specified by:
getSourceDocument in interface UIDocument<Component>
Returns:
the source Document instance that this UIDocument is based on or null


Copyright © 1995-2020 levigo holding gmbh. All Rights Reserved.