From 0c6acc0d22658c68d80257e3faa927bdbc1bd5df Mon Sep 17 00:00:00 2001
From: Jeffrey Phillips Freeman <jeffrey.freeman@syncleus.com>
Date: Sun, 24 Sep 2017 01:33:28 -0400
Subject: [PATCH] docs: updated existing documentation to include latest
changes to the API.
---
docs/annotations/adjacency.md | 271 ++++++++++++++++++++++++++--------
docs/annotations/property.md | 68 ++++++---
docs/getting_started.md | 2 +-
mkdocs.yml | 2 +-
4 files changed, 263 insertions(+), 80 deletions(-)
diff --git a/docs/annotations/adjacency.md b/docs/annotations/adjacency.md
index e1abe1c4..ad087d6e 100644
--- a/docs/annotations/adjacency.md
+++ b/docs/annotations/adjacency.md
@@ -1,38 +1,52 @@
Valid on frames: Vertex
-Allowed prefixes: `add`, `get`, `remove`, `set`
+Allowed prefixes when operation is AUTO: `add`, `get`, `remove`, `set`
Annotation arguments:
-`label` - The label assigned to the edge which connects the adjacent nodes.
+`value` - The label assigned to the edge which connects the adjacent nodes.
`direction` - The direction for the edge which creates the adjacency. It can be assigned any of the values from @org.apache.tinkerpop.gremlin.structure.Direction@.
+`operation` - The operation the method will perform. Must be one of the following: `GET`, `ADD`, `SET`, `REMOVE`, `AUTO`.
+Defaults to `AUTO`.
-## add prefix
+```java
+@Adjacency("foo")
+//Method declared here
+```
-Valid method signatures: `()`, `(<Any Vertex Frame>)`, `(ClassInitializer)`, `(ClassInitializer, ClassInitializer)`
+## ADD Operation
+
+Valid method signatures: `( )`, `(VertexFrame)`, `(ClassInitializer)`, `(ClassInitializer, ClassInitializer)`
Adds a node as an adjacency to the current node, and the returns the newly connected node.
-### ()
+### Signature: `( )`
+
+Valid return types: `VertexFrame`
-Valid return types: `Object` or `VertexFrame`
+Creates a new vertex without any type information as well as an untyped edge to connect to it. The newly created VertexFrame is returned.
-Creates a new vertex without any type information as well as an untyped edge to connect to it. The newly created VertexFrame is returned. Since it is untyped the return type of the signature can either be `Object` or `VertexFrame`.
+Since the returned `VertexFrame` is always untyped the return type must be either `VertexFrame` or `TVertex` specifically.
example:
```java
@Adjacency("Foo")
-VertexFrame addFoobar()
+VertexFrame addFoobar();
+```
+
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.ADD)
+VertexFrame addFoobar();
```
-### (<Any Vertex Frame>)
+### Signature: `(VertexFrame)`
-Valid return types: *Any Vertex Frame*
+Valid return types: `VertexFrame`
Creates a new edge without any type information and connects it between this vertex the vertex specified as an argument to the method. The frame returned is the same as the frame given in the argument, it is only there for compatability with other add methods. This method can also have a `void` return type.
@@ -40,23 +54,28 @@ examples:
```java
@Adjacency("Foo")
-Bar addFoobar(Bar existingVertex)
+Bar addFoobar(Bar existingVertex);
```
```java
@Adjacency("Foo")
-<E extends Bar> E addFoobar(E existingVertex)
+<E extends Bar> E addFoobar(E existingVertex);
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> E addFoobar(E existingVertex)
+<E extends VertexFrame> E addFoobar(E existingVertex);
+```
+
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.ADD)
+Bar E includeFoobar(Bar existingVertex);
```
-### (ClassInitializer)
+### Signature: `(ClassInitializer)`
-Valid return types: *Any Vertex Frame*
+Valid return types: `VertexFrame`
Creates a new edge without any type information and connects it between this vertex and a newly created vertex. The newly created vertex will have a type, as well as be initiated, according to the details specified in the ClassInitializer argument. Java generics can, and should, be used to narrow the return type.
@@ -64,23 +83,27 @@ example:
```java
@Adjacency("Foo")
-Bar addFoobar(ClassInitializer<? extends Bar> vertexInitializer)
+Bar addFoobar(ClassInitializer<? extends Bar> vertexInitializer);
```
```java
@Adjacency("Foo")
-<E extends Bar> E addFoobar(ClassInitializer<? extends E> vertexInitializer)
+<E extends Bar> E addFoobar(ClassInitializer<? extends E> vertexInitializer);
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> E addFoobar(ClassInitializer<? extends E> vertexInitializer)
+<E extends VertexFrame> E addFoobar(ClassInitializer<? extends E> vertexInitializer);
```
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.ADD)
+Bar includeFoobar(ClassInitializer<? extends Bar> vertexInitializer);
+```
-### (ClassInitializer, ClassInitializer)
+### Signature: `(ClassInitializer, ClassInitializer)`
-Valid return types: *Any Vertex Frame*
+Valid return types: `VertexFrame`
Creates a new edge and connects this to a new vertex. The newly created vertex will have a type, as well as be initiated, according to the details specified in the first ClassInitializer argument. Similarly the newly created edge will hava type, and be initiated using, the second ClassInitializer argument. Java generics can, and should, be used to narrow the return type.
@@ -89,73 +112,93 @@ example:
```java
@Adjacency("Foo")
Bar addFoobar(ClassInitializer<? extends Bar> vertexInitializer,
- ClassInitializer<?> edgeInitializer)
+ ClassInitializer<?> edgeInitializer);
```
```java
@Adjacency("Foo")
<E extends Bar> E addFoobar(ClassInitializer<? extends E> vertexInitializer,
- ClassInitializer<?> edgeInitializer)
+ ClassInitializer<?> edgeInitializer);
```
```java
@Adjacency("Foo")
<E extends VertexFrame> E addFoobar(ClassInitializer<? extends E> vertexInitializer,
- ClassInitializer<?> edgeInitializer)
+ ClassInitializer<?> edgeInitializer);
```
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.ADD)
+Bar includeFoobar(ClassInitializer<? extends Bar> vertexInitializer,
+ ClassInitializer<?> edgeInitializer);
+```
-## get prefix
+## GET Operation
Valid method signatures: `()`, `(Class)`
Get's one or more adjacent vertex from the graph.
-### ()
+### Signature: `( )`
-Valid return types: *Any Vertex Frame* or `Object` or `VertexFrame` or `Iterator`
+Valid return types: `VertexFrame` or `Iterator` or `List` or `Set`
-Retrieves one or more of the adjacent vertex. If the return type is a specific Frame, an `Object`, or a `VertexFrame` then only the first instance is returned. If the return type is an iterator then it will iterate over all matching vertex. When using an Iterator it is encouraged to use generics. The returned frames will always be instantiated as the type encoded in the graph if there is one.
+Retrieves one or more of the adjacent vertex. If the return type is a single Frame then only the first instance is returned. If the return type is an `Iterator` or `Iterable` then it will supply all matching vertex. When using an `Iterator` or `Iterable` it is encouraged, but not required, to use generics. The returned frames will always be instantiated as the type encoded in the graph if there is one.
-**Note:** If a type is specified that is more specific than the type of the returned element then an exception will be thrown. Therefore the return type specifed should always by the same type, or a super-type, of the expected return type. VertexFrame is always a safe return type for this method.
+**Note:** If a type is specified in the arguments is a superclass of the returned element then an exception will be thrown. Therefore the return type specifed should always by the same type, or a superclass, of the expected return type. VertexFrame is always a safe return type for this method.
example:
```java
@Adjacency("Foo")
-Bar getFoobar()
+Bar getFoobar();
```
```java
@Adjacency("Foo")
-<E extends Bar> E getFoobar()
+<E extends Bar> E getFoobar();
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> E getFoobar()
+<E extends VertexFrame> E getFoobar();
```
```java
@Adjacency("Foo")
-Iterator<Bar> getFoobar()
+Iterator<Bar> getFoobar();
```
```java
@Adjacency("Foo")
-<E extends Bar> Iterator<E> getFoobar()
+<E extends Bar> Iterator<E> getFoobar();
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> Iterator<E> getFoobar()
+<E extends VertexFrame> Iterator<E> getFoobar();
```
+```java
+@Adjacency("Foo")
+List<Bar> getFoobar();
+```
-### (Class)
+```java
+@Adjacency("Foo")
+Set<Bar> getFoobar();
+```
+
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.GET)
+Bar obtainFoobar();
+```
-Valid return types: *Any Vertex Frame* or `Object` or `VertexFrame` or `Iterator`
+
+### Signature: `(Class)`
+
+Valid return types: `VertexFrame` or `Iterator` or `List` or `Set`
Retrieves one or more of the adjacent vertex. If the return type is a specific Frame, an `Object`, or a `VertexFrame` then only the first instance is returned. If the return type is an iterator then it will iterate over all matches vertex. When using an Iterator it is encouraged to use generics.
@@ -165,95 +208,207 @@ example:
```java
@Adjacency("Foo")
-Bar getFoobar(Class<? extends Bar> filter)
+Bar getFoobar(Class<? extends Bar> filter);
+```
+
+```java
+@Adjacency("Foo")
+<E extends Bar> E getFoobar(Class<? extends E> filter);
+```
+
+```java
+@Adjacency("Foo")
+<E extends VertexFrame> E getFoobar(Class<? extends E> filter);
```
```java
@Adjacency("Foo")
-<E extends Bar> E getFoobar(Class<? extends E> filter)
+Iterator<Bar> getFoobar(Class<? extends Bar> filter);
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> E getFoobar(Class<? extends E> filter)
+<E extends Bar> Iterator<E> getFoobar(Class<? extends E> filter);
```
```java
@Adjacency("Foo")
-Iterator<Bar> getFoobar(Class<? extends Bar> filter)
+<E extends VertexFrame> Iterator<E> getFoobar(Class<? extends E> filter);
```
```java
@Adjacency("Foo")
-<E extends Bar> Iterator<E> getFoobar(Class<? extends E> filter)
+List<Bar> getFoobar(Class<? extends Bar> filter);
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> Iterator<E> getFoobar(Class<? extends E> filter)
+Set<Bar> getFoobar(Class<? extends Bar> filter);
```
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.GET)
+Bar obtainFoobar(Class<? extends Bar> filter);
+```
+
+
+## REMOVE Operation
+
+Valid method signatures: `( )`, `(VertexFrame)`
+
+Removes any edges which cause an adjacency, leaving the vertex in place.
-## remove prefix
+### Signature: `( )`
-Valid method signatures: `(<Any Vertex Frame>)`
+Valid return types: `void`
-Removes any edges which cause an adjacency.
+Removes all edges which create any adjacency between the current vertex and any other vertex using the specified label.
+example:
-### (<Any Vertex Frame>)
+```java
+@Adjacency("Foo")
+void removeFoobar();
+```
+
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.REMOVE)
+void deleteAllFoobar(E vertex);
+```
+
+
+### Signature: `(VertexFrame)`
Valid return types: `void`
-Removes any edges which create an adjacency between the vurrent vertex and the vertex specified in the methods argument.
+Removes all edges which create an adjacency between the current vertex and the vertex specified in the methods argument
+and has the specified label.
example:
```java
@Adjacency("Foo")
-void removeFoobar(Bar vertex)
+void removeFoobar(Bar vertex);
```
```java
@Adjacency("Foo")
-<E extends Bar> void removeFoobar(E vertex)
+<E extends Bar> void removeFoobar(E vertex);
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> void removeFoobar(E vertex)
+<E extends VertexFrame> void removeFoobar(E vertex);
```
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.REMOVE)
+void removeFoobar(Bar vertex);
+```
-## set prefix
-Valid method signatures: `(Iterator)`
+## SET Operation
-Creates new edges connected to several vertex.
+Valid method signatures: `(VertexFrame)`, `(Iterator)`, `(Iterable)`
+Creates new edges connected to several vertex and at the same time removes any existing edges. If the any of the vertex
+being set are already an adjacency then the edge will be preserved as-is.
-### (Iterator)
+### Signature: `(VertexFrame)`
Valid return types: `void`
-The argument for this method must be an Iterator which iterates over any vertex Frames. It is suggested you specify a Generic Type for the Iterator for usability.
+The argument for this method must be a `VertexFrame` or a class or interface which inherits from that class.
+
+This method will drop any existing edges with the specified label and create a single new edge to the vertex specified.
+If the specified vertex is already an adjacency than any edges already connected to it will be preserved. Any newly
+created edges will not encode a type.
+
+example:
+
+```java
+@Adjacency("Foo")
+void setFoobar(Bar vertex);
+```
+
+```java
+@Adjacency("Foo")
+<E extends Bar> void setFoobar(E vertex);
+```
+
+```java
+@Adjacency(value = "Foo", operation = Adjacency.Operation.SET)
+void assignFoobar(Bar vertex);
+```
+
+### Signature: `(Iterator)`
+
+Valid return types: `void`
+
+The argument for this method must be an `Iterator` which iterates over vertex Frames. It is suggested you specify a Generic Type for the Iterator for usability.
This method will iterate over all the vertex specified in the Iterator argument and create new edges to connect to it. The edges in the graph will not encode a type.
+Any existing edges matching the specified label that do not connect to one of the `VertexFrame` provided by the iterator will be removed.
+
example:
```java
@Adjacency("Foo")
-void setFoobar(Iterator<Bar> vertex)
+void setFoobar(Iterator<Bar> vertex);
+```
+
+```java
+@Adjacency("Foo")
+<E extends Bar> void setFoobar(Iterator<? extends E> vertex);
+```
+
+```java
+@Adjacency("Foo")
+<E extends VertexFrame> void setFoobar(Iterator<? extends E> vertex);
+```
+
+### Signature: `(Iterable)`
+
+Valid return types: `void`
+
+The argument for this method must be an `Iterable` or a subclass of `Iterable` which iterates over vertex Frames. It is suggested you specify a Generic Type for the Iterator for usability.
+
+Since all Java collections inherit from the `Iterable` interface they can also be used as parameters to these methods.
+
+This method will iterate over all the vertex specified in the `Iterable` argument and create new edges to connect to it. The edges in the graph will not encode a type.
+
+Any existing edges matching the specified label that do not connect to one of the `VertexFrame` provided by the iterator will be removed.
+
+example:
+
+```java
+@Adjacency("Foo")
+void setFoobar(Iterable<Bar> vertex);
+```
+
+```java
+@Adjacency("Foo")
+void setFoobar(Collection<Bar> vertex);
+```
+
+```java
+@Adjacency("Foo")
+void setFoobar(List<Bar> vertex);
+```
+
+```java
+@Adjacency("Foo")
+void setFoobar(Set<Bar> vertex);
```
```java
@Adjacency("Foo")
-<E extends Bar> void setFoobar(Iterator<? extends E> vertex)
+<E extends Bar> void setFoobar(Iterable<? extends E> vertex);
```
```java
@Adjacency("Foo")
-<E extends VertexFrame> void setFoobar(Iterator<? extends E> vertex)
+<E extends VertexFrame> void setFoobar(Iterable<? extends E> vertex);
```
diff --git a/docs/annotations/property.md b/docs/annotations/property.md
index ce0b7a51..c09733c7 100644
--- a/docs/annotations/property.md
+++ b/docs/annotations/property.md
@@ -1,11 +1,14 @@
Valid on frames: Edge and Vertex
-Allowed prefixes: `get`, `is`, `can`, `set`, `remove`
+Allowed prefixes when operation is AUTO: `get`, `is`, `can`, `set`, `remove`
Annotation arguments:
`value` - The name of the property
+`operation` - The operation the method will perform. Must be one of the following: `GET`, `SET`, `REMOVE`, `AUTO`.
+Defaults to `AUTO`.
+
The following would bind the method it is used on to the property named `foo`:
```java
@@ -14,12 +17,12 @@ The following would bind the method it is used on to the property named `foo`:
```
-## get prefix
+## GET Operation
-Valid method signatures: `()`
+Valid method signatures: `( )`
-### ()
+### Signature: `( )`
Valid return types: *Any Object*
@@ -29,26 +32,31 @@ example:
```java
@Property("Foo")
-Bar getFoobar()
+Bar getFoobar();
```
```java
@Property("Foo")
-<E extends Bar> E getFoobar()
+<E extends Bar> E getFoobar();
```
```java
@Property("Foo")
-<E> E getFoobar()
+<E> E getFoobar();
```
+```java
+@Property(value = "Foo", operation = Property.Operation.GET)
+Bar obtainFoobar();
+```
-## is prefix
-Valid method signatures: `()`
+## GET Operation (is prefix)
+Valid method signatures: `( )`
-### ()
+
+### Signature: `( )`
Valid return types: `boolean`
@@ -58,16 +66,21 @@ example:
```java
@Property("Foobared")
-boolean isFoobared()
+boolean isFoobared();
+```
+
+```java
+@Property(value = "Foo", operation = Property.Operation.GET)
+boolean obtainFoobared();
```
-## set prefix
+## SET Operation
Valid method signatures: `(Object)`
-### (Object)
+### Signature: `(Object)`
Valid return types: `void`
@@ -77,26 +90,36 @@ example:
```java
@Property("Foo")
-void setFoobar(Bar foobar)
+void setFoobar(Bar foobar);
```
```java
@Property("Foo")
-<E extends Bar> void setFoobar(E foobar)
+<E extends Bar> void setFoobar(E foobar);
```
```java
@Property("Foo")
-<E extends VectorFrame> void setFoobar(E foobar)
+<E extends VectorFrame> void setFoobar(E foobar);
```
+```java
+@Property("Foo")
+void setFoobar(Bar foobar);
+```
+
+```java
+@Property(value = "Foo", operation = Property.Operation.SET)
+void applyFoobar(Bar foobar);
+```
-## remove prefix
-Valid method signatures: `()`
+## REMOVE Operation
+Valid method signatures: `( )`
-### ()
+
+### Signature: `( )`
Valid return types: `void`
@@ -106,5 +129,10 @@ example:
```java
@Property("Foo")
-void removeFoobar()
+void removeFoobar();
+```
+
+```java
+@Property(value = "Foo", operation = Property.Operation.REMOVE)
+void removeFoobar();
```
diff --git a/docs/getting_started.md b/docs/getting_started.md
index e16be091..6116561a 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -8,7 +8,7 @@ To include Ferma in your project of choice include the following Maven dependenc
<dependency>
<groupId>com.syncleus.ferma</groupId>
<artifactId>ferma</artifactId>
- <version>3.0.1</version>
+ <version>3.2.0</version>
</dependency>
```
diff --git a/mkdocs.yml b/mkdocs.yml
index fbbbbd5b..10d3d6f5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,7 +13,7 @@ pages:
- '@Property': annotations/property.md
- '@adjacency': annotations/adjacency.md
extra:
- version: '3.0.1'
+ version: '3.2.0'
logo: 'images/ferma-logo.svg'
github:
download_release: true
--
GitLab