# 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 Summary

  Constructors
  Constructor
  Description
  `DocumentNode(String id, String name, boolean folder)`
  Creates a node.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DocumentNode`
  `add(DocumentNode child)`
  Adds a child to this folder.
  `static DocumentNode`
  `file(String id, String name)`
  Creates a file node.
  `static DocumentNode`
  `folder(String id, String name)`
  Creates a folder node.
  `List<DocumentNode>`
  `getChildren()`
  Returns the children of this folder, empty for a file.
  `String`
  `getContentType()`
  Returns the MIME type of this item's content, or null when unknown.
  `String`
  `getId()`
  Returns the stable identity of this item.
  `long`
  `getLastModified()`
  Returns the last-modified time in milliseconds since the epoch, or -1 when unknown.
  `String`
  `getName()`
  Returns the display name shown in the file browser.
  `String`
  `getPath()`
  Returns the path of this item's content relative to the shared directory, or null.
  `String`
  `getRemoteId()`
  Returns the key this item's content is fetched by from the remote endpoint, or null.
  `long`
  `getSize()`
  Returns the size in bytes, or -1 when unknown.
  `boolean`
  `isFolder()`
  Returns true when this node is a folder.
  `DocumentNode`
  `setContentType(String contentType)`
  Sets the MIME type of this item's content.
  `DocumentNode`
  `setLastModified(long lastModified)`
  Sets the last-modified time.
  `DocumentNode`
  `setName(String name)`
  Sets the display name shown in the file browser.
  `DocumentNode`
  `setPath(String path)`
  Points this item at bytes the app has written under `DocumentProvider.getSharedDirectory()`.
  `DocumentNode`
  `setRemoteId(String remoteId)`
  Points this item at content fetched on demand from the endpoint given to `DocumentProvider.setRemoteEndpoint`.
  `DocumentNode`
  `setSize(long size)`
  Sets the size in bytes.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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