Added P.typeOf() predicate, which recognized a new set of GType enum token, String as registered in the GlobalTypeCache, as well as Class in Java/Groovy usage. (#3211)

https://issues.apache.org/jira/browse/TINKERPOP-2234

Author: xiazcy

CHANGELOG.asciidoc

@@ -91,6 +91,8 @@ This release also includes changes from <<release-3-7-XXX, 3.7.XXX>>.
 * Deprecated `ProcessLimitedStandardSuite` and `ProcessLimitedComputerSuite` in favor of `ProcessEmbeddedStandardSuite` and `ProcessEmbeddedComputerSuite` respectively.
 * Deprecated `ProcessStandardSuite` and the `ProcessComputerSuite` in favor of Gherkin testing and the `ProcessEmbeddedStandardSuite` and `ProcessEmbeddedComputerSuite` for testing JVM-specific Gremlin behaviors.
 * Removed lambda oriented Gremlin testing from Gherkin test suite.
+* Implemented `P.typeOf()` predicate.
+* Added `GType` enum to denote types.
 * Removed `P.getOriginalValue()` in favor of `P.getValue()`.
 * Simplified comparability semantics from ternary boolean logic to binary logic.
 * Introduced `NotP` class for negation of `P`.

docs/src/dev/provider/gremlin-semantics.asciidoc

@@ -337,6 +337,35 @@ for providers to decide how to handle this in their implementation. The referenc
 equivalent keys to appear in a map (e.g. `1` and `1.0` can both be keys in the same map), but when comparing maps we
 treat pairwise entries with semantically equivalent keys as the same.
 
+==== Comparability of Types
+
+The `P.typeOf()` predicate enables type-based filtering in TinkerPop using inheritance-aware comparison, where a value
+matches if it is the specified type or any of its subtypes.
+
+===== GType Enums
+
+Based on the support type space, we have defined a `GType` enum, which contains a set of enumerations that is used for
+type casting (`asNumber()`) and comparison (`P.typeOf()`) operations.
+
+* **Numeric types**: `INT`, `LONG`, `DOUBLE`, `FLOAT`, `BYTE`, `SHORT`, `BIGDECIMAL`, `BIGINT`
+* **General types**: `STRING`, `BOOLEAN`, `CHAR`, `UUID`, `BINARY`
+* **Collection types**: `LIST`, `SET`, `MAP`
+* **Graph types**: `VERTEX`, `EDGE`, `PROPERTY`, `VPROPERTY`, `PATH`, `TREE`, `GRAPH`
+* **Temporal types**: `DATETIME`, `DURATION`
+* **Special types**: `NULL`, `NUMBER` (supertype for all numeric types)
+
+===== GlobalTypeCache
+
+Providers can register custom types outside the TinkerPop type space using the `GlobalTypeCache`, making them available
+for `P.typeOf(String)` filtering. Unregistered string inputs will throw an `IllegalArgumentException`.
+
+The `registerDataType()` method registers the class's simple name by default, or accepts a custom string name. Providers
+should use PascalCase following Java conventions and prefix type names to avoid conflicts
+(e.g., `ProviderPrefix:SimpleTypeName`).
+
+Do note that the type cache only enables type recognition for filtering. Custom types still require separate
+serialization support - clients without custom serializers cannot deserialize these types.
+
 [[gremlin-semantics-orderability]]
 === Orderability
 
@@ -776,7 +805,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asDate-step[reference]
 
 *Description:* converts the incoming traverser to the nearest parsable type if no argument is provided, or to the desired numerical type, based on the number token (`N`) provided.
 
-*Syntax:* `asNumber()` | `asNumber(N numberToken)`
+*Syntax:* `asNumber()` | `asNumber(GType typeToken)`
 
 [width="100%",options="header"]
 |=========================================================
@@ -786,7 +815,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asDate-step[reference]
 
 *Arguments:*
 
-* `numberToken` - The enum `N` to denote the desired type to parse/cast to.
+* `typeToken` - The enum `GType` to denote the desired type to parse/cast to.
 
 If no type token is provided, the incoming number remains unchanged.
 
@@ -795,6 +824,7 @@ If no type token is provided, the incoming number remains unchanged.
 * If any overflow occurs during narrowing of types, then an `ArithmeticException` will be thrown.
 * If the incoming string cannot be parsed into a valid number format, then a `NumberFormatException` will be thrown.
 * If the incoming traverser is a non-String/Number (including `null`) value then an `IllegalArgumentException` will be thrown.
+* If the supplied type token is not a number type, then an `IllegalArgumentException` will be thrown.
 
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsNumberStep.java[source],
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asNumber-step[reference]

docs/src/reference/gremlin-variants.asciidoc

@@ -1369,6 +1369,42 @@ java -cp target/run-examples-shaded.jar examples.BasicGremlin
 java -cp target/run-examples-shaded.jar examples.ModernTraversals
 ----
 
+[[gremlin-java-differences]]
+=== Differences
+
+Gremlin-Java provides additional syntactic sugar that leverages Java's type system for the `P.typeOf()` predicate,
+which accepts Java `Class` objects directly, providing a more natural way to perform type checking:
+
+[gremlin-groovy,modern]
+----
+// Java-specific syntax using Class objects
+g.V().values("age").is(P.typeOf(Integer.class))
+g.V().values("name").is(P.typeOf(String.class))
+
+// Further simplification with Groovy sugar syntax
+g.E().has("weight", P.typeOf(Double))
+----
+
+This is equivalent to using `GType` enums. Other Gremlin language variants must use the canonical `GType` enum approach:
+
+[gremlin-groovy,modern]
+----
+// Canonical syntax available in all languages
+g.V().values("age").is(P.typeOf(GType.INT))
+g.V().values("name").is(P.typeOf(GType.STRING))
+----
+
+Any valid Java class accepted in the Console and with embedded Java is also accepted by `P.typeOf()`, as they are not
+restricted by the grammar or serialization.
+[gremlin-groovy,modern]
+----
+// Using java.awt.Color for example
+gremlin> g.inject(java.awt.Color.red)
+==>java.awt.Color[r=255,g=0,b=0]
+gremlin> g.inject(java.awt.Color.red, "hi", 123).is(P.typeOf(java.awt.Color))
+==>java.awt.Color[r=255,g=0,b=0]
+----
+
 [[gremlin-javascript]]
 == Gremlin-JavaScript
 

docs/src/reference/the-traversal.asciidoc

@@ -854,7 +854,7 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre
 === AsNumber Step
 
 The `asNumber()`-step (*map*) converts the incoming traverser to the nearest parsable type if no argument is provided,
-or to the desired numerical type, based on the number token (`N`) provided.
+or to the desired numerical type, based on the type token (`GType`) provided. If a type token entered isn't a numerical type, an `IllegalArgumentException` will be thrown.
 
 Numerical input will pass through unless a type is specified by the number token. `ArithmeticException` will be thrown
 for any overflow during narrowing of types.
@@ -868,17 +868,13 @@ All other input types will result in `IllegalArgumentException`.
 [gremlin-groovy,modern]
 ----
 g.inject(1234).asNumber() <1>
-g.inject(1.76).asNumber() <2>
-g.inject(1.76).asNumber(N.int_) <3>
-g.inject("1b").asNumber() <4>
-g.inject(33550336).asNumber(N.byte_) <5>
+g.inject(1.76d).asNumber() <2>
+g.inject(1.76d).asNumber(GType.INT) <3>
 ----
 
 <1> An int will be passed through.
 <2> A double will be passed through.
 <3> A double is converted into an int.
-<4> String containing any character other than numerical ones will result in `NumberFormatException`.
-<5> Narrowing of int to byte that overflows will throw `ArithmeticException`.
 
 [NOTE, caption=Java]
 ====
@@ -5477,12 +5473,8 @@ a comparatively slow script compilation, which makes parameterization essential
 [[a-note-on-predicates]]
 == A Note on Predicates
 
-A `P` is a predicate of the form `Function<Object,Boolean>`. That is, given some object, return true or false. As of
-the release of TinkerPop 3.4.0, Gremlin also supports simple text predicates, which only work on `String` values. The `TextP`
-text predicates extend the `P` predicates, but are specialized in that they are of the form `Function<String,Boolean>`.
-The provided predicates are outlined in the table below and are used in various steps such as <<has-step,`has()`>>-step,
-<<where-step,`where()`>>-step, <<is-step,`is()`>>-step, etc. Two new additional `TextP` predicate members were added in the
-TinkerPop 3.6.0 release that allow working with regular expressions. These are `TextP.regex` and `TextP.notRegex`
+A `P` is a predicate of the form `Function<Object,Boolean>`. That is, given some object, return true or false. Gremlin
+supports text predicates (`TextP`), which are specialized predicates that only work on String values and are of the form `Function<String,Boolean>`. Additionally, type predicate (`P.typeOf`) supports filtering traversers based on their runtime types. The provided predicates are outlined in the table below and are used in various steps such as <<has-step,`has()`>>-step, <<where-step,`where()`>>-step, <<is-step,`is()`>>-step, etc.
 
 [width="100%",cols="3,15",options="header"]
 |=========================================================
@@ -5498,6 +5490,8 @@ TinkerPop 3.6.0 release that allow working with regular expressions. These are `
 | `P.between(number,number)` | Is the incoming number greater than or equal to the first provided number and less than the second?
 | `P.within(objects...)` | Is the incoming object in the array of provided objects?
 | `P.without(objects...)` | Is the incoming object not in the array of the provided objects?
+| `P.typeOf(GType)` | Is the incoming object of the type indicated by the provided `GType` token?
+| `P.typeOf(string)` | Is the incoming object of the type indicated by the provided `String`?
 | `TextP.startingWith(string)` | Does the incoming `String` start with the provided `String`?
 | `TextP.endingWith(string)` | Does the incoming `String` end with the provided `String`?
 | `TextP.containing(string)` | Does the incoming `String` contain the provided `String`?
@@ -5555,6 +5549,69 @@ g.V().as('a').both().both().as('b').count()
 g.V().as('a').both().both().as('b').where('a',neq('b')).count()
 ----
 
+[[a-note-on-types]]
+== A Note on Types
+
+Gremlin steps typically operate over a handful of types that are mostly standard across graph systems. There are the
+common numeric types like `Integer`, `Long`, `Double`, general types like `String`, and `Boolean`, container types like
+`List`, `Set`, and `Map`, and structural types particular to graphs such as `Vertex`, `Edge`, and `Property`. During
+traversal execution, it's common to encounter mixed data types, especially when extracting values from multiple
+properties or when working with heterogeneous data that may have been stored inconsistently over time.
+
+Gremlin identifies these types in the `GType` enumeration, offering a clear presentation of the standard data types one
+might typically encounter with Gremlin. This enumeration is an important part of the Gremlin language in that it acts
+as the argument to the `typeOf()` predicate used for filtering values based on their runtime data type.
+
+[[gtype-enum]]
+=== GType Enums
+
+`GType` consists of the following enumerations:
+
+* **Numeric types**: `INT`, `LONG`, `DOUBLE`, `FLOAT`, `BYTE`, `SHORT`, `BIGDECIMAL`, `BIGINT`
+* **General types**: `STRING`, `BOOLEAN`, `CHAR`, `UUID`, `BINARY`
+* **Collection types**: `LIST`, `SET`, `MAP`
+* **Graph types**: `VERTEX`, `EDGE`, `PROPERTY`, `VPROPERTY`, `PATH`, `TREE`, `GRAPH`
+* **Temporal types**: `DATETIME`, `DURATION`
+* **Special types**: `NULL`, `NUMBER` (supertype for all numeric types)
+
+As mentioned, the `typeOf()` predicate becomes particularly useful when dealing with mixed data scenarios. For example,
+you would like to only return the integer values of a set of properties for further processing:
+
+[gremlin-groovy,modern]
+----
+g.V().values('age','name').is(P.typeOf(GType.INT)).asNumber(GType.SHORT)
+----
+
+The `NUMBER` type allows for broader type-based filtering without needing to specify each individual numeric type:
+
+[gremlin-groovy,modern]
+----
+g.union(V(), E()).values().is(P.typeOf(GType.NUMBER))
+----
+
+Type filtering is also valuable when working with traversals that return mixed graph elements. For example, when a
+traversal might return both vertices and edges, you can add filter or condition based on the elements of interest:
+
+[gremlin-groovy,modern]
+----
+g.V().outE().inV().path().unfold().is(P.typeOf(GType.EDGE))
+g.V().outE().inV().path().unfold().choose(typeOf(VERTEX), values('name'), values('weight'))
+----
+
+[[global-type-cache]]
+=== GlobalTypeCache
+
+The `GlobalTypeCache` stores custom types registered by database providers as string-to-class mappings. These registered
+type names can then be used with `P.typeOf()` for type filtering in the traversal. Consult your provider's documentation
+for the correct type names when using provider-specific types.
+
+By default, `GType` enumerations are registered using their simple class names and can be used as shown below.
+
+[gremlin-groovy,modern]
+----
+gremlin> g.V().values('age','name').is(P.typeOf('Integer'))
+----
+
 [[a-note-on-maps]]
 == A Note on Maps