net.xqhs.graphs.matchingPlatform
Interface GraphMatchingPlatform

All Known Implementing Classes:
GMPImplementation

public interface GraphMatchingPlatform

Implementations of this interface serve as platforms that handle on-demand matching of various graphs and patterns against a designated, 'principal' graph.

In order to not lose matches in case the graph changes too quickly, the matching works on a 'shadow' of the principal graph. Individual (or, if requested, sets of multiple) changes to the principal graph are recorded in individual TrackingGraph.Transaction instances (see TrackingGraph). At each call of incrementSequence() (or similar methods) the shadow graph applies the next transactions and gets closer to the current state of the principal graph. In this way, if an edge is added to the graph and then removed, at subsequent sequence increments, the list of matches will first not contain the matches of the edge, then it will, and then it will not.

Author:
Andrei Olaru

Nested Class Summary
static interface GraphMatchingPlatform.PlatformPrincipalGraph
          Interface for graphs that are principal graphs of a platform.
static interface GraphMatchingPlatform.PlatformShadowGraph
          Interface for graphs that are shadows of a master graph (most likely the platform principal graph).
 
Method Summary
 GraphMatchingPlatform addPattern(GraphPattern pattern)
          Adds a new pattern to the platform.
 int getGraphSequence()
          Retrieves the sequence of the last change to the principal graph.
 GraphMatchingProcess getMatcherAgainstGraph(GraphPattern pattern)
          Retrieves a GraphMatchingPlatform for the specified pattern and the current sequence of the principal graph (not the matching sequence).
 java.util.Set<Match> getMatches(GraphPattern pattern, int maxK)
          Builds and returns the matches between the specified pattern and the principal graph (as it is in the current matching sequence).
 int getMathingSequence()
          Retrieves the current 'matching sequence', which is incremented by incrementSequence().
 java.util.Collection<GraphPattern> getPatterns()
           
 GraphMatchingPlatform.PlatformPrincipalGraph getPrincipalGraph()
          Retrieves the principal graph of the platform.
 java.util.Set<Match> incrementSequence()
          Builds and returns the full matches between the patterns and the principal graph with the next set of operations (transaction) applied, moving the matching sequence one step closer to the graph sequence.
 java.util.List<java.util.Map.Entry<java.lang.Integer,java.util.Set<Match>>> incrementSequence(int targetSequence)
          Applies incrementSequence() until the matching process (matching sequence) reaches desired sequence of the principal graph.
 java.util.List<java.util.Map.Entry<java.lang.Integer,java.util.Set<Match>>> incrementSequenceFastForward()
          Applies incrementSequence() until the matching process is synchronized with the principal graph.
 GraphMatchingPlatform removePattern(GraphPattern pattern)
          Removes a pattern from the platform.
 GraphMatchingPlatform setPrincipalGraph(GraphMatchingPlatform.PlatformPrincipalGraph graph)
          Sets the principal graph of the platform.
 

Method Detail

setPrincipalGraph

GraphMatchingPlatform setPrincipalGraph(GraphMatchingPlatform.PlatformPrincipalGraph graph)
Sets the principal graph of the platform.

If another graph was previously set, all old data is cleared and patterns are re-added to match the new graph.

Parameters:
graph - - the graph, as a GraphMatchingPlatform.PlatformPrincipalGraph.
Returns:
the platform itself.

getPrincipalGraph

GraphMatchingPlatform.PlatformPrincipalGraph getPrincipalGraph()
Retrieves the principal graph of the platform.

Returns:
the graph.

addPattern

GraphMatchingPlatform addPattern(GraphPattern pattern)
Adds a new pattern to the platform. Further match retrievals will also contain matches between this new pattern and the principal graph.

Parameters:
pattern - - the GraphPattern to add.
Returns:
the platform itself.

removePattern

GraphMatchingPlatform removePattern(GraphPattern pattern)
Removes a pattern from the platform. All data related to the pattern is removed.

Parameters:
pattern - - the GraphPattern to remove.
Returns:
the platform itself.

getPatterns

java.util.Collection<GraphPattern> getPatterns()
Returns:
a Collection of existing patterns in the platform. May be an unmodifiable or immutable list.

incrementSequence

java.util.Set<Match> incrementSequence()
Builds and returns the full matches between the patterns and the principal graph with the next set of operations (transaction) applied, moving the matching sequence one step closer to the graph sequence.

If the matching process was already synchronized with the principal graph, null is returned.

Returns:
full matches for the newly incremented sequence, or null if the sequence cannot be incremented.

incrementSequence

java.util.List<java.util.Map.Entry<java.lang.Integer,java.util.Set<Match>>> incrementSequence(int targetSequence)
Applies incrementSequence() until the matching process (matching sequence) reaches desired sequence of the principal graph. For each incremented sequence, the corresponding complete list of full matches is returned.

If the matching process was already synchronized with the principal graph, an empty list is returned.

Parameters:
targetSequence - - the desired sequence to reach.
Returns:
a list of pairs with the sequence as key and the list of full matches existing in that sequence, as value; the empty list if there is nowhere to increment.

incrementSequenceFastForward

java.util.List<java.util.Map.Entry<java.lang.Integer,java.util.Set<Match>>> incrementSequenceFastForward()
Applies incrementSequence() until the matching process is synchronized with the principal graph.

If the matching process was already synchronized with the principal graph, an empty list is returned.

Returns:
a list of pairs with the sequence as key and the list of full matches existing in that sequence, as value; the empty list if there is nowhere to increment.

getMatches

java.util.Set<Match> getMatches(GraphPattern pattern,
                                int maxK)
Builds and returns the matches between the specified pattern and the principal graph (as it is in the current matching sequence). Only the matches with k between 0 and maxK (inclusive) are returned.

Parameters:
pattern - - the pattern for which to get the matches.
maxK - - the maximum k for retrieved matches.
Returns:
the set of matches between the pattern and the current matching sequence of the graph.
Throws:
java.lang.IllegalArgumentException - if the pattern has not been added to the platform.

getMathingSequence

int getMathingSequence()
Retrieves the current 'matching sequence', which is incremented by incrementSequence().

Returns:
the matching sequence.

getGraphSequence

int getGraphSequence()
Retrieves the sequence of the last change to the principal graph.

Returns:
the graph sequence.

getMatcherAgainstGraph

GraphMatchingProcess getMatcherAgainstGraph(GraphPattern pattern)
Retrieves a GraphMatchingPlatform for the specified pattern and the current sequence of the principal graph (not the matching sequence). Matching is done against a shadow of the principal graph. Any subsequent changes to the principal graph will not be visible in the matching process.

Except for the snapshot of the principal graph, this method uses no resources of the platform. The return matching process is independent of the platform's patterns and matching processes.

Parameters:
pattern - - the pattern to match (can also be a normal graph).
Returns:
the matching process.