Core Annotations

Bryn Cooke edited this page Jul 7, 2013 · 11 revisions

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, is, can, 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.

Annotations valid on all frames (VertexFrame and EdgeFrame):

annotation method prefix arguments description example
@Property get,is,can 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")

Annotations valid on vertices (VertexFrame):

annotation method prefix arguments description example
@Adjacency get label, direction get the vertex or vertices X related to the vertex @Adjacency(label="X", direction=Direction.OUT)
@Adjacency set label, direction set the vertex or vertices X related to the vertex @Adjacency(label="X", direction=Direction.OUT)
@Adjacency add label, direction add a vertex X related to the vertex and return the vertex X @Adjacency(label="X", direction=Direction.OUT)
@Adjacency remove label, direction remove a vertex X related to the vertex @Adjacency(label="X", direction=Direction.OUT)
@Incidence get label, direction get the edges X related to the vertex @Incidence(label="X", direction=Direction.OUT)
@Incidence add label, direction add an edge X related to the vertex and return the edge X @Incidence(label="X", direction=Direction.OUT)
@Incidence remove label, direction remove an edge X related to the vertex @Incidence(label="X", direction=Direction.OUT)

Note that “get” and “set” methods for @Adjacency can be either single-valued or Iterable-valued. For example:

public interface Person {
    @Adjacency(label = "spouse")
    Person getSpouse();
    
    @Adjacency(label = "spouse")
    void setSpouse(Person spouse);
    
    @Adjacency(label = "child")
    Iterable<Person> getChildren();
    
    @Adjacency(label = "child")
    void setChildren(Iterable<Person> children);
}

The above interface uses both styles of getter and setter: an Iterable-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.

“add” methods for @Adjacency can be either single-valued or no-valued For example:

public interface Person {
    @Adjacency(label = "friend")
    Person addFriend(); //Returns a new vertex of type friend

    @Adjacency(label = "friend")
    Person addFriend(Person friend); //Add an existing person as a friend
}

Annotations valid on edges (EdgeFrame):

annotation method prefix arguments description example
@InVertex get none get the in-vertex. This is equivalent to calling Edge.getVertex(Direction.IN) @InVertex
@OutVertex get none get the out-vertex. This is equivalent to calling Edge.getVertex(Direction.OUT) @OutVertex
@Domain get none get the out-vertex of the edge when the frame was created with direction parameter Direction.OUT, otherwise get the in-vertex of the edge @Domain
@Range get none get the out-vertex of the edge when the frame was created with direction parameter Direction.IN, otherwise get the in-vertex of the edge @Range

Please note: @Domain and @Range are deprecated. You should use @InVertex and @OutVertex

The use of @Domain and @Range on an EdgeFrame created by an @Incidence annotation, has the following characteristics: The Incidence.direction parameter of the annotation is used for both the edge direction and for determining the @Domain and @Range of the frame. Effectively with Direction.OUT the frame source and edge source are equal, with Direction.IN they are each others opposites. This means that when you want to put an @Incidence annotation on the vertices at both sides of the edge, you must create two EdgeFrame types e.g. Created and CreatedBy.