Getting Started

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.

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();
  
  @Adjacency(label="knows")
  public Iterable<Person> getKnowsPeople();
  @Adjacency(label="knows")
  public void addKnowsPerson(Person person);
  
  @Adjacency(label="created")
  public Iterable<Project> getCreatedProjects();
  @Adjacency(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.

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 and is available as TinkerGraphFactory.createTinkerGraph().

To frame vertex 1 (marko) in terms of the Person interface defined previously, simply do the following.

Graph graph = TinkerGraphFactory.createTinkerGraph();
FramedGraphFactory factory = new FramedGraphFactory();
FramedGraph manager = factory.create(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.

marko.setAge(31)
assert marko.getName().equals("marko")
for(Person person : marko.getKnowsPeople()) {
  System.out.println(person.getName()); // prints vadas and josh
}

Adding a Few More Constructs

In the example graph, there are people and there are projects. Lets model a project as a Java interface.

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();

  @Adjacency(label="created", direction=Direction.IN)
  public Iterable<Person> getCreatedByPerson();

  @Incidence(label = "created", direction = Direction.IN)
  public Iterable<CreatedInfo> getCreatedInfo();
}

public interface CreatedInfo extends EdgeFrame {
    @Property("weight")
    public Float getWeight();
    @Property("weight")
    public void setWeight(float weight);

    @OutVertex
    Person getPerson();

    @InVertex
    Project getProject();
}

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, note that there is a difference between a Adjacency and an Incidence. An adjacency exists between two vertices. An incidence exists between a vertex and edge. An incidence is an EdgeFrame and thus, a wrapper to an edge. The frame class for the edge (CreatedInfo) has annotations to mark what the out-vertex (@OutVertex) and in-vertex (@InVertex) of the edge frame represent.

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.

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"

The full code for this simple domain is provided in the Frames test case available here.
There is more to Frames, but what has been presented are the basic constructs to help get you started.