issues/1649: javadocs

strongbox-data-service/pom.xml

@@ -56,8 +56,7 @@
                 <artifactId>maven-compiler-plugin</artifactId>
                 <configuration>
                     <annotationProcessors>
-                        <annotationProcessor>org.apache.tinkerpop.gremlin.process.traversal.dsl.GremlinDslProcessor
-                        </annotationProcessor>
+                        <annotationProcessor>org.apache.tinkerpop.gremlin.process.traversal.dsl.GremlinDslProcessor</annotationProcessor>
                     </annotationProcessors>
                 </configuration>
             </plugin>
@@ -110,7 +109,7 @@
             <artifactId>strongbox-common-resources</artifactId>
             <version>${project.version}</version>
         </dependency>
-        
+
         <dependency>
             <groupId>javax.inject</groupId>
             <artifactId>javax.inject</artifactId>
@@ -150,15 +149,15 @@
             <groupId>javax.persistence</groupId>
             <artifactId>javax.persistence-api</artifactId>
         </dependency>
-        
+
         <dependency>
             <groupId>org.aspectj</groupId>
             <artifactId>aspectjrt</artifactId>
         </dependency>
         <dependency>
             <groupId>org.aspectj</groupId>
             <artifactId>aspectjweaver</artifactId>
-        </dependency>        
+        </dependency>
 
         <dependency>
             <groupId>net.sf.ehcache</groupId>
@@ -198,7 +197,7 @@
             <groupId>com.google.code.findbugs</groupId>
             <artifactId>jsr305</artifactId>
         </dependency>
-        
+
         <dependency>
             <groupId>org.liquibase</groupId>
             <artifactId>liquibase-core</artifactId>
@@ -242,7 +241,7 @@
             <exclusions>
                 <exclusion>
                     <groupId>org.neo4j</groupId>
-                    <artifactId>neo4j-ogm-bolt-driver</artifactId>                    
+                    <artifactId>neo4j-ogm-bolt-driver</artifactId>
                 </exclusion>
             </exclusions>
         </dependency>

strongbox-data-service/src/main/java/org/carlspring/strongbox/gremlin/adapters/EntityTraversalAdapter.java

@@ -3,16 +3,47 @@
 import org.apache.tinkerpop.gremlin.structure.Element;
 import org.carlspring.strongbox.data.domain.DomainObject;
 import org.carlspring.strongbox.gremlin.dsl.EntityTraversal;
+import org.springframework.data.repository.Repository;
 
+/**
+ * Makes possible to translate {@link Repository} operations on underlying graph using Gremlin query language.
+ * Every entity should have corresponding {@link EntityTraversalAdapter} implementation.
+ *
+ * @param <S>
+ * @param <E>
+ *
+ * @author sbespalov
+ */
 public interface EntityTraversalAdapter<S extends Element, E extends DomainObject>
 {
 
+    /**
+     * Element label associated with the entity type.
+     *
+     * @return target element label
+     */
     String label();
 
+    /**
+     * Folds the current traversal into entity instance.
+     *
+     * @return traversal with entity instance
+     */
     EntityTraversal<S, E> fold();
 
+    /**
+     * Unfolds the entity instance on graph.
+     *
+     * @param entity entity to unfold
+     * @return traversal with element associated with the entity
+     */
     UnfoldEntityTraversal<S, S> unfold(E entity);
 
+    /**
+     * Performs entity cascade operations on graph.
+     *
+     * @return traversal with cascaded graph elements
+     */
     EntityTraversal<S, Element> cascade();
 
 }

strongbox-data-service/src/main/java/org/carlspring/strongbox/gremlin/adapters/UnfoldEntityTraversal.java

@@ -17,6 +17,14 @@
 import org.carlspring.strongbox.data.domain.DomainObject;
 import org.carlspring.strongbox.gremlin.dsl.EntityTraversal;
 
+/**
+ * Traversal wrapper which is used to unfold entity on graph.
+ *
+ * @param <S>
+ * @param <E>
+ *
+ * @author sbespalov
+ */
 public class UnfoldEntityTraversal<S, E> implements EntityTraversal<S, E>
 {
 
@@ -37,7 +45,7 @@ public String getEntityLabel()
     {
         return entityLabel;
     }
-    
+
     public DomainObject getEntity()
     {
         return entity;

strongbox-data-service/src/main/java/org/carlspring/strongbox/gremlin/adapters/VertexEntityTraversalAdapter.java

@@ -4,9 +4,11 @@
 import org.carlspring.strongbox.data.domain.DomainObject;
 
 /**
- * @author sbespalov
+ * {@link EntityTraversalAdapter} for entities associated with vertices.
  *
  * @param <E>
+ *
+ * @author sbespalov
  */
 public interface VertexEntityTraversalAdapter<E extends DomainObject> extends EntityTraversalAdapter<Vertex, E>
 {

strongbox-data-service/src/main/java/org/carlspring/strongbox/gremlin/dsl/EntityTraversalDsl.java

@@ -7,11 +7,9 @@
 import java.util.UUID;
 
 import org.apache.tinkerpop.gremlin.process.traversal.Traversal;
-import org.apache.tinkerpop.gremlin.process.traversal.Traverser;
 import org.apache.tinkerpop.gremlin.process.traversal.dsl.GremlinDsl;
 import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal;
 import org.apache.tinkerpop.gremlin.structure.Edge;
-import org.apache.tinkerpop.gremlin.structure.Element;
 import org.apache.tinkerpop.gremlin.structure.Vertex;
 import org.apache.tinkerpop.gremlin.structure.VertexProperty.Cardinality;
 import org.carlspring.strongbox.data.domain.DomainObject;
@@ -22,17 +20,23 @@
 import org.springframework.util.CollectionUtils;
 
 /**
+ * The application specific Gremlin DSL extension. Provides shortcut methods for the traversals that commonly used.
+ *
  * @author sbespalov
  *
  * @param <S>
  * @param <E>
+ * @see <a href="https://tinkerpop.apache.org/docs/current/reference/#gremlin-java-dsl">Domain Specific Languages</a>
  */
 @GremlinDsl(traversalSource = "org.carlspring.strongbox.gremlin.dsl.EntityTraversalSourceDsl")
 public interface EntityTraversalDsl<S, E> extends GraphTraversal.Admin<S, E>
 {
 
     Logger logger = LoggerFactory.getLogger(EntityTraversalDsl.class);
 
+    /**
+     * Defines pseudo `null` for properties with no value, needed because Gremlin do not support `null` values.
+     */
     Object NULL = new Object()
     {
 
@@ -44,6 +48,13 @@ public String toString()
 
     };
 
+    /**
+     * Search graph to vertices with specified labels by `uuid`.
+     *
+     * @param uuid `uuid` property value
+     * @param labels vertex labels
+     * @return traversal within the search result
+     */
     @SuppressWarnings("unchecked")
     default GraphTraversal<S, Vertex> findById(Object uuid,
                                                String... labels)
@@ -57,25 +68,50 @@ default GraphTraversal<S, Vertex> findById(Object uuid,
         return result;
     }
 
+    /**
+     * Get the property value for current traversal element, or {@link EntityTraversalDsl#NULL} if no such property.
+     *
+     * @param propertyName name of the property
+     * @return property value traversal
+     */
     @SuppressWarnings("unchecked")
     default Traversal<S, Object> enrichPropertyValue(String propertyName)
     {
         return coalesce(__.properties(propertyName).value(), __.<Object>constant(NULL));
     }
 
+    /**
+     * Get the collection of property values for current traversal element, or {@link EntityTraversalDsl#NULL} if no such property.
+     *
+     * @param propertyName name of the property
+     * @return property values collection traversal
+     */
     @SuppressWarnings("unchecked")
     default Traversal<S, Object> enrichPropertyValues(String propertyName)
     {
         return coalesce(__.propertyMap(propertyName).map(t -> t.get().get(propertyName)), __.<Object>constant(NULL));
     }
 
+    /**
+     * Traverse to the expected entity value, or {@link EntityTraversalDsl#NULL} if no such entity.
+     *
+     * @param <S2> entity type
+     * @param enrichObjectTraversal entity traversal
+     * @return entity value traversal
+     */
     default <S2> Traversal<S, Object> mapToObject(Traversal<S2, Object> enrichObjectTraversal)
     {
         return fold().choose(t -> t.isEmpty(),
                              __.<Object>constant(NULL),
                              __.<Edge>unfold().map(enrichObjectTraversal));
     }
 
+    /**
+     * Traverse the graph to the specified entity.
+     *
+     * @param entity entity value
+     * @return entity vertex traversal
+     */
     default GraphTraversal<S, Vertex> V(DomainObject entity)
     {
         if (entity instanceof EntityHierarchyNode)
@@ -97,6 +133,14 @@ default GraphTraversal<S, Vertex> V(DomainObject entity)
         return V();
     }
 
+    /**
+     * Checks if the given entity exists, and adds or updates the entity as appropriate.
+     *
+     * @param <S2>
+     * @param uuid entity `uuid`
+     * @param unfoldTraversal traversal to unfold the entity on graph
+     * @return entity vertex traversal
+     */
     default <S2> Traversal<S, Vertex> saveV(Object uuid,
                                             UnfoldEntityTraversal<S2, Vertex> unfoldTraversal)
     {
@@ -115,6 +159,14 @@ default <S2> Traversal<S, Vertex> saveV(Object uuid,
                               .map(unfoldTraversal);
     }
 
+    /**
+     * Adds entity with specified `uuid`
+     *
+     * @param <S2>
+     * @param uuid entity `uuid`
+     * @param unfoldTraversal traversal to unfold the entity on graph
+     * @return entity vertex traversal
+     */
     default <S2> Traversal<S, Vertex> addV(Object uuid,
                                            UnfoldEntityTraversal<S2, Vertex> unfoldTraversal)
     {
@@ -130,18 +182,40 @@ default <S2> Traversal<S, Vertex> addV(Object uuid,
                           .sideEffect(EntityTraversalUtils::created);
     }
 
+    /**
+     * Logs traverser value labeled with action.
+     *
+     * @param <E2>
+     * @param action the action label
+     * @return current traversal
+     */
     @SuppressWarnings("unchecked")
     default <E2> Traversal<S, E2> info(String action)
     {
         return (Traversal<S, E2>) sideEffect(t -> EntityTraversalUtils.info(action, t));
     }
 
+    /**
+     * Logs traverser value labeled with action.
+     *
+     * @param <E2>
+     * @param action the action label
+     * @return current traversal
+     */
     @SuppressWarnings("unchecked")
     default <E2> Traversal<S, E2> debug(String action)
     {
         return (Traversal<S, E2>) sideEffect(t -> EntityTraversalUtils.debug(action, t));
     }
 
+    /**
+     * Sets the property value with {@link Cardinality#set}
+     *
+     * @param <E2>
+     * @param key property key
+     * @param values property value
+     * @return current traversal
+     */
     default <E2> GraphTraversal<S, E2> property(final String key,
                                                 final Set<String> values)
     {

strongbox-data-service/src/main/java/org/carlspring/strongbox/gremlin/dsl/EntityTraversalSourceDsl.java

@@ -13,13 +13,15 @@
 import org.slf4j.LoggerFactory;
 
 /**
+ * Helper class to create {@link EntityTraversalDsl} instance.
+ *
  * @author sbespalov
  */
 public class EntityTraversalSourceDsl extends GraphTraversalSource
 {
 
     private static final Logger logger = LoggerFactory.getLogger(EntityTraversalSourceDsl.class);
-    
+
     public EntityTraversalSourceDsl(Graph graph,
                                     TraversalStrategies traversalStrategies)
     {
@@ -36,12 +38,18 @@ public EntityTraversalSourceDsl(RemoteConnection connection)
         super(connection);
     }
 
+    /**
+     * Creates {@link EntityTraversalDsl} instance based on specified entity.
+     *
+     * @param entity
+     * @return
+     */
     public GraphTraversal<Vertex, Vertex> V(DomainObject entity)
     {
         GraphTraversalSource clone = this.clone();
         clone.getBytecode().addStep(GraphTraversal.Symbols.V);
         GraphTraversal<Vertex, Vertex> traversal = new DefaultGraphTraversal<>(clone);
-        
+
         Long vertexId = entity.getNativeId();
         if (vertexId != null)
         {

strongbox-data-service/src/main/java/org/carlspring/strongbox/gremlin/dsl/EntityTraversalUtils.java

@@ -2,9 +2,7 @@
 
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
-import java.time.Instant;
 import java.time.LocalDateTime;
-import java.time.ZoneId;
 import java.util.Collections;
 import java.util.Date;
 import java.util.LinkedList;
@@ -19,6 +17,11 @@
 import org.carlspring.strongbox.data.domain.DomainObject;
 import org.strongbox.util.Commons;
 
+/**
+ * Utility methods to work with {@link EntityTraversalDsl} traversals.
+ *
+ * @author sbespalov
+ */
 public class EntityTraversalUtils
 {
     public static final String DATE_FORMAT = "yyyy-MM-dd HH:mm:ss.SSSXXX";
@@ -119,7 +122,7 @@ static <E2> void created(Traverser<E2> t)
     }
 
     static <E2> void info(String action,
-                                 Traverser<E2> t)
+                          Traverser<E2> t)
     {
         EntityTraversalDsl.logger.info(String.format("%s [%s]-[%s]-[%s]",
                                                      action,
@@ -130,7 +133,7 @@ static <E2> void info(String action,
     }
 
     static <E2> void debug(String action,
-                                  Traverser<E2> t)
+                           Traverser<E2> t)
     {
         EntityTraversalDsl.logger.debug(String.format("%s [%s]-[%s]-[%s]",
                                                       action,
@@ -139,7 +142,7 @@ static <E2> void debug(String action,
                                                       ((Element) t.get()).property("uuid")
                                                                          .orElse("null")));
     }
-    
+
     static <E2> void fetched(Traverser<E2> t)
     {
         debug("Fetched", t);