From d43e4eb7d8e8c5445c0fb9a1010c183902b29d9c Mon Sep 17 00:00:00 2001
From: Ludovic Le Frioux <ludovic.le-frioux@inria.fr>
Date: Tue, 3 Nov 2020 18:23:20 +0100
Subject: [PATCH] Add more code documentation.
---
src/commonMain/kotlin/client/CObject.kt | 28 +++++--------
src/commonMain/kotlin/client/Collection.kt | 37 ++++++++---------
src/commonMain/kotlin/client/Session.kt | 40 +++++++++++++++----
.../kotlin/client/utils/CObjectUId.kt | 2 +-
.../kotlin/client/utils/CollectionUId.kt | 2 +-
.../kotlin/client/utils/ConsistencyLevel.kt | 2 +-
src/commonMain/kotlin/client/utils/Globals.kt | 2 +-
.../client/utils/NotificationHandler.kt | 2 +-
.../kotlin/client/utils/OperationUId.kt | 2 +-
9 files changed, 66 insertions(+), 51 deletions(-)
diff --git a/src/commonMain/kotlin/client/CObject.kt b/src/commonMain/kotlin/client/CObject.kt
index cf51f21..ab0de5c 100644
--- a/src/commonMain/kotlin/client/CObject.kt
+++ b/src/commonMain/kotlin/client/CObject.kt
@@ -21,31 +21,22 @@ package client
import client.utils.ActiveSession
import client.utils.CObjectUId
+import client.utils.CService
import client.utils.OperationUId
import crdtlib.crdt.DeltaCRDT
-open class CObject<T> {
-
- /**
- * Concordant object unique id
- */
- private val id: CObjectUId<T>
-
- /**
- * Is openned in read only mode
- */
- private val readOnly: Boolean
+/**
+* Class representing a Concordant object.
+* @property id Concordant object unique identifier.
+* @property readOnly is object openned in read-only mode.
+*/
+open class CObject<T>(private val id: CObjectUId<T>, private val readOnly: Boolean) {
/**
- * The encapsulated CRDT
+ * The encapsulated CRDT.
*/
protected var crdt: DeltaCRDT<T>? = null
- constructor(oid: CObjectUId<T>, readOnly: Boolean) {
- this.id = oid
- this.readOnly = readOnly
- }
-
protected fun beforeUpdate(): OperationUId {
if (this.readOnly) throw RuntimeException("CObject has been opened in read-only mode.")
if (ActiveSession == null) RuntimeException("Not active session.")
@@ -64,6 +55,9 @@ open class CObject<T> {
protected fun afterGetter() {
}
+ /**
+ * Closes this object.
+ */
fun close() {
}
}
diff --git a/src/commonMain/kotlin/client/Collection.kt b/src/commonMain/kotlin/client/Collection.kt
index 997e331..689e611 100644
--- a/src/commonMain/kotlin/client/Collection.kt
+++ b/src/commonMain/kotlin/client/Collection.kt
@@ -23,32 +23,29 @@ import client.utils.CObjectUId
import client.utils.CollectionUId
import client.utils.NotificationHandler
-class Collection {
-
- /**
- * The collection unique id
- */
- private val id: CollectionUId
+/**
+* This class represents a collection of objects.
+* @property id the collection unique identifier.
+* @property readOnly is the collection open in read-only mode.
+*/
+class Collection(private val id: CollectionUId, private val readOnly: Boolean) {
/**
- * Is the collection open in read only mode
- */
- private val readOnly: Boolean
-
- constructor(cid: CollectionUId, readOnly: Boolean) {
- this.id = cid
- this.readOnly = readOnly
- }
-
- // c_open_read|write<T>
- fun <T> open(oid: String, readOnly: Boolean, handler: NotificationHandler<T>): T {
+ * Opens an object of the collection.
+ * @param objectId the name of the object.
+ * @param readOnly is the object open in read-only mode.
+ * @param handler currently not used.
+ */
+ fun <T> open(objectId: String, readOnly: Boolean, handler: NotificationHandler<T>): T {
if (this.readOnly && !readOnly) throw RuntimeException("Collection has been opened in read-only mode.")
- val oid = CObjectUId<T>(this.id, oid)
- return CObject<T>(oid, readOnly) as T
+ val objectUId = CObjectUId<T>(this.id, objectId)
+ return CObject<T>(objectUId, readOnly) as T
}
- // c_close_collection
+ /**
+ * Closes this collection.
+ */
fun close() {
}
}
diff --git a/src/commonMain/kotlin/client/Session.kt b/src/commonMain/kotlin/client/Session.kt
index 46343f1..aa6dfd5 100644
--- a/src/commonMain/kotlin/client/Session.kt
+++ b/src/commonMain/kotlin/client/Session.kt
@@ -21,16 +21,20 @@
package client
import client.utils.ActiveSession
+import client.utils.CService
import client.utils.CollectionUId
import client.utils.ConsistencyLevel
import crdtlib.utils.ClientUId
import crdtlib.utils.SimpleEnvironment
import crdtlib.utils.VersionVector
+/**
+* Class representing a client session.
+*/
class Session {
/**
- * The client unique id
+ * The client unique identifier
*/
private val clientUId: ClientUId
@@ -39,32 +43,52 @@ class Session {
*/
public val environment: SimpleEnvironment
- private constructor(cid: ClientUId) {
- this.clientUId = cid
+ /**
+ * Private constructor.
+ * @param clientUId the client unique identifier.
+ */
+ private constructor(clientUId: ClientUId) {
+ this.clientUId = clientUId
this.environment = SimpleEnvironment(this.clientUId)
}
// c_pull_XX_view
fun pull(type: ConsistencyLevel) {
+ // Not yet implemented
+ throw RuntimeException("Method pull is not yet supported.")
}
// c_pull_XX_view(v)
fun pull(type: ConsistencyLevel, vv: VersionVector) {
+ // Not yet implemented
+ throw RuntimeException("Method pull is not yet supported.")
}
- // c_open_collection_read|write
- fun openCollection(cid: CollectionUId, readOnly: Boolean): Collection {
- return Collection(cid, readOnly)
+ /**
+ * Opens a given collection with the given read-only mode.
+ * @param collectionUId the collection unique identifier.
+ * @param readOnly is read-only mode activated.
+ * @return the corresponding collection.
+ */
+ fun openCollection(collectionUId: CollectionUId, readOnly: Boolean): Collection {
+ return Collection(collectionUId, readOnly)
}
- // c_end_session
+ /**
+ * Closes this session.
+ */
fun close() {
CService.close(this.clientUId)
ActiveSession = null
}
companion object {
- // c_begin_session
+ /**
+ * Connects a client to Concordant platform.
+ * @param dbName the database name that should be accessed.
+ * @param credentials the crediantials provided by the client.
+ * @return the client session to communicate with Concordant.
+ */
fun connect(dbName: String, credentials: String): Session {
val clientUId = ClientUId("MY_ID")
if (!CService.connect(dbName, clientUId)) throw RuntimeException("Connection to server failed.")
diff --git a/src/commonMain/kotlin/client/utils/CObjectUId.kt b/src/commonMain/kotlin/client/utils/CObjectUId.kt
index 4deadbc..e94617d 100644
--- a/src/commonMain/kotlin/client/utils/CObjectUId.kt
+++ b/src/commonMain/kotlin/client/utils/CObjectUId.kt
@@ -20,6 +20,6 @@
package client.utils
/**
-* Concordant object unique identifiers
+* Concordant object unique identifier.
*/
data class CObjectUId<T>(val cid: CollectionUId, val name: String)
diff --git a/src/commonMain/kotlin/client/utils/CollectionUId.kt b/src/commonMain/kotlin/client/utils/CollectionUId.kt
index 2d266f3..2de4524 100644
--- a/src/commonMain/kotlin/client/utils/CollectionUId.kt
+++ b/src/commonMain/kotlin/client/utils/CollectionUId.kt
@@ -21,6 +21,6 @@
package client.utils
/**
-* Collection unique identifiers
+* Collection unique identifier.
*/
typealias CollectionUId = String
diff --git a/src/commonMain/kotlin/client/utils/ConsistencyLevel.kt b/src/commonMain/kotlin/client/utils/ConsistencyLevel.kt
index 3decd74..0170ec8 100644
--- a/src/commonMain/kotlin/client/utils/ConsistencyLevel.kt
+++ b/src/commonMain/kotlin/client/utils/ConsistencyLevel.kt
@@ -20,7 +20,7 @@
package client.utils
/**
-* Different types of consistency level provided by the Concordant platform
+* Different types of consistency level provided by the Concordant platform.
*/
enum class ConsistencyLevel {
diff --git a/src/commonMain/kotlin/client/utils/Globals.kt b/src/commonMain/kotlin/client/utils/Globals.kt
index c1f3ea3..44da253 100644
--- a/src/commonMain/kotlin/client/utils/Globals.kt
+++ b/src/commonMain/kotlin/client/utils/Globals.kt
@@ -22,6 +22,6 @@ package client.utils
import client.Session
/**
-* Global variable(s)
+* Global variable storing a reference to the currently active session.
*/
var ActiveSession: Session? = null
diff --git a/src/commonMain/kotlin/client/utils/NotificationHandler.kt b/src/commonMain/kotlin/client/utils/NotificationHandler.kt
index 152f93e..17acf94 100644
--- a/src/commonMain/kotlin/client/utils/NotificationHandler.kt
+++ b/src/commonMain/kotlin/client/utils/NotificationHandler.kt
@@ -22,6 +22,6 @@ package client.utils
import crdtlib.utils.VersionVector
/**
-* The notification handler (function) type accepted for c-objects
+* The notification handler (function) type used is case of object update.
*/
typealias NotificationHandler<T> = (VersionVector, CObjectUId<T>) -> Unit
diff --git a/src/commonMain/kotlin/client/utils/OperationUId.kt b/src/commonMain/kotlin/client/utils/OperationUId.kt
index 997b6a6..40c46b4 100644
--- a/src/commonMain/kotlin/client/utils/OperationUId.kt
+++ b/src/commonMain/kotlin/client/utils/OperationUId.kt
@@ -22,6 +22,6 @@ package client.utils
import crdtlib.utils.Timestamp
/**
-* Operations unique identifiers
+* Operation unique identifier.
*/
typealias OperationUId = Timestamp
--
GitLab