diff --git a/mobile/noarch/documentation/changes.md b/mobile/noarch/documentation/changes.md index 6bb02be..74ffeb6 100644 --- a/mobile/noarch/documentation/changes.md +++ b/mobile/noarch/documentation/changes.md @@ -1,3 +1,8 @@ +2014-06-10 + +Initial release of module based on [couchbase-lite-ios](https://github.com/couchbase/couchbase-lite-ios) +and [couchbase-lite-android](https://github.com/couchbase/couchbase-lite-android) version 1.0.0. + 2014-01-20 The couchbase-lite-ios project is undergoing another set of API changes, which diff --git a/mobile/noarch/documentation/index.md b/mobile/noarch/documentation/index.md index 93c0654..d3334f9 100644 --- a/mobile/noarch/documentation/index.md +++ b/mobile/noarch/documentation/index.md @@ -77,6 +77,12 @@ Stop the listener if it is running. * QUERY_UPDATE_INDEX_NEVER * QUERY_UPDATE_INDEX_AFTER +#### Query options + +* QUERY_ALL_DOCS +* QUERY_INCLUDE_DELETED +* QUERY_SHOW_CONFLICTS +* QUERY_ONLY_CONFLICTS ## DatabaseManager @@ -101,30 +107,35 @@ string, read-only. The actual data storage directory. dictionary, read-only. The most-recent error that occurred in the database manager. -**internalURL** +### Methods -string, read-only. The internal URL of the database manager. This can be used by local -HTTP clients to communicate with the database. For local-to-local replication, use the -database `name` property. +**close**() -### Methods +Closes the manager and all its databases. -**databaseNamed**(name) +**getDatabase**(name) -* name (string): the name of the `database` to create. +* name (string): the name of the `database` to open or create. Returns the [`database`](#database) with the given name, creating it if it didn't already exist. Multiple calls with the same name will return the same object instance. NOTE: Database names may not contain capital letters and may not start with an underscore! -**existingDatabaseNamed**(name) +**getExistingDatabse**(name) * name (string): the name of the `database` to return. Return the [`database`](#database) with the specified name. If the database manager does not have a database with the provided name, returns null. Multiple calls with the same name will return the same object instance. -**installDatabase**(name, pathToDatabase, pathToAttachments) +**isValidDatabaseName**(name) + +* name (string): the prospective database name to test + +Returns true if the provided string can be used as a database name. (Only the characters in +"abcdefghijklmnopqrstuvwxyz0123456789_$()+-/" are allowed.) + +**replaceDatabase**(name, pathToDatabase, pathToAttachments) * name (string): the name of the `database` to install * pathToDatabase (string): the path of the .touchdb database file to install @@ -134,13 +145,6 @@ Replaces or installs a database from a file. This is primarily used to install launch of an app, in which case you should first check .exists to avoid replacing the database if it exists already. Returns true if the database was copied successfully. -**isValidDatabaseName**(name) - -* name (string): the prospective database name to test - -Returns true if the provided string can be used as a database name. (Only the characters in -"abcdefghijklmnopqrstuvwxyz0123456789_$()+-/" are allowed.) - ## Database @@ -149,8 +153,7 @@ and validations). Databases in TiTouchDB are primarily namespaces for document Note on replication: the methods which create [`Replication`](#replication) objects can take either a URL of a remote CouchDB database or the name of a database running under the current -[`DatabaseManager`](#databaseManager). The value of the `internalURL` property should not be used -to set up a local-to-local replication. +[`DatabaseManager`](#databaseManager). ### Properties @@ -173,10 +176,9 @@ integer, read-only. The latest sequence number used. Every new revision is assi so this property increases monotonically as changes are made to the database. It can be used to check whether the database has changed between two points in time. -**maxRevTreeDepth** +**manager** -unsigned integer, read/write. The maximum depth of a document's revision tree. Revisions older than this limit -will be deleted during a compact operation. Default is 20. +DatabaseManager object, read-only. The database manager used to create this database. **name** @@ -214,33 +216,17 @@ object. The returned object can be customized prior to the start of replication Set up a one-time replication from this database to a remote target database and return a [`replication`](#replication) object. The returned object can be customized prior to the start of replication. -**defineFilter**(name, filter) - -* name (string): the name of the filter function -* filter (function(rev, params)): the filter function, return true to replicate the revision. Set this - argument to null to remove the named filter function. - * rev: the revision object to be validated - * params: the filter params (currently null) - -Defines or clears a named filter function. Filters are used by push replications to choose which documents to send. - -**defineValidation**(name, validate) +**deleteDatabase**() -* name (string): the name of the validation function -* validate (function(rev, context)): the validation function, return true to accept revision. Set this - argument to null to remove the named validation function. - * rev: the revision object to be validated - * context: the validation context (currently null) +Permanently delete this database and all of its documents. -Defines or clears a named document validation function. Before any change to the database, all registered -validation functions are called and given a chance to reject it. (This includes incoming changes from a -pull replication.) +**deleteLocalDocument**(docid) -**deleteDatabase**() +* docid (string): the unique id of the local document to delete -Permanently remove this database and all associated data. +Delete a local document with the specified ID. -**documentWithID**(docid) +**getDocument**(docid) * docid (string, optional): the unique ID of the document @@ -248,35 +234,80 @@ Fetch a [`document`](#document) object from the database by its identifier or cr the provided identifier if it doesn't already exist. Note that the new document is not saved until a call to **putProperties**() is made. If no document ID is provided, one will be generated. -**existingDocumentWithID**(docid) +**getExistingDocument**(docid) * docid (string): the unique ID of the document Fetch a [`document`](#document) object from the database by its identifier. Returns null if a document with the provided identifier doesn't already exist. -**existingViewNamed**(name) +**getExistingLocalDocument**(docid) + +* docid (string): the unique ID of the local document + +Fetch a local [`document`](#document) object from the database by its identifier. Returns null if a local +document with the provided identifier doesn't already exist. + +**getExistingView**(name) * name (string): the name of the view to fetch Returns a [`view`](#view) object with the given name or null if no view with the provided name exists. -**slowQueryWithMap**(map) +**getFilter**(name) -* map (string): map function source in JavaScript +* name (string): the name of the filter function to fetch -Returns a [`query`](#query) object that runs an arbitrary map. This is the equivalent of a CouchDB -temporary view, and as such is very slow compared to a precompiled view. It may be useful during -development, but in general this is inefficient if this map will be used more than once, -because the entire view has to be regenerated from scratch every time. +Get the filter function defined for the given name, or null if it does not exist. -**viewNamed**(name) +**getValidation**(name) + +* name (string): the name of the validation function to fetch + +Get the validation function defined for the given name, or null if it does not exist. + +**getView**(name) * name (string): the name of the view to fetch Returns a [`view`](#view) object with the given name. (This succeeds even if the view doesn't already exist, but the view won't be added to the database until it is assigned a map function.) +**putLocalDocument**(docid, doc) + +* docid (string): the identifier of the local document to save +* doc (dictionary): the document properties + +Set the contents of the local document with the specified document ID. + +**runAsync**(fn) + +* fn (function(db)): the function to run + +Asynchronously run a function, providing a reference to the current database as a function parameter. + +**setFilter**(name, filter) + +* name (string): the name of the filter function +* filter (function(rev, params)): the filter function, return true to replicate the revision. Set this + argument to null to remove the named filter function. + * rev: the saved revision object to be validated + * params: the filter params (currently null) + +Defines or clears a named filter function. Filters are used by push replications to choose which documents to send. + +**setValidation**(name, validate) + +* name (string): the name of the validation function +* validate (function(rev, context)): the validation function, return true to accept revision. Set this + argument to null to remove the named validation function. + * rev: the saved revision object to be validated + * context: the validation context + +Defines or clears a named document validation function. Before any change to the database, all registered +validation functions are called and given a chance to reject it. (This includes incoming changes from a +pull replication.) + ### Events **change**: fired when modifications are made to the documents in the database. @@ -290,10 +321,10 @@ object. Document properties that begin with an underscore are reserved. ### Properties -**abbreviatedID** +**conflictingRevisions** -string, read-only. The document ID abbreviated to a maximum of 10 characters including ".." in the middle. -Useful for logging or debugging. +array of [`revision`](#revision), read-only. Get all of the current conflicting revisions for the document, or an array +containing only the current revision if there are no conflicts. **currentRevision** @@ -303,6 +334,14 @@ Useful for logging or debugging. string, read-only. The ID of the current revision. If not known, returns null. +**database** + +[`database`](#database), read-only. The database that contains this document. + +**deleted** + +boolean, read-only. True if this document has been deleted. + **documentID** string, read-only. The unique ID of this document; its key in the database. @@ -311,9 +350,10 @@ string, read-only. The unique ID of this document; its key in the database. dictionary, read-only. The most-recent error that occurred in the document. -**isDeleted** +**leafRevisions** -boolean, read-only. True if the document has been deleted from the database. +array of [`revision`](#revision), read-only. Get all of the current leaf revisions for the document, +including deleted revisions (i.e. previously-resolved conflicts.) **properties** @@ -322,6 +362,14 @@ dictionary, read-only The contents of the current revision of the document; shorthand for `doc.currentRevision.properties`. Any keys in the returned dictionary that start with an underscore are TouchDB metadata. +**revisionHistory** + +array of [`revision`](#revision), read-only. Returns an array of available [`revision`](#revision) objects. +The ordering is essentially arbitrary, but usually chronological unless there has been merging with changes +from another server. The number of historical revisions available may vary; it depends on how recently the +database has been compacted. You should not rely on earlier revisions being available, except for those +representing unresolved conflicts. + **userProperties** dictionary, read-only @@ -343,23 +391,18 @@ No change is made to the database until/unless you save the new revision. Mark the document as deleted from the database. The next time the database is compacted, the document will be permanently deleted. -**getLeafRevisions**() - -Returns an array of leaf [`revision`](#revision) objects in the document's revision tree, -including deleted revisions (i.e. previously-resolved conflicts.) +**getProperty**(key) -**getRevisionHistory**() +* key (string): the key of the property in the document to return. -Returns an array of available [`revision`](#revision) objects. The ordering is essentially arbitrary, -but usually chronological unless there has been merging with changes from another server. The number of -historical revisions available may vary; it depends on how recently the database has been compacted. -You should not rely on earlier revisions being available, except for those representing unresolved conflicts. +Return the value of the document property specified by the `key` argument. -**propertyForKey**(key) +**getRevision**(revisionId) -* key (string): the key of the property in the document to return. +* revisionId (string): the identifier of the revision to fetch -Return the value of the document property specified by the `key` argument. +Returns the [`revision`](#revision) object with the specified ID or null if no revision with the +ID is present in the document. **purgeDocument**() @@ -376,13 +419,6 @@ revisionID. Any object returned from **properties** will have this value, so it that object and pass it to **putProperties**() to do updates. Returns a new [`revision`](#revision) object or null if the put failed. -**revisionWithID**(revisionId) - -* revisionId (string): the identifier of the revision to fetch - -Returns the [`revision`](#revision) object with the specified ID or null if no revision with the -ID is present in the document. - ### Events @@ -401,14 +437,14 @@ cannot be queried with view functions. Titanium.Blob, read-only. The body data of the attachment. -**contentURL** - -string, read-only. A file URL pointing to the attachment contents. - **contentType** string, read-only. The MIME type of the attachment. +**document** + +[`document`](#document) object, read-only. The document under which this attachment is stored. + **error** dictionary, read-only. The most-recent error that occurred in the attachment. @@ -425,6 +461,11 @@ dictionary, read-only. The CouchDB metadata for the attachment. string, read-only. The filename of the attachment (the final URL path component). +**revision** + +[`revision`](#revision) object, read-only. The revision under which this attachment is stored. + + ## Revision @@ -435,12 +476,12 @@ determine if incoming changes will result in a conflict in the document contents version control system for your documents, however, as they can be permanently removed by a database `compact` operation. -In TiTouchDB, there are two types of revision objects: existing revisions that have been persisted into +In TiTouchDB, there are two types of revision objects: saved revisions that have been persisted into the database and new revisions that are returned by the `createRevision()` method on the `database` and existing revision objects. Think of new revision objects as scratchpads where you can add properties and attachments in multiple steps prior to saving. -TODO maybe split out the docs for new revisions and existing revisions. +`Revision` is the base class for [`SavedRevision`](#savedrevision) and [`UnsavedRevision`](#unsavedrevision) ### Properties @@ -456,21 +497,20 @@ array of [`attachment`](#attachment) objects, read-only. All attachments on this dictionary, read-only. The most-recent error that occurred in the revision. -**isDeletion** +**database** -boolean, read-only for existing revisions; read-write for new revisions. True if this revision marks -the deletion of a document from the database. +[`database`](#database) object, read-only. The database where this revision is stored. -**isGone** +**isDeletion** -boolean, read-only. True if this revision marks the deletion or removal from available channels of -its document +boolean, read-only for saved revisions; read-write for unsaved revisions. True if this revision marks +the deletion of a document from the database. -**parentRevision** +**parent** -dictionary, read-only. The previous revision object in this document's local history. +[`revision`](#revision) object, read-only. The previous revision object in this document's local history. -**parentRevisionID** +**parentID** string, read-only. The identifier previous revision object in this document's local history. @@ -480,11 +520,10 @@ dictionary, read-only for existing revisions; read-write for new revisions. The Any keys in the returned dictionary that start with an underscore are reserved. Revision properties are cached for the lifespan of the object. -**propertiesAvailable** +**revisionHistory** -boolean, read-only. Returns true if the revision properties can be accessed. They may not be if the -revision is an ancestor and either the database has been compacted, or the revision was replicated from -another db. +array of [`revision`](#revision) object, read-only. Returns the history of this document in forward order. +Older revisions are NOT guaranteed to have their properties available. **revisionID** @@ -497,65 +536,78 @@ database. Can be set on unsaved revisions. ### Methods -**setAttachment**(name, contentType, content) - -* name (string): the name of the new attachment -* contentType (string): the MIME type of the new attachment -* content (TiBlob): the attachment content - -Creates a new attachment object with the specified name, MIME type, and content. The attachment -data will be written to the database when the revision is saved (new revision only). - -**attachmentNamed**(name) +**getAttachment**(name) * name (string): the name of the attachment to fetch Returns the [`attachment`](#attachment) object with the specified name or null if the attachment does not exist. +**getDocument**() + +Returns the [`document`](#document) object that this revision belongs to. + +**getProperty**(key) + +* key (string): the key for the revision property to fetch + +Returns the revision property associated with the provided key. + + + +## SavedRevision + +A SavedRevision is a revision object that has been persisted to the database. SavedRevisions may +not be modified. + +### Properties + +**propertiesAvailable** + +boolean, read-only. True if the properties of this revision are available. Always true for the current +revision of a document but may be false for older revisions. + +### Methods + **createRevision**(properties) -* properties (dictionary): the properties to write to the new revision. Optional. +* properties (dictionary, optional) -Create a new revision object for this revision's document. If properties are specified, then -the revision will be saved before it is returned; otherwise, the revision will be saved when -properties are assigned. +Create a new [`UnsavedRevision`](#unsavedrevision) object. If `properties` are specified, the new +revision will contain those property values; otherwise, the new revision will contain the values of +the current revision properties. -**deleteDocument**() +**deleteDocument()** -Deletes the document by creating a new deletion-marker revision (existing revisions only). +Permanently delete the document that contains this revision. -**getRevisionHistory**() + +## UnsavedRevision -Returns the history of this document as an array of revisions, in forward order. Older revisions are -NOT guaranteed to have their properties available. +An UnsavedRevision is a revision that has not yet been persisted to the database. UnsavedRevision +objects are used to add new properties and attachments to a document. -**propertyForKey**(key) +### Properties -* key (string): key of the property to return +NOTE: `isDeletion`, `properties`, and `userProperties` are all writable on UnsavedRevision objects. -Returns the revision property for the specified key. +### Methods -**putProperties**(properties) +**setAttachment**(name, contentType, content) -* properties (dictionary): the properties to write to the new revision. +* name (string): the name of the new attachment +* contentType (string): the MIME type of the new attachment +* content (TiBlob): the attachment content -Creates a new revision for this revision's document with the provided properties (existing revision -only). +Creates a new attachment object with the specified name, MIME type, and content. The attachment +data will be written to the database when the revision is saved. **removeAttachment**(name) * name (string): the name of the attachment to remove Deletes any existing attachment with the given name. The attachment will be deleted from the -database when the revision is saved (new revisions only). - -**setPropertyForKey**(key, value) - -* key (string): key of the property to set -* value (object): the value of the property to set - -Set a property on the revision corresponding to the specified key (new revision only). +database when the revision is saved. **save**() @@ -592,9 +644,9 @@ application is run. ### Properties -**name** +**database** -string, read-only. The name of the view. +[`database`](#database) object, read-only. The database where this view is stored. **isStale** @@ -602,22 +654,34 @@ boolean, read-only. True if the view has not indexed all documents. **lastSequenceIndexed** -The internal sequence number of the last document that was indexed by this view. +integer, read-only. The internal sequence number of the last document that was indexed by this view. + +**map** + +function, read-only. The map function for this view. + +**name** + +string, read-only. The name of the view. + +**reduce** + +function, read-only. The reduce function for this view, or null if no reduce function has been defined. ### Methods -**deleteIndex()** +**createQuery**() -Deletes the view's persistent index, which will be regenerated on the next query. +Return a [`query`](#query) object that can be used to fetch the keys, values, and documents from this +view's index. **deleteView()** Permanently delete this view. -**query**() +**deleteIndex()** -Return a [`query`](#query) object that can be used to fetch the keys, values, and documents from this -view's index. +Deletes the view's persistent index, which will be regenerated on the next query. **setMap**(map) @@ -625,7 +689,7 @@ view's index. Set the map function for the view. Calling setMap(null) will delete the view. -**setMapAndReduce**(map, reduce) +**setMapReduce**(map, reduce) * map (function(document)): the map function for this view * reduce (function(keys, values, rereduce)): the reduce function for this view. @@ -654,6 +718,10 @@ set to one of the following: the conflicts, if any, for the document. * `TiTouchDB.QUERY_ONLY_CONFLICTS`: only documents in conflict will be returned. +**database** + +[`database`](#database) object, read-only. The database where the query index is stored. + **descending** boolean, read/write. Should the rows be returned in descending key order? Default value is false. @@ -713,11 +781,6 @@ scalar|dictionary|array, read/write. If present, the minimum key value of the f string, read/write. The identifier of the first document to return. -**stale** - -number, read/write. If set, allows faster results at the expense of returning possibly out-of-date -data. One of `module.STALE_QUERY_NEVER`, `module.STALE_QUERY_OK`, or `module.STALE_QUERY_UPDATE_AFTER`. - ### Methods **run**() @@ -747,18 +810,18 @@ boolean, read-only. True if the database has changed since the view was generat ### Methods -**nextRow**() - -Returns the next [`query row`](#query_row) object in the query results or null if no more rows are -present. Usually called in a `while` loop. - -**rowAtIndex**(index) +**getRow**(index) * index (number): the index of the row to return Returns the [`query row`](#query_row) object at the specified index or null if there is no row at that index. +**next**() + +Returns the next [`query row`](#query_row) object in the query results or null if no more rows are +present. Usually called in a `while` loop. + **reset()** Resets the enumeration so the next call to `nextRow()` will return the first row. @@ -778,11 +841,9 @@ with the default "winning" revision in the first element. Only present for a qu `createAllDocumentsQuery()` which also has its `allDocsMode` property set to `QUERY_SHOW_CONFLICTS` or `QUERY_ONLY_CONFLICTS`. -**document** +**database** -[`document`](#document) object, read-only. The document that was used to generate this row. This will be -null if a grouping was enabled in the query because then the result rows don't correspond to individual -documents. +[`database`](#database) object, read-only. The database where the query index is stored. **documentID** @@ -793,7 +854,7 @@ string, read-only. The unique identifier of the document associated with this r dictionary, read-only. The properties of the document this row was mapped from. This property will be null unless the **prefetch** property on the query was set to true. -**documentRevision** +**documentRevisionID** string, read-only. The revision ID of the source document. @@ -801,22 +862,6 @@ string, read-only. The revision ID of the source document. scalar|dictionary|array, read-only. The key for this row as emitted by the map/reduce functions. -**key0** - -scalar|dictionary|array, read-only. Shorthand for the first element in an array key (see `keyAtIndex()`). - -**key1** - -scalar|dictionary|array, read-only. Shorthand for the second element in an array key (see `keyAtIndex()`). - -**key2** - -scalar|dictionary|array, read-only. Shorthand for the third element in an array key (see `keyAtIndex()`). - -**key3** - -scalar|dictionary|array, read-only. Shorthand for the fourth element in an array key (see `keyAtIndex()`). - **sequenceNumber** integer, read-only. The local sequence number of the associated doc/revision. @@ -835,12 +880,11 @@ scalar|dictionary|array, read-only. The value for this row as emitted by the ma ### Methods -**keyAtIndex**(index) +**getDocument**() -* index (number): the array index of the key part to fetch - -If the row's key is an array, fetch the key value at the specified index. If the key is not an array, -index = 0 will fetch the entire key. If the index is out of range, returns null. +Returns the [`document`](#document) object that was used to generate this row. This will be +null if a grouping was enabled in the query because then the result rows don't correspond to individual +documents. ## Replication @@ -868,7 +912,7 @@ database is modified? Default is false. boolean, read/write. If true, create the target database if it doesn't already exist. Default is false. -**documentIDs** +**docIds** array of string, read/write. Sets the documents to specify as part of the replication. @@ -889,26 +933,25 @@ dictionary, read/write. Parameters to pass to the filter function. dictionary, read/write. Extra HTTP headers to send in all requests to the remote server. Should map strings (header names) to strings. -**lastError** +**isPull** -dictionary, read-only. The most recent error during replication, if any. +boolean, read-only. If true, the replication is pulling from the remote database to the local database. -**network** +**isRunning** -string, read/write. Specify which class of network the replication will use. Valid values are -"WiFi" and "Cell". +boolean, read-only. True if the replication is currently running -**pull** +**lastError** -boolean, read-only. If true, the replication is pulling from the remote database to the local database. +dictionary, read-only. The most recent error during replication, if any. -**remoteURL** +**localDatabase** -string, read-only. The URL of the remote database. +[`database`](#database) object, read-only. The database where the replication is stored. -**running** +**remoteUrl** -boolean, read-only. True if the replication is currently running. +string, read-only. The URL of the remote database. **status** @@ -921,6 +964,13 @@ number, read-only. The current mode of the replication. One of `module.REPLICA Restarts a completed or failed replication. +**setCredential**(credential) + +* credential (dictionary): the credentials to use on the remote server + +Sets the authentication credentials to use on the remote server. Currently supports HTTP Basic +authentication with a dictionary that contains the keys `user` for the username and `pass` for the password. + **start**() Starts the replication process.