From 6f6e69611562aed3d3882b46dc12caf7e30d62fb Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Thu, 23 Jan 2020 12:47:03 +0100
Subject: [PATCH] DOC: docs for new code
---
src/main/java/caosdb/server/CaosDBServer.java | 1 -
.../server/database/BackendTransaction.java | 6 ++++++
.../caosdb/server/database/DatabaseUtils.java | 16 ++++++++++++++++
.../implementation/MySQL/MySQLGetAllNames.java | 1 +
.../MySQL/MySQLRetrieveSparseEntity.java | 5 +++++
.../backend/interfaces/GetAllNamesImpl.java | 5 +++++
.../caosdb/server/entity/EntityInterface.java | 2 ++
.../caosdb/server/jobs/core/RetriveAllNames.java | 7 +++++++
.../handlers/GetNamesRequestHandler.java | 1 +
9 files changed, 43 insertions(+), 1 deletion(-)
diff --git a/src/main/java/caosdb/server/CaosDBServer.java b/src/main/java/caosdb/server/CaosDBServer.java
index fc693306..9da7f9af 100644
--- a/src/main/java/caosdb/server/CaosDBServer.java
+++ b/src/main/java/caosdb/server/CaosDBServer.java
@@ -635,7 +635,6 @@ public class CaosDBServer extends Application {
protectedRouter.attach("/scripting", ScriptingResource.class);
protectedRouter.attach("/Entities/names", EntityNamesResource.class);
protectedRouter.attach("/Entity/names", EntityNamesResource.class);
-
protectedRouter.attach("/Entities", EntityResource.class);
protectedRouter.attach("/Entities/", EntityResource.class);
protectedRouter.attach("/Entities/{specifier}", EntityResource.class);
diff --git a/src/main/java/caosdb/server/database/BackendTransaction.java b/src/main/java/caosdb/server/database/BackendTransaction.java
index bdace0c9..e4b6c617 100644
--- a/src/main/java/caosdb/server/database/BackendTransaction.java
+++ b/src/main/java/caosdb/server/database/BackendTransaction.java
@@ -146,6 +146,12 @@ public abstract class BackendTransaction implements Undoable {
this.addMeasurement(this, t2 - t1);
}
+ /**
+ * Intialiaze the adapters to the database backend.
+ *
+ * <p>Currently this is hard-coded to the MySQL-Backend but the architecture of this class is
+ * designed to make it easy in the future to choose other implementations (i.e. other back-ends)
+ */
public static void init() {
if (impl.isEmpty()) {
setImpl(GetAllNamesImpl.class, MySQLGetAllNames.class);
diff --git a/src/main/java/caosdb/server/database/DatabaseUtils.java b/src/main/java/caosdb/server/database/DatabaseUtils.java
index 5fcc2682..84c38fa4 100644
--- a/src/main/java/caosdb/server/database/DatabaseUtils.java
+++ b/src/main/java/caosdb/server/database/DatabaseUtils.java
@@ -186,6 +186,14 @@ public class DatabaseUtils {
return ret;
}
+ /**
+ * Helper function for parsing MySQL results.
+ *
+ * <p>This function creates SparseEntities and parses only the name, the role and the acl of an
+ * entity.
+ *
+ * <p>Never returns null.
+ */
public static SparseEntity parseNameRoleACL(ResultSet rs) throws SQLException {
final SparseEntity ret = new SparseEntity();
ret.role = bytes2UTF8(rs.getBytes("EntityRole"));
@@ -194,6 +202,14 @@ public class DatabaseUtils {
return ret;
}
+ /**
+ * Helper function for parsing MySQL results.
+ *
+ * <p>This function creates SparseEntities and parses all fields which belong to a SparseEntity:
+ * id, name, role, acl, description, datatype, and the file properties.
+ *
+ * <p>Never returns null.
+ */
public static SparseEntity parseEntityResultSet(final ResultSet rs) throws SQLException {
SparseEntity ret = parseNameRoleACL(rs);
ret.id = rs.getInt("EntityID");
diff --git a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java
index 6f69f343..d7c641ca 100644
--- a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java
+++ b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java
@@ -11,6 +11,7 @@ import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;
+/** Retrieve name, role and acl of all entities from the MySQL backend. */
public class MySQLGetAllNames extends MySQLTransaction implements GetAllNamesImpl {
public MySQLGetAllNames(Access access) {
diff --git a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveSparseEntity.java b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveSparseEntity.java
index ebe2aa5f..907c7471 100644
--- a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveSparseEntity.java
+++ b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveSparseEntity.java
@@ -31,6 +31,11 @@ import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
+/**
+ * Retrieve a single SparseEntity by id.
+ *
+ * <p>A SparseEntity contains only id, name, role, acl, datatype and the file properties.
+ */
public class MySQLRetrieveSparseEntity extends MySQLTransaction
implements RetrieveSparseEntityImpl {
diff --git a/src/main/java/caosdb/server/database/backend/interfaces/GetAllNamesImpl.java b/src/main/java/caosdb/server/database/backend/interfaces/GetAllNamesImpl.java
index dfd5bd75..3a89e579 100644
--- a/src/main/java/caosdb/server/database/backend/interfaces/GetAllNamesImpl.java
+++ b/src/main/java/caosdb/server/database/backend/interfaces/GetAllNamesImpl.java
@@ -3,6 +3,11 @@ package caosdb.server.database.backend.interfaces;
import caosdb.server.database.proto.SparseEntity;
import java.util.List;
+/**
+ * Interface for the retrieval of all known names from the backend.
+ *
+ * <p>The returned list contains SparseEntities which have only their name, role and acl defined.
+ */
public interface GetAllNamesImpl extends BackendTransactionImpl {
List<SparseEntity> execute();
diff --git a/src/main/java/caosdb/server/entity/EntityInterface.java b/src/main/java/caosdb/server/entity/EntityInterface.java
index fc88f428..21ed5cd8 100644
--- a/src/main/java/caosdb/server/entity/EntityInterface.java
+++ b/src/main/java/caosdb/server/entity/EntityInterface.java
@@ -171,8 +171,10 @@ public interface EntityInterface
public abstract void checkPermission(Permission permission);
+ /** Return true iff the current thread's subject has a permission. */
public abstract boolean hasPermission(Permission permission);
+ /** Return true iff the given subject has a permission. */
public abstract boolean hasPermission(Subject subject, Permission permission);
public abstract boolean hasEntityACL();
diff --git a/src/main/java/caosdb/server/jobs/core/RetriveAllNames.java b/src/main/java/caosdb/server/jobs/core/RetriveAllNames.java
index 955bb5aa..d7f58e00 100644
--- a/src/main/java/caosdb/server/jobs/core/RetriveAllNames.java
+++ b/src/main/java/caosdb/server/jobs/core/RetriveAllNames.java
@@ -8,6 +8,13 @@ import caosdb.server.jobs.JobExecutionTime;
import caosdb.server.permissions.EntityPermission;
import caosdb.server.utils.EntityStatus;
+/**
+ * A jobs which retrieves all known names for which the requesting user has the RETRIEVE_ENTITY
+ * permission.
+ *
+ * <p>The entites' status are set to VALID because the entities parents and properties do not have
+ * to be retrieved.
+ */
@JobAnnotation(flag = "names", time = JobExecutionTime.INIT)
public class RetriveAllNames extends FlagJob {
diff --git a/src/main/java/caosdb/server/resource/transaction/handlers/GetNamesRequestHandler.java b/src/main/java/caosdb/server/resource/transaction/handlers/GetNamesRequestHandler.java
index 3c941b7f..f69c1128 100644
--- a/src/main/java/caosdb/server/resource/transaction/handlers/GetNamesRequestHandler.java
+++ b/src/main/java/caosdb/server/resource/transaction/handlers/GetNamesRequestHandler.java
@@ -5,6 +5,7 @@ import caosdb.server.resource.transaction.EntityResource;
public class GetNamesRequestHandler extends RequestHandler<RetrieveContainer> {
+ /** Adds the `names` flag to the RetrieveContainer which triggers the RetrieveAllNames job. */
@Override
public void handle(EntityResource t, RetrieveContainer container) throws Exception {
container.getFlags().put("names", null);
--
GitLab