com.sun.sgs.impl.service.nodemap.affinity.graph
Interface AffinityGraphBuilder

All Known Subinterfaces:

DLPAGraphBuilder

All Known Implementing Classes:

BipartiteGraphBuilder, DistGraphBuilder, DistGraphBuilderServerImpl, SingleGraphBuilder, WeightedGraphBuilder

public interface AffinityGraphBuilder

Graph builder interface. Graph builder objects take task access information and create a graph from it, and can return the graph. Builders are also responsible for instantiating the objects which will consume the graph.

The returned graph vertices are identities, and the edges are the object references the vertices have in common. Edge weights refer to the number of common references of all objects (e.g. if obj1 is used twice by both objects, the weight is 2. If both objects then use obj2, the weight becomes 3). Parallel edges are not supported.

Graphs are pruned as time goes by, both to ensure that endless resources are not consumed, and to ensure that while the graph contains enough history to be useful, it doesn't contain too much very old history.

The graphs contain only application information (no system service information) to limit the size of the graphs.

Graph builders are typically instantiated by the node GraphListener. In order to be instantiated by the GraphListener, they should implement a constructor taking the arguments (Properties, ComponentRegistry, TransactionProxy). The transaction proxy can be null for testing outside of the Darkstar service framework.

Method Summary

void	disable() Disables this builder.
void	enable() Enables this builder.
edu.uci.ics.jung.graph.UndirectedGraph<LabelVertex,WeightedEdge>	getAffinityGraph() Returns the current graph, with identities as vertices, and edges representing each object accessed by both identity endpoints.
LPAAffinityGroupFinder	getAffinityGroupFinder() Returns the affinity group finder created by this builder, or null if none was created.
LabelVertex	getVertex(Identity id) Gets the graph vertex for the given Identity.
void	shutdown() Shuts down this builder.
void	updateGraph(Identity owner, AccessedObjectsDetail detail) Update the graph based on the objects accessed in a task.

Method Detail

updateGraph

void updateGraph(Identity owner,
                 AccessedObjectsDetail detail)

Update the graph based on the objects accessed in a task. If the builder is disabled, does nothing.

Parameters:

owner - the task owner (the object making the accesses)

detail - detailed information about the object accesses, including a list of the accessed objects

Throws:

UnsupportedOperationException - if this builder cannot access the affinity graph. Typically, this occurs because the builder itself is distributed.

IllegalStateException - if the builder is shut down

getAffinityGraph

edu.uci.ics.jung.graph.UndirectedGraph<LabelVertex,WeightedEdge> getAffinityGraph()

Returns the current graph, with identities as vertices, and edges representing each object accessed by both identity endpoints. An empty graph will be returned if there is no affinity data collected.

The returned graph can not be modified.

Returns:

the graph of access information

Throws:

UnsupportedOperationException - if this builder cannot access the affinity graph. Typically, this occurs because the builder itself is distributed.

enable

void enable()

Enables this builder. Enabled builders can be disabled or shutdown. Multiple calls to enable are allowed.

Throws:

IllegalStateException - if the builder has been shut down

disable

void disable()

Disables this builder. Disabled builders can be enabled or shutdown. Multiple calls to disable are allowed.

While disabled, no new graph updates are applied, but the graph pruners continue to discard old data.

Throws:

IllegalStateException - if the builder has been shut down

shutdown

void shutdown()

Shuts down this builder. Once shut down, a builder cannot be enabled or disabled. Multiple calls to shutdown are allowed.

getVertex

LabelVertex getVertex(Identity id)

Gets the graph vertex for the given Identity.

Parameters:

id - an identity

Returns:

the graph vertex for the identity, or null if there is no such vertex

getAffinityGroupFinder

LPAAffinityGroupFinder getAffinityGroupFinder()

Returns the affinity group finder created by this builder, or null if none was created. Some algorithms only create the finder on the server node.

Returns:

the affinity group finder or null