diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/NodeNotFoundException.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/NodeNotFoundException.java
index 16de8d916a..91fefc4a90 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/NodeNotFoundException.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/NodeNotFoundException.java
@@ -18,10 +18,18 @@
*/
package org.phoebus.service.saveandrestore;
+/**
+ * Custom {@link Exception} used to indicate that a wanted {@link org.phoebus.applications.saveandrestore.model.Node}
+ * requested by client could not be found.
+ */
public class NodeNotFoundException extends RuntimeException {
private static final long serialVersionUID = -1828621412391490962L;
-
+
+ /**
+ *
+ * @param message Some error message...
+ */
public NodeNotFoundException(String message) {
super(message);
}
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/SnapshotNotFoundException.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/SnapshotNotFoundException.java
index e51dee52f9..0663832132 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/SnapshotNotFoundException.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/SnapshotNotFoundException.java
@@ -18,10 +18,18 @@
*/
package org.phoebus.service.saveandrestore;
+/**
+ * Custom {@link Exception} used to indicate that a {@link org.phoebus.applications.saveandrestore.model.Snapshot}
+ * request by client could not be found.
+ */
public class SnapshotNotFoundException extends RuntimeException {
private static final long serialVersionUID = -980968730210448760L;
-
+
+ /**
+ *
+ * @param message Suitable error message.
+ */
public SnapshotNotFoundException(String message) {
super(message);
}
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/Application.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/Application.java
index fac6e03d21..07533df571 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/Application.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/Application.java
@@ -1,5 +1,5 @@
/**
- * Copyright (C) 2018 European Spallation Source ERIC.
+ * Copyright (C) 2024 European Spallation Source ERIC.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
@@ -17,14 +17,12 @@
*/
package org.phoebus.service.saveandrestore.application;
-import com.fasterxml.jackson.databind.annotation.JsonAppend.Prop;
import org.phoebus.service.saveandrestore.migration.MigrateRdbToElastic;
import org.phoebus.service.saveandrestore.persistence.dao.impl.elasticsearch.ElasticsearchDAO;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
-import org.springframework.core.env.PropertiesPropertySource;
import org.springframework.scheduling.annotation.EnableScheduling;
import java.util.ArrayList;
@@ -32,6 +30,9 @@
import java.util.List;
import java.util.Properties;
+/**
+ * Save-and-restore service main class.
+ */
@SpringBootApplication(scanBasePackages = "org.phoebus.service.saveandrestore")
@EnableScheduling
@EnableAutoConfiguration
@@ -48,6 +49,10 @@ private static void help() {
System.out.println();
}
+ /**
+ * Main class
+ * @param args Program arguments. Specifying -help will print options.
+ */
public static void main(String[] args) {
// load the default properties
@@ -87,7 +92,6 @@ public static void main(String[] args) {
}
-
context = SpringApplication.run(Application.class, args);
if (runMigration) {
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/PropertiesHelper.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/PropertiesHelper.java
index 4fa2e84d55..976c6a4fa7 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/PropertiesHelper.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/application/PropertiesHelper.java
@@ -5,6 +5,9 @@
import java.util.Properties;
import java.util.logging.Logger;
+/**
+ * Helper class to read application properties.
+ */
public class PropertiesHelper {
static Properties prop = new Properties();
@@ -26,6 +29,10 @@ public class PropertiesHelper {
}
}
+ /**
+ *
+ * @return Properties read from application properties file.
+ */
public static Properties getProperties() {
return prop;
}
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/epics/exception/PVConversionException.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/epics/exception/PVConversionException.java
deleted file mode 100644
index 81251020dd..0000000000
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/epics/exception/PVConversionException.java
+++ /dev/null
@@ -1,27 +0,0 @@
-/**
- * Copyright (C) 2018 European Spallation Source ERIC.
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License
- * as published by the Free Software Foundation; either version 2
- * 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 General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- */
-package org.phoebus.service.saveandrestore.epics.exception;
-
-public class PVConversionException extends RuntimeException {
-
- private static final long serialVersionUID = -5717295423339192670L;
-
- public PVConversionException(String message) {
- super(message);
- }
-}
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/migration/MigrateRdbToElastic.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/migration/MigrateRdbToElastic.java
index c033b64882..713a91fc4a 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/migration/MigrateRdbToElastic.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/migration/MigrateRdbToElastic.java
@@ -65,6 +65,11 @@ public class MigrateRdbToElastic {
private final Logger logger = Logger.getLogger(MigrateRdbToElastic.class.getName());
+ /**
+ * @param elasticsearchDAO An {@link ElasticsearchDAO} object.
+ * @param legacyServiceUrl The URL to the legacy RDB-based save-and-restore service.
+ * @param dryRun true for a dry run.
+ */
public MigrateRdbToElastic(ElasticsearchDAO elasticsearchDAO, String legacyServiceUrl, boolean dryRun) {
this.legacyServiceUrl = legacyServiceUrl;
this.dryRun = dryRun;
@@ -72,6 +77,9 @@ public MigrateRdbToElastic(ElasticsearchDAO elasticsearchDAO, String legacyServi
}
+ /**
+ * Runs the migration.
+ */
public void runMigration() {
RestTemplate restTemplate = new RestTemplate();
Node legacyRootNode = restTemplate.getForObject(legacyServiceUrl + "/root", Node.class);
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/model/ESTreeNode.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/model/ESTreeNode.java
index 47e8aaa642..0d08c8af7f 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/model/ESTreeNode.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/model/ESTreeNode.java
@@ -23,23 +23,42 @@
import java.util.List;
+/**
+ * Pojo class representing a tree node and a list of child nodes.
+ */
public class ESTreeNode {
private Node node;
private List childNodes;
+ /**
+ * @return The {@link Node} object represented by this class.
+ */
public Node getNode() {
return node;
}
+ /**
+ * Setter
+ * @param node A {@link Node} object
+ */
public void setNode(Node node) {
this.node = node;
}
+ /**
+ *
+ * @return List of child {@link Node}s for the {@link Node} object represented by this class. May be null
+ * or empty.
+ */
public List getChildNodes() {
return childNodes;
}
+ /**
+ *
+ * @param childNodes {@link List} of child {@link Node}s
+ */
public void setChildNodes(List childNodes) {
this.childNodes = childNodes;
}
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/config/ElasticConfig.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/config/ElasticConfig.java
index 65548d15e2..eb6f1b289d 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/config/ElasticConfig.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/config/ElasticConfig.java
@@ -37,6 +37,9 @@
import static org.phoebus.applications.saveandrestore.model.Node.ROOT_FOLDER_UNIQUE_ID;
+/**
+ * Configures the Elasticsearch environment, e.g. creates indices if they do not exist.
+ */
@Configuration
@ComponentScan(basePackages = {"org.phoebus.service.saveandrestore"})
@PropertySource("classpath:application.properties")
@@ -44,30 +47,38 @@ public class ElasticConfig {
private static final Logger logger = Logger.getLogger(ElasticConfig.class.getName());
+ @SuppressWarnings("unused")
@Value("${elasticsearch.tree_node.index:saveandrestore_tree}")
- public String ES_TREE_INDEX;
+ private String ES_TREE_INDEX;
+ @SuppressWarnings("unused")
@Value("${elasticsearch.configuration_node.index:saveandrestore_configuration}")
- public String ES_CONFIGURATION_INDEX;
+ private String ES_CONFIGURATION_INDEX;
+ @SuppressWarnings("unused")
@Value("${elasticsearch.snapshot_node.index:saveandrestore_snapshot}")
- public String ES_SNAPSHOT_INDEX;
+ private String ES_SNAPSHOT_INDEX;
+ @SuppressWarnings("unused")
@Value("${elasticsearch.composite_snapshot_node.index:saveandrestore_composite_snapshot}")
- public String ES_COMPOSITE_SNAPSHOT_INDEX;
+ private String ES_COMPOSITE_SNAPSHOT_INDEX;
+ @SuppressWarnings("unused")
@Value("${elasticsearch.filter.index:saveandrestore_filter}")
- public String ES_FILTER_INDEX;
+ private String ES_FILTER_INDEX;
+ @SuppressWarnings("unused")
@Value("${elasticsearch.network.host:localhost}")
private String host;
+
+ @SuppressWarnings("unused")
@Value("${elasticsearch.http.port:9200}")
private int port;
private ElasticsearchClient client;
private static final AtomicBoolean esInitialized = new AtomicBoolean();
- public static final Node ROOT_NODE;
+ private static final Node ROOT_NODE;
static{
Date now = new Date();
@@ -76,6 +87,10 @@ public class ElasticConfig {
}
+ /**
+ *
+ * @return The {@link org.elasticsearch.client.ElasticsearchClient} bean.
+ */
@Bean({"client"})
public ElasticsearchClient getClient() {
if (client == null) {
@@ -210,6 +225,11 @@ private void elasticIndexInitialization(ElasticsearchClient indexClient) {
}
}
+ /**
+ *
+ * @return A {@link SearchUtil} instance.
+ */
+ @SuppressWarnings("unused")
@Bean
public SearchUtil searchUtil(){
return new SearchUtil();
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/NodeDAO.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/NodeDAO.java
index 0fa5aa4304..62dd0a91c9 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/NodeDAO.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/NodeDAO.java
@@ -87,6 +87,11 @@ public interface NodeDAO {
Node createNode(String parentNodeId, Node node);
+ /**
+ *
+ * @param uniqueNodeId Valid {@link Node} id.
+ * @return The parent {@link Node}
+ */
Node getParentNode(String uniqueNodeId);
/**
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/CompositeSnapshotDataRepository.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/CompositeSnapshotDataRepository.java
index e9f219948a..f0eb32b221 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/CompositeSnapshotDataRepository.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/CompositeSnapshotDataRepository.java
@@ -56,11 +56,14 @@
import java.util.logging.Logger;
import java.util.stream.Collectors;
+/**
+ * {@link Repository} class for {@link CompositeSnapshotData}.
+ */
@Repository
public class CompositeSnapshotDataRepository implements CrudRepository {
@Value("${elasticsearch.composite_snapshot_node.index:saveandrestore_composite_snapshot}")
- public String ES_COMPOSITE_SNAPSHOT_INDEX;
+ private String ES_COMPOSITE_SNAPSHOT_INDEX;
@Autowired
@Qualifier("client")
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ConfigurationDataRepository.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ConfigurationDataRepository.java
index f8281f5b36..31811c657c 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ConfigurationDataRepository.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ConfigurationDataRepository.java
@@ -45,15 +45,18 @@
import java.util.logging.Logger;
import java.util.stream.Collectors;
+/**
+ * Repository for {@link ConfigurationData}.
+ */
@Repository
public class ConfigurationDataRepository implements CrudRepository {
@Value("${elasticsearch.configuration_node.index:saveandrestore_configuration}")
- public String ES_CONFIGURATION_INDEX;
+ private String ES_CONFIGURATION_INDEX;
@Autowired
@Qualifier("client")
- ElasticsearchClient client;
+ private ElasticsearchClient client;
@Autowired
private SearchUtil searchUtil;
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchDAO.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchDAO.java
index 5ff7180588..01d4527614 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchDAO.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchDAO.java
@@ -60,6 +60,9 @@
import static org.phoebus.applications.saveandrestore.model.Node.ROOT_FOLDER_UNIQUE_ID;
+/**
+ * Data Access Object interfacing Elasticsearch as defined by {@link NodeDAO} interface.
+ */
public class ElasticsearchDAO implements NodeDAO {
@SuppressWarnings("unused")
@@ -805,6 +808,12 @@ public Node findParentFromPathElements(Node parentNode, String[] splitPath, int
return null;
}
+ /**
+ * Checks if a {@link Node} is present in a subtree. This is called recursively.
+ * @param startNode {@link Node} id from which the search will start.
+ * @param nodeToLookFor Self-explanatory.
+ * @return true if the #nodeToLookFor is found in the subtree, otherwise false.
+ */
public boolean isContainedInSubtree(String startNode, String nodeToLookFor) {
Optional esStartNode = elasticsearchTreeRepository.findById(startNode);
if (esStartNode.isEmpty()) {
@@ -1255,6 +1264,9 @@ protected String determineNewNodeName(Node sourceNode, List targetParentCh
}
}
+ /**
+ * Compares {@link Node} names for the purpose of ordering.
+ */
public static class NodeNameComparator implements Comparator{
@Override
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchTreeRepository.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchTreeRepository.java
index ef4fdec0ad..16cce96aec 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchTreeRepository.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/ElasticsearchTreeRepository.java
@@ -21,26 +21,9 @@
import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch._types.Refresh;
import co.elastic.clients.elasticsearch._types.Result;
-import co.elastic.clients.elasticsearch._types.query_dsl.BoolQuery;
+import co.elastic.clients.elasticsearch._types.query_dsl.*;
import co.elastic.clients.elasticsearch._types.query_dsl.BoolQuery.Builder;
-import co.elastic.clients.elasticsearch._types.query_dsl.ExistsQuery;
-import co.elastic.clients.elasticsearch._types.query_dsl.MatchAllQuery;
-import co.elastic.clients.elasticsearch._types.query_dsl.MatchQuery;
-import co.elastic.clients.elasticsearch._types.query_dsl.NestedQuery;
-import co.elastic.clients.elasticsearch._types.query_dsl.TermQuery;
-import co.elastic.clients.elasticsearch.core.DeleteByQueryRequest;
-import co.elastic.clients.elasticsearch.core.DeleteByQueryResponse;
-import co.elastic.clients.elasticsearch.core.DeleteRequest;
-import co.elastic.clients.elasticsearch.core.DeleteResponse;
-import co.elastic.clients.elasticsearch.core.ExistsRequest;
-import co.elastic.clients.elasticsearch.core.GetRequest;
-import co.elastic.clients.elasticsearch.core.GetResponse;
-import co.elastic.clients.elasticsearch.core.IndexRequest;
-import co.elastic.clients.elasticsearch.core.IndexResponse;
-import co.elastic.clients.elasticsearch.core.MgetRequest;
-import co.elastic.clients.elasticsearch.core.MgetResponse;
-import co.elastic.clients.elasticsearch.core.SearchRequest;
-import co.elastic.clients.elasticsearch.core.SearchResponse;
+import co.elastic.clients.elasticsearch.core.*;
import co.elastic.clients.elasticsearch.core.search.Hit;
import co.elastic.clients.transport.endpoints.BooleanResponse;
import org.phoebus.applications.saveandrestore.model.Tag;
@@ -52,28 +35,27 @@
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.data.repository.CrudRepository;
+import org.springframework.lang.NonNull;
import org.springframework.stereotype.Repository;
import org.springframework.util.MultiValueMap;
import java.io.IOException;
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.Date;
-import java.util.List;
-import java.util.Optional;
-import java.util.UUID;
+import java.util.*;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.stream.Collectors;
-
+/**
+ * Repository for {@link ESTreeNode} objects.
+ */
@Repository
public class ElasticsearchTreeRepository implements CrudRepository {
private static final Logger logger = Logger.getLogger(ElasticsearchTreeRepository.class.getName());
+ @SuppressWarnings("unused")
@Value("${elasticsearch.tree_node.index:saveandrestore_tree}")
- public String ES_TREE_INDEX;
+ private String ES_TREE_INDEX;
/**
* Used to determine if the {@link ESTreeNode} is saved or updated in connection to a migration
@@ -89,6 +71,9 @@ public class ElasticsearchTreeRepository implements CrudRepository S save(S elasticTreeNode) {
+ public S save(@NonNull S elasticTreeNode) {
Date now = new Date();
try {
if (elasticTreeNode.getNode().getCreated() == null) {
@@ -149,13 +134,23 @@ public S save(S elasticTreeNode) {
return null;
}
+ /**
+ * Not implemented.
+ *
+ * @param entities {@link Iterable} of {@link ESTreeNode}s.
+ * @throws RuntimeException as it is not implemented.
+ */
@Override
- public Iterable saveAll(Iterable entities) {
+ public Iterable saveAll(@NonNull Iterable entities) {
throw new RuntimeException("Not implemented");
}
+ /**
+ * @param id Non-null unique id of a {@link ESTreeNode}.
+ * @return Optional object.
+ */
@Override
- public Optional findById(String id) {
+ public Optional findById(@NonNull String id) {
try {
GetRequest getRequest =
GetRequest.of(g ->
@@ -173,19 +168,27 @@ public Optional findById(String id) {
}
}
+ /**
+ * @param id Non-null unique id of a {@link ESTreeNode}.
+ * @return true if document is found, otherwise false
+ */
@Override
- public boolean existsById(String s) {
+ public boolean existsById(@NonNull String id) {
try {
- ExistsRequest existsRequest = ExistsRequest.of(e -> e.index(ES_TREE_INDEX).id(s));
+ ExistsRequest existsRequest = ExistsRequest.of(e -> e.index(ES_TREE_INDEX).id(id));
BooleanResponse existsResponse = client.exists(existsRequest);
return existsResponse.value();
} catch (IOException e) {
- logger.log(Level.SEVERE, "Failed to query if ESTreeNode with id " + s + " exists");
+ logger.log(Level.SEVERE, "Failed to query if ESTreeNode with id " + id + " exists");
}
return false;
}
+ /**
+ *
+ * @return Always null.
+ */
@Override
public Iterable findAll() {
return null;
@@ -225,24 +228,32 @@ public Iterable findAllById(Iterable uniqueIds) {
}
}
+ /**
+ *
+ * @return Always 0.
+ */
@Override
public long count() {
return 0;
}
+ /**
+ * Deletes a {@link ESTreeNode}.
+ * @param id unique {@link org.phoebus.applications.saveandrestore.model.Node} id.
+ */
@Override
- public void deleteById(String s) {
+ public void deleteById(@NonNull String id) {
try {
DeleteRequest deleteRequest = DeleteRequest.of(d ->
- d.index(ES_TREE_INDEX).id(s).refresh(Refresh.True));
+ d.index(ES_TREE_INDEX).id(id).refresh(Refresh.True));
DeleteResponse deleteResponse = client.delete(deleteRequest);
if (deleteResponse.result().equals(Result.Deleted)) {
- logger.log(Level.WARNING, "Node with id " + s + " deleted.");
+ logger.log(Level.WARNING, "Node with id " + id + " deleted.");
} else {
- logger.log(Level.WARNING, "Node with id " + s + " NOT deleted.");
+ logger.log(Level.WARNING, "Node with id " + id + " NOT deleted.");
}
} catch (IOException e) {
- logger.log(Level.SEVERE, "Failed to delete node with id: " + s, e);
+ logger.log(Level.SEVERE, "Failed to delete node with id: " + id, e);
throw new RuntimeException(e);
}
}
@@ -338,6 +349,12 @@ public List searchNodesForTag(boolean goldenOnly) {
}
}
+ /**
+ * Performs search for {@link ESTreeNode}s matching the search parameters
+ * @param searchParameters {@link MultiValueMap} of search parameters.
+ * @return A {@link SearchResult} with {@link org.phoebus.applications.saveandrestore.model.Node} objects matching
+ * the search criteria. May of course be empty.
+ */
public SearchResult search(MultiValueMap searchParameters) {
SearchRequest searchRequest = searchUtil.buildSearchRequest(searchParameters);
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/FilterRepository.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/FilterRepository.java
index af9fb579ef..64ef434f22 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/FilterRepository.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/FilterRepository.java
@@ -45,6 +45,7 @@
import org.springframework.beans.factory.annotation.Value;
import org.springframework.data.repository.CrudRepository;
import org.springframework.http.HttpStatus;
+import org.springframework.lang.NonNull;
import org.springframework.stereotype.Repository;
import org.springframework.web.server.ResponseStatusException;
@@ -58,18 +59,21 @@
import java.util.logging.Logger;
import java.util.stream.Collectors;
-
+/**
+ * Repository class for {@link Filter} objects.
+ */
@Repository
public class FilterRepository implements CrudRepository {
private static final Logger logger = Logger.getLogger(FilterRepository.class.getName());
+ @SuppressWarnings("unused")
@Value("${elasticsearch.filter.index:saveandrestore_filter}")
- public String ES_FILTER_INDEX;
+ private String ES_FILTER_INDEX;
@Autowired
@Qualifier("client")
- ElasticsearchClient client;
+ private ElasticsearchClient client;
/**
* Saves an {@link Filter} object.
@@ -104,13 +108,22 @@ public S save(S filter) {
return null;
}
+ /**
+ * Not implemented, will always throw {@link RuntimeException}
+ * @param entities must not be {@literal null} nor must it contain {@literal null}.
+ * @throws RuntimeException always
+ */
@Override
- public Iterable saveAll(Iterable entities) {
+ public Iterable saveAll(@NonNull Iterable entities) {
throw new RuntimeException("Not implemented");
}
+ /**
+ * @param name Unique {@link Filter} name.
+ * @return {@link Optional}, may be empty.
+ */
@Override
- public Optional findById(String name) {
+ public Optional findById(@NonNull String name) {
try {
GetRequest getRequest =
GetRequest.of(g ->
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/SnapshotDataRepository.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/SnapshotDataRepository.java
index e93d686b51..d5102fd974 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/SnapshotDataRepository.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/persistence/dao/impl/elasticsearch/SnapshotDataRepository.java
@@ -34,6 +34,7 @@
import org.springframework.beans.factory.annotation.Value;
import org.springframework.data.repository.CrudRepository;
import org.springframework.http.HttpStatus;
+import org.springframework.lang.NonNull;
import org.springframework.stereotype.Repository;
import org.springframework.web.server.ResponseStatusException;
@@ -42,20 +43,28 @@
import java.util.logging.Level;
import java.util.logging.Logger;
+/**
+ * {@link Repository} class for {@link SnapshotData} objects.
+ */
@Repository
public class SnapshotDataRepository implements CrudRepository {
@Value("${elasticsearch.snapshot_node.index:saveandrestore_snapshot}")
- public String ES_SNAPSHOT_INDEX;
+ private String ES_SNAPSHOT_INDEX;
@Autowired
@Qualifier("client")
- ElasticsearchClient client;
+ private ElasticsearchClient client;
private final Logger logger = Logger.getLogger(SnapshotDataRepository.class.getName());
+ /**
+ * Saves a {@link org.phoebus.applications.saveandrestore.model.SnapshotData}.
+ * @param entity A {@link org.phoebus.applications.saveandrestore.model.SnapshotData} object.
+ * @return The persisted {@link SnapshotData} object.
+ */
@Override
- public S save(S entity) {
+ public S save(@NonNull S entity) {
try {
IndexRequest indexRequest =
IndexRequest.of(i ->
@@ -119,26 +128,46 @@ public Iterable findAllById(Iterable strings) {
return null;
}
+ /**
+ *
+ * @return Always 0.
+ */
@Override
public long count() {
return 0;
}
+ /**
+ * Not implemented, i.e. does nothing
+ * @param id Unique id of a {@link SnapshotData} object.
+ */
@Override
- public void deleteById(String s) {
+ public void deleteById(String id) {
}
+ /**
+ * Not implemented, i.e. does nothing
+ * @param entity A {@link SnapshotData} object.
+ */
@Override
public void delete(SnapshotData entity) {
}
+ /**
+ * Not implemented, i.e. does nothing
+ * @param strings A list of {@link SnapshotData} ids.
+ */
@Override
public void deleteAllById(Iterable strings) {
}
+ /**
+ * Not implemented, i.e. does nothing
+ * @param entities A list of {@link SnapshotData} objects.
+ */
@Override
public void deleteAll(Iterable entities) {
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/search/SearchUtil.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/search/SearchUtil.java
index 63bc00169a..ff6ee9e4e3 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/search/SearchUtil.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/search/SearchUtil.java
@@ -30,13 +30,14 @@
public class SearchUtil {
final private static String MILLI_PATTERN = "yyyy-MM-dd HH:mm:ss.SSS";
- final public static DateTimeFormatter MILLI_FORMAT = DateTimeFormatter.ofPattern(MILLI_PATTERN).withZone(ZoneId.systemDefault());
+ final private static DateTimeFormatter MILLI_FORMAT = DateTimeFormatter.ofPattern(MILLI_PATTERN).withZone(ZoneId.systemDefault());
@SuppressWarnings("unused")
@Value("${elasticsearch.tree_node.index:saveandrestore_tree}")
- public String ES_TREE_INDEX;
+ private String ES_TREE_INDEX;
+ @SuppressWarnings("unused")
@Value("${elasticsearch.configuration_node.index:saveandrestore_configuration}")
- public String ES_CONFIGURATION_INDEX;
+ private String ES_CONFIGURATION_INDEX;
@SuppressWarnings("unused")
@Value("${elasticsearch.result.size.search.default:100}")
private int defaultSearchSize;
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebConfiguration.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebConfiguration.java
index 4f68cbf7e6..e44a8ef857 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebConfiguration.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebConfiguration.java
@@ -22,16 +22,26 @@
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
-
+/**
+ * {@link Configuration} class setting up beans for {@link org.springframework.stereotype.Controller} classes.
+ */
@Configuration
public class WebConfiguration {
+ /**
+ *
+ * @return A {@link NodeDAO} instance.
+ */
@SuppressWarnings("unused")
@Bean
public NodeDAO nodeDAO() {
return new ElasticsearchDAO();
}
+ /**
+ *
+ * @return An {@link AcceptHeaderResolver} instance.
+ */
@SuppressWarnings("unused")
@Bean
public AcceptHeaderResolver acceptHeaderResolver() {
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebSecurityConfig.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebSecurityConfig.java
index 090101b991..8b2bad60d2 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebSecurityConfig.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/config/WebSecurityConfig.java
@@ -29,6 +29,10 @@
import org.springframework.security.ldap.userdetails.PersonContextMapper;
import org.springframework.security.web.SecurityFilterChain;
+/**
+ * {@link Configuration} class setting up authentication/authorization depending on the
+ * auth.impl application property.
+ */
@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
@@ -71,73 +75,115 @@ public class WebSecurityConfig {
String ldap_user_search_filter;
@Value("${role.user:sar-user}")
- public String roleUser;
+ private String roleUser;
@Value("${role.admin:sar-admin}")
- public String roleAdmin;
+ private String roleAdmin;
@Value("${demo.user:user}")
- public String demoUser;
+ private String demoUser;
@Value("${demo.user.password:userPass}")
- public String demoUserPassword;
+ private String demoUserPassword;
@Value("${demo.admin:admin}")
- public String demoAdmin;
+ private String demoAdmin;
@Value("${demo.admin.password:adminPass}")
- public String demoAdminPassword;
+ private String demoAdminPassword;
@Value("${demo.readOnly:johndoe}")
- public String demoReadOnly;
+ private String demoReadOnly;
@Value("${demo.readOnly.password:1234}")
- public String demoReadOnlyPassword;
+ private String demoReadOnlyPassword;
+ /**
+ *
+ * @return name of regular user role
+ */
@Bean
public String roleUser() {
return roleUser.toUpperCase();
}
+ /**
+ *
+ * @return name of admin user role
+ */
@Bean
public String roleAdmin() {
return roleAdmin.toUpperCase();
}
+ /**
+ *
+ * @return Identity of demo regular user
+ */
@Bean
public String demoUser(){
return demoUser;
}
+ /**
+ *
+ * @return Password of demo regular user
+ */
@Bean
public String demoUserPassword(){
return demoUserPassword;
}
+ /**
+ *
+ * @return Identity of the demo admin user.
+ */
@Bean
public String demoAdmin(){
return demoAdmin;
}
+ /**
+ *
+ * @return Password of the demo admin user.
+ */
@Bean
public String demoAdminPassword(){
return demoAdminPassword;
}
+ /**
+ *
+ * @return Identity of the demo read-only user.
+ */
@Bean
public String demoReadOnly(){
return demoReadOnly;
}
+ /**
+ *
+ * @return Password of the demo read-only user.
+ */
@Bean
public String demoReadOnlyPassword(){
return demoReadOnlyPassword;
}
+ /**
+ *
+ * @return The authentication implementation as specified in application property auth.impl.
+ */
+ @SuppressWarnings("unused")
@Bean
public String authenticationImplementation(){
return authenitcationImplementation;
}
+
+ /**
+ * Configures endpoints not subject to authentication.
+ * @return A {@link WebSecurityCustomizer} object.
+ */
@Bean
public WebSecurityCustomizer ignoringCustomizer() {
return web -> {
@@ -147,6 +193,12 @@ public WebSecurityCustomizer ignoringCustomizer() {
};
}
+ /**
+ * Configures http security policy.
+ * @param http A {@link HttpSecurity} object provided by Spring
+ * @return A {@link SecurityFilterChain} object.
+ * @throws Exception on failure
+ */
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http.csrf().disable();
@@ -155,6 +207,10 @@ public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
return http.build();
}
+ /**
+ * Created based on condition implemented in {@link LdapAuthCondition}.
+ * @return A {@link DefaultSpringSecurityContextSource} object
+ */
@Bean
@Conditional(LdapAuthCondition.class)
public DefaultSpringSecurityContextSource contextSourceFactoryBeanLdap() {
@@ -167,6 +223,12 @@ public DefaultSpringSecurityContextSource contextSourceFactoryBeanLdap() {
return contextSource;
}
+
+ /**
+ * Created based on condition implemented in {@link LdapAuthCondition}.
+ * @param contextSource provided by Spring
+ * @return A {@link AuthenticationManager} object
+ */
@Bean
@Conditional(LdapAuthCondition.class)
public AuthenticationManager ldapAuthenticationManager(
@@ -180,6 +242,11 @@ public AuthenticationManager ldapAuthenticationManager(
return factory.createAuthenticationManager();
}
+ /**
+ * Created based on condition implemented in {@link LdapAuthCondition}.
+ * @param contextSource provided by Spring
+ * @return A {@link LdapAuthoritiesPopulator} object
+ */
@Bean
@Conditional(LdapAuthCondition.class)
public LdapAuthoritiesPopulator authorities(BaseLdapPathContextSource contextSource) {
@@ -201,6 +268,11 @@ public LdapAuthoritiesPopulator authorities(BaseLdapPathContextSource contextSou
return myAuthPopulator;
}
+ /**
+ * Created only if application property auth.impl = ad.
+ * @return A {@link AuthenticationManager} object
+ * @throws Exception on error
+ */
@Bean
@ConditionalOnProperty(name = "auth.impl", havingValue = "ad")
public AuthenticationManager authenticationProvider() throws Exception {
@@ -220,6 +292,12 @@ public O postProcess(O object) {
}).authenticationProvider(adProvider).build();
}
+ /**
+ * Created only if application property auth.impl = demo.
+ * @param auth Injected by Spring
+ * @return A {@link AuthenticationManager} object
+ * @throws Exception on error
+ */
@Bean
@ConditionalOnProperty(name = "auth.impl", havingValue = "demo")
public AuthenticationManager demoAuthenticationManager(AuthenticationManagerBuilder auth) throws Exception {
@@ -235,12 +313,20 @@ public O postProcess(O object) {
.withUser(demoReadOnly).password(encoder().encode(demoReadOnlyPassword)).roles().and().and().build();
}
+ /**
+ *
+ * @return A {@link PasswordEncoder} object.
+ */
@Bean
@Scope("singleton")
public PasswordEncoder encoder() {
return new BCryptPasswordEncoder();
}
+ /**
+ *
+ * @return An {@link ObjectMapper} object used for serialization/deserialization.
+ */
@SuppressWarnings("unused")
@Bean
@Scope("singleton")
@@ -252,7 +338,7 @@ public ObjectMapper objectMapper() {
/**
* Configures role hierarchy, i.e. user - superuser - admin. Do not remove this {@link Bean}!
- * NOTE!
+ * NOTE!
* Some Spring Security documentation will state that "and" can be used instead of new-line char to
* separate rule items. But that does NOT work, at least not with the Spring Security version used in this project.
*
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AppMetaDataController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AppMetaDataController.java
index 24ae730786..6b9ff1078d 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AppMetaDataController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AppMetaDataController.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2018 European Spallation Source ERIC.
+ * Copyright (C) 2024 European Spallation Source ERIC.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
@@ -26,6 +26,7 @@
* @author georgweiss
* Created 13 Dec 2018
*/
+@SuppressWarnings("unused")
@RestController
public class AppMetaDataController extends BaseController {
@@ -34,7 +35,10 @@ public class AppMetaDataController extends BaseController {
@Value("${app.version}")
private String appVersion;
-
+
+ /**
+ * @return Current version of the save-and-restore service.
+ */
@GetMapping("/version")
public String version() {
return appName + ", version " + appVersion;
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthenticationController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthenticationController.java
index c4d4f0c887..e6becf5aed 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthenticationController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthenticationController.java
@@ -38,6 +38,9 @@
import java.util.List;
import java.util.stream.Collectors;
+/**
+ * Controller class for user authentication endpoints.
+ */
@SuppressWarnings("unused")
@RestController
public class AuthenticationController extends BaseController {
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthorizationHelper.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthorizationHelper.java
index 087949bfe1..b0a4aebd27 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthorizationHelper.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/AuthorizationHelper.java
@@ -53,7 +53,7 @@ public class AuthorizationHelper {
private String roleUser;
@Value("${authorization.permitall:true}")
- public boolean permitAll;
+ private boolean permitAll;
private static final String ROLE_PREFIX = "ROLE_";
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/BaseController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/BaseController.java
index 8a025c82bb..b27949b546 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/BaseController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/BaseController.java
@@ -40,13 +40,19 @@
@SuppressWarnings("unused")
public abstract class BaseController {
- public static final String JSON = "application/json";
+ protected static final String JSON = "application/json";
private final Logger logger = Logger.getLogger(BaseController.class.getName());
+ /**
+ * Identity of the admin role
+ */
@Autowired
public String roleAdmin; // This MUST be public!!!
+ /**
+ * Identity of regular user.
+ */
@Autowired
public String roleUser; // This MUST be public!!!
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/CompositeSnapshotController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/CompositeSnapshotController.java
index 96690cf79b..0b73c05108 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/CompositeSnapshotController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/CompositeSnapshotController.java
@@ -34,6 +34,9 @@
import java.security.Principal;
import java.util.List;
+/**
+ * Controller class for {@link NodeType#COMPOSITE_SNAPSHOT} {@link Node} endpoints.
+ */
@SuppressWarnings("unused")
@RestController
public class CompositeSnapshotController extends BaseController {
@@ -41,6 +44,13 @@ public class CompositeSnapshotController extends BaseController {
@Autowired
private NodeDAO nodeDAO;
+ /**
+ * Creates a new {@link CompositeSnapshot} {@link Node}.
+ * @param parentNodeId Valid id of the {@link Node}s intended parent.
+ * @param compositeSnapshot {@link CompositeSnapshot} data.
+ * @param principal User {@link Principal} injected by Spring.
+ * @return The new {@link CompositeSnapshot}.
+ */
@PutMapping(value = "/composite-snapshot", produces = JSON)
@PreAuthorize("@authorizationHelper.mayCreate(#root)")
public CompositeSnapshot createCompositeSnapshot(@RequestParam(value = "parentNodeId") String parentNodeId,
@@ -53,6 +63,12 @@ public CompositeSnapshot createCompositeSnapshot(@RequestParam(value = "parentNo
return nodeDAO.createCompositeSnapshot(parentNodeId, compositeSnapshot);
}
+ /**
+ * Updates/overwrites a {@link CompositeSnapshot} {@link Node}.
+ * @param compositeSnapshot {@link CompositeSnapshot} data.
+ * @param principal User {@link Principal} injected by Spring.
+ * @return The new {@link CompositeSnapshot}.
+ */
@PostMapping(value = "/composite-snapshot", produces = JSON)
@PreAuthorize("@authorizationHelper.mayUpdate(#compositeSnapshot, #root)")
public CompositeSnapshot updateCompositeSnapshot(@RequestBody CompositeSnapshot compositeSnapshot,
@@ -64,17 +80,31 @@ public CompositeSnapshot updateCompositeSnapshot(@RequestBody CompositeSnapshot
return nodeDAO.updateCompositeSnapshot(compositeSnapshot);
}
+ /**
+ * @param uniqueId Unique {@link Node} id of a {@link CompositeSnapshot}
+ * @return The {@link CompositeSnapshotData} associated with the {@link CompositeSnapshot} {@link Node}.
+ */
@GetMapping(value = "/composite-snapshot/{uniqueId}", produces = JSON)
public CompositeSnapshotData getCompositeSnapshotData(@PathVariable String uniqueId) {
return nodeDAO.getCompositeSnapshotData(uniqueId);
}
+ /**
+ *
+ * @param uniqueId Unique {@link Node} id of a {@link CompositeSnapshot}
+ * @return A list of references {@link Node}s, that are either of type {@link NodeType#SNAPSHOT} or
+ * {@link NodeType#COMPOSITE_SNAPSHOT}.
+ */
@GetMapping(value = "/composite-snapshot/{uniqueId}/nodes", produces = JSON)
public List getCompositeSnapshotNodes(@PathVariable String uniqueId) {
CompositeSnapshotData compositeSnapshotData = nodeDAO.getCompositeSnapshotData(uniqueId);
return nodeDAO.getNodes(compositeSnapshotData.getReferencedSnapshotNodes());
}
+ /**
+ * @param uniqueId Unique {@link Node} id of a {@link CompositeSnapshot}
+ * @return List of {@link SnapshotItem}s contained in the referenced {@link Node}s
+ */
@GetMapping(value = "/composite-snapshot/{uniqueId}/items", produces = JSON)
public List getCompositeSnapshotItems(@PathVariable String uniqueId) {
return nodeDAO.getSnapshotItemsFromCompositeSnapshot(uniqueId);
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ConfigurationController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ConfigurationController.java
index 81813e3a27..4e832bfcc3 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ConfigurationController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ConfigurationController.java
@@ -34,6 +34,9 @@
import java.security.Principal;
+/**
+ * Controller class for {@link Configuration} endpoints.
+ */
@RestController
@RequestMapping("/config")
public class ConfigurationController extends BaseController {
@@ -42,6 +45,13 @@ public class ConfigurationController extends BaseController {
@Autowired
private NodeDAO nodeDAO;
+ /**
+ * Creates new {@link Configuration} {@link Node}.
+ * @param parentNodeId Valid id of the {@link Node}s intended parent.
+ * @param configuration {@link Configuration} data.
+ * @param principal User {@link Principal} injected by Spring.
+ * @return The new {@link Configuration}.
+ */
@SuppressWarnings("unused")
@PutMapping(produces = JSON)
@PreAuthorize("@authorizationHelper.mayCreate(#root)")
@@ -52,12 +62,23 @@ public Configuration createConfiguration(@RequestParam(value = "parentNodeId") S
return nodeDAO.createConfiguration(parentNodeId, configuration);
}
+ /**
+ * Retrieves data associated with a {@link Configuration} {@link Node}-.
+ * @param uniqueId unique {@link Node} id of a {@link Configuration}.
+ * @return A {@link ConfigurationData} object.
+ */
@SuppressWarnings("unused")
@GetMapping(value = "/{uniqueId}", produces = JSON)
public ConfigurationData getConfigurationData(@PathVariable String uniqueId) {
return nodeDAO.getConfigurationData(uniqueId);
}
+ /**
+ * Updates/overwrites an existing {@link Configuration}
+ * @param configuration The {@link Configuration} subject to update.
+ * @param principal User {@link Principal} injected by Spring.
+ * @return The updated {@link Configuration}.
+ */
@SuppressWarnings("unused")
@PostMapping(produces = JSON)
@PreAuthorize("@authorizationHelper.mayUpdate(#configuration, #root)")
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ControllersConfig.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ControllersConfig.java
index 60d69f492b..6cf435dbf4 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ControllersConfig.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/ControllersConfig.java
@@ -28,8 +28,16 @@
import java.util.logging.Level;
import java.util.logging.Logger;
+/**
+ * {@link RestControllerAdvice} to log client requests that cannot be read for any reason.
+ */
@RestControllerAdvice
public class ControllersConfig {
+
+ /**
+ * @param e {@link HttpMessageNotReadableException} triggering this method.
+ */
+ @SuppressWarnings("unused")
@ExceptionHandler
@ResponseStatus(HttpStatus.BAD_REQUEST)
public void handle(HttpMessageNotReadableException e) {
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/FilterController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/FilterController.java
index 11ca952fc5..cac134bfad 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/FilterController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/FilterController.java
@@ -29,6 +29,9 @@
import java.util.List;
import java.util.Optional;
+/**
+ * Controller class for {@link Filter} endpoints.
+ */
@RestController
public class FilterController extends BaseController {
@@ -52,12 +55,21 @@ public Filter saveFilter(@RequestBody final Filter filter,
return nodeDAO.saveFilter(filter);
}
+ /**
+ *
+ * @return A {@link List} of all persisted {@link Filter} objects. Empty if none are found.
+ */
@SuppressWarnings("unused")
@GetMapping(value = "/filters", produces = JSON)
public List getAllFilters() {
return nodeDAO.getAllFilters();
}
+ /**
+ * Deletes a {@link Filter}
+ * @param name Unique name of the {@link Filter}
+ * @param principal User {@link Principal} as injected by Spring.
+ */
@SuppressWarnings("unused")
@DeleteMapping(value = "/filter/{name}")
@PreAuthorize("@authorizationHelper.maySaveOrDeleteFilter(#name, #root)")
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/NodeController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/NodeController.java
index 95ef3471c1..842beae6f5 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/NodeController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/NodeController.java
@@ -107,12 +107,22 @@ public List getNodes(@RequestBody List uniqueNodeIds) {
return nodeDAO.getNodes(uniqueNodeIds);
}
+ /**
+ *
+ * @param uniqueNodeId Unique {@link Node} id.
+ * @return The parent {@link Node} of #uniqueNodeId.
+ */
@SuppressWarnings("unused")
@GetMapping(value = "/node/{uniqueNodeId}/parent", produces = JSON)
public Node getParentNode(@PathVariable String uniqueNodeId) {
return nodeDAO.getParentNode(uniqueNodeId);
}
+ /**
+ *
+ * @param uniqueNodeId Unique {@link Node} id.
+ * @return Potentially empty list of child {@link Node}s of the {@link Node} identified by #uniqueNodeId.
+ */
@SuppressWarnings("unused")
@GetMapping(value = "/node/{uniqueNodeId}/children", produces = JSON)
public List getChildNodes(@PathVariable final String uniqueNodeId) {
@@ -159,7 +169,7 @@ public void deleteNode(@PathVariable final String uniqueNodeId, Authentication a
*
* Note also that an unauthenticated user (e.g. no basic authentication header in client's request) will
* receive a HTTP 401 response, i.e. the {@link PreAuthorize} check is not invoked.
- * @param nodeIds
+ * @param nodeIds List of {@link Node} ids to remove.
*/
@SuppressWarnings("unused")
@DeleteMapping(value = "/node", produces = JSON)
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/RequestLoggingFilterConfig.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/RequestLoggingFilterConfig.java
index 1a366b343d..3712e041d9 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/RequestLoggingFilterConfig.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/RequestLoggingFilterConfig.java
@@ -4,9 +4,16 @@
import org.springframework.context.annotation.Configuration;
import org.springframework.web.filter.CommonsRequestLoggingFilter;
+/**
+ * {@link Configuration} class setting up a {@link CommonsRequestLoggingFilter}.
+ */
@Configuration
public class RequestLoggingFilterConfig {
+ /**
+ *
+ * @return CommonsRequestLoggingFilter used to log client requests.
+ */
@Bean
public CommonsRequestLoggingFilter logFilter() {
CommonsRequestLoggingFilter filter
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SearchController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SearchController.java
index 4a6ff63d2e..7d9c9ad065 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SearchController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SearchController.java
@@ -35,6 +35,9 @@
import java.time.temporal.TemporalAmount;
import java.time.temporal.UnsupportedTemporalTypeException;
+/**
+ * Controller class for search endpoints.
+ */
@RestController
public class SearchController extends BaseController {
@@ -43,6 +46,11 @@ public class SearchController extends BaseController {
@Autowired
private NodeDAO nodeDAO;
+ /**
+ * Invokes Elasticsearch search.
+ * @param allRequestParams {@link MultiValueMap} of search parameters.
+ * @return A {@link SearchResult} containing potentially empty list of {@link org.phoebus.applications.saveandrestore.model.Node}s.
+ */
@SuppressWarnings("unused")
@GetMapping("/search")
public SearchResult search(@RequestParam MultiValueMap allRequestParams) {
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SnapshotController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SnapshotController.java
index 5654233e3c..68906377de 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SnapshotController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/SnapshotController.java
@@ -29,6 +29,9 @@
import java.security.Principal;
import java.util.List;
+/**
+ * Controller class for {@link Snapshot} endppoints
+ */
@SuppressWarnings("unused")
@RestController
public class SnapshotController extends BaseController {
@@ -36,16 +39,32 @@ public class SnapshotController extends BaseController {
@Autowired
private NodeDAO nodeDAO;
+ /**
+ *
+ * @param uniqueId Unique {@link Node} id of a snapshot.
+ * @return SnapshotData object associated with #uniqueId.
+ */
@GetMapping(value = "/snapshot/{uniqueId}", produces = JSON)
public SnapshotData getSnapshotData(@PathVariable String uniqueId) {
return nodeDAO.getSnapshotData(uniqueId);
}
+ /**
+ *
+ * @return All persisted snapshot {@link Node}s
+ */
@GetMapping(value = "/snapshots", produces = JSON)
public List getAllSnapshots() {
return nodeDAO.getAllSnapshots();
}
+ /**
+ * Creates a new {@link Snapshot}
+ * @param parentNodeId Unique {@link Node} id of the new {@link Snapshot}.
+ * @param snapshot {@link Snapshot} data.
+ * @param principal User {@link Principal} as injected by Spring.
+ * @return The new {@link Snapshot}.
+ */
@PutMapping(value = "/snapshot", produces = JSON)
@PreAuthorize("@authorizationHelper.mayCreate(#root)")
public Snapshot createSnapshot(@RequestParam(value = "parentNodeId") String parentNodeId,
@@ -58,6 +77,12 @@ public Snapshot createSnapshot(@RequestParam(value = "parentNodeId") String pare
return nodeDAO.createSnapshot(parentNodeId, snapshot);
}
+ /**
+ * Updates a {@link Snapshot}.
+ * @param snapshot The {@link Snapshot} subject to update.
+ * @param principal User {@link Principal} as injected by Spring.
+ * @return The updated {@link Snapshot}
+ */
@PostMapping(value = "/snapshot", produces = JSON)
@PreAuthorize("@authorizationHelper.mayUpdate(#snapshot, #root)")
public Snapshot updateSnapshot(@RequestBody Snapshot snapshot,
diff --git a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/TagController.java b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/TagController.java
index 2c04dac8df..7ca04e5036 100644
--- a/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/TagController.java
+++ b/services/save-and-restore/src/main/java/org/phoebus/service/saveandrestore/web/controllers/TagController.java
@@ -45,6 +45,10 @@ public class TagController extends BaseController {
@Autowired
private NodeDAO nodeDAO;
+ /**
+ *
+ * @return A {@link List} of all {@link Tag}s.
+ */
@GetMapping("/tags")
public List getTags() {
return nodeDAO.getAllTags();