Este post explica cómo puedes empezar a usar Couchbase Lite en tu aplicación iOS. Couchbase Lite es una base de datos JSON embebida que puede funcionar de forma autónoma, en una red P2P, o con un Sync Gateway como endpoint remoto. Aunque veremos el framework en el contexto de una App iOS en Swift, todo lo que se discute aquí se aplica igualmente a apps móviles desarrolladas en cualquier otra plataforma (Android, iOS (ObjC), Xamarin). Las desviaciones se especificarán como tales. ¡Permanece atento a los posts relacionados para las otras plataformas!
NOTA: Vamos a discutir Couchbase Mobile v1.4 que es la versión de producción actual. Hay una versión Vista previa para desarrolladores de la versión 2.0 de Couchbase Mobile . Hablaremos de ello en un próximo artículo.
Fondo
Couchbase Mobile Stack se compone de Couchbase Server, Couchbase Sync Gateway y Couchbase Lite embedded Database. Puede obtener más información sobre el servidor en la Guía de introducción a Couchbase Server y el Sync Gateway en el Guía de introducción a Couchbase Sync Gateway.
Asumiré que estás familiarizado con el desarrollo de aplicaciones iOS y los conceptos básicos de Swift. Si quieres leer sobre bases de datos NoSQL o Couchbase, puedes encontrar un montón de recursos en el Couchbase sitio.
Couchbase es de código abierto. Todo lo que voy a utilizar aquí es libre de probar.
Couchbase Lite
Couchbase Lite puede utilizarse en varios modos de despliegue.
- Opción 1: Puede utilizarse como base de datos independiente multiplataforma integrada en un dispositivo.
- Opción 2: Se puede utilizar junto con un Sync Gateway remoto que le permitiría sincronizar datos entre dispositivos. Este caso se puede extender para incluir la pila completa de Couchbase con el Couchbase Server. Desde la perspectiva de Couchbase Lite en el dispositivo, no debería importar si hay un Couchbase Server o no, ya que Couchbase Lite interactuará con el Sync Gateway remoto.
- Opción 3: Puede utilizarse en modo P2P
Aquí nos centraremos en la Opción 1.
API nativa
Couchbase Lite expone una API nativa para iOS, Android y Windows que permite a las aplicaciones interactuar fácilmente con la plataforma Couchbase. Como desarrollador de aplicaciones, no tienes que preocuparte por el funcionamiento interno de la base de datos integrada de Couchbase Lite, sino que puedes centrarte en crear tu aplicación. La API nativa te permite interactuar con el framework de Couchbase Lite como lo harías con otros frameworks/subsistemas de la plataforma. De nuevo, hablaremos de Couchbase Mobile v1.4 en esta entrada del blog. Puedes obtener una lista completa de las APIs en nuestro Desarrollador Couchbase sitio.
Integración
Hay muchas opciones para integrar el framework Couchbase Lite en tu aplicación iOS. Probablemente la más sencilla sea utilizar sistemas de gestión de dependencias como Cocoapods o Cartagopero si lo prefiere, puede incluir manualmente el framework en su proyecto de aplicación. Echa un vistazo a nuestro Guía de inicio de Couchbase Mobile para las distintas opciones de integración.
Nota que en el caso de una aplicación Swift, después de importar el framework, tendrás que crear un Bridging Header (si tu aplicación no tiene ya uno) e importar los siguientes archivos
|
1 2 |
#import <CouchbaseLite/CouchbaseLite.h> #import <CouchbaseLiteListener/CBLListener.h> |
Aplicación de demostración
Descargue el proyecto de demostración de Xcode desde Repo de Github . Utilizaremos esta aplicación como ejemplo en el resto del blog.
|
1 |
git clone git@github.com:couchbaselabs/couchbase-lite-ios-starterapp.git |
Esta aplicación utiliza Cocoapods para integrar el framework Couchbase Lite y pretende familiarizarte con los conceptos básicos del uso del framework Couchbase Lite. Una vez descargada, compila y ejecuta la aplicación. Puedes usar esta aplicación como punto de partida y extenderla para probar otras APIs.
Flujo de trabajo básico
Creación de una base de datos local
Abra el DBMainMenuViewController.swift y localice el archivo createDBWithName función.
Esto creará una base de datos con el nombre especificado en la ruta por defecto (/Library/Application Support). Puede especificar un directorio diferente cuando instale la aplicación CBLManager clase.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
do { // 1: Set Database Options let options = CBLDatabaseOptions() options.storageType = kCBLSQLiteStorage options.create = true // 2: Create a DB if it does not exist else return handle to existing one try cbManager.openDatabaseNamed(name.lowercased(), with: options) } catch { // handle error } |
- Crea el objeto CBLDatabaseOptions para asociarlo con la base de datos. Por ejemplo, puede establecer la clave de cifrado que se utilizará con la base de datos mediante la propiedad encryptionKey. Explore las otras opciones en CBLDatabaseOptions clase.
- Los nombres de las bases de datos deben estar en minúsculas. La aplicación de ejemplo pondrá automáticamente los nombres en minúsculas. Si tiene éxito, se creará una nueva base de datos local si no existe. Si existe, se devolverá un "handle" de la base de datos existente.
Listado de bases de datos
Esto es muy sencillo. Abra el DBListTableViewController.swift expediente. La dirección allDatabaseNames propiedad en CBLManager enumera las bases de datos creadas.
Añadir un nuevo documento a una base de datos
Abra el DocListTableViewController.swift y localice el archivo crearDocConNombre función.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
do { // 1: Create Document with unique Id let doc = self.db?.createDocument() // 2: Construct user properties Object let userProps = [DocumentUserProperties.name.rawValue:name,DocumentUserProperties.overview.rawValue:overview] // 3: Add a new revision with specified user properties let _ = try doc?.putProperties(userProps) } catch { // handle error } |
- Como resultado de esta llamada, se crea un Documento con un Id único
- Puede especificar un conjunto de propiedades de usuario como pares . Existe una alternativa en la que puede utilizar CBLDocumentModel para especificar los datos de su aplicación. La dirección CBLDocumentModel sólo está disponible para la plataforma iOS. En nuestro ejemplo utilizaremos las propiedades <key:value
Esto crea una nueva revisión del documento con las propiedades de usuario especificadas
Listado de documentos en la base de datos
Abra el DocListTableViewController.swift y localice el archivo getAllDocumentForDatabase función
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
do { guard let dbName = dbName else { return } // 1. Get handle to DB with specified name self.db = try cbManager.existingDatabaseNamed(dbName) // 2. Create Query to fetch all documents. You can set a number of properties // on the query object liveQuery = self.db?.createAllDocumentsQuery().asLive() guard let liveQuery = liveQuery else { return } // 3: You can optionally set a number of properties on the query object. // Explore other properties on the query object liveQuery.limit = UInt(UINT32_MAX) // All documents // query.postFilter = //4. Start observing for changes to the database self.addLiveQueryObserverAndStartObserving() // 5: Run the query to fetch documents asynchronously liveQuery.runAsync({ (enumerator, error) in switch error { case nil: // 6: The "enumerator" is of type CBLQueryEnumerator and // is an enumerator for the results self.docsEnumerator = enumerator default: } }) } catch { // handle error } |
- Obtener el acceso a la base de datos con el nombre especificado
- Crear un CBLQuery objeto. Esta consulta se utiliza para obtener todos los documentos. Puede crear un objeto de consulta normal o un objeto de consulta "en vivo". El objeto de consulta "en vivo" es de tipo CBLLiveQuery que se actualiza automáticamente cada vez que se producen cambios en la base de datos que afectan a los resultados de la consulta.
- El objeto de consulta tiene una serie de propiedades que pueden modificarse para personalizar los resultados. Pruebe a modificar las propiedades y vea el efecto en los resultados
- Tendrá que añadir explícitamente un observador al objeto Live Query para ser notificado de los cambios en la base de datos. Discutiremos esto más a fondo en la sección "Observar cambios en los documentos de la base de datos". No olvides retirar el observador y dejar de observar los cambios cuando ya no lo necesites.
- Ejecute la consulta de forma asíncrona. También puede hacerlo de forma sincrónica si lo prefiere, pero probablemente sea recomendable hacerlo de forma asincrónica si los conjuntos de datos son grandes.
- Una vez que la consulta se ejecuta correctamente, se obtiene un mensaje CBLQueryEnumerator objeto. El enumerador de consultas permite enumerar los resultados. Se presta muy bien como fuente de datos para la vista de tabla que muestra los resultados
Editar un documento existente
Abra el DocListTableViewController.swift y localice el archivo updateDocConNombre función.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
do { // 1: Get the document associated with the row let doc = self.docAtIndex(index) // 2: Construct user properties Object with updated values var userProps = [DocumentUserProperties.name.rawValue:name,DocumentUserProperties.overview.rawValue:overview] // 3: If a previous revision of document exists, make sure to specify that. // SInce its an update, it should exist! if let revId = doc?.currentRevisionID { userProps["_rev"] = revId } // 4: Add a new revision with specified user properties let savedRev = try doc?.putProperties(userProps) } catch { // handle error } fileprivate func docAtIndex(_ index:Int) -> CBLDocument? { // 1. Get the CBLQueryRow object at specified index let queryRow = self.docsEnumerator?.row(at: UInt(index)) // 2: Get the document associated with the row let doc = queryRow?.document return doc } |
- Obtener el control del documento que necesita ser editado. La dirección CBLQueryEnumerator se puede consultar para obtener el nombre del documento en el índice seleccionado
- Actualice las propiedades del usuario como pares . Existe una alternativa en la que puede utilizar CBLDocumentModel para especificar los datos de su aplicación. Esto sólo está disponible en iOS. Usaremos propiedades en nuestro ejemplo.
- Las actualizaciones del documento requerirán un revisionId para indicar explícitamente la revisión del documento que debe actualizarse. Esto se especifica utilizando "_rev". Esto es necesario para la resolución de conflictos. Más información aquí. Esto crea una nueva revisión del documento con las propiedades de usuario especificadas
Borrar un documento existente
Abra el DocListTableViewController.swift y localice el archivo deleteDocAtIndex función.
|
1 2 3 4 5 6 7 8 9 10 |
do { // 1: Get the document associated with the row let doc = self.docAtIndex(index) // 2: Delete the document try doc?.delete() } catch { // Handle error } |
- Obtiene el manejador del documento que necesita ser editado. Se puede consultar el CBLQueryEnumerator para obtener el identificador del documento en el índice seleccionado.
- Borrar el documento. Esto borra todas las revisiones del documento
Observar los cambios en los documentos de la base de datos
Abra el DocListTableViewController.swift y localice el archivo addLiveQueryObserverAndStartObserving función
|
1 2 3 4 5 |
// 1. iOS Specific. Add observer to the live Query object liveQuery.addObserver(self, forKeyPath: "rows", options: NSKeyValueObservingOptions.new, context: nil) // 2. Start observing changes liveQuery.start() |
- Para ser notificado de los cambios en la base de datos que afectan a los resultados de la consulta, añada un observador al objeto Live Query . Este es un caso en el que las versiones Swift/ Obj C difieren de otras plataformas móviles. Si está desarrollando en otras plataformas, puede llamar a la función addChangeListener API en el objeto Live Query. Sin embargo, en Couchbase Lite 1.4, esta API no está soportada en las plataformas iOS y en su lugar aprovecharemos el patrón Key-Value-Observer de iOS para ser notificados de los cambios. Añadir un observador KVO al objeto Live Query para empezar a observar los cambios en la propiedad "rows" del objeto Live Query.
- Empezar a observar los cambios
Siempre que se produzca un cambio en la base de datos que afecte a la propiedad "rows" del objeto LiveQuery, tu aplicación recibirá una notificación de cambios. Cuando recibas la notificación de cambio, puedes actualizar tu UI, que en este caso sería recargar la tableview.
|
1 2 3 4 5 6 |
override func observeValue(forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey : Any]?, context: UnsafeMutableRawPointer?) { if keyPath == "rows" { self.docsEnumerator = self.liveQuery?.rows tableView.reloadData() } } |
Eliminar una base de datos
Abra el DBListTableViewController.swift y localice el archivo deleteDatabaseAtIndex función.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
do { // 1. Get handle to database if exists let db = try cbManager.existingDatabaseNamed(dbToDelete) // 2. Delete the database try db.delete() // 3. update local bookkeeping self.dbNames?.remove(at: indexPath.row) // 4. Update UI tableView.deleteRows(at: [indexPath], with: .automatic) } catch { // handle error } |
La eliminación de una base de datos se gestiona mediante una simple llamada a delete() en la base de datos.
Conclusión
Como puedes ver, es bastante sencillo integrar una versión independiente de Couchbase Lite en tu nueva o existente aplicación iOS. Puedes descargar la aplicación de ejemplo de la que hablamos en este post desde Repo de Github y prueba a explorar las distintas interfaces. Si tienes más preguntas, no dudes en ponerte en contacto conmigo en Twitter @rajagp o envíeme un correo electrónico priya.rajagopal@couchbase.com.
En Foros de desarrollo de Couchbase Mobile es otro buen lugar para resolver tus dudas sobre móviles. Además, echa un vistazo a la Portal para desarrolladores de Couchbase para obtener más información sobre Couchbase Mobile.
[...] de Couchbase Server, Sync Gateway y Couchbase Lite embedded NoSQL Database. En un post anterior, hablamos de cómo Couchbase Lite se puede utilizar como una base de datos NoSQL incrustada independiente en aplicaciones iOS. [...]
[...] modo. En este post, no vamos a repasar los detalles de la integración con Couchbase Lite. El blog Getting Started With Couchbase Lite es un buen lugar para empezar a [...]