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

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.INVERSE)
  public Collection<Person> getCreatedByPerson();

  @Incidence(label = "created", direction = Direction.INVERSE)
  public Collection<CreatedBy> getCreatedBy();
}

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 adjacency by using inverting a created edge. In other words, the people who create a project are the people that the project was created by. Third, 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 adjacency is a EdgeFrame and thus, a wrapper to an edge.

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.