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

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