Revert to the old behavior for Domain/Range annotations, introduce

Initial and Terminal annotations for edge framing

Following the discussion in #65 the Domain and Range annotations are now
deprecated. Instead of altering their semantics, the new behavior
is activated by using Initial/Terminal instead of Domain/Range

Author: gjdev

CHANGELOG.textile

@@ -15,7 +15,7 @@ h3. Version 2.4.0 (NOT OFFICIALLY RELEASED YET)
 </dependency>
 ```
 
-* Deprecate direction parameter for framing Edges from FramedGraph.frame. Starting from 2.4.0 the direction for Domain/Range annotations is taken from the edge direction.
+* Deprecate direction parameter for framing Edges from FramedGraph.frame. Starting from the next major release the direction parameter will be dropped. Instead of using Domain/Range annotations with a frame direction, you should use EdgeSource/EdgeTarget annotations that use the implicit direction of the edge.
 * Framing a null element returns null   
 * Fixed NPE when enum property type set to null
 * Inheritance/Poymorphism support

src/main/java/com/tinkerpop/frames/Domain.java

@@ -9,6 +9,8 @@
  * The source of the adjacency.
  *
  * @author Marko A. Rodriguez (http://markorodriguez.com)
+ * 
+ * @deprecated Use {@link Initial} or {@link Terminal} instead.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

src/main/java/com/tinkerpop/frames/FramedElement.java

@@ -42,7 +42,7 @@ public class FramedElement implements InvocationHandler {
     }
 
     /**
-     * @deprecated The direction field will be dropped in 2.4.0
+     * @deprecated The direction field will be dropped in the next major release
      */
     public FramedElement(final FramedGraph framedGraph, final Element element, final Direction direction) {
         if (null == framedGraph) {
@@ -59,7 +59,7 @@ public FramedElement(final FramedGraph framedGraph, final Element element, final
     }
 
     public FramedElement(final FramedGraph framedGraph, final Element element) {
-        this(framedGraph, element, null);
+        this(framedGraph, element, Direction.OUT);
     }
 
     public Object invoke(final Object proxy, final Method method, final Object[] arguments) {

src/main/java/com/tinkerpop/frames/FramedGraph.java

@@ -18,8 +18,10 @@
 import com.tinkerpop.frames.annotations.AnnotationHandler;
 import com.tinkerpop.frames.annotations.DomainAnnotationHandler;
 import com.tinkerpop.frames.annotations.IncidenceAnnotationHandler;
+import com.tinkerpop.frames.annotations.InitialAnnotationHandler;
 import com.tinkerpop.frames.annotations.PropertyAnnotationHandler;
 import com.tinkerpop.frames.annotations.RangeAnnotationHandler;
+import com.tinkerpop.frames.annotations.TerminalAnnotationHandler;
 import com.tinkerpop.frames.annotations.gremlin.GremlinGroovyAnnotationHandler;
 import com.tinkerpop.frames.structures.FramedEdgeIterable;
 import com.tinkerpop.frames.structures.FramedVertexIterable;
@@ -68,6 +70,8 @@ public FramedGraph(final T baseGraph) {
 		registerAnnotationHandler(new IncidenceAnnotationHandler());
 		registerAnnotationHandler(new DomainAnnotationHandler());
 		registerAnnotationHandler(new RangeAnnotationHandler());
+		registerAnnotationHandler(new InitialAnnotationHandler());
+		registerAnnotationHandler(new TerminalAnnotationHandler());
 		registerAnnotationHandler(new GremlinGroovyAnnotationHandler());
 	}
 
@@ -117,8 +121,8 @@ public <F> F frame(final Vertex vertex, final Class<F> kind) {
 	 * @return a proxy objects backed by an edge and interpreted from the
 	 *         perspective of the annotate interface or null if the edge paramenter was null
 	 *         
-	 * @deprecated Use {@link #frame(Edge, Class)}, which uses the edge direction to determine
-	 *             {@link Domain} and {@link Range} of the frame.
+	 * @deprecated Use {@link #frame(Edge, Class)}, in combination with {@link Initial}
+	 *             and {@link Terminal}.
 	 */
 	public <F> F frame(final Edge edge, final Direction direction,
 			final Class<F> kind) {
@@ -141,7 +145,7 @@ public <F> F frame(final Edge edge, final Direction direction,
 
 	/**
 	 * A helper method for framing an edge. Note that all framed edges implement
-	 * {@link EdgeFrame} to allow access to the underlying element
+	 * {@link EdgeFrame} to allow access to the underlying element.
 	 * 
 	 * @param edge
 	 *            the edge to frame
@@ -153,7 +157,7 @@ public <F> F frame(final Edge edge, final Direction direction,
 	 *         perspective of the annotate interface or null if the edge paramenter was null
 	 */
 	public <F> F frame(final Edge edge, final Class<F> kind) {
-		return frame(edge, null, kind);
+		return frame(edge, Direction.OUT, kind);
 	}
 
 	/**
@@ -187,8 +191,8 @@ public <F> Iterable<F> frameVertices(final Iterable<Vertex> vertices,
 	 * @return an iterable of proxy objects backed by an edge and interpreted
 	 *         from the perspective of the annotate interface
 	 *         
-	 * @deprecated Use {@link #frameEdges(Iterable, Class)}, which uses the edge direction to determine
-	 *             {@link Domain} and {@link Range} of the framed edges.
+	 * @deprecated Use {@link #frameEdges(Iterable, Class)}, in combination with {@link Initial}
+	 *             and {@link Terminal}.
 	 */
 	public <F> Iterable<F> frameEdges(final Iterable<Edge> edges,
 			final Direction direction, final Class<F> kind) {
@@ -276,8 +280,8 @@ public Edge getEdge(final Object id) {
 	 * @return a proxy object backed by the edge and interpreted from the
 	 *         perspective of the annotate interface
 	 *         
-	 * @deprecated Use {@link #getEdges(Object, Class)}, which uses the edge direction to determine
-	 *             {@link Domain} and {@link Range} of the framed edge.      
+	 * @deprecated Use {@link #getEdges(Object, Class)}, in combination with {@link Initial}
+	 *             and {@link Terminal}.      
 	 */
 	public <F> F getEdge(final Object id, final Direction direction,
 			final Class<F> kind) {
@@ -328,8 +332,7 @@ public Edge addEdge(final Object id, final Vertex outVertex,
 	 *         perspective of the annotate interface
 	 *         
 	 * @deprecated Use {@link #addEdge(Object, Vertex, Vertex, String, Class)},
-	 *             which uses the edge direction to determine {@link Domain}
-	 *             and {@link Range} of the framed edge.
+     *             in combination with {@link Initial} and {@link Terminal}.
 	 */
 	public <F> F addEdge(final Object id, final Vertex outVertex,
 			final Vertex inVertex, final String label,
@@ -344,7 +347,7 @@ public <F> F addEdge(final Object id, final Vertex outVertex,
 	public <F> F addEdge(final Object id, final Vertex outVertex,
 			final Vertex inVertex, final String label,
 			final Class<F> kind) {
-		return addEdge(id, outVertex, inVertex, label, null, kind);
+		return addEdge(id, outVertex, inVertex, label, Direction.OUT, kind);
 	}
 
 	public void removeVertex(final Vertex vertex) {
@@ -407,9 +410,8 @@ public Iterable<Edge> getEdges(final String key, final Object value) {
 	 * @return an iterable of proxy objects backed by the edges and interpreted
 	 *         from the perspective of the annotate interface
 	 *         
-	 * @deprecated Use {@link #getEdges(String, Object, Class)},
-	 *             which uses the edge direction to determine {@link Domain}
-	 *             and {@link Range} of the framed edges.
+	 * @deprecated Use {@link #getEdges(String, Object, Class)}, in combination with
+	 *             {@link Initial} and {@link Terminal}.
 	 */
 	public <F> Iterable<F> getEdges(final String key, final Object value,
 			final Direction direction, final Class<F> kind) {
@@ -432,10 +434,6 @@ public <F> Iterable<F> getEdges(final String key, final Object value,
 	 *            the default type of the annotated interface
 	 * @return an iterable of proxy objects backed by the edges and interpreted
 	 *         from the perspective of the annotate interface
-	 *         
-	 * @deprecated Use {@link #getEdges(String, Object, Class)},
-	 *             which uses the edge direction to determine {@link Domain}
-	 *             and {@link Range} of the framed edges.
 	 */
 	public <F> Iterable<F> getEdges(final String key, final Object value,
 			final Class<F> kind) {

src/main/java/com/tinkerpop/frames/FramedGraphFactory.java

@@ -5,8 +5,10 @@
 import com.tinkerpop.frames.annotations.AdjacencyAnnotationHandler;
 import com.tinkerpop.frames.annotations.DomainAnnotationHandler;
 import com.tinkerpop.frames.annotations.IncidenceAnnotationHandler;
+import com.tinkerpop.frames.annotations.InitialAnnotationHandler;
 import com.tinkerpop.frames.annotations.PropertyAnnotationHandler;
 import com.tinkerpop.frames.annotations.RangeAnnotationHandler;
+import com.tinkerpop.frames.annotations.TerminalAnnotationHandler;
 
 /**
  * Creates a factory for creating {@link FramedGraph}s using a set of modules to
@@ -86,6 +88,8 @@ private FramedGraphConfiguration getBaseConfig() {
 		config.addAnnotationhandler(new IncidenceAnnotationHandler());
 		config.addAnnotationhandler(new DomainAnnotationHandler());
 		config.addAnnotationhandler(new RangeAnnotationHandler());
+		config.addAnnotationhandler(new InitialAnnotationHandler());
+		config.addAnnotationhandler(new TerminalAnnotationHandler());
 		return config;
 	}
 

src/main/java/com/tinkerpop/frames/Initial.java

@@ -0,0 +1,14 @@
+package com.tinkerpop.frames;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks the Initial Vertex (source) of a framed edge.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface Initial {
+}

src/main/java/com/tinkerpop/frames/Range.java

@@ -9,6 +9,8 @@
  * The target of the adjacency.
  *
  * @author Marko A. Rodriguez (http://markorodriguez.com)
+ * 
+ * @deprecated Use {@link Initial} or {@link Terminal} instead.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

src/main/java/com/tinkerpop/frames/Terminal.java

@@ -0,0 +1,14 @@
+package com.tinkerpop.frames;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks the Terminal Vertex (target) of a framed edge.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface Terminal {
+}

src/main/java/com/tinkerpop/frames/annotations/DomainAnnotationHandler.java

@@ -25,11 +25,7 @@ public Object processElement(final Domain annotation, final Method method, final
     }
 
     public Object processEdge(final Domain annotation, final Method method, final Object[] arguments, final FramedGraph framedGraph, final Edge edge, final Direction direction) {
-    	if (direction != null)
-    		//deprecated behavior: the edge direction should be used instead
-    		return framedGraph.frame(edge.getVertex(direction), method.getReturnType());
-    	//correct behavior (not using deprecated edge-framing is used):
-    	return framedGraph.frame(edge.getVertex(Direction.OUT), method.getReturnType());
+        return framedGraph.frame(edge.getVertex(direction), method.getReturnType());
     }
 
 }

src/main/java/com/tinkerpop/frames/annotations/IncidenceAnnotationHandler.java

@@ -30,14 +30,14 @@ public Object processElement(final Incidence annotation, final Method method, fi
 
     public Object processVertex(final Incidence incidence, final Method method, final Object[] arguments, final FramedGraph framedGraph, final Vertex element) {
         if (ClassUtilities.isGetMethod(method)) {
-            return new FramedEdgeIterable(framedGraph, element.getEdges(incidence.direction(), incidence.label()), ClassUtilities.getGenericClass(method));
+            return new FramedEdgeIterable(framedGraph, element.getEdges(incidence.direction(), incidence.label()), incidence.direction(), ClassUtilities.getGenericClass(method));
         } else if (ClassUtilities.isAddMethod(method)) {
 
             switch(incidence.direction()) {
             case OUT:
-                return framedGraph.addEdge(null, element, ((VertexFrame) arguments[0]).asVertex(), incidence.label(), method.getReturnType());
+                return framedGraph.addEdge(null, element, ((VertexFrame) arguments[0]).asVertex(), incidence.label(), Direction.OUT, method.getReturnType());
             case IN:
-                return framedGraph.addEdge(null, ((VertexFrame) arguments[0]).asVertex(), element, incidence.label(), method.getReturnType());
+                return framedGraph.addEdge(null, ((VertexFrame) arguments[0]).asVertex(), element, incidence.label(), Direction.IN, method.getReturnType());
             case BOTH:
                 throw new UnsupportedOperationException("Direction.BOTH it not supported on 'add' or 'set' methods");
             }

src/main/java/com/tinkerpop/frames/annotations/InitialAnnotationHandler.java

@@ -0,0 +1,25 @@
+package com.tinkerpop.frames.annotations;
+
+import com.tinkerpop.blueprints.Direction;
+import com.tinkerpop.blueprints.Edge;
+import com.tinkerpop.blueprints.Element;
+import com.tinkerpop.frames.FramedGraph;
+import com.tinkerpop.frames.Initial;
+
+import java.lang.reflect.Method;
+
+public class InitialAnnotationHandler implements AnnotationHandler<Initial> {
+    @Override
+    public Class<Initial> getAnnotationType() {
+        return Initial.class;
+    }
+
+    @Override
+    public Object processElement(final Initial annotation, final Method method, final Object[] arguments, final FramedGraph framedGraph, final Element element, final Direction direction) {
+        if (element instanceof Edge) {
+            return framedGraph.frame(((Edge)element).getVertex(Direction.OUT), method.getReturnType());
+        } else {
+            throw new UnsupportedOperationException();
+        }
+    }
+}

src/main/java/com/tinkerpop/frames/annotations/RangeAnnotationHandler.java

@@ -25,11 +25,7 @@ public Object processElement(final Range annotation, final Method method, final
     }
 
     public Object processEdge(final Range annotation, final Method method, final Object[] arguments, final FramedGraph framedGraph, final Edge edge, final Direction direction) {
-    	if (direction != null)
-    		//deprecated behavior: the edge direction should be used instead
-    		return framedGraph.frame(edge.getVertex(direction.opposite()), method.getReturnType());
-    	//correct behavior (not using deprecated edge-framing is used):
-    	return framedGraph.frame(edge.getVertex(Direction.IN), method.getReturnType());
+        return framedGraph.frame(edge.getVertex(direction.opposite()), method.getReturnType());
     }
 
 }

src/main/java/com/tinkerpop/frames/annotations/TerminalAnnotationHandler.java

@@ -0,0 +1,25 @@
+package com.tinkerpop.frames.annotations;
+
+import com.tinkerpop.blueprints.Direction;
+import com.tinkerpop.blueprints.Edge;
+import com.tinkerpop.blueprints.Element;
+import com.tinkerpop.frames.FramedGraph;
+import com.tinkerpop.frames.Terminal;
+
+import java.lang.reflect.Method;
+
+public class TerminalAnnotationHandler implements AnnotationHandler<Terminal> {
+    @Override
+    public Class<Terminal> getAnnotationType() {
+        return Terminal.class;
+    }
+
+    @Override
+    public Object processElement(final Terminal annotation, final Method method, final Object[] arguments, final FramedGraph framedGraph, final Element element, final Direction direction) {
+        if (element instanceof Edge) {
+        	return framedGraph.frame(((Edge)element).getVertex(Direction.IN), method.getReturnType());
+        } else {
+            throw new UnsupportedOperationException();
+        }
+    }
+}

src/main/java/com/tinkerpop/frames/structures/FramedEdgeIterable.java

@@ -3,9 +3,9 @@
 import com.tinkerpop.blueprints.Direction;
 import com.tinkerpop.blueprints.Edge;
 import com.tinkerpop.blueprints.Graph;
-import com.tinkerpop.frames.Domain;
+import com.tinkerpop.frames.Initial;
+import com.tinkerpop.frames.Terminal;
 import com.tinkerpop.frames.FramedGraph;
-import com.tinkerpop.frames.Range;
 
 import java.util.Iterator;
 
@@ -19,8 +19,8 @@ public class FramedEdgeIterable<T> implements Iterable<T> {
     protected final FramedGraph<? extends Graph> framedGraph;
 
     /**
-	 * @deprecated Use {@link #FramedEdgeIterable(FramedGraph, Iterable, Class)}, which uses
-	 *             the edge direction to determine {@link Domain} and {@link Range} of the frame.
+	 * @deprecated Use {@link #FramedEdgeIterable(FramedGraph, Iterable, Class)}, in combination with {@link Initial}
+	 *             and {@link Terminal}.
 	 */
     public FramedEdgeIterable(final FramedGraph<? extends Graph> framedGraph, final Iterable<Edge> iterable, final Direction direction, final Class<T> kind) {
         this.framedGraph = framedGraph;
@@ -33,7 +33,7 @@ public FramedEdgeIterable(final FramedGraph<? extends Graph> framedGraph, final
         this.framedGraph = framedGraph;
         this.iterable = iterable;
         this.kind = kind;
-        this.direction = null;
+        this.direction = Direction.OUT;
     }
 
     public Iterator<T> iterator() {