Class DocumentProvider

java.lang.Object
com.codename1.documents.DocumentProvider
public final class DocumentProvider extends Object

The static entry point for exposing your app's documents to the system file browser: the Files app on iOS, the storage picker on Android. Publish a tree, and your content becomes browsable from outside your app -- and openable by other apps -- without the user launching yours.

DocumentNode root = DocumentNode.folder("root", "My Invoices");
root.add(DocumentNode.file("inv-2031", "January.pdf")
        .setContentType("application/pdf")
        .setPath("invoices/january.pdf"));
DocumentProvider.publish(root);
Two ways to supply content

From the shared directory. Write the bytes under getSharedDirectory() and point each node at a relative path. Nothing else is involved: no server, no network code, and the content opens instantly because it is already on the device.

From your server. Call setRemoteEndpoint(String) and give each node a remoteId. Content is fetched on demand over HTTPS, which is what a cloud drive wants -- the index can list far more than the device holds. A node may carry both, and a local copy always wins, which is how a cached document opens without a round trip.

The reader is not your app

On iOS the browser talks to a generated app extension, a separate process that runs while your app is dead and cannot call your Java code. That is why this API publishes data rather than installing callbacks: the tree is serialized into a container both processes can read, and the extension serves the browser from it. Publish whenever your data changes -- after a sync, after a login -- not in response to being browsed, because you will not be asked.

Android has no such split (the provider runs in your app's process), but the same rule applies so that one publishing discipline works everywhere.

Zero cost when unused

Merely referencing this package makes the build inject the native plumbing -- the file provider extension and App Group on Apple platforms, the documents provider in the Android manifest. Apps that never touch com.codename1.documents get none of it, and on unsupported ports the whole API is an inert no-op.

If all you want is for your app's own documents folder to be visible in the Files app, you do not need any of this -- see the developer guide, which describes the two build hints that do that with no extension at all.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    clear()
    Withdraws everything: the published tree disappears from the file browser, the endpoint and token are forgotten and the shared directory is emptied.
    static String
    getSharedDirectory()
    Returns the directory whose contents the platform reader can also see, creating it if needed.
    static boolean
    isSupported()
    Returns true when this platform can expose documents to the system file browser.
    static void
    publish(DocumentNode root)
    Publishes the tree the file browser should show, replacing whatever was published before.
    static void
    setBridge(DocumentProviderBridge b)
    Test seam: installs a bridge, bypassing platform resolution.
    static void
    setRemoteEndpoint(String endpoint)
    Sets the HTTPS endpoint with no bearer token.
    static void
    setRemoteEndpoint(String endpoint, String authToken)
    Sets the HTTPS endpoint the platform reader fetches remote content from, and the bearer token it presents.
    static void
    signalChange()
    Asks the platform browser to re-enumerate the published tree.

    Methods inherited from class Object

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

  • Method Details

    • isSupported

      public static boolean isSupported()

      Returns true when this platform can expose documents to the system file browser.

      Returns

      true when document providing is supported

    • getSharedDirectory

      public static String getSharedDirectory()

      Returns the directory whose contents the platform reader can also see, creating it if needed. Write the bytes of any node that carries a path under here, using the ordinary com.codename1.io.FileSystemStorage API.

      On Apple platforms this is inside the App Group container rather than in your app's own sandbox, so a file written to FileSystemStorage's home directory is not visible to the extension. Always resolve paths against this value.

      Update published content by writing a NEW file and republishing the tree against it, never by rewriting a file already in the published tree. Another app can be reading a published file at any moment, and rewriting one in place refills the same file underneath that reader, which sees the two versions spliced together. Publishing the replacement under a new name and then calling publish gives every reader a whole document: the ones already reading finish the old file, and the ones that come after open the new one.

      Returns

      the shared directory path, or null when unsupported on this port

    • publish

      public static void publish(DocumentNode root)

      Publishes the tree the file browser should show, replacing whatever was published before.

      The call returns as soon as the index is persisted; the browser picks it up on its own schedule. Publishing the same tree twice is harmless.

      Parameters
      • root: the root of the tree, must not be null

    • setRemoteEndpoint

      public static void setRemoteEndpoint(String endpoint, String authToken)

      Sets the HTTPS endpoint the platform reader fetches remote content from, and the bearer token it presents. Call before publishing nodes that carry a remoteId.

      The endpoint is contacted by the extension, not by your app, so it must be reachable without any state your app holds in memory -- the token given here is all it carries. Keep the token fresh by calling this again whenever you renew it; the extension reads the latest value each time it runs.

      The developer guide documents the two requests the reader makes and the JSON it expects back.

      Parameters
      • endpoint: the HTTPS base URL, or null to serve only from the shared directory
      • authToken: a bearer token sent with each request, or null for none
      Throws
      • IllegalArgumentException: when the endpoint is not HTTPS

    • setRemoteEndpoint

      public static void setRemoteEndpoint(String endpoint)

      Sets the HTTPS endpoint with no bearer token.

      Parameters
      • endpoint: the HTTPS base URL, or null to serve only from the shared directory

    • signalChange

      public static void signalChange()
      Asks the platform browser to re-enumerate the published tree. publish already does this; call it directly only when the bytes behind an unchanged tree changed.

    • clear

      public static void clear()

      Withdraws everything: the published tree disappears from the file browser, the endpoint and token are forgotten and the shared directory is emptied. Call this on logout -- the shared container outlives your process, so documents left there stay browsable by anyone holding the device.

      Everything the app owns is gone by the time this returns. On Apple platforms one step is the system's rather than the app's: taking the published location away is a request to the file provider daemon, and this waits a few seconds for it. If the daemon is slow the call returns anyway rather than holding up a logout, and items the system had already copied out of the container can stay visible until it catches up. Nothing is left pending on the app's side, and there is no API that makes the system faster.

    • setBridge

      public static void setBridge(DocumentProviderBridge b)

      Test seam: installs a bridge, bypassing platform resolution.

      Parameters
      • b: the bridge, or null to resolve from the platform again