diff --git a/src/main/java/com/syncleus/grail/graph/AbstractSignalMultiplyingEdge.java b/src/main/java/com/syncleus/grail/graph/AbstractSignalMultiplyingEdge.java
index 5b2a7da2586fefdeb2cfee7fa7ddb9e3b1e5fce0..ee83b5189edd0cb1c2f2b25219163245676c56e5 100644
--- a/src/main/java/com/syncleus/grail/graph/AbstractSignalMultiplyingEdge.java
+++ b/src/main/java/com/syncleus/grail/graph/AbstractSignalMultiplyingEdge.java
@@ -22,6 +22,12 @@ import com.tinkerpop.frames.modules.javahandler.*;
import java.util.Random;
+/**
+ * This is the Java handler class associated with the SignalMultiplyingEdge type. It ensures initial weights are set
+ * to a random value as well as defines how to propagate the signal.
+ *
+ * @since 0.1
+ */
public abstract class AbstractSignalMultiplyingEdge implements SignalMultiplyingEdge {
private static final Random RANDOM = new Random();
private static final double RANGE = 2.0;
diff --git a/src/main/java/com/syncleus/grail/graph/GrailGraphFactory.java b/src/main/java/com/syncleus/grail/graph/GrailGraphFactory.java
index 46223b002017ac51b31fb1de68fcc7756ee5384a..87ab690596d60656691e6a983065a2f5689fb424 100644
--- a/src/main/java/com/syncleus/grail/graph/GrailGraphFactory.java
+++ b/src/main/java/com/syncleus/grail/graph/GrailGraphFactory.java
@@ -27,6 +27,15 @@ import com.tinkerpop.frames.modules.typedgraph.*;
import java.util.*;
+/**
+ * The GrailGraphFactory class is responsible for creating new graphs compatible with GRAIL classes. Using this factory
+ * instead of the built-in TinkerPop factory ensures that the proper modules and class typing is instantiated. If this
+ * class is bypassed and the built-in TinkerPop FramedGraphFactory is used instead it is imperative that the GrailModule
+ * be passed to the FramedGraphFractory during instantiation. It is also important to pass a TypedModule contained the
+ * GRAIL classes that will be used when calling FramedGraphFactory directly.
+ *
+ * @since 0.1
+ */
public class GrailGraphFactory extends FramedGraphFactory {
private static final Set<Class<?>> BUILT_IN_TYPES = new HashSet<Class<?>>(Arrays.asList(new Class<?>[]{
SignalMultiplyingEdge.class,
@@ -34,14 +43,36 @@ public class GrailGraphFactory extends FramedGraphFactory {
ActionTriggerEdge.class,
PrioritySerialTriggerEdge.class}));
+ /**
+ * Creates a graph factory using only the built-in modules. Only built in GRAIL classes will be handled by the
+ * typing engine.
+ *
+ * @since 0.1
+ */
public GrailGraphFactory() {
super(GrailGraphFactory.constructModules(Collections.<Module>emptySet()));
}
+ /**
+ * Creates a graph factory using the built-in modules supplemented by the specified additional modules. Only
+ * built-in GRAIL classes will be handled by the typing engine unless explicitly handled by a one of the specified
+ * modules.
+ *
+ * @param modules additional modules to configure.
+ * @since 0.1
+ */
public GrailGraphFactory(final Collection<? extends Module> modules) {
super(GrailGraphFactory.constructModules(modules));
}
+ /**
+ * Creates a graph factory using the built-in modules supplemented by the specified additional Modules. All built-in
+ * classes will be handled by the typing engine in addition to any additional classes specified.
+ *
+ * @param modules additional modules to configure.
+ * @param types additional classes for the typing engine to handle.
+ * @since 0.1
+ */
public GrailGraphFactory(final Collection<? extends Module> modules, final Collection<? extends Class<?>> types) {
super(GrailGraphFactory.constructModules(modules, types));
}
diff --git a/src/main/java/com/syncleus/grail/graph/GrailModule.java b/src/main/java/com/syncleus/grail/graph/GrailModule.java
index 68319f7dc90de46312622d50e8a15e93d9af3515..6afc8299c8f520d85bdae427712763c28e8a9e3e 100644
--- a/src/main/java/com/syncleus/grail/graph/GrailModule.java
+++ b/src/main/java/com/syncleus/grail/graph/GrailModule.java
@@ -25,9 +25,23 @@ import com.tinkerpop.frames.modules.typedgraph.TypeValue;
import java.util.*;
+/**
+ * The GrailModule is a TinkerPop module which extends the built-in annotations with the following additional
+ * annotations: TypedAdjacency, and TypedIncidence. This module is automatically added to any graph created using the
+ * GraphGraphFactory. However the module is provided whenever a different graph factory is preferred.
+ *
+ * @since 0.1
+ */
public class GrailModule implements Module {
private final Map<String, Set<String>> hierarchy;
+ /**
+ * Creates a new GraphModule with a typing engine that can recognize the specified types. While these types still
+ * need to be included in a separate TypedModule they must be created here as well to ensure proper look-ups occur.
+ *
+ * @param types Class types known to the typing engine.
+ * @since 0.1
+ */
public GrailModule(final Collection<? extends Class<?>> types) {
this.hierarchy = GrailModule.constructTypedHierarchy(types);
}
diff --git a/src/main/java/com/syncleus/grail/graph/ReflectionUtility.java b/src/main/java/com/syncleus/grail/graph/ReflectionUtility.java
index 90037e43756a2ec21a58ec66a7f07d4c59ce3296..d271e95224fa68d1557e4fc14f7cea7df055ded7 100644
--- a/src/main/java/com/syncleus/grail/graph/ReflectionUtility.java
+++ b/src/main/java/com/syncleus/grail/graph/ReflectionUtility.java
@@ -20,10 +20,25 @@ package com.syncleus.grail.graph;
import com.tinkerpop.frames.modules.typedgraph.*;
+/**
+ * The reflection utility is a helper class that can be used to determine the GRAIL specific annotations present on a
+ * class.
+ *
+ * @since 0.1
+ */
final class ReflectionUtility {
+ //Utility class can not be instantiated
private ReflectionUtility() {
}
+ /**
+ * Gets the TypeValue annotation specified on this class, throws a runtime exception if there is none. This only
+ * checks the direct class and does not check parent classes for the annotation.
+ *
+ * @param type The class type to check for annotations.
+ * @return The TypeValue assigned to the specified class.
+ * @since 0.1
+ */
public static TypeValue determineTypeValue(final Class<?> type) {
final TypeValue typeValue = type.getDeclaredAnnotation(TypeValue.class);
if( typeValue == null )
@@ -31,6 +46,15 @@ final class ReflectionUtility {
return typeValue;
}
+ /**
+ * Gets the TypeField annotation associated with the given class. If the specified class does not have a TypeField
+ * annotation than each parent class is checked until one is found, at which point it is returned. If not TypeField
+ * annotation can be found a runtime exception is thrown.
+ *
+ * @param type The class type to check for annotations.
+ * @return The TypeField assigned to the specified class, or one of its parent classes.
+ * @since 0.1
+ */
public static TypeField determineTypeField(final Class<?> type) {
TypeField typeField = type.getAnnotation(TypeField.class);
if( typeField == null ) {
@@ -48,7 +72,7 @@ final class ReflectionUtility {
return typeField;
}
- public static TypeField determineTypeFieldRecursive(final Class<?> type) {
+ private static TypeField determineTypeFieldRecursive(final Class<?> type) {
TypeField typeField = type.getAnnotation(TypeField.class);
if( typeField == null ) {
final Class<?>[] parents = type.getInterfaces();
diff --git a/src/main/java/com/syncleus/grail/graph/TypedAdjacencyMethodHandler.java b/src/main/java/com/syncleus/grail/graph/TypedAdjacencyMethodHandler.java
index f82bd1761bddd981fd1d2a03de40275d1783751b..9825b6a4f7d143480d3d291708408a25df505de9 100644
--- a/src/main/java/com/syncleus/grail/graph/TypedAdjacencyMethodHandler.java
+++ b/src/main/java/com/syncleus/grail/graph/TypedAdjacencyMethodHandler.java
@@ -28,10 +28,24 @@ import com.tinkerpop.gremlin.java.GremlinPipeline;
import java.lang.reflect.Method;
import java.util.*;
+/**
+ * A TinkerPop method handler that implemented the TypedAdjacency Annotation.
+ *
+ * @since 0.1
+ */
public class TypedAdjacencyMethodHandler implements MethodHandler<TypedAdjacency> {
private final Map<String, Set<String>> hierarchy;
+ /**
+ * Creates a new method handler with the specified hierarchy map. The hierarchy map has as a key all the TypeValue's
+ * value property from all the classes known to the typing engine. The value associated with each key is a set of
+ * TypeValue value parameters for all the children classes which also have a TypeValue. For convenience purposes the
+ * key will always be present as a single element in the set. This is because a class is always a type of itself.
+ *
+ * @param hierarchy the TypeValue hierarchy of all classes known to the typing engine.
+ * @since 0.1
+ */
public TypedAdjacencyMethodHandler(final Map<String, Set<String>> hierarchy) {
this.hierarchy = hierarchy;
}
diff --git a/src/main/java/com/syncleus/grail/graph/TypedIncidenceMethodHandler.java b/src/main/java/com/syncleus/grail/graph/TypedIncidenceMethodHandler.java
index 782d45faca2eea5e156d3a7fabf03d7edd28b411..baaf5fe78bb9b49b4ea47f07a1e41cc068372db4 100644
--- a/src/main/java/com/syncleus/grail/graph/TypedIncidenceMethodHandler.java
+++ b/src/main/java/com/syncleus/grail/graph/TypedIncidenceMethodHandler.java
@@ -27,10 +27,24 @@ import com.tinkerpop.gremlin.java.GremlinPipeline;
import java.lang.reflect.*;
import java.util.*;
+/**
+ * A TinkerPop method handler that implemented the TypedIncidence Annotation.
+ *
+ * @since 0.1
+ */
public class TypedIncidenceMethodHandler implements MethodHandler<TypedIncidence> {
private final Map<String, Set<String>> hierarchy;
+ /**
+ * Creates a new method handler with the specified hierarchy map. The hierarchy map has as a key all the TypeValue's
+ * value property from all the classes known to the typing engine. The value associated with each key is a set of
+ * TypeValue value parameters for all the children classes which also have a TypeValue. For convenience purposes the
+ * key will always be present as a single element in the set. This is because a class is always a type of itself.
+ *
+ * @param hierarchy the TypeValue hierarchy of all classes known to the typing engine.
+ * @since 0.1
+ */
public TypedIncidenceMethodHandler(final Map<String, Set<String>> hierarchy) {
this.hierarchy = hierarchy;
}
diff --git a/src/main/java/com/syncleus/grail/graph/action/AbstractActionTrigger.java b/src/main/java/com/syncleus/grail/graph/action/AbstractActionTrigger.java
index 933905d9aefc1c3ed78c7f70da3630924676ffdf..6d81fc2fdfe53a517eaa483004e7bea5e1a6580a 100644
--- a/src/main/java/com/syncleus/grail/graph/action/AbstractActionTrigger.java
+++ b/src/main/java/com/syncleus/grail/graph/action/AbstractActionTrigger.java
@@ -21,6 +21,12 @@ package com.syncleus.grail.graph.action;
import java.lang.reflect.Method;
import java.util.*;
+/**
+ * This is the Java handler class associated with the ActionTrigger type. It doesnt do much, as it is expected to be
+ * extended. It does however construct a reflection cache of Action annotations on previously seen classes.
+ *
+ * @since 0.1
+ */
public abstract class AbstractActionTrigger implements ActionTrigger {
private static final Map<Class<?>, Map<String, Set<Method>>> ACTION_METHOD_CACHE = new HashMap<>();
diff --git a/src/main/java/com/syncleus/grail/graph/action/AbstractPrioritySerialTrigger.java b/src/main/java/com/syncleus/grail/graph/action/AbstractPrioritySerialTrigger.java
index a040d5ddfc53bab762a1719c344eba84d40bd9e4..5f872d46107268373ff60acf0fbe139b8501e3ef 100644
--- a/src/main/java/com/syncleus/grail/graph/action/AbstractPrioritySerialTrigger.java
+++ b/src/main/java/com/syncleus/grail/graph/action/AbstractPrioritySerialTrigger.java
@@ -28,6 +28,12 @@ import com.tinkerpop.pipes.util.structures.Pair;
import java.lang.reflect.*;
import java.util.*;
+/**
+ * This is the Java handler class associated with the ActionTrigger type. It defines how the Trigger is to be executed.
+ * In this case all triggers are executed in serial within the current thread.
+ *
+ * @since 0.1
+ */
public abstract class AbstractPrioritySerialTrigger extends AbstractActionTrigger implements PrioritySerialTrigger, JavaHandlerContext {
@Override
public void trigger() {
diff --git a/src/main/java/com/syncleus/grail/graph/action/PrioritySerialTrigger.java b/src/main/java/com/syncleus/grail/graph/action/PrioritySerialTrigger.java
index 2f7d1f79d656e9da57384103b1f3387988078703..1ef98288a4a5cd399309d33c982439896ac9b1b8 100644
--- a/src/main/java/com/syncleus/grail/graph/action/PrioritySerialTrigger.java
+++ b/src/main/java/com/syncleus/grail/graph/action/PrioritySerialTrigger.java
@@ -33,6 +33,14 @@ import com.tinkerpop.frames.modules.typedgraph.TypeValue;
@TypeValue("PrioritySerialTrigger")
@JavaHandlerClass(AbstractPrioritySerialTrigger.class)
public interface PrioritySerialTrigger extends ActionTrigger {
+ /**
+ * This will initiate the execution of the action's triggered by this node. The trigger method is also annotated as
+ * an action with label actionTrigger. This allows for multiple ActionTrigger classes to be chained together.
+ * Specifically this class executes the triggers in serial by order of the edge's priority value property. All the
+ * actions are executed in series in the existing thread.
+ *
+ * @since 0.1
+ */
@JavaHandler
@Action("actionTrigger")
@Override
diff --git a/src/main/java/com/syncleus/grail/graph/action/package-info.java b/src/main/java/com/syncleus/grail/graph/action/package-info.java
new file mode 100644
index 0000000000000000000000000000000000000000..6c93e9f71d206c86d1cc2ea2cc3725f868841cc5
--- /dev/null
+++ b/src/main/java/com/syncleus/grail/graph/action/package-info.java
@@ -0,0 +1,27 @@
+/******************************************************************************
+ * *
+ * Copyright: (c) Syncleus, Inc. *
+ * *
+ * You may redistribute and modify this source code under the terms and *
+ * conditions of the Open Source Community License - Type C version 1.0 *
+ * or any later version as published by Syncleus, Inc. at www.syncleus.com. *
+ * There should be a copy of the license included with this file. If a copy *
+ * of the license is not included you are granted no right to distribute or *
+ * otherwise use this file except through a legal and valid license. You *
+ * should also contact Syncleus, Inc. at the information below if you cannot *
+ * find a license: *
+ * *
+ * Syncleus, Inc. *
+ * 2604 South 12th Street *
+ * Philadelphia, PA 19148 *
+ * *
+ ******************************************************************************/
+
+/**
+ * The action package houses all the framework to facilitate action triggers. Action triggers are responsible for
+ * triggering and propagating actions across a graph. Action triggers can define the order in which actions take place
+ * as well as how they are executed.
+ *
+ * @since 0.1
+ */
+package com.syncleus.grail.graph.action;
\ No newline at end of file
diff --git a/src/main/java/com/syncleus/grail/graph/package-info.java b/src/main/java/com/syncleus/grail/graph/package-info.java
new file mode 100644
index 0000000000000000000000000000000000000000..c503a84576b30b0932f4c2500b12b81d004cc392
--- /dev/null
+++ b/src/main/java/com/syncleus/grail/graph/package-info.java
@@ -0,0 +1,25 @@
+/******************************************************************************
+ * *
+ * Copyright: (c) Syncleus, Inc. *
+ * *
+ * You may redistribute and modify this source code under the terms and *
+ * conditions of the Open Source Community License - Type C version 1.0 *
+ * or any later version as published by Syncleus, Inc. at www.syncleus.com. *
+ * There should be a copy of the license included with this file. If a copy *
+ * of the license is not included you are granted no right to distribute or *
+ * otherwise use this file except through a legal and valid license. You *
+ * should also contact Syncleus, Inc. at the information below if you cannot *
+ * find a license: *
+ * *
+ * Syncleus, Inc. *
+ * 2604 South 12th Street *
+ * Philadelphia, PA 19148 *
+ * *
+ ******************************************************************************/
+
+/**
+ * The graph package handles all the base framework for querying, traversing, and persisting to and from a GRAIL graph.
+ *
+ * @since 0.1
+ */
+package com.syncleus.grail.graph;
\ No newline at end of file