Interface Document

  • All Superinterfaces:
    com.google.gwt.user.client.rpc.IsSerializable, Item, MetadataProvider, PermissionsProvider<Document>, PropertiesProvider
    All Known Implementing Classes:
    FilteredDocument

    public interface Document
    extends PermissionsProvider<Document>, Item, MetadataProvider, com.google.gwt.user.client.rpc.IsSerializable
    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.
    • Field Detail

      • 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

      • 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

        org.jadice.util.glazedlists.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.
      • 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