From 89d083beec151d0da97799eb7e567adf09f98da9 Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Mon, 9 Oct 2023 16:30:33 +0200
Subject: [PATCH] DOC: add doc strings to a lot of classes, update Copyright
---
.../java/org/caosdb/server/CaosDBServer.java | 6 +--
.../server/database/BackendTransaction.java | 16 +++++-
.../database/access/AbstractAccess.java | 8 +++
.../caosdb/server/database/access/Access.java | 18 +++++++
.../MySQL/MySQLDeleteEntityProperties.java | 5 +-
.../MySQL/MySQLDeleteSparseEntity.java | 5 +-
.../MySQL/MySQLGetDependentEntities.java | 14 ++++--
.../MySQL/MySQLGetFileRecordByPath.java | 10 ++--
.../MySQL/MySQLGetIDByName.java | 10 ++--
.../MySQL/MySQLGetUpdateableChecksums.java | 11 ++--
.../MySQL/MySQLInsertEntityDatatype.java | 28 +++++++++++
.../MySQL/MySQLInsertEntityProperties.java | 16 ++++--
.../MySQL/MySQLInsertSparseEntity.java | 5 +-
.../MySQL/MySQLRetrieveCurrentMaxId.java | 24 +++++++++
.../MySQL/MySQLRetrieveProperties.java | 15 ++++--
.../MySQL/MySQLSetFileChecksum.java | 21 +++++++-
.../MySQLSetQueryTemplateDefinition.java | 10 ++--
.../interfaces/RetrieveCurrentMaxIdImpl.java | 26 ++++++++++
.../transaction/RetrieveCurrentMaxId.java | 29 +++++++++++
.../server/datatype/ReferenceValue.java | 11 ++--
.../java/org/caosdb/server/entity/Entity.java | 18 +++++--
.../org/caosdb/server/entity/EntityID.java | 21 ++++++++
.../server/entity/EntityIdRegistry.java | 34 +++++++++++++
.../entity/EntityIdRegistryStrategy.java | 24 +++++++++
.../org/caosdb/server/entity/LegacyIds.java | 28 +++++++++++
.../org/caosdb/server/entity/StringIds.java | 25 ++++++++++
.../entity/container/RetrieveContainer.java | 22 ++++++--
.../container/TransactionContainer.java | 12 +++--
.../grpc/EntityTransactionServiceImpl.java | 10 ++--
.../server/grpc/GrpcToCaosDBConverters.java | 17 +++----
.../org/caosdb/server/jobs/JobConfig.java | 4 +-
.../server/jobs/LazyEntityResolver.java | 37 ++++++++++++++
.../java/org/caosdb/server/jobs/Schedule.java | 6 ++-
.../org/caosdb/server/jobs/ScheduledJob.java | 6 +--
.../jobs/core/CheckDatatypePresent.java | 12 ++---
.../core/CheckDependenciesBeforeDeletion.java | 5 +-
.../server/jobs/core/CheckParValid.java | 7 ++-
.../server/jobs/core/CheckPropValid.java | 7 ++-
.../jobs/core/CheckRefidIsaParRefid.java | 12 ++---
.../server/jobs/core/CheckRefidValid.java | 9 ++--
.../server/jobs/core/EntityIdHandler.java | 25 ----------
.../server/jobs/core/EntityStateJob.java | 4 +-
.../server/jobs/core/GenerateEntityId.java | 50 +++++++++++++++++++
.../caosdb/server/jobs/core/Inheritance.java | 7 +--
.../org/caosdb/server/jobs/core/NoCache.java | 12 +++--
.../jobs/core/ProcessNameProperties.java | 13 +++--
.../caosdb/server/jobs/core/ResolveNames.java | 17 +++++--
.../org/caosdb/server/query/IDFilter.java | 10 ++--
.../java/org/caosdb/server/query/POV.java | 10 ++--
.../caosdb/server/resource/UserResource.java | 7 ++-
.../resource/transaction/EntityResource.java | 13 +++--
.../transaction/RetrieveEntityResource.java | 12 +++--
.../EntityTransactionInterface.java | 25 ++++++++++
.../caosdb/server/transaction/Retrieve.java | 15 ------
.../server/transaction/Transaction.java | 20 +++++++-
.../server/transaction/WriteTransaction.java | 4 +-
.../caosdb/server/utils/UseCacheResource.java | 25 ++++++++++
.../utils/UseCacheResourceDelegate.java | 28 +++++++++++
58 files changed, 719 insertions(+), 182 deletions(-)
delete mode 100644 src/main/java/org/caosdb/server/jobs/core/EntityIdHandler.java
create mode 100644 src/main/java/org/caosdb/server/jobs/core/GenerateEntityId.java
diff --git a/src/main/java/org/caosdb/server/CaosDBServer.java b/src/main/java/org/caosdb/server/CaosDBServer.java
index 5781f2e1..8a09883b 100644
--- a/src/main/java/org/caosdb/server/CaosDBServer.java
+++ b/src/main/java/org/caosdb/server/CaosDBServer.java
@@ -3,8 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2019-2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2019-2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2019-2021,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2019-2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -129,7 +129,7 @@ public class CaosDBServer extends Application {
private static boolean NO_TLS = false;
public static final String REQUEST_TIME_LOGGER = "REQUEST_TIME_LOGGER";
public static final String REQUEST_ERRORS_LOGGER = "REQUEST_ERRORS_LOGGER";
- private static boolean USE_CACHE = false;
+ private static boolean USE_CACHE = true;
private static Scheduler SCHEDULER;
public static String getServerProperty(final String key) {
diff --git a/src/main/java/org/caosdb/server/database/BackendTransaction.java b/src/main/java/org/caosdb/server/database/BackendTransaction.java
index 7021dfbb..c014972a 100644
--- a/src/main/java/org/caosdb/server/database/BackendTransaction.java
+++ b/src/main/java/org/caosdb/server/database/BackendTransaction.java
@@ -3,8 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2019-2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2019-2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2019-2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2019-2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -133,6 +133,18 @@ import org.caosdb.server.database.misc.TransactionBenchmark;
import org.caosdb.server.utils.UndoHandler;
import org.caosdb.server.utils.Undoable;
+/**
+ * Abstract class for backend transactions.
+ *
+ * <p>This class is the glue between the Transaction layer and the actual implementation of the
+ * communication with the back end.
+ *
+ * <p>This class also acts as a registry which stores which implementation is being used for which
+ * backend transaction interface.
+ *
+ * @see {@link Transaction}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public abstract class BackendTransaction implements Undoable {
private final UndoHandler undoHandler = new UndoHandler();
diff --git a/src/main/java/org/caosdb/server/database/access/AbstractAccess.java b/src/main/java/org/caosdb/server/database/access/AbstractAccess.java
index 680b1827..574dabed 100644
--- a/src/main/java/org/caosdb/server/database/access/AbstractAccess.java
+++ b/src/main/java/org/caosdb/server/database/access/AbstractAccess.java
@@ -3,6 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -25,6 +27,12 @@ import org.caosdb.server.database.misc.RollBackHandler;
import org.caosdb.server.transaction.TransactionInterface;
import org.caosdb.server.utils.UseCacheResourceDelegate;
+/**
+ * Abstract implementation of an Access.
+ *
+ * @see {@link Access}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public abstract class AbstractAccess<T extends TransactionInterface>
extends UseCacheResourceDelegate implements Access {
diff --git a/src/main/java/org/caosdb/server/database/access/Access.java b/src/main/java/org/caosdb/server/database/access/Access.java
index a98afa27..6b8a521c 100644
--- a/src/main/java/org/caosdb/server/database/access/Access.java
+++ b/src/main/java/org/caosdb/server/database/access/Access.java
@@ -3,6 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -22,6 +24,22 @@ package org.caosdb.server.database.access;
import org.caosdb.server.database.misc.DBHelper;
import org.caosdb.server.utils.UseCacheResource;
+/**
+ * Access Interface.
+ *
+ * <p>The access object is part of a Transactions state and it is the glue between the Transaction
+ * and the actual backend implementation of those transactions. It represents different levels of
+ * access (RO, RW) and provides all the helper objects shared by all the single calls to the backend
+ * (package .../database/backend/implementation/...).
+ *
+ * <p>It is further used to commit or roll-back the owning transaction.
+ *
+ * <p>The DatabaseAccessManager issues the Access to a requesting Transaction.
+ *
+ * @see {@link Transaction}
+ * @see {@link DatabaseAccessManager}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public interface Access extends UseCacheResource {
public abstract void setHelper(String name, DBHelper helper);
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteEntityProperties.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteEntityProperties.java
index 615adca4..747cf50d 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteEntityProperties.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteEntityProperties.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteSparseEntity.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteSparseEntity.java
index b6348646..a1ab389b 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteSparseEntity.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLDeleteSparseEntity.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetDependentEntities.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetDependentEntities.java
index bb33b4df..2af80f80 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetDependentEntities.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetDependentEntities.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
@@ -31,6 +30,15 @@ import org.caosdb.server.database.backend.interfaces.GetDependentEntitiesImpl;
import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.entity.EntityID;
+/**
+ * Get a list of ids of all entities which require the given entity to exists.
+ *
+ * <p>That is the list of all direct child entities (by is-a relation), referenced entities (i.e.
+ * the given entity is a property's value), all properties which have this entity as their data type
+ * and all implemented properties which use this entity as their abtract property.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLGetDependentEntities extends MySQLTransaction
implements GetDependentEntitiesImpl {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetFileRecordByPath.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetFileRecordByPath.java
index 922c2b6b..0dd10ec1 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetFileRecordByPath.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetFileRecordByPath.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
@@ -30,6 +29,11 @@ import org.caosdb.server.database.backend.interfaces.GetFileRecordByPathImpl;
import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.database.proto.SparseEntity;
+/**
+ * Retrieve the entity id of a file with the given path (or null).
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLGetFileRecordByPath extends MySQLTransaction implements GetFileRecordByPathImpl {
public MySQLGetFileRecordByPath(final Access access) {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java
index 4837fc59..5d3e3a7d 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
@@ -32,6 +31,11 @@ import org.caosdb.server.database.backend.interfaces.GetIDByNameImpl;
import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.entity.EntityID;
+/**
+ * Retrieve the entity id of an entity with the given name (or null).
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLGetIDByName extends MySQLTransaction implements GetIDByNameImpl {
public MySQLGetIDByName(final Access access) {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetUpdateableChecksums.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetUpdateableChecksums.java
index 2081b026..81c0dfd6 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetUpdateableChecksums.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLGetUpdateableChecksums.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
@@ -30,6 +29,12 @@ import org.caosdb.server.database.backend.interfaces.GetUpdateableChecksumsImpl;
import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.entity.EntityID;
+/**
+ * Retrieve the entity ids of all files which have a checksum which should be updated (because the
+ * checksum is NULL, currently).
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLGetUpdateableChecksums extends MySQLTransaction
implements GetUpdateableChecksumsImpl {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java
index 7aa692e4..4260ae03 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java
@@ -1,3 +1,22 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.database.backend.implementation.MySQL;
import java.sql.PreparedStatement;
@@ -8,6 +27,15 @@ import org.caosdb.server.database.exceptions.IntegrityException;
import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.database.proto.SparseEntity;
+/**
+ * Insert an entity's (meaning: an abstract property's) data type.
+ *
+ * <p>This inserts the abstract property's data type as opposed to the (overridden data type which
+ * is being inserted/updated via InsertEntityPropertiesImpl.
+ *
+ * @see {@link InsertEntityPropertiesImpl}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLInsertEntityDatatype extends MySQLTransaction
implements InsertEntityDatatypeImpl {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityProperties.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityProperties.java
index 2fb7c95f..2b28a3d9 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityProperties.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityProperties.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
@@ -48,6 +47,17 @@ import org.caosdb.server.entity.EntityID;
import org.caosdb.server.entity.EntityInterface;
import org.caosdb.server.entity.wrapper.Property;
+/**
+ * Insert the entity's properties.
+ *
+ * <p>This implementation transforms a deep tree of properties into a flat representation. This
+ * transformation is a MySQL-backend implementation detail and should not be leaked to the clients.
+ *
+ * <p>The reverse transformation happens in MySQLRetrieveProperties.
+ *
+ * @see {@link MySQLRetrieveProperties}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLInsertEntityProperties extends MySQLTransaction
implements InsertEntityPropertiesImpl {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertSparseEntity.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertSparseEntity.java
index 5dcd2634..fa70a145 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertSparseEntity.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLInsertSparseEntity.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveCurrentMaxId.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveCurrentMaxId.java
index 1bc9a89d..9f56324f 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveCurrentMaxId.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveCurrentMaxId.java
@@ -1,3 +1,22 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.database.backend.implementation.MySQL;
import java.sql.PreparedStatement;
@@ -7,6 +26,11 @@ import org.caosdb.server.database.access.Access;
import org.caosdb.server.database.backend.interfaces.RetrieveCurrentMaxIdImpl;
import org.caosdb.server.database.exceptions.TransactionException;
+/**
+ * Implements {@link RetrieveCurrentMaxIdImpl} for a MySQL/MariaDB back-end.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLRetrieveCurrentMaxId extends MySQLTransaction
implements RetrieveCurrentMaxIdImpl {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveProperties.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveProperties.java
index 30a0f530..97fe4dc1 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveProperties.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveProperties.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
@@ -35,6 +34,16 @@ import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.database.proto.ProtoProperty;
import org.caosdb.server.entity.EntityID;
+/**
+ * Retrieve the entity's properties.
+ *
+ * <p>This implemation transforms the flat structure of properties which is stored in the back end
+ * to a deep tree of properties (if applicable) which is the reverse transformation to that
+ * happening in MySQLInsertEntityProperties.
+ *
+ * @see {@link MySQLInsertEntityProperties}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLRetrieveProperties extends MySQLTransaction implements RetrievePropertiesImpl {
public MySQLRetrieveProperties(final Access access) {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetFileChecksum.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetFileChecksum.java
index 69ecfba5..79c72531 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetFileChecksum.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetFileChecksum.java
@@ -1,3 +1,22 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.database.backend.implementation.MySQL;
import java.sql.PreparedStatement;
@@ -10,7 +29,7 @@ import org.caosdb.server.entity.EntityID;
/**
* Implements {@link SetFileChecksumImpl} for a MySQL/MariaDB back-end.
*
- * @author Timm Fitschen (t.fitschen@indiscale.com)
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class MySQLSetFileChecksum extends MySQLTransaction implements SetFileChecksumImpl {
diff --git a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetQueryTemplateDefinition.java b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetQueryTemplateDefinition.java
index b03630f5..ad1f40c7 100644
--- a/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetQueryTemplateDefinition.java
+++ b/src/main/java/org/caosdb/server/database/backend/implementation/MySQL/MySQLSetQueryTemplateDefinition.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.database.backend.implementation.MySQL;
@@ -29,6 +28,11 @@ import org.caosdb.server.database.backend.interfaces.SetQueryTemplateDefinitionI
import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.entity.EntityID;
+/**
+ * Implements {@link SetQueryTemplateDefinitionImpl} for a MySQL/MariaDB back-end.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class MySQLSetQueryTemplateDefinition extends MySQLTransaction
implements SetQueryTemplateDefinitionImpl {
diff --git a/src/main/java/org/caosdb/server/database/backend/interfaces/RetrieveCurrentMaxIdImpl.java b/src/main/java/org/caosdb/server/database/backend/interfaces/RetrieveCurrentMaxIdImpl.java
index 2a3ce327..ca711d52 100644
--- a/src/main/java/org/caosdb/server/database/backend/interfaces/RetrieveCurrentMaxIdImpl.java
+++ b/src/main/java/org/caosdb/server/database/backend/interfaces/RetrieveCurrentMaxIdImpl.java
@@ -1,5 +1,31 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.database.backend.interfaces;
+import org.caosdb.server.database.backend.transaction.RetrieveCurrentMaxId;
+
+/**
+ * Interface for the backend implementation of {@link RetrieveCurrentMaxId}
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public interface RetrieveCurrentMaxIdImpl extends BackendTransactionImpl {
public Integer execute();
diff --git a/src/main/java/org/caosdb/server/database/backend/transaction/RetrieveCurrentMaxId.java b/src/main/java/org/caosdb/server/database/backend/transaction/RetrieveCurrentMaxId.java
index a3b9f6d9..4dd76d30 100644
--- a/src/main/java/org/caosdb/server/database/backend/transaction/RetrieveCurrentMaxId.java
+++ b/src/main/java/org/caosdb/server/database/backend/transaction/RetrieveCurrentMaxId.java
@@ -1,8 +1,37 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.database.backend.transaction;
import org.caosdb.server.database.BackendTransaction;
import org.caosdb.server.database.backend.interfaces.RetrieveCurrentMaxIdImpl;
+/**
+ * Retrieve the maximum currently known entity id.
+ *
+ * <p>This is used by the EntityIdRegistry for the legacy ids (i.e. integer ids) to generate
+ * sequential ids which have not been used yet.
+ *
+ * @see {@link EntityIdRegistry}
+ * @see {@link LegacyIds}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class RetrieveCurrentMaxId extends BackendTransaction {
private Integer maxId;
diff --git a/src/main/java/org/caosdb/server/datatype/ReferenceValue.java b/src/main/java/org/caosdb/server/datatype/ReferenceValue.java
index 20620a43..4c84a760 100644
--- a/src/main/java/org/caosdb/server/datatype/ReferenceValue.java
+++ b/src/main/java/org/caosdb/server/datatype/ReferenceValue.java
@@ -1,5 +1,4 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
@@ -20,8 +19,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
/** @review Daniel Hornung 2022-03-04 */
@@ -41,7 +38,13 @@ import org.jdom2.Element;
* <p>Differently from other properties, they may be versioned, i.e. they may reference to a
* specific version of an entity.
*
- * <p>TODO: Ways to specify a reference value, what are the consequences of versioned references?
+ * <p>Ways to specify a reference value: {id}@{version} using either the version id (a hex'ed sha256
+ * string) or "HEAD", "HEAD~1", "HEAD~2" and so on. Note: "HEAD" always means the "HEAD"
+ * <i>after</i> the transaction. So, if you are changing the referenced entity in the same
+ * transaction and you want to reference the entity in the version before the change you need to use
+ * "HEAD~1" because that is the old version of the future.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class ReferenceValue implements SingleValue {
private EntityInterface entity = null;
diff --git a/src/main/java/org/caosdb/server/entity/Entity.java b/src/main/java/org/caosdb/server/entity/Entity.java
index dd80101f..16dbbdd5 100644
--- a/src/main/java/org/caosdb/server/entity/Entity.java
+++ b/src/main/java/org/caosdb/server/entity/Entity.java
@@ -1,11 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2020 - 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020 - 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -19,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.entity;
@@ -62,6 +59,17 @@ import org.caosdb.server.utils.TransactionLogMessage;
import org.caosdb.unit.Unit;
import org.jdom2.Element;
+/**
+ * Abstract base class for all the important entity classes.
+ *
+ * <p>This is the central data class of the server. It represents Records, RecordTypes, Properties,
+ * and Files.
+ *
+ * <p>This class holds the messages and other transient information as well as the actual data that
+ * is being retrieved from or written to the back-end during a transaction.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public abstract class Entity extends AbstractObservable implements EntityInterface {
public static final String DATATYPE_CHANGED_EVENT = "DatatypeChangedEvent";
diff --git a/src/main/java/org/caosdb/server/entity/EntityID.java b/src/main/java/org/caosdb/server/entity/EntityID.java
index 469b2e50..9f61127d 100644
--- a/src/main/java/org/caosdb/server/entity/EntityID.java
+++ b/src/main/java/org/caosdb/server/entity/EntityID.java
@@ -1,3 +1,22 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2022 - 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2022 - 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.entity;
import java.io.Serializable;
@@ -11,6 +30,8 @@ import java.util.Objects;
* <p>It also allows to link entities together, e.g. an Entity's Property with the corresponding
* abstract Property, even when the abstract Property does not have a valid ID yet (during bulk
* inserts).
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class EntityID implements Serializable {
diff --git a/src/main/java/org/caosdb/server/entity/EntityIdRegistry.java b/src/main/java/org/caosdb/server/entity/EntityIdRegistry.java
index c6010eda..e3cfd736 100644
--- a/src/main/java/org/caosdb/server/entity/EntityIdRegistry.java
+++ b/src/main/java/org/caosdb/server/entity/EntityIdRegistry.java
@@ -1,3 +1,22 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.entity;
import java.lang.reflect.Constructor;
@@ -5,11 +24,24 @@ import java.lang.reflect.InvocationTargetException;
import org.caosdb.server.database.exceptions.TransactionException;
import org.caosdb.server.transaction.Transaction;
+/**
+ * An abstract layer for managing entity ids.
+ *
+ * <p>That is, checking wether something is a well-formed id, generating well-formed ids and more.
+ *
+ * <p>This class follows a Strategy Pattern. The actual implemenation can be found in one of the
+ * implementations of the {@link EntityIdRegistryStrategy} interface.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class EntityIdRegistry {
private EntityIdRegistryStrategy strategy;
public EntityIdRegistry(Transaction<?> t) {
+ // This is the place where we will inject the new string id behavior in the
+ // future:
+ //
// this("org.caosdb.server.entity.StringIds", t);
this("org.caosdb.server.entity.LegacyIds", t);
}
@@ -18,6 +50,7 @@ public class EntityIdRegistry {
this.strategy = strategy;
}
+ /** Return a well-formed, new and unused entity id. */
public String generate() {
return this.strategy.generate();
}
@@ -40,6 +73,7 @@ public class EntityIdRegistry {
}
}
+ /** Return true if the id is a well-formed id. */
public boolean matchIdPattern(String id) {
return this.strategy.matchIdPattern(id);
}
diff --git a/src/main/java/org/caosdb/server/entity/EntityIdRegistryStrategy.java b/src/main/java/org/caosdb/server/entity/EntityIdRegistryStrategy.java
index 66235e98..e70f4f52 100644
--- a/src/main/java/org/caosdb/server/entity/EntityIdRegistryStrategy.java
+++ b/src/main/java/org/caosdb/server/entity/EntityIdRegistryStrategy.java
@@ -1,7 +1,31 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.entity;
import org.caosdb.server.transaction.Transaction;
+/**
+ * Strategy interface for {@link EntityIdRegistry}.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public abstract class EntityIdRegistryStrategy {
private Transaction<?> transaction;
diff --git a/src/main/java/org/caosdb/server/entity/LegacyIds.java b/src/main/java/org/caosdb/server/entity/LegacyIds.java
index 38f5bfef..04541293 100644
--- a/src/main/java/org/caosdb/server/entity/LegacyIds.java
+++ b/src/main/java/org/caosdb/server/entity/LegacyIds.java
@@ -1,8 +1,36 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.entity;
import org.caosdb.server.database.backend.transaction.RetrieveCurrentMaxId;
import org.caosdb.server.transaction.Transaction;
+/**
+ * Implementation of {@link EntityIdRegistryStrategy} which re-implements the legacy integer-based
+ * entity ids.
+ *
+ * <p>This implementation will generate sequences of entity ids and matches all strings which can be
+ * cast to integer as well-formed entity ids.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class LegacyIds extends EntityIdRegistryStrategy {
private boolean isInit;
diff --git a/src/main/java/org/caosdb/server/entity/StringIds.java b/src/main/java/org/caosdb/server/entity/StringIds.java
index ca60730a..e1f5cb04 100644
--- a/src/main/java/org/caosdb/server/entity/StringIds.java
+++ b/src/main/java/org/caosdb/server/entity/StringIds.java
@@ -1,8 +1,33 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.entity;
import java.util.UUID;
import org.caosdb.server.transaction.Transaction;
+/**
+ * Example implementation for string ids based on UUID.
+ *
+ * @see {@link EntityIdRegistryStrategy}
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class StringIds extends EntityIdRegistryStrategy {
public StringIds(Transaction<?> t) {
diff --git a/src/main/java/org/caosdb/server/entity/container/RetrieveContainer.java b/src/main/java/org/caosdb/server/entity/container/RetrieveContainer.java
index d58d85dc..99262f56 100644
--- a/src/main/java/org/caosdb/server/entity/container/RetrieveContainer.java
+++ b/src/main/java/org/caosdb/server/entity/container/RetrieveContainer.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.entity.container;
@@ -27,6 +26,23 @@ import org.apache.shiro.subject.Subject;
import org.caosdb.server.entity.EntityID;
import org.caosdb.server.entity.RetrieveEntity;
+/**
+ * A container of entities which are about to be retrieved.
+ *
+ * <p>A suitable name would also be `ReadOnlyEntitiesContainer` because entities in this container
+ * will only be retrieved, not changed, inserted or deleted.
+ *
+ * <p>Because all entities are expected to be existing, all entities can theoretically be identified
+ * via their (valid) entity id (plus version id, if applicable).
+ *
+ * <p>However, sometimes, entities are being retrieved via the name instead of the id. Then the id
+ * has to be resolved first. This happens during the init stage of the owning transaction.
+ *
+ * <p>The container also holds the flags of the current transaction (e.g. cache=false, ACL=true,
+ * ...).
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class RetrieveContainer extends TransactionContainer {
private static final long serialVersionUID = 4816050921531043503L;
diff --git a/src/main/java/org/caosdb/server/entity/container/TransactionContainer.java b/src/main/java/org/caosdb/server/entity/container/TransactionContainer.java
index f2f2c025..049f54cd 100644
--- a/src/main/java/org/caosdb/server/entity/container/TransactionContainer.java
+++ b/src/main/java/org/caosdb/server/entity/container/TransactionContainer.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.entity.container;
@@ -38,6 +37,12 @@ import org.caosdb.server.query.Query;
import org.caosdb.server.utils.EntityStatus;
import org.jdom2.Element;
+/**
+ * Base class for transaction containers used by classes such as {@link RetrieveContainer} or {@link
+ * WritableContainer}.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class TransactionContainer extends Container<EntityInterface>
implements ToElementable, JobTarget {
@@ -122,7 +127,6 @@ public class TransactionContainer extends Container<EntityInterface>
private TransactionBenchmark benchmark;
private Query query;
- private Integer currentMaxId = null;
public void setFiles(final HashMap<String, FileProperties> files) {
this.files = files;
diff --git a/src/main/java/org/caosdb/server/grpc/EntityTransactionServiceImpl.java b/src/main/java/org/caosdb/server/grpc/EntityTransactionServiceImpl.java
index c8f56610..33866768 100644
--- a/src/main/java/org/caosdb/server/grpc/EntityTransactionServiceImpl.java
+++ b/src/main/java/org/caosdb/server/grpc/EntityTransactionServiceImpl.java
@@ -1,8 +1,8 @@
/*
* This file is a part of the CaosDB Project.
*
- * Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2021,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -18,7 +18,6 @@
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
*/
-
package org.caosdb.server.grpc;
import io.grpc.stub.StreamObserver;
@@ -68,6 +67,11 @@ import org.caosdb.server.transaction.UpdateACL;
import org.caosdb.server.transaction.WriteTransaction;
import org.caosdb.server.utils.ServerMessages;
+/**
+ * Main entry point for the entity transaction service of the servers GRPC API.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class EntityTransactionServiceImpl extends EntityTransactionServiceImplBase {
// TODO(tf) let the clients define the time zone of the date time values which are being returned.
diff --git a/src/main/java/org/caosdb/server/grpc/GrpcToCaosDBConverters.java b/src/main/java/org/caosdb/server/grpc/GrpcToCaosDBConverters.java
index 1c0b0f42..587b8966 100644
--- a/src/main/java/org/caosdb/server/grpc/GrpcToCaosDBConverters.java
+++ b/src/main/java/org/caosdb/server/grpc/GrpcToCaosDBConverters.java
@@ -1,8 +1,8 @@
/*
* This file is a part of the CaosDB Project.
*
- * Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -16,9 +16,7 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
*/
-
package org.caosdb.server.grpc;
import java.util.ArrayList;
@@ -64,14 +62,13 @@ import org.caosdb.server.permissions.EntityACLFactory;
import org.caosdb.server.utils.EntityStatus;
import org.caosdb.server.utils.ServerMessages;
+/**
+ * Utility class for converting GRPC's native objects into our own CaosDB objects.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class GrpcToCaosDBConverters {
- /*
- public EntityID getId(final String id) {
- return new EntityID(Integer.parseInt(id));
- }
- */
-
public Role convert(final EntityRole role) {
switch (role) {
case ENTITY_ROLE_FILE:
diff --git a/src/main/java/org/caosdb/server/jobs/JobConfig.java b/src/main/java/org/caosdb/server/jobs/JobConfig.java
index ab6cd819..b2bb0d4a 100644
--- a/src/main/java/org/caosdb/server/jobs/JobConfig.java
+++ b/src/main/java/org/caosdb/server/jobs/JobConfig.java
@@ -1,8 +1,8 @@
/*
* This file is a part of the CaosDB Project.
*
- * Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2021,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
diff --git a/src/main/java/org/caosdb/server/jobs/LazyEntityResolver.java b/src/main/java/org/caosdb/server/jobs/LazyEntityResolver.java
index 285378e1..a85b0ca0 100644
--- a/src/main/java/org/caosdb/server/jobs/LazyEntityResolver.java
+++ b/src/main/java/org/caosdb/server/jobs/LazyEntityResolver.java
@@ -1,3 +1,22 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.jobs;
import org.caosdb.server.database.backend.transaction.RetrieveParents;
@@ -8,12 +27,30 @@ import org.caosdb.server.entity.container.PropertyContainer;
import org.caosdb.server.entity.wrapper.EntityWrapper;
import org.caosdb.server.transaction.Transaction;
+/**
+ * Implementation of {@link EntityInterface} which retrieves the parents and properties only when
+ * requested via getProperties and getParents.
+ *
+ * <p>This is particularly useful for jobs sharing the same entity object between jobs which need
+ * different parts of it while reducing the logic of checking whether the entity is "only" sparse,
+ * or has been retrieved fully and so on.
+ *
+ * <p>However, when the entities parents or properties are being retrieved after the transaction's
+ * access has been released, a {@link IllegalStateException} will be thrown.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class LazyEntityResolver extends EntityWrapper {
private Transaction<?> transaction;
private boolean propertiesResolved = false;
private boolean parentsResolved = false;
+ /**
+ * Constructor.
+ *
+ * <p>Initialize this with a sparse entity.
+ */
public LazyEntityResolver(EntityInterface entity, Transaction<?> transaction) {
super(entity);
this.transaction = transaction;
diff --git a/src/main/java/org/caosdb/server/jobs/Schedule.java b/src/main/java/org/caosdb/server/jobs/Schedule.java
index ab0f63a2..bc51fca9 100644
--- a/src/main/java/org/caosdb/server/jobs/Schedule.java
+++ b/src/main/java/org/caosdb/server/jobs/Schedule.java
@@ -3,8 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2020-2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2020-2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2020-2021,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020-2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -35,6 +35,8 @@ import org.caosdb.server.entity.EntityInterface;
* <p>The Schedule class orders jobs by {@link TransactionStage} and also assures that jobs are
* skipped when appropriate and to prevent that jobs run more than once (because sometimes they
* trigger each other).
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class Schedule {
diff --git a/src/main/java/org/caosdb/server/jobs/ScheduledJob.java b/src/main/java/org/caosdb/server/jobs/ScheduledJob.java
index f729e004..1754f19f 100644
--- a/src/main/java/org/caosdb/server/jobs/ScheduledJob.java
+++ b/src/main/java/org/caosdb/server/jobs/ScheduledJob.java
@@ -1,8 +1,8 @@
/*
* This file is a part of the CaosDB Project.
*
- * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2020,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -28,7 +28,7 @@ import org.caosdb.server.entity.Message;
* <p>It is mainly a means to have simplified interface for the Scheduler which also measures the
* execution time of the job "from outside".
*
- * @author Timm Fitschen (t.fitschen@indiscale.com)
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class ScheduledJob {
diff --git a/src/main/java/org/caosdb/server/jobs/core/CheckDatatypePresent.java b/src/main/java/org/caosdb/server/jobs/core/CheckDatatypePresent.java
index adc02caf..257e1895 100644
--- a/src/main/java/org/caosdb/server/jobs/core/CheckDatatypePresent.java
+++ b/src/main/java/org/caosdb/server/jobs/core/CheckDatatypePresent.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -41,10 +40,11 @@ import org.caosdb.server.utils.EntityStatus;
import org.caosdb.server.utils.ServerMessages;
/**
- * Check whether the entity has a data type. Assign the data type of the abstract property if
- * necessary
+ * Check whether the entity has a data type.
+ *
+ * <p>Assign the data type of the abstract property if necessary.
*
- * @author tf
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public final class CheckDatatypePresent extends EntityJob {
diff --git a/src/main/java/org/caosdb/server/jobs/core/CheckDependenciesBeforeDeletion.java b/src/main/java/org/caosdb/server/jobs/core/CheckDependenciesBeforeDeletion.java
index c9f6de7c..ecbbf4af 100644
--- a/src/main/java/org/caosdb/server/jobs/core/CheckDependenciesBeforeDeletion.java
+++ b/src/main/java/org/caosdb/server/jobs/core/CheckDependenciesBeforeDeletion.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
diff --git a/src/main/java/org/caosdb/server/jobs/core/CheckParValid.java b/src/main/java/org/caosdb/server/jobs/core/CheckParValid.java
index e125e5dd..fd235c21 100644
--- a/src/main/java/org/caosdb/server/jobs/core/CheckParValid.java
+++ b/src/main/java/org/caosdb/server/jobs/core/CheckParValid.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -42,7 +41,7 @@ import org.caosdb.server.utils.ServerMessages;
/**
* Check whether all parents of an entity are valid/qualified.
*
- * @author tf
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
@JobAnnotation(stage = TransactionStage.PRE_CHECK)
public class CheckParValid extends EntityJob {
diff --git a/src/main/java/org/caosdb/server/jobs/core/CheckPropValid.java b/src/main/java/org/caosdb/server/jobs/core/CheckPropValid.java
index b57e7abb..bfd2bc30 100644
--- a/src/main/java/org/caosdb/server/jobs/core/CheckPropValid.java
+++ b/src/main/java/org/caosdb/server/jobs/core/CheckPropValid.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -41,7 +40,7 @@ import org.caosdb.server.utils.ServerMessages;
/**
* Check whether all properties of an entity are valid or qualified.
*
- * @author tf
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
@JobAnnotation(stage = TransactionStage.PRE_CHECK)
public class CheckPropValid extends EntityJob {
diff --git a/src/main/java/org/caosdb/server/jobs/core/CheckRefidIsaParRefid.java b/src/main/java/org/caosdb/server/jobs/core/CheckRefidIsaParRefid.java
index af7269a3..7b0a9977 100644
--- a/src/main/java/org/caosdb/server/jobs/core/CheckRefidIsaParRefid.java
+++ b/src/main/java/org/caosdb/server/jobs/core/CheckRefidIsaParRefid.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -41,10 +40,11 @@ import org.caosdb.server.utils.Observer;
import org.caosdb.server.utils.ServerMessages;
/**
- * Check if the referenced entity is in the scope of the data type. E.g. if the data type is
- * 'Person' the referenced entity is to be a child of 'Person'.
+ * Check if the referenced entity is in the scope of the data type.
+ *
+ * <p>E.g. if the data type is 'Person' the referenced entity is to be a child of 'Person'.
*
- * @author tf
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class CheckRefidIsaParRefid extends EntityJob implements Observer {
diff --git a/src/main/java/org/caosdb/server/jobs/core/CheckRefidValid.java b/src/main/java/org/caosdb/server/jobs/core/CheckRefidValid.java
index b01c5bf3..86e95542 100644
--- a/src/main/java/org/caosdb/server/jobs/core/CheckRefidValid.java
+++ b/src/main/java/org/caosdb/server/jobs/core/CheckRefidValid.java
@@ -1,11 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2020-2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2020-2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2020-2021,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020-2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -19,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -43,7 +40,7 @@ import org.caosdb.server.utils.ServerMessages;
/**
* Check whether a reference property is pointing to a valid entity.
*
- * @author tf
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class CheckRefidValid extends EntityJob implements Observer {
@Override
diff --git a/src/main/java/org/caosdb/server/jobs/core/EntityIdHandler.java b/src/main/java/org/caosdb/server/jobs/core/EntityIdHandler.java
deleted file mode 100644
index bd4d4b80..00000000
--- a/src/main/java/org/caosdb/server/jobs/core/EntityIdHandler.java
+++ /dev/null
@@ -1,25 +0,0 @@
-package org.caosdb.server.jobs.core;
-
-import org.caosdb.server.entity.EntityInterface;
-import org.caosdb.server.entity.InsertEntity;
-import org.caosdb.server.entity.Message;
-import org.caosdb.server.jobs.EntityJob;
-import org.caosdb.server.jobs.JobAnnotation;
-import org.caosdb.server.jobs.TransactionStage;
-import org.caosdb.server.transaction.WriteTransactionInterface;
-import org.caosdb.server.utils.EntityStatus;
-
-@JobAnnotation(stage = TransactionStage.PRE_TRANSACTION)
-public class EntityIdHandler extends EntityJob {
-
- @Override
- protected void run() throws Message {
- EntityInterface entity = getEntity();
- if (entity instanceof InsertEntity
- && getTransaction() instanceof WriteTransactionInterface
- && entity.getEntityStatus() == EntityStatus.QUALIFIED) {
- String id = ((WriteTransactionInterface) getTransaction()).generateId();
- entity.getId().setId(id);
- }
- }
-}
diff --git a/src/main/java/org/caosdb/server/jobs/core/EntityStateJob.java b/src/main/java/org/caosdb/server/jobs/core/EntityStateJob.java
index 40971801..01b0ecb2 100644
--- a/src/main/java/org/caosdb/server/jobs/core/EntityStateJob.java
+++ b/src/main/java/org/caosdb/server/jobs/core/EntityStateJob.java
@@ -1,8 +1,8 @@
/*
* This file is a part of the CaosDB Project.
*
- * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2020,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
diff --git a/src/main/java/org/caosdb/server/jobs/core/GenerateEntityId.java b/src/main/java/org/caosdb/server/jobs/core/GenerateEntityId.java
new file mode 100644
index 00000000..4bb23ab4
--- /dev/null
+++ b/src/main/java/org/caosdb/server/jobs/core/GenerateEntityId.java
@@ -0,0 +1,50 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+package org.caosdb.server.jobs.core;
+
+import org.caosdb.server.entity.EntityInterface;
+import org.caosdb.server.entity.InsertEntity;
+import org.caosdb.server.entity.Message;
+import org.caosdb.server.jobs.EntityJob;
+import org.caosdb.server.jobs.JobAnnotation;
+import org.caosdb.server.jobs.TransactionStage;
+import org.caosdb.server.transaction.WriteTransactionInterface;
+import org.caosdb.server.utils.EntityStatus;
+
+/**
+ * Generates entity ids for newly inserted entities.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
+@JobAnnotation(stage = TransactionStage.PRE_TRANSACTION)
+public class GenerateEntityId extends EntityJob {
+
+ @Override
+ protected void run() throws Message {
+ EntityInterface entity = getEntity();
+ if (entity instanceof InsertEntity
+ && getTransaction() instanceof WriteTransactionInterface
+ && entity.getEntityStatus() == EntityStatus.QUALIFIED) {
+ String id = ((WriteTransactionInterface) getTransaction()).generateId();
+ entity.getId().setId(id);
+ }
+ }
+}
diff --git a/src/main/java/org/caosdb/server/jobs/core/Inheritance.java b/src/main/java/org/caosdb/server/jobs/core/Inheritance.java
index 7bcda3b9..70aea112 100644
--- a/src/main/java/org/caosdb/server/jobs/core/Inheritance.java
+++ b/src/main/java/org/caosdb/server/jobs/core/Inheritance.java
@@ -1,11 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2019-2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2019-2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2019-2021,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2019-2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -19,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
diff --git a/src/main/java/org/caosdb/server/jobs/core/NoCache.java b/src/main/java/org/caosdb/server/jobs/core/NoCache.java
index 6ad38f49..78b54f6c 100644
--- a/src/main/java/org/caosdb/server/jobs/core/NoCache.java
+++ b/src/main/java/org/caosdb/server/jobs/core/NoCache.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -26,6 +25,13 @@ import org.caosdb.server.jobs.FlagJob;
import org.caosdb.server.jobs.JobAnnotation;
import org.caosdb.server.jobs.TransactionStage;
+/**
+ * Turn off caching, just for the current transaction.
+ *
+ * <p>If the caching is disabled globally this has no effect.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
@JobAnnotation(
flag = "cache",
defaultValue = "true",
diff --git a/src/main/java/org/caosdb/server/jobs/core/ProcessNameProperties.java b/src/main/java/org/caosdb/server/jobs/core/ProcessNameProperties.java
index 1fdd59e2..ecac0504 100644
--- a/src/main/java/org/caosdb/server/jobs/core/ProcessNameProperties.java
+++ b/src/main/java/org/caosdb/server/jobs/core/ProcessNameProperties.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -42,9 +41,13 @@ import org.caosdb.server.utils.EntityStatus;
import org.caosdb.server.utils.ServerMessages;
/**
- * To be called after CheckPropValid and Inheritance.
+ * Checks if a property is a subproperty of "name" and flags the entity accordingly.
+ *
+ * <p>This enables a different behavior in the search.
+ *
+ * <p>To be called after CheckPropValid and Inheritance.
*
- * @author tf
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
@JobAnnotation(stage = TransactionStage.PRE_TRANSACTION)
public class ProcessNameProperties extends EntityJob {
diff --git a/src/main/java/org/caosdb/server/jobs/core/ResolveNames.java b/src/main/java/org/caosdb/server/jobs/core/ResolveNames.java
index d1ab07b7..b19aca6d 100644
--- a/src/main/java/org/caosdb/server/jobs/core/ResolveNames.java
+++ b/src/main/java/org/caosdb/server/jobs/core/ResolveNames.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.jobs.core;
@@ -36,6 +35,18 @@ import org.caosdb.server.jobs.ContainerJob;
import org.caosdb.server.utils.EntityStatus;
import org.caosdb.server.utils.ServerMessages;
+/**
+ * Resolve the names to ids for all entities in the current retrieval.
+ *
+ * <p>If an entity has a name which looks like an id: Check whether that is an existing id first.
+ *
+ * <p>Otherwise, search via the name.
+ *
+ * <p>It there are multiple matching entities, add all of them to the current container. The clients
+ * may handle the ambiguity.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class ResolveNames extends ContainerJob {
@Override
diff --git a/src/main/java/org/caosdb/server/query/IDFilter.java b/src/main/java/org/caosdb/server/query/IDFilter.java
index c0089034..80111397 100644
--- a/src/main/java/org/caosdb/server/query/IDFilter.java
+++ b/src/main/java/org/caosdb/server/query/IDFilter.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.query;
@@ -32,6 +31,11 @@ import java.sql.SQLException;
import org.caosdb.server.query.Query.QueryException;
import org.jdom2.Element;
+/**
+ * Applies an ID filter to the query's current result set.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class IDFilter implements EntityFilterInterface {
private final String operator;
diff --git a/src/main/java/org/caosdb/server/query/POV.java b/src/main/java/org/caosdb/server/query/POV.java
index af5b446f..6ee5f9d0 100644
--- a/src/main/java/org/caosdb/server/query/POV.java
+++ b/src/main/java/org/caosdb/server/query/POV.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.query;
@@ -50,6 +49,11 @@ import org.jdom2.Element;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * Applies a POV (Property-operator-value) filter to the query's current result set.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class POV implements EntityFilterInterface {
public static final Pattern NUMBER_PATTERN =
Pattern.compile(
diff --git a/src/main/java/org/caosdb/server/resource/UserResource.java b/src/main/java/org/caosdb/server/resource/UserResource.java
index 362e5eb6..e7561dd8 100644
--- a/src/main/java/org/caosdb/server/resource/UserResource.java
+++ b/src/main/java/org/caosdb/server/resource/UserResource.java
@@ -1,9 +1,10 @@
/*
- * ** header v3.0
* This file is a part of the CaosDB Project.
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -17,8 +18,6 @@
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
*/
package org.caosdb.server.resource;
@@ -48,7 +47,7 @@ import org.restlet.representation.Representation;
/**
* This class handles requests for Users.
*
- * @author Timm Fitschen
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class UserResource extends AbstractCaosDBServerResource {
diff --git a/src/main/java/org/caosdb/server/resource/transaction/EntityResource.java b/src/main/java/org/caosdb/server/resource/transaction/EntityResource.java
index c920d8c9..8aa5bbb4 100644
--- a/src/main/java/org/caosdb/server/resource/transaction/EntityResource.java
+++ b/src/main/java/org/caosdb/server/resource/transaction/EntityResource.java
@@ -3,8 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
- * Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2021,2023 IndiScale GmbH <info@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -53,11 +53,16 @@ import org.restlet.representation.Representation;
*
* <p>The GET requests (Retrieval) is handled in the superclass {@link RetrieveEntityResource}.
*
- * @author Timm Fitschen (t.fitschen@indiscale.com)
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public class EntityResource extends RetrieveEntityResource {
- /** Handle entity deletions (DELETE requests). */
+ /**
+ * Handle entity deletions (DELETE requests).
+ *
+ * <p>Note: The list of entity "specifier" is treated strictly as a list of entity ids. You cannot
+ * delete an entity by name.
+ */
@Override
protected final Representation httpDeleteInChildClass() throws Exception {
diff --git a/src/main/java/org/caosdb/server/resource/transaction/RetrieveEntityResource.java b/src/main/java/org/caosdb/server/resource/transaction/RetrieveEntityResource.java
index 8f2809b2..7a4ca373 100644
--- a/src/main/java/org/caosdb/server/resource/transaction/RetrieveEntityResource.java
+++ b/src/main/java/org/caosdb/server/resource/transaction/RetrieveEntityResource.java
@@ -3,8 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
- * Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2021,2023 IndiScale GmbH <info@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -27,6 +27,7 @@ import java.sql.SQLException;
import org.caosdb.server.CaosDBException;
import org.caosdb.server.database.backend.implementation.MySQL.ConnectionException;
import org.caosdb.server.entity.container.RetrieveContainer;
+import org.caosdb.server.jobs.core.ResolveNames;
import org.caosdb.server.resource.AbstractCaosDBServerResource;
import org.caosdb.server.transaction.Retrieve;
import org.jdom2.Document;
@@ -37,14 +38,15 @@ import org.restlet.representation.Representation;
* Handles GET requests for different subclasses which all have in common that they retrieve
* Entities (plus other information in some cases).
*
- * @author Timm Fitschen (t.fitschen@indiscale.com)
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
*/
public abstract class RetrieveEntityResource extends AbstractCaosDBServerResource {
/**
- * Parse the segment which specifies the entities which are to be retrieved
+ * Parse the segment which specifies the entities which are to be retrieved.
*
- * @param container
+ * <p>The segments are being treated as names here. The {@link ResolveNames} job is responsible
+ * for detecting whether the name is actually an id.
*/
protected void handleRetrieveContainer(final RetrieveContainer container) {
diff --git a/src/main/java/org/caosdb/server/transaction/EntityTransactionInterface.java b/src/main/java/org/caosdb/server/transaction/EntityTransactionInterface.java
index dc98f826..9d96c4e7 100644
--- a/src/main/java/org/caosdb/server/transaction/EntityTransactionInterface.java
+++ b/src/main/java/org/caosdb/server/transaction/EntityTransactionInterface.java
@@ -1,7 +1,32 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.transaction;
import org.caosdb.server.entity.EntityID;
+/**
+ * This interface is implemented by all transactions of entities (as opposed to transaction which
+ * only concern users or other kinds of transactions).
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public interface EntityTransactionInterface extends TransactionInterface {
public boolean matchIdPattern(String id);
diff --git a/src/main/java/org/caosdb/server/transaction/Retrieve.java b/src/main/java/org/caosdb/server/transaction/Retrieve.java
index 4fc4fbc2..643c1201 100644
--- a/src/main/java/org/caosdb/server/transaction/Retrieve.java
+++ b/src/main/java/org/caosdb/server/transaction/Retrieve.java
@@ -115,21 +115,6 @@ public class Retrieve extends Transaction<RetrieveContainer> {
private void retrieveFullEntities(final RetrieveContainer container, final Access access)
throws Exception {
execute(new RetrieveFullEntityTransaction(container), access);
- for (EntityInterface e : container) {
- if (e.getEntityStatus() == EntityStatus.NONEXISTENT
- && e.hasId()
- && e.hasName()
- && e.getName().equals(e.getId().toString())) {
- // remove duplicates by name
- for (EntityInterface o : container) {
- if (o.getEntityStatus() == EntityStatus.VALID
- && o.hasName()
- && e.getName().equalsIgnoreCase(o.getName())) {
- e.setEntityStatus(EntityStatus.IGNORE);
- }
- }
- }
- }
}
@Override
diff --git a/src/main/java/org/caosdb/server/transaction/Transaction.java b/src/main/java/org/caosdb/server/transaction/Transaction.java
index 8474125d..2ccff7b2 100644
--- a/src/main/java/org/caosdb/server/transaction/Transaction.java
+++ b/src/main/java/org/caosdb/server/transaction/Transaction.java
@@ -3,8 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2019-2021 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2019-2021 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2019-2021,2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2019-2021,2023 Timm Fitschen <t.fitschen@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
@@ -55,6 +55,14 @@ import org.caosdb.server.utils.Observer;
import org.caosdb.server.utils.UseCacheResource;
import org.caosdb.server.utils.UseCacheResourceDelegate;
+/**
+ * The NoOpCache is used when the caching is diabled (globally or for the current transaction.
+ *
+ * <p>It results in much simpler code when the callers do not need to check whether the caching is
+ * active all the time.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
@SuppressWarnings("rawtypes")
class NoOpCache implements Map {
@@ -117,6 +125,14 @@ class NoOpCache implements Map {
}
}
+/**
+ * Abstract base implementation for all EntityTransactions (Transaction involving entities).
+ *
+ * <p>Handles caching, benchmark timing, the access to the back end, generates and checks entity
+ * ids, holds the state of the transaction and triggers the scheduler to run the jobs.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public abstract class Transaction<C extends TransactionContainer> extends AbstractObservable
implements EntityTransactionInterface, UseCacheResource {
diff --git a/src/main/java/org/caosdb/server/transaction/WriteTransaction.java b/src/main/java/org/caosdb/server/transaction/WriteTransaction.java
index 9a355410..b780d3d6 100644
--- a/src/main/java/org/caosdb/server/transaction/WriteTransaction.java
+++ b/src/main/java/org/caosdb/server/transaction/WriteTransaction.java
@@ -3,8 +3,8 @@
*
* Copyright (C) 2018 Research Group Biomedical Physics,
* Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- * Copyright (C) 2019-2022 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2019-2022 Timm Fitschen <t.fitschen@indiscale.com>
+ * Copyright (C) 2019-2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2019-2023 Timm Fitschen <t.fitschen@indiscale.com>
* Copyright (C) 2022 Daniel Hornung <d.hornung@indiscale.com>
*
* This program is free software: you can redistribute it and/or modify
diff --git a/src/main/java/org/caosdb/server/utils/UseCacheResource.java b/src/main/java/org/caosdb/server/utils/UseCacheResource.java
index 23196012..89057f51 100644
--- a/src/main/java/org/caosdb/server/utils/UseCacheResource.java
+++ b/src/main/java/org/caosdb/server/utils/UseCacheResource.java
@@ -1,5 +1,30 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.utils;
+/**
+ * Interface which indicates that a class can turn on and off the caching of the current transaction
+ * and inform the caller about the state of the transactions's caching.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public interface UseCacheResource {
public default boolean useCache() {
diff --git a/src/main/java/org/caosdb/server/utils/UseCacheResourceDelegate.java b/src/main/java/org/caosdb/server/utils/UseCacheResourceDelegate.java
index 81d862b0..c537f0a8 100644
--- a/src/main/java/org/caosdb/server/utils/UseCacheResourceDelegate.java
+++ b/src/main/java/org/caosdb/server/utils/UseCacheResourceDelegate.java
@@ -1,7 +1,35 @@
+/*
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2023 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2023 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
package org.caosdb.server.utils;
import org.caosdb.server.CaosDBServer;
+/**
+ * Basic implementation of the {@link UseCacheResource} interface.
+ *
+ * <p>This implementation uses a Delegator Pattern to link different UseCacheResources together.
+ * This is uses to delegate the responsibility to the transaction as the final Object of the
+ * delegation.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
public class UseCacheResourceDelegate implements UseCacheResource {
private boolean useCache = CaosDBServer.useCache();
private UseCacheResource delegate = null;
--
GitLab