com.bigdata.rdf.graph

Interface IGASState<VS,ES,ST>

Type Parameters:

VS - The generic type for the per-vertex state. This is scoped to the computation of the IGASProgram.

ES - The generic type for the per-edge state. This is scoped to the computation of the IGASProgram.

ST - The generic type for the SUM. This is often directly related to the generic type for the per-edge state, but that is not always true. The SUM type is scoped to the GATHER + SUM operation (NOT the computation).

All Known Implementing Classes:

BigdataGASState, GASState

public interface IGASState<VS,ES,ST>

Interface exposes access to the VS and ES that is visible during a GATHER or SCATTER operation.

This interface is intended to be restrictive in both its API and the state that the API will expose in order to facilitate scaling in multi-machine environments.

A concrete implementation of this interface for a cluster WILL ONLY provide O(1) access to vertices whose state has not been materialized on a given node by a GATHER or SCATTER. State for vertices that were not materialized will not be accessible.

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
org.openrdf.model.Value	asValue(org.openrdf.model.Value value) Convert a value into an appropriate internal form.
int	compareTo(org.openrdf.model.Value u, org.openrdf.model.Value v) Return -1, o, or 1 if u is LT, EQ, or GT v.
org.openrdf.model.Statement	decodeStatement(org.openrdf.model.Value v) If the vertex is actually an edge, then return the decoded edge.
void	endRound() End the current round, advance the round counter, and compact the new frontier.
IStaticFrontier	frontier() The current frontier.
org.openrdf.model.Literal	getLinkAttr(org.openrdf.model.Value u, org.openrdf.model.Statement e) Return the link attribute, if there is one.
org.openrdf.model.Value	getOtherVertex(org.openrdf.model.Value u, org.openrdf.model.Statement e) Return the other end of a link.
IGASSchedulerImpl	getScheduler() Return the IGASSchedulerImpl.
ES	getState(org.openrdf.model.Statement e) Get the state for the edge using the appropriate factory.
VS	getState(org.openrdf.model.Value v) Get the state for the vertex using the appropriate factory.
boolean	isAttrib(org.openrdf.model.Statement e) Return true iff the given Statement models an property value for a vertex of the graph (Statements also model edges).
boolean	isEdge(org.openrdf.model.Statement e) Return true iff the given Statement models an edge that connects two vertices (Statements also model property values).
boolean	isLinkAttrib(org.openrdf.model.Statement e, org.openrdf.model.URI linkAttribType) Return true iff the statement models a link attribute having the specified link type.
boolean	isVisited(Set<org.openrdf.model.Value> v) Return true iff the specified vertices all have an associated vertex state object - this is interpreted as meaning that the vertex has been "visited".
boolean	isVisited(org.openrdf.model.Value v) Return true iff the specified vertex has an associated vertex state object - this is interpreted as meaning that the vertex has been "visited".
<T> T	reduce(IReducer<VS,ES,ST,T> op) Compute a reduction over the vertex state table (all vertices that have had their vertex state materialized).
void	reset() Discard computation state (the frontier, vertex state, and edge state) and reset the round counter.
void	retainAll(Set<org.openrdf.model.Value> retainSet) Retain only those vertices in the visited set that are found in the specified collection.
int	round() Return the current evaluation round (origin ZERO).
void	setFrontier(IGASContext<VS,ES,ST> ctx, org.openrdf.model.Value... v) reset() the computation state and populate the initial frontier.
String	toString(org.openrdf.model.Statement e) Return a useful representation of an edge (non-batch API, debug only).
void	traceState() Conditionally log various interesting information about the state of the computation.

Method Detail

setFrontier

void setFrontier(IGASContext<VS,ES,ST> ctx,
               org.openrdf.model.Value... v)

reset() the computation state and populate the initial frontier.

Parameters:

ctx - The execution context.

v - One or more vertices that will be included in the initial frontier.

Throws:

IllegalArgumentException - if no vertices are specified.

reset

void reset()

Discard computation state (the frontier, vertex state, and edge state) and reset the round counter.

Note: The graph is NOT part of the computation and is not discared by this method.

round

int round()

Return the current evaluation round (origin ZERO).

getState

VS getState(org.openrdf.model.Value v)

Get the state for the vertex using the appropriate factory. If this is the first visit for that vertex, then the state is initialized using the factory. Otherwise the existing state is returned.

Parameters:

v - The vertex.

Returns:

The state for that vertex.

See Also:

IGASOptions.getVertexStateFactory()

getState

ES getState(org.openrdf.model.Statement e)

Get the state for the edge using the appropriate factory. If this is the first visit for that vertex, then the state is initialized using the factory. Otherwise the existing state is returned.

Parameters:

v - The vertex.

Returns:

The state for that vertex.

See Also:

IGASOptions.getEdgeStateFactory()

isVisited

boolean isVisited(org.openrdf.model.Value v)

Return true iff the specified vertex has an associated vertex state object - this is interpreted as meaning that the vertex has been "visited".

Parameters:

v - The vertex.

Returns:

true iff there is vertex state associated with that vertex.

isVisited

boolean isVisited(Set<org.openrdf.model.Value> v)

Return true iff the specified vertices all have an associated vertex state object - this is interpreted as meaning that the vertex has been "visited".

Parameters:

v - The vertices.

Returns:

true iff there is vertex state associated with all specified vertices.

frontier

IStaticFrontier frontier()

The current frontier.

getScheduler

IGASSchedulerImpl getScheduler()

Return the IGASSchedulerImpl.

reduce

<T> T reduce(IReducer<VS,ES,ST,T> op)

Compute a reduction over the vertex state table (all vertices that have had their vertex state materialized).

Parameters:

op - The reduction operation.

Returns:

The reduction.

endRound

void endRound()

End the current round, advance the round counter, and compact the new frontier.

traceState

void traceState()

Conditionally log various interesting information about the state of the computation.

getOtherVertex

org.openrdf.model.Value getOtherVertex(org.openrdf.model.Value u,
                                     org.openrdf.model.Statement e)

Return the other end of a link.

Parameters:

u - One end of the link.

e - The link.

Returns:

The other end of the link.

getLinkAttr

org.openrdf.model.Literal getLinkAttr(org.openrdf.model.Value u,
                                    org.openrdf.model.Statement e)

Return the link attribute, if there is one.

Parameters:

u - One end of the link.

e - The link.

Returns:

The other end of the link.

toString

String toString(org.openrdf.model.Statement e)

Return a useful representation of an edge (non-batch API, debug only). This method is only required when the edge objects are internal database objects lacking fully materialized RDF Values. In this case, it will materialize the RDF Values and present a pleasant view of the edge. The materialization step is a random access, which is why this method is for debug only. Efficient, vectored mechanisms exist to materialize RDF Values for other purposes, e.g., when exporting a set of edges as as graph in a standard interchange syntax.

Parameters:

e - The edge.

Returns:

The representation of that edge.

isEdge

boolean isEdge(org.openrdf.model.Statement e)

Return true iff the given Statement models an edge that connects two vertices (Statements also model property values).

Parameters:

e - The statement.

Returns:

true iff that Statement is an edge of the graph.

isAttrib

boolean isAttrib(org.openrdf.model.Statement e)

Return true iff the given Statement models an property value for a vertex of the graph (Statements also model edges).

Parameters:

e - The statement.

Returns:

true iff that Statement is an edge of the graph.

isLinkAttrib

boolean isLinkAttrib(org.openrdf.model.Statement e,
                   org.openrdf.model.URI linkAttribType)

Return true iff the statement models a link attribute having the specified link type. When this method returns true, the Statement.getSubject() may be decoded to obtain the link described by that link attribute using decodeStatement(Value).

Parameters:

e - The statement.

linkAttribType - The type for the link attribute.

Returns:

true iff the statement is an instance of a link attribute for the specified link type.

decodeStatement

org.openrdf.model.Statement decodeStatement(org.openrdf.model.Value v)

If the vertex is actually an edge, then return the decoded edge.

Note: A vertex may be an edge. A link attribute is modeled by treating the link as a vertex and then asserting a property value about that "link vertex". For bigdata, this is handled efficiently as inline statements about statements. This approach subsumes the property graph model (property graphs do not permit recursive nesting of these relationships) and is 100% consistent with RDF reification, except that the link attributes are modeled efficiently inline with the links. This is what we call Reification Done Right .

Parameters:

v - The vertex.

Returns:

The edge decoded from that vertex and null iff the vertex is not an edge.

See Also:

Reification Done Right , RDF GAS API

compareTo

int compareTo(org.openrdf.model.Value u,
            org.openrdf.model.Value v)

Return -1, o, or 1 if u is LT, EQ, or GT v. A number of GAS programs depend on the ability to place an order over the vertex identifiers, as does 2D partitioning. The ordering provided by this method MAY be arbitrary, but it MUST be total and stable across the life-cycle of the GAS program evaluation.

Parameters:

u - A vertex.

v - Another vertex.

retainAll

void retainAll(Set<org.openrdf.model.Value> retainSet)

Retain only those vertices in the visited set that are found in the specified collection.

Parameters:

retainSet - The set of vertices to be retained.

asValue

org.openrdf.model.Value asValue(org.openrdf.model.Value value)

Convert a value into an appropriate internal form.

Parameters:

value - The value.

Returns:

The internal form and null if the argument is null.