Java Code Examples for android.content.ContentProviderClient#releaseQuietly()

/**
 * Return thumbnail representing the document at the given URI. Callers are
 * responsible for their own in-memory caching.
 *
 * @param documentUri document to return thumbnail for, which must have
 *            {@link Document#FLAG_SUPPORTS_THUMBNAIL} set.
 * @param size optimal thumbnail size desired. A provider may return a
 *            thumbnail of a different size, but never more than double the
 *            requested size.
 * @param signal signal used to indicate if caller is no longer interested
 *            in the thumbnail.
 * @return decoded thumbnail, or {@code null} if problem was encountered.
 * @see DocumentsProvider#openDocumentThumbnail(String, Point,
 *      android.os.CancellationSignal)
 */
public static Bitmap getDocumentThumbnail(
        ContentResolver resolver, Uri documentUri, Point size, CancellationSignal signal)
        throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            documentUri.getAuthority());
    try {
        return getDocumentThumbnail(client, documentUri, size, signal);
    } catch (Exception e) {
        if (!(e instanceof OperationCanceledException)) {
            Log.w(TAG, "Failed to load thumbnail for " + documentUri + ": " + e);
        }
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Delete the given document.
 *
 * @param documentUri document with {@link Document#FLAG_SUPPORTS_DELETE}
 * @return if the document was deleted successfully.
 */
public static boolean deleteDocument(ContentResolver resolver, Uri documentUri)
        throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            documentUri.getAuthority());
    try {
        deleteDocument(client, documentUri);
        return true;
    } catch (Exception e) {
        Log.w(TAG, "Failed to delete document", e);
        rethrowIfNecessary(resolver, e);
        return false;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Moves the given document under a new parent.
 *
 * @param sourceDocumentUri document with {@link Document#FLAG_SUPPORTS_MOVE}
 * @param sourceParentDocumentUri parent document of the document to move.
 * @param targetParentDocumentUri document which will become a new parent of the source
 *         document.
 * @return the moved document, or {@code null} if failed.
 */
public static Uri moveDocument(ContentResolver resolver, Uri sourceDocumentUri,
        Uri sourceParentDocumentUri, Uri targetParentDocumentUri) throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            sourceDocumentUri.getAuthority());
    try {
        return moveDocument(client, sourceDocumentUri, sourceParentDocumentUri,
                targetParentDocumentUri);
    } catch (Exception e) {
        Log.w(TAG, "Failed to move document", e);
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Removes the given document from a parent directory.
 *
 * <p>In contrast to {@link #deleteDocument} it requires specifying the parent.
 * This method is especially useful if the document can be in multiple parents.
 *
 * @param documentUri document with {@link Document#FLAG_SUPPORTS_REMOVE}
 * @param parentDocumentUri parent document of the document to remove.
 * @return true if the document was removed successfully.
 */
public static boolean removeDocument(ContentResolver resolver, Uri documentUri,
        Uri parentDocumentUri) throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            documentUri.getAuthority());
    try {
        removeDocument(client, documentUri, parentDocumentUri);
        return true;
    } catch (Exception e) {
        Log.w(TAG, "Failed to remove document", e);
        rethrowIfNecessary(resolver, e);
        return false;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Finds the canonical path from the top of the document tree.
 *
 * The {@link Path#getPath()} of the return value contains the document ID
 * of all documents along the path from the top the document tree to the
 * requested document, both inclusive.
 *
 * The {@link Path#getRootId()} of the return value returns {@code null}.
 *
 * @param treeUri treeUri of the document which path is requested.
 * @return the path of the document, or {@code null} if failed.
 * @see DocumentsProvider#findDocumentPath(String, String)
 */
public static Path findDocumentPath(ContentResolver resolver, Uri treeUri)
        throws FileNotFoundException {
    checkArgument(isTreeUri(treeUri), treeUri + " is not a tree uri.");

    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            treeUri.getAuthority());
    try {
        return findDocumentPath(client, treeUri);
    } catch (Exception e) {
        Log.w(TAG, "Failed to find path", e);
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Create a new document with given MIME type and display name.
 *
 * @param parentDocumentUri directory with {@link Document#FLAG_DIR_SUPPORTS_CREATE}
 * @param mimeType MIME type of new document
 * @param displayName name of new document
 * @return newly created document, or {@code null} if failed
 */
public static Uri createDocument(ContentResolver resolver, Uri parentDocumentUri,
        String mimeType, String displayName) throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            parentDocumentUri.getAuthority());
    try {
        return createDocument(client, parentDocumentUri, mimeType, displayName);
    } catch (Exception e) {
        Log.w(TAG, "Failed to create document", e);
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Change the display name of an existing document.
 * <p>
 * If the underlying provider needs to create a new
 * {@link Document#COLUMN_DOCUMENT_ID} to represent the updated display
 * name, that new document is returned and the original document is no
 * longer valid. Otherwise, the original document is returned.
 *
 * @param documentUri document with {@link Document#FLAG_SUPPORTS_RENAME}
 * @param displayName updated name for document
 * @return the existing or new document after the rename, or {@code null} if
 *         failed.
 */
public static Uri renameDocument(ContentResolver resolver, Uri documentUri,
        String displayName) throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            documentUri.getAuthority());
    try {
        return renameDocument(client, documentUri, displayName);
    } catch (Exception e) {
        Log.w(TAG, "Failed to rename document", e);
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Copies the given document.
 *
 * @param sourceDocumentUri document with {@link Document#FLAG_SUPPORTS_COPY}
 * @param targetParentDocumentUri document which will become a parent of the source
 *         document's copy.
 * @return the copied document, or {@code null} if failed.
 */
public static Uri copyDocument(ContentResolver resolver, Uri sourceDocumentUri,
        Uri targetParentDocumentUri) throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            sourceDocumentUri.getAuthority());
    try {
        return copyDocument(client, sourceDocumentUri, targetParentDocumentUri);
    } catch (Exception e) {
        Log.w(TAG, "Failed to copy document", e);
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Ejects the given root. It throws {@link IllegalStateException} when ejection failed.
 *
 * @param rootUri root with {@link Root#FLAG_SUPPORTS_EJECT} to be ejected
 */
public static void ejectRoot(ContentResolver resolver, Uri rootUri) {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            rootUri.getAuthority());
    try {
        ejectRoot(client, rootUri);
    } catch (RemoteException e) {
        e.rethrowAsRuntimeException();
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Returns metadata associated with the document. The type of metadata returned
 * is specific to the document type. For example the data returned for an image
 * file will likely consist primarily or soley of EXIF metadata.
 *
 * <p>The returned {@link Bundle} will contain zero or more entries depending
 * on the type of data supported by the document provider.
 *
 * <ol>
 * <li>A {@link DocumentsContract.METADATA_TYPES} containing a {@code String[]} value.
 *     The string array identifies the type or types of metadata returned. Each
 *     value in the can be used to access a {@link Bundle} of data
 *     containing that type of data.
 * <li>An entry each for each type of returned metadata. Each set of metadata is
 *     itself represented as a bundle and accessible via a string key naming
 *     the type of data.
 * </ol>
 *
 * <p>Example:
 * <p><pre><code>
 *     Bundle metadata = DocumentsContract.getDocumentMetadata(client, imageDocUri, tags);
 *     if (metadata.containsKey(DocumentsContract.METADATA_EXIF)) {
 *         Bundle exif = metadata.getBundle(DocumentsContract.METADATA_EXIF);
 *         int imageLength = exif.getInt(ExifInterface.TAG_IMAGE_LENGTH);
 *     }
 * </code></pre>
 *
 * @param documentUri a Document URI
 * @return a Bundle of Bundles.
 * {@hide}
 */
public static Bundle getDocumentMetadata(ContentResolver resolver, Uri documentUri)
        throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            documentUri.getAuthority());

    try {
        return getDocumentMetadata(client, documentUri);
    } catch (Exception e) {
        Log.w(TAG, "Failed to get document metadata");
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}
 

/**
 * Creates an intent for obtaining a web link for the specified document.
 *
 * <p>Note, that due to internal limitations, if there is already a web link
 * intent created for the specified document but with different options,
 * then it may be overridden.
 *
 * <p>Providers are required to show confirmation UI for all new permissions granted
 * for the linked document.
 *
 * <p>If list of recipients is known, then it should be passed in options as
 * {@link Intent#EXTRA_EMAIL} as a list of email addresses. Note, that
 * this is just a hint for the provider, which can ignore the list. In either
 * case the provider is required to show a UI for letting the user confirm
 * any new permission grants.
 *
 * <p>Note, that the entire <code>options</code> bundle will be sent to the provider
 * backing the passed <code>uri</code>. Make sure that you trust the provider
 * before passing any sensitive information.
 *
 * <p>Since this API may show a UI, it cannot be called from background.
 *
 * <p>In order to obtain the Web Link use code like this:
 * <pre><code>
 * void onSomethingHappened() {
 *   IntentSender sender = DocumentsContract.createWebLinkIntent(<i>...</i>);
 *   if (sender != null) {
 *     startIntentSenderForResult(
 *         sender,
 *         WEB_LINK_REQUEST_CODE,
 *         null, 0, 0, 0, null);
 *   }
 * }
 *
 * <i>(...)</i>
 *
 * void onActivityResult(int requestCode, int resultCode, Intent data) {
 *   if (requestCode == WEB_LINK_REQUEST_CODE && resultCode == RESULT_OK) {
 *     Uri weblinkUri = data.getData();
 *     <i>...</i>
 *   }
 * }
 * </code></pre>
 *
 * @param uri uri for the document to create a link to.
 * @param options Extra information for generating the link.
 * @return an intent sender to obtain the web link, or null if the document
 *      is not linkable, or creating the intent sender failed.
 * @see DocumentsProvider#createWebLinkIntent(String, Bundle)
 * @see Intent#EXTRA_EMAIL
 */
public static IntentSender createWebLinkIntent(ContentResolver resolver, Uri uri,
        Bundle options) throws FileNotFoundException {
    final ContentProviderClient client = resolver.acquireUnstableContentProviderClient(
            uri.getAuthority());
    try {
        return createWebLinkIntent(client, uri, options);
    } catch (Exception e) {
        Log.w(TAG, "Failed to create a web link intent", e);
        rethrowIfNecessary(resolver, e);
        return null;
    } finally {
        ContentProviderClient.releaseQuietly(client);
    }
}