public class DocumentNode

Object
DocumentNode

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));

Constructors

public DocumentNode(String id, String name, boolean folder) Creates a node.

Methods

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

Inherited methods

From Object

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

Constructor details

DocumentNode

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

Creates a node.

Parameters

id String: the stable identity of this item; must not be null or empty
name String: the display name shown in the file browser
folder boolean: 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 String: the stable identity of this folder
name String: the display name

Returns

the new folder

file

public static DocumentNode file(String id, String name)

Creates a file node.

Parameters

id String: the stable identity of this file
name String: 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 String: 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 String: 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 String: 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 String: 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 long: 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 long: 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 DocumentNode: the child node

Returns

this node, for chaining

getChildren

public List<DocumentNode> getChildren()

Returns the children of this folder, empty for a file.