Core Annotations

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.