Merge branch 'gjdev-edgedir3'

Conflicts:
	CHANGELOG.textile

Author: BrynCooke

CHANGELOG.textile

@@ -15,6 +15,9 @@ h3. Version 2.4.0 (NOT OFFICIALLY RELEASED YET)
 </dependency>
 ```
 
+* Deprecate the direction parameter for framing Edges from FramedGraph.frame. When using Initial/Terminal to annotate the out/in vertices of an edgeframe, the direction parameter is not used. The deprecated methods will be removed in the next major release.
+* Deprecate the Domain and Range annotations in favour of Initial and Terminal. See #65 and #57 for the rationale behind this change. Domain and Range will be removed from the next major release.
+* Introduce Initial and Terminal annotations for framed edges to set the source (out-vertex) and target (in-vertex) of an edge frame. These annotations will replace Domain and Range in the next major release.
 * Framing a @null@ element returns @null@
 * Fixed @NullPointerException@ 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

@@ -41,6 +41,9 @@ public class FramedElement implements InvocationHandler {
         }
     }
 
+    /**
+     * @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) {
             throw new IllegalArgumentException("FramedGraph can not be null");
@@ -56,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());
 	}
 
@@ -116,6 +120,9 @@ public <F> F frame(final Vertex vertex, final Class<F> kind) {
 	 *            the default type of the annotated interface
 	 * @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)}, in combination with {@link Initial}
+	 *             and {@link Terminal}.
 	 */
 	public <F> F frame(final Edge edge, final Direction direction,
 			final Class<F> kind) {
@@ -135,6 +142,23 @@ public <F> F frame(final Edge edge, final Direction direction,
 				resolvedTypes.toArray(new Class[resolvedTypes.size()]),
 				new FramedElement(this, edge, direction));
 	}
+	
+	/**
+	 * A helper method for framing an edge. Note that all framed edges implement
+	 * {@link EdgeFrame} to allow access to the underlying element.
+	 * 
+	 * @param edge
+	 *            the edge to frame
+	 * @param kind
+	 *            the default annotated interface to frame the edges as
+	 * @param <F>
+	 *            the default type of the annotated interface
+	 * @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
+	 */
+	public <F> F frame(final Edge edge, final Class<F> kind) {
+		return frame(edge, Direction.OUT, kind);
+	}
 
 	/**
 	 * A helper method for framing an iterable of vertices.
@@ -166,11 +190,33 @@ public <F> Iterable<F> frameVertices(final Iterable<Vertex> vertices,
 	 *            the default type of the annotated interface
 	 * @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)}, in combination with {@link Initial}
+	 *             and {@link Terminal}.
 	 */
 	public <F> Iterable<F> frameEdges(final Iterable<Edge> edges,
 			final Direction direction, final Class<F> kind) {
 		return new FramedEdgeIterable<F>(this, edges, direction, kind);
 	}
+	
+	/**
+	 * A helper method for framing an iterable of edges.
+	 * 
+	 * @param edges
+	 *            the edges to frame
+	 * @param direction
+	 *            the direction of the edges
+	 * @param kind
+	 *            the default annotated interface to frame the edges as
+	 * @param <F>
+	 *            the default type of the annotated interface
+	 * @return an iterable of proxy objects backed by an edge and interpreted
+	 *         from the perspective of the annotate interface
+	 */
+	public <F> Iterable<F> frameEdges(final Iterable<Edge> edges,
+			final Class<F> kind) {
+		return new FramedEdgeIterable<F>(this, edges, kind);
+	}
 
 	public Vertex getVertex(final Object id) {
 		return config.getConfiguredGraph().getVertex(id);
@@ -233,11 +279,32 @@ public Edge getEdge(final Object id) {
 	 *            the default type of the annotated interface
 	 * @return a proxy object backed by the edge and interpreted from the
 	 *         perspective of the annotate interface
+	 *         
+	 * @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) {
 		return this.frame(getEdge(id), direction, kind);
 	}
+	
+	/**
+	 * Frame an edge according to a particular kind of annotated interface.
+	 * 
+	 * @param id
+	 *            the id of the edge
+	 * @param direction
+	 *            the direction of the edge
+	 * @param kind
+	 *            the default annotated interface to frame the edge as
+	 * @param <F>
+	 *            the default type of the annotated interface
+	 * @return a proxy object backed by the edge and interpreted from the
+	 *         perspective of the annotate interface     
+	 */
+	public <F> F getEdge(final Object id, final Class<F> kind) {
+		return this.frame(getEdge(id), kind);
+	}
 
 	public Edge addEdge(final Object id, final Vertex outVertex,
 			final Vertex inVertex, final String label) {
@@ -263,6 +330,9 @@ public Edge addEdge(final Object id, final Vertex outVertex,
 	 *            the default type of the annotated interface
 	 * @return a proxy object backed by the edge and interpreted from the
 	 *         perspective of the annotate interface
+	 *         
+	 * @deprecated Use {@link #addEdge(Object, Vertex, Vertex, String, Class)},
+     *             in combination with {@link Initial} and {@link Terminal}.
 	 */
 	public <F> F addEdge(final Object id, final Vertex outVertex,
 			final Vertex inVertex, final String label,
@@ -273,6 +343,12 @@ public <F> F addEdge(final Object id, final Vertex outVertex,
 		}
 		return this.frame(edge, direction, kind);
 	}
+	
+	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, Direction.OUT, kind);
+	}
 
 	public void removeVertex(final Vertex vertex) {
 		config.getConfiguredGraph().removeVertex(vertex);
@@ -333,12 +409,37 @@ public Iterable<Edge> 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)}, 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) {
 		return new FramedEdgeIterable<F>(this, config.getConfiguredGraph().getEdges(key,
 				value), direction, kind);
 	}
+	
+	/**
+	 * Frame edges according to a particular kind of annotated interface.
+	 * 
+	 * @param key
+	 *            the key of the edges to get
+	 * @param value
+	 *            the value of the edges to get
+	 * @param direction
+	 *            the direction of the edges
+	 * @param kind
+	 *            the default annotated interface to frame the edges as
+	 * @param <F>
+	 *            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
+	 */
+	public <F> Iterable<F> getEdges(final String key, final Object value,
+			final Class<F> kind) {
+		return new FramedEdgeIterable<F>(this, config.getConfiguredGraph().getEdges(key,
+				value), kind);
+	}
 
 	public Features getFeatures() {
 		Features features = config.getConfiguredGraph().getFeatures().copyFeatures();

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/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/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,6 +3,8 @@
 import com.tinkerpop.blueprints.Direction;
 import com.tinkerpop.blueprints.Edge;
 import com.tinkerpop.blueprints.Graph;
+import com.tinkerpop.frames.Initial;
+import com.tinkerpop.frames.Terminal;
 import com.tinkerpop.frames.FramedGraph;
 
 import java.util.Iterator;
@@ -16,12 +18,23 @@ public class FramedEdgeIterable<T> implements Iterable<T> {
     protected final Iterable<Edge> iterable;
     protected final FramedGraph<? extends Graph> framedGraph;
 
+    /**
+	 * @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;
         this.iterable = iterable;
         this.kind = kind;
         this.direction = direction;
     }
+    
+    public FramedEdgeIterable(final FramedGraph<? extends Graph> framedGraph, final Iterable<Edge> iterable, final Class<T> kind) {
+        this.framedGraph = framedGraph;
+        this.iterable = iterable;
+        this.kind = kind;
+        this.direction = Direction.OUT;
+    }
 
     public Iterator<T> iterator() {
         return new Iterator<T>() {