Este post mostra como você pode começar a usar o Couchbase Lite em seu aplicativo iOS. O Couchbase Lite é um banco de dados JSON incorporado que pode funcionar de forma autônoma, em uma rede P2P ou com um Sync Gateway como um endpoint remoto. Embora estejamos analisando a estrutura no contexto de um aplicativo iOS em Swift, tudo o que foi discutido aqui se aplica igualmente a aplicativos móveis desenvolvidos em qualquer outra plataforma (Android, iOS (ObjC), Xamarin). Os desvios serão especificados como tal. Fique atento às postagens relacionadas às outras plataformas!
OBSERVAÇÃO: Discutiremos o Couchbase Mobile v1.4, que é a versão de produção atual. Há uma versão mais recente Versão 2.0 do Developer Preview do Couchbase Mobile . Vamos nos aprofundar nesse assunto em um post futuro.
Histórico
O Couchbase Mobile Stack inclui o Couchbase Server, o Couchbase Sync Gateway e o banco de dados incorporado Couchbase Lite. Você pode saber mais sobre o servidor na seção Guia de introdução ao Couchbase Server e o Sync Gateway na seção Guia de introdução ao Couchbase Sync Gateway.
Presumo que você esteja familiarizado com o desenvolvimento de aplicativos iOS e com noções básicas de Swift. Se quiser ler sobre bancos de dados NoSQL ou Couchbase, você pode encontrar muitos recursos no site Couchbase local.
O Couchbase é de código aberto. Tudo o que usarei aqui é gratuito para ser testado.
Couchbase Lite
O Couchbase Lite pode ser usado em vários modos de implantação.
- Opção 1: Pode ser usado como um banco de dados incorporado independente e multiplataforma em um dispositivo
- Opção 2: Pode ser usado em conjunto com um Sync Gateway remoto que permita a sincronização de dados entre dispositivos. Esse caso pode ser estendido para incluir a pilha completa do Couchbase com o Couchbase Server. Do ponto de vista do Couchbase Lite no dispositivo, não deve importar se há um servidor Couchbase ou não, pois o Couchbase Lite fará a interface com o Sync Gateway remoto.
- Opção 3: Pode ser usado em um modo P2P
Vamos nos concentrar na Opção 1 aqui.
API nativa
O Couchbase Lite expõe uma API nativa para iOS, Android e Windows que permite que os aplicativos interajam facilmente com a plataforma Couchbase. Como desenvolvedor de aplicativos, você não precisa se preocupar com os aspectos internos do banco de dados incorporado do Couchbase Lite, mas pode se concentrar na criação de seu aplicativo incrível. A API nativa permite que você interaja com a estrutura do Couchbase Lite da mesma forma que faria com outras estruturas/subsistemas da plataforma. Novamente, discutiremos o Couchbase Mobile v1.4 nesta postagem do blog. Você pode obter uma listagem completa das APIs em nosso Desenvolvedor do Couchbase local.
Integração
Há muitas opções para integrar a estrutura do Couchbase Lite em seu aplicativo iOS. Provavelmente, a mais simples é usar sistemas de gerenciamento de dependências, como o Cocoápodes ou Cartagomas, se preferir, há a opção de incluir manualmente a estrutura em seu projeto de aplicativo. Dê uma olhada em nosso Guia de introdução ao Couchbase Mobile para as várias opções de integração.
Observação que, no caso de um aplicativo Swift, após importar a estrutura, você terá que criar um Bridging Header (se seu aplicativo ainda não tiver um) e importar os seguintes arquivos
|
1 2 |
#import <CouchbaseLite/CouchbaseLite.h> #import <CouchbaseLiteListener/CBLListener.h> |
Aplicativo de demonstração
Faça o download do projeto de demonstração do Xcode a partir deste Repositório do Github . Usaremos esse aplicativo como exemplo no restante do blog.
|
1 |
git clone git@github.com:couchbaselabs/couchbase-lite-ios-starterapp.git |
Este aplicativo usa o Cocoapods para integrar a estrutura do Couchbase Lite e tem o objetivo de familiarizá-lo com os conceitos básicos do uso da estrutura do Couchbase Lite. Após o download, crie e execute o aplicativo. Você pode usar este aplicativo como ponto de partida e estendê-lo para testar as outras APIs.
Fluxo de trabalho básico
Criação de um banco de dados local
Abra o DBMainMenuViewController.swift e localize o arquivo createDBWithName função.
Isso criará um banco de dados com o nome especificado no caminho padrão (/Library/Application Support). Você pode especificar um diretório diferente ao instanciar o Gerenciador de CBL classe.
|
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 } |
- Crie o objeto CBLDatabaseOptions para associá-lo ao banco de dados. Por exemplo, você pode definir a chave de criptografia a ser usada com seu banco de dados usando a propriedade encryptionKey. Explore as outras opções em CBLDatabaseOptions classe.
- Os nomes dos bancos de dados devem estar em letras minúsculas. O aplicativo de amostra colocará os nomes em minúsculas automaticamente. Se for bem-sucedido, será criado um novo banco de dados local, caso ele não exista. Se existir, será retornado um identificador para o banco de dados existente.
Listando os bancos de dados
Isso é muito simples. Abra a seção DBListTableViewController.swift arquivo. O arquivo todos os nomes de bancos de dados propriedade em Gerenciador de CBL lista os bancos de dados que foram criados.
Adição de um novo documento a um banco de dados
Abra o DocListTableViewController.swift e localize o arquivo createDocWithName função.
|
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 dessa chamada, um documento é criado com um ID exclusivo
- É possível especificar um conjunto de propriedades do usuário como pares . Há uma alternativa na qual você pode usar CBLDocumentModel para especificar os dados do seu aplicativo. O objeto CBLDocumentModel está disponível apenas para a plataforma iOS. Usaremos as propriedades em nosso exemplo
Isso cria uma nova revisão do documento com as propriedades de usuário especificadas
Listagem de documentos no banco de dados
Abra o DocListTableViewController.swift e localize o arquivo getAllDocumentForDatabase função
|
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 } |
- Obter o identificador do banco de dados com o nome especificado
- Criar um CBLQuery objeto. Essa consulta é usada para buscar todos os documentos. Você pode criar um objeto de consulta regular ou um objeto de consulta "ao vivo". O objeto de consulta "ao vivo" é do tipo CBLLiveQuery que se atualiza automaticamente sempre que o banco de dados é alterado de forma a afetar os resultados da consulta
- O objeto de consulta tem várias propriedades que podem ser ajustadas para personalizar os resultados. Tente modificar as propriedades e veja o efeito nos resultados
- Você terá de adicionar explicitamente um observador ao objeto Live Query para ser notificado das alterações no banco de dados. Falaremos mais sobre isso na seção "Observando alterações em documentos no banco de dados". Não se esqueça de remover o observador e parar de observar as alterações quando não precisar mais dele!
- Execute a consulta de forma assíncrona. Você também pode fazer isso de forma síncrona, se preferir, mas provavelmente é recomendável fazê-lo de forma assíncrona se os conjuntos de dados forem grandes.
- Quando a consulta for executada com êxito, você receberá uma mensagem CBLQueryEnumerator objeto. O enumerador de consultas permite que você enumere os resultados. Ele se presta muito bem como fonte de dados para a exibição de tabela que mostra os resultados
Edição de um documento existente
Abra o DocListTableViewController.swift e localize o arquivo updateDocWithName função.
|
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 } |
- Obter o identificador do documento que precisa ser editado. O CBLQueryEnumerator pode ser consultado para buscar o identificador do documento no índice selecionado
- Atualize as propriedades do usuário como pares . Há uma alternativa em que você pode usar CBLDocumentModel para especificar os dados do seu aplicativo. Isso só está disponível no iOS. Usaremos as propriedades em nosso exemplo.
- As atualizações do documento exigirão um revisionId para indicar explicitamente a revisão do documento que precisa ser atualizada. Isso é especificado usando "_rev". Isso é necessário para a resolução de conflitos. Você pode encontrar mais detalhes aqui. Isso cria uma nova revisão do documento com as propriedades de usuário especificadas
Exclusão de um documento existente
Abra o DocListTableViewController.swift e localize o arquivo deleteDocAtIndex função.
|
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 } |
- Obter o identificador do documento que precisa ser editado. O CBLQueryEnumerator pode ser consultado para buscar o identificador do documento no índice selecionado
- Excluir o documento. Isso exclui todas as revisões do documento
Observação de alterações em documentos no banco de dados
Abra o DocListTableViewController.swift e localize o arquivo addLiveQueryObserverAndStartObserving função
|
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 sobre alterações no banco de dados que afetem os resultados da consulta, adicione um observador ao objeto Live Query. Esse é um caso em que as versões do Swift/ Obj C diferem de outras plataformas móveis. Se você estiver desenvolvendo em outras plataformas, poderá chamar a função addChangeListener API no objeto Live Query. No entanto, no Couchbase Lite 1.4, essa API não é compatível com as plataformas iOS e, em vez disso, aproveitaremos o padrão Key-Value-Observer do iOS para sermos notificados das alterações. Adicione um observador KVO ao objeto Live Query para começar a observar as alterações na propriedade "rows" do objeto Live Query
- Comece a observar as mudanças
Sempre que houver uma alteração no banco de dados que afete a propriedade "rows" do objeto LiveQuery, seu aplicativo será notificado das alterações. Ao receber a notificação de alteração, você pode atualizar a interface do usuário, que, nesse caso, seria recarregar a exibição da tabela.
|
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() } } |
Exclusão de um banco de dados
Abra o DBListTableViewController.swift e localize o arquivo deleteDatabaseAtIndex função.
|
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 } |
A exclusão de um banco de dados é tratada por meio de uma simples chamada delete() no banco de dados.
Conclusão
Como você pode ver, é bastante simples integrar uma versão autônoma do Couchbase Lite em seu aplicativo iOS novo ou existente. Você pode fazer o download do aplicativo de amostra discutido nesta postagem em Repositório do Github e experimente explorar as várias interfaces. Se tiver mais perguntas, sinta-se à vontade para entrar em contato comigo pelo Twitter @rajagp ou envie-me um e-mail priya.rajagopal@couchbase.com.
O Fóruns de desenvolvimento do Couchbase Mobile é outro ótimo lugar para obter respostas para suas perguntas relacionadas a dispositivos móveis. Além disso, dê uma olhada no Portal do desenvolvedor do Couchbase para saber mais sobre o Couchbase Mobile.
[...] do Couchbase Server, do Sync Gateway e do banco de dados NoSQL incorporado Couchbase Lite. Em uma postagem anterior, discutimos como o Couchbase Lite pode ser usado como um banco de dados NoSQL incorporado autônomo em aplicativos iOS. [...]
[...] modo. Nesta postagem, não abordaremos os detalhes da integração com o Couchbase Lite. O blog Getting Started With Couchbase Lite é um bom lugar para começar a [...]