Pal 1027 palisade shell

client-fuse/src/main/java/uk/gov/gchq/palisade/client/fuse/FuseClient.java

@@ -64,7 +64,8 @@ public FuseClient(final String clientUri) {
     /**
      * Run a simple CLI application for this client, taking the clientUri, resourceId and mountDir from command-line args
      *
-     * @param args command-line arguments, expected to contain the application name and three passed arguments
+     * @param args Command-line arguments, expected to contain the application name and three-or-more passed arguments.
+     *             The args list should be ordered [this-jar-name, client-uri-config, resource-id, local-mount-point, context-map...]
      *             e.g. [client-fuse.jar, pal://cluster/?userid=Alice, file:/data/local-data-store/, /mnt/palisade, purpose=SALARY]
      */
     public static void main(final String... args) {
@@ -94,7 +95,7 @@ public static void main(final String... args) {
     }
 
     /**
-     * Register a request with palisade using a configured client.
+     * Register a request with Palisade using a configured client.
      * Mount the fuse directory and block until application exit.
      * Attempt to gracefully unmount on application exit.
      *

client-fuse/src/main/java/uk/gov/gchq/palisade/client/fuse/client/ResourceTreeClient.java

@@ -55,7 +55,7 @@ public static class ResourceTreeWithContext extends ResourceTree {
         private final String token;
 
         /**
-         * Construct a new  ResourceTree and keep track of the given token.
+         * Construct a new ResourceTree and keep track of the given token.
          *
          * @param token the response from the Palisade Service used to identify this
          *              request with the Data Service.
@@ -114,11 +114,11 @@ protected Resource reapplyScheme(final Resource resource) {
     }
 
     /**
-     * Substitute a data-service address using a env map of connection-detail
+     * Substitute a Data Service address using a env map of connection-detail
      * service names to their substitutions.
      * If a serviceName is not found in the map, it is unchanged.
      *
-     * @param env         the map of data-service names to substitutions
+     * @param env         the map of Data Service names to substitutions
      * @param serviceName the service-name to lookup in the map
      * @return the substitution for this service-name
      */
@@ -139,6 +139,14 @@ protected UnaryOperator<Resource> substDataServiceAddress(final Map<String, Stri
         };
     }
 
+    /**
+     * Apply a formatting function (unary operator) to a resource and each of its parents recursively.
+     *
+     * @param resource  the resource to apply the formatter function to (it will also apply to all parents)
+     * @param formatter some function that will edit each of the resources, eg. adding a prefix to the id
+     * @param <T> the type of the resource
+     * @return the resource after applying the formatting function to it and its parents
+     */
     protected <T extends Resource> T formatResource(final T resource, final UnaryOperator<Resource> formatter) {
         if (resource instanceof ChildResource) {
             ((ChildResource) resource).parent(formatResource(((ChildResource) resource).getParent(), formatter));

client-fuse/src/main/java/uk/gov/gchq/palisade/client/fuse/fs/ResourceTreeFS.java

@@ -79,7 +79,9 @@ public ResourceTreeFS(final ResourceTree resourceTree, final Function<LeafResour
     }
 
     private static int getattr(final TreeNode<Resource> node, final FuseContext ctx, final FileStat stat) {
-        final int readOnly = FileStat.S_IRUSR | FileStat.S_IRGRP; // ug+r
+        // Mark the file as read-only to the owning user and group, no access to others
+        // Same as "chmod ug=r o=", "chmod 440", or an "ls" permissions line of "r--r-----"
+        final int readOnly = FileStat.S_IRUSR | FileStat.S_IRGRP;
         if (node instanceof ParentNode) {
             // Directory, read-only
             stat.st_mode.set(FileStat.S_IFDIR | readOnly);

client-fuse/src/main/java/uk/gov/gchq/palisade/client/fuse/tree/ResourceTree.java

@@ -156,7 +156,7 @@ private static Optional<TreeNode<Resource>> getNode(final TreeNode<Resource> nod
         }
     }
 
-    /* Collections API */
+    /* Implementations for Collection interface */
 
     @Override
     public int size() {

client-fuse/src/main/java/uk/gov/gchq/palisade/client/fuse/tree/impl/BranchResourceNode.java

@@ -52,11 +52,11 @@ public class BranchResourceNode implements ParentNode<Resource>, ChildNode<Resou
     // We actively want the parent to be a mutable ref, not a copy
     @SuppressWarnings("java:S2384")
     public BranchResourceNode(final String id, final ParentNode<ParentResource> parent, final ChildResource resource) {
-        this.id = id;
-        this.parent = parent;
         if (!(resource instanceof ParentResource)) {
             throw new IllegalArgumentException("Resource must be both parent and child");
         }
+        this.id = id;
+        this.parent = parent;
         this.resource = resource;
         this.children = new HashSet<>();
     }

client-fuse/src/main/java/uk/gov/gchq/palisade/client/fuse/tree/impl/LeafResourceNode.java

@@ -77,7 +77,7 @@ public Stream<Resource> traverse() {
         return Stream.of(this.get());
     }
 
-    // Collection
+    /* Implementations for Collection interface */
 
     @Override
     public int size() {

client-fuse/src/main/java/uk/gov/gchq/palisade/client/fuse/tree/impl/RootResourceNode.java

@@ -68,7 +68,7 @@ public Resource get() {
         return resource;
     }
 
-    // Collection
+    /* Implementations for Collection interface */
 
     @Override
     public int size() {

client-fuse/src/unit-tests/java/uk/gov/gchq/palisade/client/fuse/tree/ResourceTreeTest.java

@@ -57,11 +57,13 @@ void testTreeBuildsCorrectly() {
         tree.add(file1);
 
         assertThat(tree.stream().collect(Collectors.toSet()))
+            .as("Tree stream should contain all (three) elements added to the tree")
             .isEqualTo(Set.of(root, some, file1));
 
         tree.add(file2);
 
         assertThat(tree.stream().collect(Collectors.toSet()))
+            .as("Tree stream should contain all (four) elements added to the tree")
             .isEqualTo(Set.of(root, some, file1, file2));
     }
 }

client-java/src/main/java/uk/gov/gchq/palisade/client/java/internal/impl/Configuration.java

@@ -18,6 +18,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import uk.gov.gchq.palisade.Generated;
 import uk.gov.gchq.palisade.client.java.util.Util;
 
 import java.net.URI;
@@ -51,7 +52,7 @@ private interface StringProperty<T> {
     private static final String TOKEN_PARAM = "%25t"; // % is percent-encoded to %25
     private static final int KV_PAIR_LENGTH = 2;
 
-    // Configurable
+    // Keys for configurable properties
     /**
      * The userId for connecting to the palisade services, will be used for all requests.
      * <p>
@@ -80,15 +81,15 @@ private interface StringProperty<T> {
      */
     public static final String POLL_SECONDS = "poll";
 
-    // Allowed user-configurable properties
+    // Allowed user-configurable properties and readers for them (from String to T)
     protected static final Map<String, StringProperty<?>> WHITELIST_PROPERTIES = Map.of(
         USER_ID, String::new,
         SSL_ENABLED, Boolean::valueOf,
         HTTP2_ENABLED, Boolean::valueOf,
         POLL_SECONDS, Long::valueOf
     );
 
-    // Dafaults
+    // Static keys which are not permitted to be configurable
     /**
      * Relative path from cluster root to palisade-service request endpoint.
      * <p>
@@ -107,7 +108,14 @@ private interface StringProperty<T> {
      * Static, default '/read/chunked'
      */
     public static final String DATA_PATH = "data.path";
+    /**
+     * Map from service-names to URIs
+     * <p>
+     * Static, default empty map
+     */
     public static final String DATA_SERVICE_MAP = "data.service-map";
+
+    // Defaults for above static and configurable keys
     protected static final Map<String, Object> DEFAULT_PROPERTIES = Map.of(
         // Static
         PALISADE_PATH, "/palisade/api/registerDataRequest",
@@ -119,7 +127,7 @@ private interface StringProperty<T> {
         POLL_SECONDS, 3600L
     );
 
-    // Required and derived
+    // Required and derived keys for connection properties
     /**
      * The original URI Spec string passed to the configuration class.
      * <p>
@@ -139,6 +147,7 @@ private interface StringProperty<T> {
      */
     public static final String FILTERED_RESOURCE_URI = "filtered-resource.uri";
 
+
     private final Map<String, Object> properties = new TreeMap<>();
 
     protected Configuration(final Map<String, Object> properties) {
@@ -195,7 +204,7 @@ public static Configuration create(final URI spec) {
         var palisadeScheme = "http";
         var filteredResourceScheme = "ws";
         var dataScheme = "http";
-        // Determine SSL config
+        // Determine SSL config for URI schemes
         if (config.<Boolean>get(SSL_ENABLED).equals(Boolean.TRUE)) {
             palisadeScheme = "https";
             filteredResourceScheme = "wss";
@@ -214,6 +223,7 @@ public static Configuration create(final URI spec) {
             DATA_SERVICE_MAP, Map.of("data-service", defaultDataUri)
         ));
 
+        // Log properties map for debugging
         LOGGER.debug("Using spec {} built config:", spec);
         config.properties.forEach((key, value) -> LOGGER.debug("{} = {}", key, value));
 
@@ -255,6 +265,7 @@ private static Map<String, Object> parseQueryParams(final String queryParamStrin
     }
 
     @Override
+    @Generated
     public boolean equals(final Object o) {
         if (this == o) {
             return true;
@@ -267,11 +278,13 @@ public boolean equals(final Object o) {
     }
 
     @Override
+    @Generated
     public int hashCode() {
         return Objects.hash(properties);
     }
 
     @Override
+    @Generated
     public String toString() {
         return properties.toString();
     }