Package org.apache.tinkerpop.gremlin.process.traversal.step

Interface Scoping

All Superinterfaces:

PopContaining

All Known Implementing Classes:

AddEdgeStartStep, AddEdgeStep, AddPropertyStep, AddVertexStartStep, AddVertexStep, DedupGlobalStep, FormatStep, MatchStep, MatchStep.MatchEndStep, MatchStep.MatchStartStep, MathStep, SelectOneStep, SelectStep, TraversalSelectStep, WherePredicateStep, WhereTraversalStep, WhereTraversalStep.WhereEndStep, WhereTraversalStep.WhereStartStep

public interface Scoping
extends PopContaining

This interface is implemented by Step implementations that access labeled path steps, side-effects or Map values by key, such as select('a') step. Note that a step like project() is non-scoping because while it creates a Map it does not introspect them.

There are four types of scopes:

1. Current scope
— the current data referenced by the traverser (“path head”).
2. Path scope
— a particular piece of data in the path of the traverser (“path history”).
3. Side-effect scope
— a particular piece of data in the global traversal blackboard.
4. Map scope
— a particular piece of data in the current scope map (“map value by key”).

The current scope refers to the current object referenced by the traverser. That is, the traverser.get() object. Another way to think about the current scope is to think in terms of the path of the traverser where the current scope is the head of the path. With the math()-step, the variable _ refers to the current scope.

 
 gremlin> g.V().values("age").math("sin _")
 ==>-0.6636338842129675
 ==>0.956375928404503
 ==>0.5514266812416906
 ==>-0.428182669496151
 
 

The path scope refers to data previously seen by the traverser. That is, data in the traverser’s path history. Paths can be accessed by path(), however, individual parts of the path can be labeled using as() and accessed later via the path label name. Thus, in the traversal below, “a” and “b” refer to objects previously traversed by the traverser.

 
 gremlin> g.V().as("a").out("knows").as("b”).
 math("a / b").by("age")
 ==>1.0740740740740742
 ==>0.90625
 
 

The side-effect scope refers objects in the global side-effects of the traversal. Side-effects are not local to the traverser, but instead, global to the traversal. In the traversal below you can see how “x” is being referenced in the math()-step and thus, the side-effect data is being used.

 
 gremlin> g.withSideEffect("x",100).V().values("age").math("_ / x")
 ==>0.29
 ==>0.27
 ==>0.32
 ==>0.35
 
 

Map scope refers to objects within the current map object. Thus, its like current scope, but a bit “deeper.” In the traversal below the project()-step generates a map with keys “a” and “b”. The subsequent math()-step is then able to access the “a” and “b” values in the respective map and use them for the division operation.

 gremlin>
 g.V().hasLabel("person”).
 project("a","b”).
   by("age”).
   by(bothE().count()).
 math("a / b")
 ==>9.666666666666666
 ==>27.0
 ==>10.666666666666666
 ==>35.0
 
 

Scoping is all about variable data access and forms the fundamental interface for access to the memory structures of Gremlin.

Author:

Marko A. Rodriguez (http://markorodriguez.com), Stephen Mallette (http://stephen.genoprime.com)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Scoping.KeyNotFoundException
static class	Scoping.Variable

Nested classes/interfaces inherited from interface org.apache.tinkerpop.gremlin.process.traversal.step.PopContaining

PopContaining.PopInstruction

Method Summary

Modifier and Type	Method	Description
default <S> S	getNullableScopeValue(Pop pop, String key, Traverser.Admin<?> traverser)	Calls getScopeValue(Pop, Object, Traverser.Admin) and returns null if the key is not found.
default HashSet<PopContaining.PopInstruction>	getPopInstructions()	Used to get PopInstruction of a Step that implements Scoping.
default <S> S	getSafeScopeValue(Pop pop, Object key, Traverser.Admin<?> traverser)	Calls getScopeValue(Pop, Object, Traverser.Admin) but throws an unchecked IllegalStateException if the key cannot be found.
Set<String>	getScopeKeys()	Get the labels that this scoping step will access during the traversal
default <S> S	getScopeValue(Pop pop, Object key, Traverser.Admin<?> traverser)	Finds the object with the specified key for the current traverser and throws an exception if the key cannot be found.

Method Detail

getScopeValue

default <S> S getScopeValue(Pop pop,
                            Object key,
                            Traverser.Admin<?> traverser)
                     throws Scoping.KeyNotFoundException

Finds the object with the specified key for the current traverser and throws an exception if the key cannot be found.

Throws:

Scoping.KeyNotFoundException - if the key does not exist

getSafeScopeValue

default <S> S getSafeScopeValue(Pop pop,
                                Object key,
                                Traverser.Admin<?> traverser)

Calls getScopeValue(Pop, Object, Traverser.Admin) but throws an unchecked IllegalStateException if the key cannot be found.

getNullableScopeValue

default <S> S getNullableScopeValue(Pop pop,
                                    String key,
                                    Traverser.Admin<?> traverser)

Calls getScopeValue(Pop, Object, Traverser.Admin) and returns null if the key is not found. Use this method with caution as null has one of two meanings as a return value. It could be that the key was found and its value was null or it might mean that the key was not found and null was simply returned.

getScopeKeys

Set<String> getScopeKeys()

Get the labels that this scoping step will access during the traversal

Returns:

the accessed labels of the scoping step

getPopInstructions

default HashSet<PopContaining.PopInstruction> getPopInstructions()

Used to get PopInstruction of a Step that implements Scoping. PopInstruction includes the labels it needs, and the pop type for each label.

Specified by:

getPopInstructions in interface PopContaining

Returns:

A Set of PopContaining.PopInstruction values which contain the label and Pop value