Frames 0.5 Beams release.

doc/wiki/Annotations.textile

@@ -0,0 +1,42 @@
+[[http://duke.kenai.com/models/Duke3DprogressionSmall.jpg|height=125px]]
+
+In Frames, a schema is defined by a collection of Java interfaces. The rules that bind the Java interfaces to the underlying graph representation are defined by the following:
+
+* Method name prefixes: get, set, add, remove
+* Annotations: method metadata.
+
+Below specifies that annotations that can be used when defining a Frames interface. By specifying the method argument and return types, the underlying graph is constrained to the interface specification.
+
+|_. annotation |_. method prefix |_. arguments |_. description |_. example |
+| @@Property@ | @get@ | @value@ |get the property value of an element | @@Property("name")@ |
+| @@Property@ | @set@ | @value@ | set the property value of an element | @@Property("name")@ |
+| @@Property@ | @remove@ | @value@ | remove the property of an element | @@Property("name")@ |
+| @@Relation@ | @get@ | @label@, @direction@ | get the vertex or vertices @X@ related to the vertex | @@Relation(label="X", direction=Direction.STANDARD)@ |
+| @@Relation@ | @set@ | @label@, @direction@ | set the vertex or vertices @X@ related to the vertex | @@Relation(label="X", direction=Direction.STANDARD)@ |
+| @@Relation@ | @add@ | @label@, @direction@ | add a vertex @X@ related to the vertex | @@Relation(label="X", direction=Direction.STANDARD)@ |
+| @@Relation@ | @remove@ | @label@, @direction@ | remove a vertex @X@ related to the vertex | @@Relation(label="X", direction=Direction.STANDARD)@ |
+| @@Adjacency@ | @get@ | @label@, @direction@ | get the edges @X@ related to the vertex | @@Adjacency(label="X", direction=Direction.STANDARD)@ |
+| @@Adjacency@ | @add@ | @label@, @direction@ | add an edge @X@ related to the vertex | @@Adjacency(label="X", direction=Direction.STANDARD)@ |
+| @@Adjacency@ | @remove@ | @label@, @direction@ | remove an edge @X@ related to the vertex | @@Adjacency(label="X", direction=Direction.STANDARD)@ |
+| @@Domain@ | @get@ | none | get the domain of the relation (i.e the source) | @@Domain@ |
+| @@Range@ | @get@ | none | get the range of the relation (i.e. the target) | @@Range@ |
+
+Note that "get" and "set" methods for @@Relations@ can be either single-valued or collection-valued.  For example:
+
+```java
+public interface Person {
+    @Relation(label = "spouse")
+    Person getSpouse();
+
+    @Relation(label = "spouse")
+    void setSpouse(Person spouse);
+
+    @Relation(label = "child")
+    Collection<Person> getChildren();
+
+    @Relation(label = "child")
+    void setChildren(Collection<Person> children);
+}
+```
+
+The above interface uses both styles of getter and setter: a collection-valued style which allows you to set multiple values simultaneously, and gives you back all values at once, and a "functional" style which requires you to specify exactly one value (which can be null), and gives you back at most one value.  Each style has its advantages, depending on your application.

doc/wiki/Creating-Frames.textile

@@ -0,0 +1,16 @@
+When you develop a Frames-annotation Java interface, you provide it "life" by binding it to the underlying "Blueprints":http://blueprints.tinkerpop.com graph. To make this binding, the @FramesManager@ is used. In @FramesManager@ there a collection of helpful methods which are articulate using the toy graph diagrammed below and the example Java code.
+
+[[https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-example-1.jpg|width=450px]]
+
+```java
+Graph graph = ... // get a reference to the graph
+FramesManager manager = new FramesManager(graph); // create a manager for the graph
+
+Person marko = manager.frame(graph.getVertex(1), Person.class);
+Person peter = manager.frameVertex(6, Person.class);
+Iterable<Project> javaProjects = manager.frameVertices(Index.VERTICES, "lang", "java", Project.class);
+
+Knows markoKnowsVadas = manager.frame(graph.getEdge(7), Direction.STANDARD, Knows.class);
+Knows markoKnowsJosh = manager.frameEdge(8, Direction.STANDARD, Knows.class);
+Iterable<CreatedBy> createdByRelations = manager.frameEdges(Index.EDGES, AutomaticIndex.LABEL, "created", Direction.INVERSE, CreatedBy.class);
+```

doc/wiki/Frames-Ecosystem.textile

@@ -0,0 +1,12 @@
+Frames is a bare-bones library. Luckily, its part of a larger ecosystem of graph technologies. When using Frames, you will find yourself making use of framed domain objects and "Blueprints":http://blueprints.tinkerpop.com.
+
+h2. Managing Transactions
+
+Frames has no notion of transaction management. To manage transactions, use Blueprints.
+
+```java
+Graph graph = ... // get reference to graph
+graph.startTransaction();
+// do Frames related mutations to the graph
+graph.stopTransaction(Conclusion.SUCCESS);
+```

doc/wiki/Getting-Started.textile

@@ -0,0 +1,87 @@
+[[http://i579.photobucket.com/albums/ss235/krissy_bby93/icon_UnderConstruction.png|width=120px]]
+
+h2. Creating a Domain Model with Java Interfaces
+
+Frames makes use of Java interfaces and annotations. Here is a simple example that mixes people and software projects. People create projects and know each other. To represent such concepts in Java, do the following. First, lets create a @Person@ interface.
+
+```java
+public interface Person {
+  @Property("name")
+  public void setName(String name);
+  @Property("name")
+  public String getName();
+  @Property("age")
+  public void setAge(int age);
+  @Property("age")
+  public int getAge();
+
+  @Relation(label="knows")
+  public Collection<Person> getKnowsPeople();
+  @Relation(label="knows")
+  public void addKnowsPerson(Person person);
+
+  @Relation(label="created")
+  public Collection<Project> getCreatedProjects();
+  @Relation(label="created")
+  public void addCreatedProject(Project project);
+}
+```
+
+That is all there is to it. Once an interface has been constructed to represent a vertex type, then a vertex in the graph can be framed within the perspective of that interface.
+
+h2. Framing Graph Elements in Terms of the Java Interfaces
+
+For the remainder of this section, the following graph example will be used. Note that this toy graph comes hardcoded with "Blueprints":http://blueprints.tinkerpop.com and is available as @TinkerGraphFactory.createTinkerGraph()@.
+
+[[https://github.com/tinkerpop/blueprints/raw/master/doc/images/graph-example-1.jpg|width=450px]]
+
+To frame vertex 1 (marko) in terms of the @Person@ interface defined previously, simply do the following.
+
+```java
+Graph graph = TinkerGraphFactory.createTinkerGraph();
+FramesManager manager = new FramesManager(graph);
+Person marko = manager.frame(graph.getVertex(1), Person.class);
+```
+
+Now its possible to update Marko's age, get his name, and determine the names of all the people he knows.
+
+```java
+marko.setAge(31)
+assert marko.getName().equals("marko")
+for(Person person : marko.getKnowsPeople()) {
+  System.out.println(person.getName()); // prints vadas and josh
+}
+```
+
+h2. Adding a Few More Constructs
+
+In the example graph, there are people and there are projects. Lets model a project as a Java interface.
+
+```java
+public interface Project extends VertexFrame {
+  @Property("name")
+  public void setName(String name);
+  @Property("name")
+  public String getName();
+  @Property("lang")
+  public void setLanguage(String language);
+  @Property("lang")
+  public int getLanguage();
+
+  @Relation(label="created", direction=Direction.INVERSE)
+  public Collection<Person> getCreatedByPerson();
+}
+```
+
+There are a few things that are worth exemplifying. First, while the property of the project vertex may have the key @lang@, the method to get and set the property value can be anything. The @@Property@ annotation makes it clear what the explicit property key is. Second, notice that there is no explicit @created_by@ edge in the example graph. We can infer this relation by using inverting a @created@ edge. In other words, the people who create a project are the people that the project was created by.
+
+Finally, notice that @Project@ extends the special, @VertexFrame@ interface.  While it is not necessary to extend @VertexFrame@ in order to create and manipulate Frames objects, doing so provides access to the @asVertex@ method which takes you from a frame to the underlying Blueprints vertex.  The @EdgeFrame@ interface provides a similar method, @asEdge@.
+
+```java
+Project ripple = manager.frame(graph.getVertex(5), Project.class);
+System.out.println(ripple.getCreatedByPerson().iterator().next().getName());  // prints "josh"
+
+System.out.println(ripple.asVertex().getId());  // prints "5"
+```
+
+There is more to Frames, but what has been presented are the basic constructs to help get you started.

doc/wiki/Home.textile

@@ -0,0 +1,56 @@
+!https://github.com/tinkerpop/frames/raw/master/doc/images/frames-logo.png!
+
+Frames exposes any "Blueprints":http://blueprints.tinkerpop.com graph as a collection of interrelated domain objects. Frames makes heavy use of @InvocationHandler@, @Proxy@ classes, and @Annotations@ to allow a developer to _frame_ a graph element (vertex or edge) in terms of a particular Java interface. With Frames, its easy to ensure that data within a graph is respective of a schema represented as a collection of annotated Java interfaces. 
+
+Please join the Gremlin users group at "http://groups.google.com/group/gremlin-users":http://groups.google.com/group/gremlin-users for all "TinkerPop":http://tinkerpop.com related discussions.
+
+Frames 0.5 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.4/api/
+Frames 0.4 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.4/api/
+Frames 0.3 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.3/api/
+Frames 0.2 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.2/api/
+Frames 0.1 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.1/api/
+
+```xml
+<dependency>
+  <groupId>com.tinkerpop</groupId>
+  <artifactId>frames</artifactId>
+  <version>0.4</version>
+</dependency>
+```
+
+For non-Maven users, *download the requisite jar*:
+* "http://tinkerpop.com/maven2/com/tinkerpop/frames/0.5/frames-0.5.jar":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.5/frames-0.5.jar
+
+```java
+public interface Person {
+  @Property("name")
+  public String getName();
+  @Adjacency(label="knows")
+  public Collection<Knows> getKnows();
+  @Relation(label="knows")
+  public Collection<Person> getKnowsPeople();
+  @Relation(label="knows")
+  public void addKnowsPerson(final Person person);
+}
+
+public class Frames {
+  public Frames() {
+   Graph graph =  new Neo4jGraph("/tmp/neo4j");
+   FramesManager manager = new FramesManager(graph);
+   Person person = manager.frame(graph.getVertex(1), Person.class);
+   person.getName(); // equals "marko"
+  }
+}
+```
+
+Frames can be used with "Rexster":http://rexster.tinkerpop.com through the "Rexster Kibbles":http://rexster-kibbles.tinkerpop.com Frames extension.
+
+==<hr/>==
+
+* [[Introduction]]
+** [[Getting Started]]
+**** [[Frames Ecosystem]]
+** [[Creating Frames]]
+** [[Annotations]] (*Cheat Sheet*)
+* Conclusion
+** [[Release Notes]]

doc/wiki/Introduction.textile

@@ -0,0 +1,5 @@
+[[http://markorodriguez.files.wordpress.com/2011/01/graph-example1.png|width=150px|align=left|float]]
+
+A "graph database":http://en.wikipedia.org/wiki/Graph_database represents a collection of vertices (nodes, dots) connected to each other by edges (arcs, lines). Some graph database vendors provide data schema functionality. In such databases, vertices and edges are typed and there are notions of data restrictions--e.g. subclassing, data validation, rules of inference, etc. Other graph database are "schema-free" in that there is no notion of a type system--only vertices, edges, and their adjacencies. When modeling worldly objects (people, places things) and their relationships to each other, schema-based graph databases are handy. When modeling graphical data structures such as an index, a schema is somewhat less important. In general, as the complexity of the the domain model increases, the need for a schema system increases.
+
+The purpose of Frames it to provide a data schema layer to "Blueprints":http://blueprints.tinkerpop.com enabled graph databases. With Blueprints, there are simply vertices, edges, and key/value properties. Frames is used to represent (or frame) aspects of the underlying graph in terms of domain objects and their relationships to one another. As such, the developer can work in terms of real-world objects instead of vertices and edges.

doc/wiki/Release-Notes.textile

@@ -0,0 +1,99 @@
+All releases can be accessed through the "TinkerPop":http://tinkerpop.com Maven2 repository identified below.
+
+```xml
+<repository>
+  <id>tinkerpop-repository</id>
+  <name>TinkerPop Maven2 Repository</name>
+  <url>http://tinkerpop.com/maven2</url>
+</repository>
+```
+
+==<hr/>==
+
+!https://github.com/tinkerpop/frames/raw/master/doc/images/frames-beams.png!
+
+h3. Version 0.5 (Beams -- September 18, 2011)
+
+```xml
+<dependency>
+  <groupId>com.tinkerpop</groupId>
+  <artifactId>frames</artifactId>
+  <version>0.5</version>
+</dependency>
+```
+
+Frames 0.5 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.5/api/
+
+==<hr/>==
+
+!https://github.com/tinkerpop/frames/raw/master/doc/images/frames-studs.png!
+
+h3. Version 0.4 (Studs -- August 1, 2011)
+
+```xml
+<dependency>
+  <groupId>com.tinkerpop</groupId>
+  <artifactId>frames</artifactId>
+  <version>0.4</version>
+</dependency>
+```
+
+Frames 0.4 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.4/api/
+
+* Added 'set to null' / 'remove all' functionality for functional relations.
+* Added @VertexFrame@ and @EdgeFrame@ interfaces to provide access to underlying vertices and edges of frames.
+* Extended @Relation@ support to both multiple-valued and single-valued (functional) relations.
+
+==<hr/>==
+
+!https://github.com/tinkerpop/frames/raw/master/doc/images/frames-lumber.png!
+
+h3. Version 0.3 (Lumber -- June 15, 2011)
+
+```xml
+<dependency>
+  <groupId>com.tinkerpop</groupId>
+  <artifactId>frames</artifactId>
+  <version>0.3</version>
+</dependency>
+```
+
+Frames 0.3 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.3/api/
+
+* Added JavaDoc
+
+==<hr/>==
+
+!https://github.com/tinkerpop/frames/raw/master/doc/images/frames-huff-and-puff.png!
+
+h3. Version 0.2 (Huff and Puff -- May 8, 2011)
+
+```xml
+<dependency>
+  <groupId>com.tinkerpop</groupId>
+  <artifactId>frames</artifactId>
+  <version>0.2</version>
+</dependency>
+```
+
+Frames 0.2 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.2/api/
+
+* Added JavaDoc
+
+==<hr/>==
+
+!https://github.com/tinkerpop/frames/raw/master/doc/images/frames-brick-by-brick.png!
+
+h3. Version 0.1 (Brick By Brick -- April 4, 2011)
+
+```xml
+<dependency>
+  <groupId>com.tinkerpop</groupId>
+  <artifactId>frames</artifactId>
+  <version>0.1</version>
+</dependency>
+```
+
+Frames 0.1 "JavaDoc":http://tinkerpop.com/maven2/com/tinkerpop/frames/0.1/api/
+
+* Initial release of the project

pom.xml

@@ -4,7 +4,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.tinkerpop</groupId>
     <artifactId>frames</artifactId>
-    <version>0.5-SNAPSHOT</version>
+    <version>0.5</version>
     <packaging>jar</packaging>
     <url>http://frames.tinkerpop.com</url>
     <name>Frames: An Object to Graph Framework</name>
@@ -33,12 +33,12 @@
         <dependency>
             <groupId>com.tinkerpop.blueprints</groupId>
             <artifactId>blueprints-core</artifactId>
-            <version>1.0-SNAPSHOT</version>
+            <version>1.0</version>
         </dependency>
         <dependency>
             <groupId>com.tinkerpop</groupId>
             <artifactId>pipes</artifactId>
-            <version>0.8-SNAPSHOT</version>
+            <version>0.8</version>
         </dependency>
         <!-- TEST -->
         <dependency>
@@ -50,7 +50,7 @@
         <dependency>
             <groupId>com.tinkerpop.blueprints</groupId>
             <artifactId>blueprints-sail-graph</artifactId>
-            <version>1.0-SNAPSHOT</version>
+            <version>1.0</version>
             <scope>test</scope>
         </dependency>
     </dependencies>