Class DocumentNode

java.lang.Object
com.codename1.documents.DocumentNode
public class DocumentNode extends Object

One entry in the tree an app publishes through DocumentProvider: a folder or a file, as the system file browser will show it.

A node is identified by an id that is stable for the lifetime of the item. The platform remembers ids -- a favourite in the Files app, a recent document, a running download -- so reusing an id for different content, or renumbering ids on every publish, makes the browser point at the wrong thing. Derive the id from your own record key rather than from list order.

A file node names its content in one of two ways, matching the two modes described on DocumentProvider:

  • setPath -- a path relative to DocumentProvider.getSharedDirectory(), for bytes the app has already written into the shared container.
  • setRemoteId -- an opaque key the app's HTTPS endpoint understands, for content fetched on demand.

A node with neither is a placeholder: it is listed, and opening it fails. A node with both prefers the local path, which is what makes a cached copy of a remote document open instantly.

DocumentNode root = DocumentNode.folder("root", "Invoices");
root.add(DocumentNode.file("inv-2031", "January.pdf")
        .setContentType("application/pdf")
        .setPath("invoices/january.pdf")
        .setSize(len));

  • Constructor Details

    • DocumentNode

      public DocumentNode(String id, String name, boolean folder)

      Creates a node.

      Parameters
      • id: the stable identity of this item; must not be null or empty
      • name: the display name shown in the file browser
      • folder: true for a folder, false for a file

  • Method Details

    • folder

      public static DocumentNode folder(String id, String name)

      Creates a folder node.

      Parameters
      • id: the stable identity of this folder
      • name: the display name
      Returns

      the new folder

    • file

      public static DocumentNode file(String id, String name)

      Creates a file node.

      Parameters
      • id: the stable identity of this file
      • name: the display name, normally including an extension
      Returns

      the new file

    • getId

      public String getId()
      Returns the stable identity of this item.

    • isFolder

      public boolean isFolder()
      Returns true when this node is a folder.

    • getName

      public String getName()
      Returns the display name shown in the file browser.

    • setName

      public DocumentNode setName(String name)

      Sets the display name shown in the file browser.

      Parameters
      • name: the display name
      Returns

      this node, for chaining

    • getContentType

      public String getContentType()
      Returns the MIME type of this item's content, or null when unknown.

    • setContentType

      public DocumentNode setContentType(String contentType)

      Sets the MIME type of this item's content. Worth setting: it is how the browser decides which apps can open the item and which preview to draw. Ignored for folders.

      Parameters
      • contentType: a MIME type such as application/pdf
      Returns

      this node, for chaining

    • getPath

      public String getPath()
      Returns the path of this item's content relative to the shared directory, or null.

    • setPath

      public DocumentNode setPath(String path)

      Points this item at bytes the app has written under DocumentProvider.getSharedDirectory().

      Parameters
      • path: a relative path such as invoices/january.pdf; a leading separator is ignored
      Returns

      this node, for chaining

    • getRemoteId

      public String getRemoteId()
      Returns the key this item's content is fetched by from the remote endpoint, or null.

    • setRemoteId

      public DocumentNode setRemoteId(String remoteId)

      Points this item at content fetched on demand from the endpoint given to DocumentProvider.setRemoteEndpoint.

      Parameters
      • remoteId: an opaque key the endpoint understands
      Returns

      this node, for chaining

    • getSize

      public long getSize()
      Returns the size in bytes, or -1 when unknown.

    • setSize

      public DocumentNode setSize(long size)

      Sets the size in bytes. The browser shows this before any content is fetched, so it is worth setting for remote items even though it costs a round trip to learn.

      For a remote item the size is NOT how the browser learns that content changed: content can change to different bytes of the same length -- a corrected total, a redacted page -- and the size would not move. setLastModified is the signal. Declare it and keep it accurate across republishes; a remote item that declares no date is versioned by the publication instead, which means it is re-fetched whenever anything is published, and one that declares a date it never updates is served from the cache for good.

      Items backed by the shared directory need none of this; their bytes are measured directly.

      Parameters
      • size: the size in bytes, or -1 when unknown
      Returns

      this node, for chaining

    • getLastModified

      public long getLastModified()
      Returns the last-modified time in milliseconds since the epoch, or -1 when unknown.

    • setLastModified

      public DocumentNode setLastModified(long lastModified)

      Sets the last-modified time.

      Parameters
      • lastModified: milliseconds since the epoch, or -1 when unknown
      Returns

      this node, for chaining

    • add

      public DocumentNode add(DocumentNode child)

      Adds a child to this folder.

      Parameters
      • child: the child node
      Returns

      this node, for chaining

    • getChildren

      public List<DocumentNode> getChildren()
      Returns the children of this folder, empty for a file.