| // Copyright 2015 The Vanadium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| import Foundation |
| |
| /// DatabaseHandle is the set of methods that work both with and without a batch. |
| /// It allows clients to pass the handle to helper methods that are batch-agnostic. |
| public protocol DatabaseHandle { |
| /// Id returns the id of this DatabaseHandle.. |
| var databaseId: DatabaseId { get } |
| |
| /// FullName returns the object name (encoded) of this DatabaseHandle. |
| var fullName: String { get } |
| |
| /// Collection returns the Collection with the given relative name. |
| /// The user blessing is derived from the context. |
| func collection(name: String) -> Collection? |
| |
| /// CollectionForId returns the Collection with the given user blessing and name. |
| func collection(collectionId: CollectionId) -> Collection? |
| |
| /// ListCollections returns a list of all Collection ids that the caller is |
| /// allowed to see. The list is sorted by blessing, then by name. |
| func listCollections() throws -> [CollectionId] |
| |
| /// Returns a ResumeMarker that points to the current end of the event log. |
| func getResumeMarker() throws -> ResumeMarker |
| } |
| |
| public protocol Database: DatabaseHandle, AccessController { |
| /// Create creates this Database. |
| /// TODO(sadovsky): Specify what happens if perms is nil. |
| func create(permissions: Permissions?) throws |
| |
| /// Destroy destroys this Database, permanently removing all of its data. |
| /// TODO(sadovsky): Specify what happens to syncgroups. |
| func destroy() throws |
| |
| // Exists returns true only if this Database exists. Insufficient permissions |
| // cause Exists to return false instead of an error. |
| func exists() throws -> Bool |
| |
| /** BeginBatch creates a new batch. Instead of calling this function directly, |
| clients are encouraged to use the RunInBatch() helper function, which |
| detects "concurrent batch" errors and handles retries internally. |
| |
| Default concurrency semantics: |
| |
| - Reads (e.g. gets, scans) inside a batch operate over a consistent |
| snapshot taken during BeginBatch(), and will see the effects of prior |
| writes performed inside the batch. |
| |
| - Commit() may fail with ErrConcurrentBatch, indicating that after |
| BeginBatch() but before Commit(), some concurrent routine wrote to a key |
| that matches a key or row-range read inside this batch. |
| |
| - Other methods will never fail with error ErrConcurrentBatch, even if it |
| is known that Commit() will fail with this error. |
| |
| Once a batch has been committed or aborted, subsequent method calls will |
| fail with no effect. |
| |
| Concurrency semantics can be configured using BatchOptions. |
| TODO(sadovsky): Use varargs for options. |
| */ |
| func beginBatch(options: BatchOptions?) throws -> BatchDatabase |
| |
| /// Watch allows a client to watch for updates to the database. For each watch |
| /// request, the client will receive a reliable stream of watch events without |
| /// reordering. See watch.GlobWatcher for a detailed explanation of the |
| /// behavior. |
| /// |
| /// If a nil ResumeMarker is provided, the WatchStream will begin with a Change |
| /// batch containing the initial state. Otherwise, the WatchStream will contain |
| /// only changes since the provided ResumeMarker. |
| /// |
| /// TODO(sadovsky): Watch should return just a WatchStream, similar to how Scan |
| /// returns just a ScanStream. |
| func watch(collection: CollectionId, prefix: String, resumeMarker: ResumeMarker?) throws -> WatchStream |
| |
| /// Syncgroup returns a handle to the syncgroup with the given name. |
| func syncgroup(sgName: String) -> Syncgroup |
| |
| /// GetSyncgroupNames returns the names of all syncgroups attached to this |
| /// database. |
| /// TODO(sadovsky): Rename to ListSyncgroups, for parity with ListDatabases. |
| func getSyncgroupNames() throws -> [String] |
| |
| /// CreateBlob creates a new blob and returns a handle to it. |
| func createBlob() throws -> Blob |
| |
| /// Blob returns a handle to the blob with the given BlobRef. |
| func blob(blobRef: BlobRef) -> Blob |
| |
| /// PauseSync pauses sync for this database. Incoming sync, as well as outgoing |
| /// sync of subsequent writes, will be disabled until ResumeSync is called. |
| /// PauseSync is idempotent. |
| func pauseSync() throws |
| |
| /// ResumeSync resumes sync for this database. ResumeSync is idempotent. |
| func resumeSync() throws |
| |
| /// Close cleans up any state associated with this database handle, including |
| /// closing the conflict resolution stream (if open). |
| func close() |
| } |