#113

carnival-data · Mar 21, 2023 · fe237d8 · fe237d8
1 parent 6c699fb
commit fe237d8
Show file tree

Hide file tree

Showing 4 changed files with 223 additions and 54 deletions.
diff --git a/app/carnival-graph/src/main/groovy/carnival/graph/PropertyValuesHolder.groovy b/app/carnival-graph/src/main/groovy/carnival/graph/PropertyValuesHolder.groovy
@@ -21,22 +21,32 @@ import org.apache.tinkerpop.gremlin.structure.Element
 @Slf4j
 class PropertyValuesHolder<T> {
 
-    /** */
+    /** A map of property definitions to property values */
     Map<PropertyDefinition,Object> propertyValues = new HashMap<PropertyDefinition,Object>()
 
-    /** */
+    /** If true, then properties must be defined to have a value */
     Boolean propertiesMustBeDefined = true
 
 
-    /** */
+    /** 
+     * Set the provided property to the provided enum value.
+     * @param propDef The property to set
+     * @param propValue The enum value to use
+     * @return This object
+     */
     public T withProperty(PropertyDefinition propDef, Enum propValue) {
         assert propDef != null
         assert propValue != null
         withProperty(propDef, propValue.name())
     }
 
 
-    /** */
+    /** 
+     * Set the provided property to the provided value.
+     * @param propDef The property to set
+     * @param prooValue The value to use
+     * @return This object
+     */
     public T withProperty(PropertyDefinition propDef, Object propValue) {
         assert this.respondsTo("getElementDef")
         ElementDefinition eDef = getElementDef()
@@ -51,7 +61,12 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set the provided property pairs of properties and values, ex.
+     * .setProperty(p1, v1, p2, v2).
+     * @param args Pairs of property definitions and values
+     * @return This object 
+     */
     public T withProperties(Object... args) {
         if (args.size() == 1) {
             assert args[0] instanceof Map
@@ -61,7 +76,12 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set all the properties specified in the provided map of property 
+     * definitions to values ex. .setProperty([p1:v1, p2:v2]).
+     * @param args Map of property definitions to property values
+     * @return This object
+     */
     public T withProperties(Map args) {
         assert this.respondsTo("getElementDef")
         ElementDefinition eDef = getElementDef()
@@ -75,7 +95,13 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set all the properties in the provided list where the list elements
+     * alternate between property definitions and property values ex.
+     * .setProperty([p1, v1, p2, v2]).
+     * @paran args A list of property definitions and values
+     * @return This object
+     */
     public T withProperties(List args) {
         def numArgs = args.size()
         assert numArgs >= 2
@@ -88,13 +114,23 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Set the pairs of property definitions and property values when the value
+     * is not null ex. .withNonNullProperties(p1, v1, p2, v2)
+     * @param args Pairs of property definitions and values
+     * @return This object 
+     */
     public T withNonNullProperties(Object... args) {
         withNonNullProperties(args.toList())
     }
 
 
-    /** */
+    /** 
+     * Set the pairs of property definitions and property values when the value
+     * is not null ex. .withNonNullProperties([p1, v1, p2, v2]).
+     * @paran args A list of property definitions and values
+     * @return This object
+     */
     public T withNonNullProperties(List args) {
         def numArgs = args.size()
         assert numArgs >= 2
@@ -110,7 +146,8 @@ class PropertyValuesHolder<T> {
     /** 
      * Matches a map of data against the properties of this element by name and
      * assignes the property value on match.
-     *
+     * @param args A map of property definitions to values
+     * @return This object
      */
     public T withMatchingProperties(Map args) {
         assert args != null
@@ -129,7 +166,8 @@ class PropertyValuesHolder<T> {
      * Matches a map of data against the properties of this element by name and
      * assignes the property value on match ignoring data records where the
      * value is null.
-     *
+     * @param args A map of property definitions to values
+     * @return This object
      */
     public T withNonNullMatchingProperties(Map args) {
         assert args != null
@@ -138,7 +176,12 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Utility method to split a list of pairs into property definition and
+     * value and then call withProperty on each pair.
+     * @param pairs A list of two element lists where each two element list
+     * is a pair of property definition and property value.
+     */
     private void holdPropertyPairs(List<List> pairs) {
         Map<PropertyDefinition,Object> props = new HashMap<PropertyDefinition,Object>()
         pairs.each { p ->
@@ -152,7 +195,10 @@ class PropertyValuesHolder<T> {
     }
 
 
-    /** */
+    /** 
+     * Returns a map of all property definitions and their value.
+     * @return A map of property definition to value
+     */
     public Map<PropertyDefinition,Object> allPropertyValues() {
         assert this.respondsTo("getElementDef")
         ElementDefinition eDef = getElementDef()
@@ -172,7 +218,11 @@ class PropertyValuesHolder<T> {
     } 
 
 
-    /** */
+    /** 
+     * Set the properties of the provided graph element to the property values 
+     * held by this object.
+     * @param el The target graph element 
+     */
     public Element setElementProperties(Element el) {
         def pvs = allPropertyValues()
         pvs.each { PropertyDefinition vp, Object val ->

diff --git a/app/carnival-graph/src/main/groovy/carnival/graph/VertexBuilder.groovy b/app/carnival-graph/src/main/groovy/carnival/graph/VertexBuilder.groovy
@@ -28,16 +28,19 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     ///////////////////////////////////////////////////////////////////////////
 
     /** 
-     * Object that owns this builder.
-     * */
+     * The source vertex definition of this builder.
+     */
     VertexDefinition vertexDef
 
 
     ///////////////////////////////////////////////////////////////////////////
     // CONSTRUCTOR
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Constructor
+     * @param The source vertex definition of this builder.
+     */
     public VertexBuilder(VertexDefinition vertexDef) {
         assert vertexDef
         this.vertexDef = vertexDef
@@ -48,7 +51,9 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     // GETTERS
     ///////////////////////////////////////////////////////////////////////////
 
-    /** */
+    /** 
+     * Return the source vertex definition as an element definition.
+     */
     public ElementDefinition getElementDef() { vertexDef }
 
 
@@ -104,7 +109,13 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     }
 
 
-    /** */
+    /** 
+     * Returns a graph traversal that starts with vertices that match this
+     * vertex builder.
+     * @param graph The property graph
+     * @param g A graph traversal source to use
+     * @return A graph traversal
+     */
     public Traversal traversal(Graph graph, GraphTraversalSource g) {
         assert graph
         assert g
@@ -174,7 +185,10 @@ class VertexBuilder extends PropertyValuesHolder<VertexBuilder> {
     }
 
 
-    /** */
+    /** 
+     * Assert that all the properties required by the source vertex definition
+     * have been set in this builder.
+     */
     void assertRequiredProperties() {
         vertexDef.requiredProperties.each { requiredPropDef ->
             boolean found = allPropertyValues().find { k, v ->