Document Provider en Android: Introducción

1. <provider
2. android:name="com.example.MyCloudProvider"
3. android:authorities="com.example.mycloudprovider"
4. android:exported="true"
5. android:grantUriPermissions="true"
6. android:permission="android.permission.MANAGE_DOCUMENTS"
7. android:enabled="@bool/isAtLeastKitKat">

Tenemos toda la información relativa a los campos que necesitamos aquí, pero vamos a comentar algunos de ellos:

• Authorities: String único que será el prefijo de todas las Uris que tengamos en nuestro document provider. Podríamos crear un String y recuperarlo desde allí, o incluso añadirlo al gradle.build de la aplicación para acceder de forma sencilla a este valor, porque vamos a utilizarlo posteriormente.
• Enabled: Si soportamos versiones previas a Kitkat, tendríamos que añadir un boolean para determinar si estamos en una versión anterior a KitKat o no, tal y cómo se ve en el código superior. Si soportamos solo versiones superiores, podríamos suprimir este campo, porque estará habilitado por defecto.

Tarea previa: Los Document Contracts

Antes de comenzar con la funcionalidad básica, vamos a recordar dos DocumentsContract que nos permitirán construir la estructura que va a tener nuestro Document Provider.

En primer lugar el Root que nos permitirá establecer los campos que tendrá nuestra raíz de documentos. Podemos añadir más columnas, que aportarán información adicional, pero lo mínimo necesario para comenzar sería lo siguiente:

• COLUMN_ROOT_ID
• COLUMN_ICON
• COLUMN_TITLE
• COLUMN_FLAGS
• COLUMN_DOCUMENT_ID

Cada raíz comienza con un document_id que será el identificador único y superior de un árbol de directorios, que puede ser una cuenta, o un tipo de almacenamiento etc y que podrá contener archivos o más directorios que se tratarán con el siguiente Contract, el Document.

Con esto, estableceremos la información para cada archivo. Lo mínimo necesario para comenzar:

• COLUMN_DOCUMENT_ID
• COLUMN_DISPLAY_NAME
• COLUMN_MIME_TYPE
• COLUMN_FLAGS
• COLUMN_SIZE
• COLUMN_LAST_MODIFIED

Los Flags de ambos contracts nos indicarán las operaciones disponibles para ese root o ese documento. Por ejemplo, si queremos permitir operaciones de creación, renombrado o borrado de documentos, tendriamos que añadir los flags correspondientes.

Comenzamos por la raíz: queryRoots

En esta función tendremos que devolver un cursor con la información relativa que queramos añadir al Root. Podemos añadir una nueva fila por cuenta, o incluso dividir las cuentas por tipo de documento que queramos mostrar: Imágenes, pdf, videos etc con los flags que consideremos oportunos para cada uno de ellos.

De esta forma poblaríamos nuestro Root, y podríamos conseguir que muestre algo similar a esto:

Listado de Roots

Mostrar los documentos en el provider: queryChildDocuments

Ahora que hemos conseguido mostrar nuestra raíz en el Provider, vamos a listar los documentos que hay en ella. Para ello usaremos la función queryChildDocuments. Se llamará a este método cada vez que seleccionemos un directorio en nuestro provider.

Esta función devolverá un MatrixCursor que tendremos que poblar con los ficheros que se encuentren en el directorio cuyo id recibimos por parámetro. Añadiremos una fila por cada fichero siguiendo el Document Contract comentado anteriormente.

Si todo ha ido bien, podremos ver nuestra lista de archivos cuando seleccionemos nuestra raíz:

Lista de archivos contenidos en el directorio

Apuntando a un documento: queryDocument

Ahora que tenemos nuestra lista de ficheros y directorios, nos interesa consultar cada uno de ellos. Para ello utilizaremos queryDocument.

Esta función es similar a la anterior, pero solo para el documento específico. Es decir, devolveremos un Cursor pero solo con los metadatos del documento que queremos consultar. Debería ser lo más rápida posible (Sin peticiones de red ni nada por el estilo).

Abriendo un Documento: openDocument

Para abrir un documento, tendremos que devolver un ParcelFileDescriptor que represente al fichero cuyo Id recibimos por parámetro. Además del id, obtendremos también el modo por parámetro, ya sea lectura o escritura. Para hacerlo lo más sencillo posible, vamos a establecer solo modo lectura.

Con esto ya quedarían resueltos todos las funciones mínimas y necesarias para tener nuestro Document Provider funcional. Pero hay algunas cosas que comentar todavía.

Notificar al Document Provider de un cambio

Podemos notificar al Document Provider de un cambio añadiendo al cursor un listener. De esta forma cuando actualicemos un archivo, o creamos un documento, notificamos al listener y actualizará la vista.

Esto puede ahorrarnos costes innecesarios de sincronización tras cada operación que realicemos y se realiza mediante Uris. Estas Uris se generarán con la authority mencionada en el apartado del manifest. Podríamos crear una funcion como esta para generar estas Uris:

1. private fun toNotifyUri(uri: Uri): Uri = DocumentsContract.buildDocumentUri(DOCUMENTS_PROVIDER_AUTHORITY, uri.toString())

Vamos a aplicarlo. Podríamos colocar un listener en nuestro queryChildDocuments, que se ocupa de actualizar la vista de los archivos si hay algún cambio, por ejemplo al renombrar o borrar un archivo. Antes de retornar el cursor, establecemos una uri de notificación tal que así:

1. resultCursor.setNotificationUri(context.contentResolver, toNotifyUri(Uri.parse(folderId)))

De tal forma que cuando actualizamos un archivo, por ejemplo al renombrarlo, llamamos al content resolver y notificamos el cambio con la misma Uri que establecimos en el listener:

1. context.contentResolver.notifyChange(toNotifyUri(Uri.parse(folderId)), null)

Si todo ha salido bien, el cambio se verá reflejado al momento y el coste de esta actualización será mínimo.

Notificación de errores

La notificación de errores se realiza mediante excepciones, lo cuál no es muy agradable de tratar, pero es lo que hay. Uno de los puntos que tiene que mejorar el Document Provider.

Cuando al realizar una operación, obtengamos un resultado no esperado, lanzamos una excepción y el Provider ya se encargará de avisar al usuario de que la operación no se completó correctamente mediante un SnackBar.

Que más funcionalidades nos ofrece el Document Provider

Además de todo lo comentado anteriormente, el document provider tiene más que ofrecer. Y es que sólo hemos comentado lo más básico, pero todavía podríamos implementar las siguientes funcionalidades:

• createDocument: Permite la creación de ficheros o directorios dentro de nuestro Document Provider
• queryRecentDocuments: Permite mostrar los últimos archivos modificados en nuestro Document Provider
• openDocumentThumbnail: Permite mostrar miniaturas de nuestros documentos
• querySearchDocuments: Permite la búsqueda de archivos en nuestra aplicación
• deleteDocument: Borrado de archivos
• renameDocument: Renombrado de archivos
• copyDocument: Copiar archivos dentro de nuestro document provider
• moveDocument: Mover archivos dentro de nuestro document provider

Pero esto lo dejaremos para la próxima.