Package com.levigo.jadice.document

Interface Document

All Superinterfaces:
Item, MetadataProvider, PermissionsProvider<Document>, PropertiesProvider
All Known Subinterfaces:
SerializableDocument
All Known Implementing Classes:
FilteredDocument
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.

  • Field Details

    • PROPERTY_STATE

      static final String PROPERTY_STATE
      Property change key for the 'state' property.
      See Also:

    • PROPERTY_NAME

      static final String PROPERTY_NAME
      Property change key for the 'name' property.
      See Also:

    • PROPERTY_PREFIX_PAGE

      static final String PROPERTY_PREFIX_PAGE
      A property name prefix used for bridged property changes from pages.
      See Also:

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

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

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

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

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

  • Method Details

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

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

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

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