Modified: tinkerpop/site/docs/3.2.3-SNAPSHOT/upgrade/index.html URL: http://svn.apache.org/viewvc/tinkerpop/site/docs/3.2.3-SNAPSHOT/upgrade/index.html?rev=1764947&r1=1764946&r2=1764947&view=diff ============================================================================== --- tinkerpop/site/docs/3.2.3-SNAPSHOT/upgrade/index.html (original) +++ tinkerpop/site/docs/3.2.3-SNAPSHOT/upgrade/index.html Fri Oct 14 17:34:29 2016 @@ -823,6 +823,252 @@ span.line-numbers { border-right: 1px so </li> </ul> </li> +<li><a href="#_tinkerpop_3_2_2">TinkerPop 3.2.2</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_2">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graphson_2_0">GraphSON 2.0</a></li> +<li><a href="#_log4j_dependencies">Log4j Dependencies</a></li> +<li><a href="#_default_for_gremlinpool">Default for gremlinPool</a></li> +<li><a href="#_new_console_features">New Console Features</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_2">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_system_providers_2">Graph System Providers</a></li> +<li><a href="#_drivers_providers">Drivers Providers</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_2_1">TinkerPop 3.2.1</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_3">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_gephi_plugin">Gephi Plugin</a></li> +<li><a href="#_gryomapper_construction">GryoMapper Construction</a></li> +<li><a href="#_traversalvertexprogram">TraversalVertexProgram</a></li> +<li><a href="#_interrupting_traversals">Interrupting Traversals</a></li> +<li><a href="#_gremlin_console_flags">Gremlin Console Flags</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_3">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_system_providers_3">Graph System Providers</a></li> +<li><a href="#_graph_database_providers">Graph Database Providers</a></li> +<li><a href="#_graph_language_providers">Graph Language Providers</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_2_0_2">TinkerPop 3.2.0</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_4">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_hadoop_filesystem_variable">Hadoop FileSystem Variable</a></li> +<li><a href="#_hadoop_configurations">Hadoop Configurations</a></li> +<li><a href="#_traversalsideeffects_update">TraversalSideEffects Update</a></li> +<li><a href="#_profilestep_update_and_graphtraversal_api_change">ProfileStep Update and GraphTraversal API Change</a></li> +<li><a href="#_branchstep_bug_fix">BranchStep Bug Fix</a></li> +<li><a href="#_memorycomputekey_and_vertexcomputekey">MemoryComputeKey and VertexComputeKey</a></li> +<li><a href="#_sparkgraphcomputer_and_giraphgraphcomputer_persistence">SparkGraphComputer and GiraphGraphComputer Persistence</a></li> +<li><a href="#_remotegraph">RemoteGraph</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_4">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_system_providers_4">Graph System Providers</a></li> +<li><a href="#_graph_processor_providers">Graph Processor Providers</a></li> +<li><a href="#_graph_language_providers_2">Graph Language Providers</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_1_0">TinkerPop 3.1.0</a></li> +<li> +<ul class="sectlevel1"> +<li><a href="#_tinkerpop_3_1_5">TinkerPop 3.1.5</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_5">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_java_driver_and_close">Java Driver and close()</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_1_4">TinkerPop 3.1.4</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_6">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_gremlin_server_workers">Gremlin Server Workers</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_1_3">TinkerPop 3.1.3</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_7">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_reserved_gremlin_server_keys">Reserved Gremlin Server Keys</a></li> +<li><a href="#_remote_timeout">Remote Timeout</a></li> +<li><a href="#_gremlin_server_workers_2">Gremlin Server Workers</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_5">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_database_providers_2">Graph Database Providers</a></li> +<li><a href="#_graph_language_providers_3">Graph Language Providers</a></li> +<li><a href="#_driver_providers">Driver Providers</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_1_2">TinkerPop 3.1.2</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_8">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_aliasing_sessions">Aliasing Sessions</a></li> +<li><a href="#_remote_console">Remote Console</a></li> +<li><a href="#_console_remote_sessions">Console Remote Sessions</a></li> +<li><a href="#_tinkerpop_archetypes">TinkerPop Archetypes</a></li> +<li><a href="#_session_transaction_management">Session Transaction Management</a></li> +<li><a href="#_session_timeout_setting">Session Timeout Setting</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_6">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_all_providers">All Providers</a></li> +<li><a href="#_graph_system_providers_5">Graph System Providers</a></li> +<li><a href="#_driver_providers_2">Driver Providers</a></li> +<li><a href="#_plugin_providers">Plugin Providers</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_1_1">TinkerPop 3.1.1</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_9">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_storage_i_o">Storage I/O</a></li> +<li><a href="#_gremlin_server_transaction_management">Gremlin Server Transaction Management</a></li> +<li><a href="#_deprecated_credentialsdblocation">Deprecated credentialsDbLocation</a></li> +<li><a href="#_tinkergraph_supports_any_i_o">TinkerGraph Supports Any I/O</a></li> +<li><a href="#_authenticator_method_deprecation">Authenticator Method Deprecation</a></li> +<li><a href="#_spark_persistence_updates">Spark Persistence Updates</a></li> +<li><a href="#_logging">Logging</a></li> +<li><a href="#_gremlin_server_sandboxing">Gremlin Server Sandboxing</a></li> +<li><a href="#_deprecated_supportsaddproperty">Deprecated supportsAddProperty()</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_7">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_system_providers_6">Graph System Providers</a></li> +<li><a href="#_graph_database_providers_3">Graph Database Providers</a></li> +<li><a href="#_graph_processor_providers_2">Graph Processor Providers</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_1_0_2">TinkerPop 3.1.0</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_10">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_shading_jackson">Shading Jackson</a></li> +<li><a href="#_partitionstrategy_and_vertexproperty">PartitionStrategy and VertexProperty</a></li> +<li><a href="#_gremlin_server_and_epoll">Gremlin Server and Epoll</a></li> +<li><a href="#_rebindings_deprecated">Rebindings Deprecated</a></li> +<li><a href="#_configurable_driver_channelizer">Configurable Driver Channelizer</a></li> +<li><a href="#_graphson_and_strict_option">GraphSON and Strict Option</a></li> +<li><a href="#_transaction_close_default_behavior">Transaction.close() Default Behavior</a></li> +<li><a href="#_threadlocal_transaction_settings">ThreadLocal Transaction Settings</a></li> +<li><a href="#_hadoop_gremlin">Hadoop-Gremlin</a></li> +<li><a href="#_spark_gremlin">Spark-Gremlin</a></li> +<li><a href="#_tinkergraph_serialization">TinkerGraph Serialization</a></li> +<li><a href="#_deprecation_in_tinkergraph">Deprecation in TinkerGraph</a></li> +<li><a href="#_deprecation_in_gremlin_groovy">Deprecation in Gremlin-Groovy</a></li> +<li><a href="#_gephi_traversal_visualization">Gephi Traversal Visualization</a></li> +<li><a href="#_alterations_to_graphtraversal">Alterations to GraphTraversal</a></li> +<li><a href="#_aliasing_remotes_in_the_console">Aliasing Remotes in the Console</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_8">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_system_providers_7">Graph System Providers</a></li> +<li><a href="#_driver_providers_3">Driver Providers</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_0_0">TinkerPop 3.0.0</a></li> +<li> +<ul class="sectlevel1"> +<li><a href="#_tinkerpop_3_0_2">TinkerPop 3.0.2</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_11">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_bulkloadervertexprogram_blvp">BulkLoaderVertexProgram (BLVP)</a></li> +<li><a href="#_tinkergraph">TinkerGraph</a></li> +<li><a href="#_gremlin_driver_and_server">Gremlin Driver and Server</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_9">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_driver_providers">Graph Driver Providers</a></li> +</ul> +</li> +</ul> +</li> +<li><a href="#_tinkerpop_3_0_1">TinkerPop 3.0.1</a></li> +<li> +<ul class="sectlevel2"> +<li><a href="#_upgrading_for_users_12">Upgrading for Users</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_gremlin_server">Gremlin Server</a></li> +<li><a href="#_neo4j">Neo4j</a></li> +</ul> +</li> +<li><a href="#_upgrading_for_providers_10">Upgrading for Providers</a></li> +<li> +<ul class="sectlevel3"> +<li><a href="#_graph_system_providers_8">Graph System Providers</a></li> +<li><a href="#_graph_driver_providers_2">Graph Driver Providers</a></li> +</ul> +</li> +</ul> +</li> </ul> </li> </ul> @@ -1085,1835 +1331,2409 @@ a <code>SubgraphStrategy</code>, it does <div class="listingblock"> <div class="content"> <pre class="CodeRay"><code class="python language-python">g = Graph().traversal().withRemote(connection). - withStrategies(SubgraphStrategy(vertices=__.hasLabel(<span class="string"><span class="delimiter">'</span><span class="content">person</span><span class="delimiter">'</span></span>),edges=__.has(<span class="string"><span class="delimiter">'</span><span class="content">weight</span><span class="delimiter">'</span></span>,gt(<span class="float">0.5</span>)))) ---- - -The `SubgraphStrategy.create(Configuration)`-method <span class="keyword">is</span> defined <span class="keyword">as</span>: - -[source,java]</code></pre> + withStrategies(SubgraphStrategy(vertices=__.hasLabel(<span class="string"><span class="delimiter">'</span><span class="content">person</span><span class="delimiter">'</span></span>),edges=__.has(<span class="string"><span class="delimiter">'</span><span class="content">weight</span><span class="delimiter">'</span></span>,gt(<span class="float">0.5</span>))))</code></pre> </div> </div> <div class="paragraph"> -<p>public static SubgraphStrategy create(final Configuration configuration) { - final Builder builder = SubgraphStrategy.build(); - if (configuration.containsKey(VERTICES)) - builder.verticesTraversal) configuration.getProperty(VERTICES; - if (configuration.containsKey(EDGES)) - builder.edgesTraversal) configuration.getProperty(EDGES; - if (configuration.containsKey(VERTEX_PROPERTIES)) - builder.vertexPropertiesTraversal) configuration.getProperty(VERTEX_PROPERTIES; - return builder.create(); -}</p> +<p>The <code>SubgraphStrategy.create(Configuration)</code>-method is defined as:</p> </div> <div class="listingblock"> <div class="content"> -<pre> -Finally, in order to make serialization possible from JVM-based Gremlin language variants, all strategies have a -`TraverserStrategy.getConfiguration()` method which returns a `Configuration` that can be used to `create()` the -`TraversalStrategy`. - -The `SubgraphStrategy.getConfiguration()`-method is defined as: - -[source,java]</pre> +<pre class="CodeRay"><code class="java language-java"><span class="directive">public</span> <span class="directive">static</span> SubgraphStrategy create(<span class="directive">final</span> <span class="predefined-type">Configuration</span> configuration) { + <span class="directive">final</span> Builder builder = SubgraphStrategy.build(); + <span class="keyword">if</span> (configuration.containsKey(VERTICES)) + builder.vertices((Traversal) configuration.getProperty(VERTICES)); + <span class="keyword">if</span> (configuration.containsKey(EDGES)) + builder.edges((Traversal) configuration.getProperty(EDGES)); + <span class="keyword">if</span> (configuration.containsKey(VERTEX_PROPERTIES)) + builder.vertexProperties((Traversal) configuration.getProperty(VERTEX_PROPERTIES)); + <span class="keyword">return</span> builder.create(); +}</code></pre> </div> </div> <div class="paragraph"> -<p>@Override -public Configuration getConfiguration() { - final Map<String, Object> map = new HashMap<>(); - map.put(STRATEGY, SubgraphStrategy.class.getCanonicalName()); - if (null != this.vertexCriterion) - map.put(VERTICES, this.vertexCriterion); - if (null != this.edgeCriterion) - map.put(EDGES, this.edgeCriterion); - if (null != this.vertexPropertyCriterion) - map.put(VERTEX_PROPERTIES, this.vertexPropertyCriterion); - return new MapConfiguration(map); -}</p> +<p>Finally, in order to make serialization possible from JVM-based Gremlin language variants, all strategies have a +<code>TraverserStrategy.getConfiguration()</code> method which returns a <code>Configuration</code> that can be used to <code>create()</code> the +<code>TraversalStrategy</code>.</p> +</div> +<div class="paragraph"> +<p>The <code>SubgraphStrategy.getConfiguration()</code>-method is defined as:</p> </div> <div class="listingblock"> <div class="content"> -<pre> -The default implementation of `TraversalStrategy.getConfiguration()` is defined as: - -[source,java]</pre> +<pre class="CodeRay"><code class="java language-java"><span class="annotation">@Override</span> +<span class="directive">public</span> <span class="predefined-type">Configuration</span> getConfiguration() { + <span class="directive">final</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">Object</span>> map = <span class="keyword">new</span> <span class="predefined-type">HashMap</span><>(); + map.put(STRATEGY, SubgraphStrategy.class.getCanonicalName()); + <span class="keyword">if</span> (<span class="predefined-constant">null</span> != <span class="local-variable">this</span>.vertexCriterion) + map.put(VERTICES, <span class="local-variable">this</span>.vertexCriterion); + <span class="keyword">if</span> (<span class="predefined-constant">null</span> != <span class="local-variable">this</span>.edgeCriterion) + map.put(EDGES, <span class="local-variable">this</span>.edgeCriterion); + <span class="keyword">if</span> (<span class="predefined-constant">null</span> != <span class="local-variable">this</span>.vertexPropertyCriterion) + map.put(VERTEX_PROPERTIES, <span class="local-variable">this</span>.vertexPropertyCriterion); + <span class="keyword">return</span> <span class="keyword">new</span> MapConfiguration(map); +}</code></pre> </div> </div> <div class="paragraph"> -<p>public default Configuration getConfiguration() { - return new BaseConfiguration(); -}</p> +<p>The default implementation of <code>TraversalStrategy.getConfiguration()</code> is defined as:</p> </div> <div class="listingblock"> <div class="content"> -<pre> -Thus, if the provider does not have any "builder"-based strategies, then no updates to their strategies are required. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1455[TINKERPOP-1455] - -Deprecated elementNotFound -++++++++++++++++++++++++++ - -Both `Graph.Exceptions.elementNotFound()` methods have been deprecated. These exceptions were being asserted in the -test suite but were not being used anywhere in `gremlin-core` itself. The assertions have been modified to simply -assert that `NoSuchElementException` was thrown, which is precisely the behavior that was being indirected asserted -when `Graph.Exceptions.elementNotFound()` were being used. - -Providers should not need to take any action in this case for their tests to pass, however, it would be wise to remove -uses of these exception builders as they will be removed in the future. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-944[TINKERPOP-944] - -Hidden Step Labels for Compilation Only -+++++++++++++++++++++++++++++++++++++++ - -In order for `SubgraphStrategy` to work, it was necessary to have multi-level children communicate with one another +<pre class="CodeRay"><code class="java language-java"><span class="directive">public</span> <span class="keyword">default</span> <span class="predefined-type">Configuration</span> getConfiguration() { + <span class="keyword">return</span> <span class="keyword">new</span> BaseConfiguration(); +}</code></pre> +</div> +</div> +<div class="paragraph"> +<p>Thus, if the provider does not have any "builder"-based strategies, then no updates to their strategies are required.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1455";>TINKERPOP-1455</a></p> +</div> +</div> +<div class="sect4"> +<h5 id="_deprecated_elementnotfound">Deprecated elementNotFound</h5> +<div class="paragraph"> +<p>Both <code>Graph.Exceptions.elementNotFound()</code> methods have been deprecated. These exceptions were being asserted in the +test suite but were not being used anywhere in <code>gremlin-core</code> itself. The assertions have been modified to simply +assert that <code>NoSuchElementException</code> was thrown, which is precisely the behavior that was being indirected asserted +when <code>Graph.Exceptions.elementNotFound()</code> were being used.</p> +</div> +<div class="paragraph"> +<p>Providers should not need to take any action in this case for their tests to pass, however, it would be wise to remove +uses of these exception builders as they will be removed in the future.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-944";>TINKERPOP-944</a></p> +</div> +</div> +<div class="sect4"> +<h5 id="_hidden_step_labels_for_compilation_only">Hidden Step Labels for Compilation Only</h5> +<div class="paragraph"> +<p>In order for <code>SubgraphStrategy</code> to work, it was necessary to have multi-level children communicate with one another via hidden step labels. It was decided that hidden step labels are for compilation purposes only and will be removed prior to traversal evaluation. This is a valid decision given that hidden labels for graph system providers are not allowed to be used by users. Likewise, hidden labels for steps should not be allowed be used by -users as well. - -PropertyMapStep with Selection Traversal -++++++++++++++++++++++++++++++++++++++++ - -`PropertyMapStep` now supports selection of properties via child property traversal. If a provider was relying solely -on the provided property keys in a `ProviderOptimizationStrategy`, they will need to check if there is a child traversal -and if so, use that in their introspection for respective strategies. This model was created to support `SubgraphStrategy.vertexProperties()` filtering. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1456[TINKERPOP-1456], -link:https://issues.apache.org/jira/browse/TINKERPOP-844[TINKERPOP-844] - -ConnectiveP Nesting Inlined -+++++++++++++++++++++++++++ - -There was a bug in `ConnectiveP` (`AndP`/`OrP`), where `eq(1).and(eq(2).and(eq(3)))` was `OrP(eq(1),AndP(eq(2),eq(3)))` -instead of unnested/inlined as `OrP(eq(1),eq(2),eq(3))`. Likewise, for `AndP`. If a provider was leveraging `ConnectiveP` +users as well.</p> +</div> +</div> +<div class="sect4"> +<h5 id="_propertymapstep_with_selection_traversal">PropertyMapStep with Selection Traversal</h5> +<div class="paragraph"> +<p><code>PropertyMapStep</code> now supports selection of properties via child property traversal. If a provider was relying solely +on the provided property keys in a <code>ProviderOptimizationStrategy</code>, they will need to check if there is a child traversal +and if so, use that in their introspection for respective strategies. This model was created to support <code>SubgraphStrategy.vertexProperties()</code> filtering.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1456";>TINKERPOP-1456</a>, +<a href="https://issues.apache.org/jira/browse/TINKERPOP-844";>TINKERPOP-844</a></p> +</div> +</div> +<div class="sect4"> +<h5 id="_connectivep_nesting_inlined">ConnectiveP Nesting Inlined</h5> +<div class="paragraph"> +<p>There was a bug in <code>ConnectiveP</code> (<code>AndP</code>/<code>OrP</code>), where <code>eq(1).and(eq(2).and(eq(3)))</code> was <code>OrP(eq(1),AndP(eq(2),eq(3)))</code> +instead of unnested/inlined as <code>OrP(eq(1),eq(2),eq(3))</code>. Likewise, for <code>AndP</code>. If a provider was leveraging <code>ConnectiveP</code> predicates for their custom steps (e.g. graph- or vertex-centric index lookups), then they should be aware of the inlining -and can simplify any and/or-tree walking code in their respective `ProviderOptimizationStrategy`. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1470[TINKERPOP-1470] - -TinkerPop 3.2.2 ---------------- - -*Release Date: September 6, 2016* - -Please see the link:https://github.com/apache/tinkerpop/blob/3.2.2/CHANGELOG.asciidoc#release-3-2-2[changelog] for a complete list of all the modifications that are part of this release. - -Upgrading for Users -~~~~~~~~~~~~~~~~~~~ - -GraphSON 2.0 -^^^^^^^^^^^^ - -GraphSON 2.0 has been introduced to improve and normalize the format of types embedded in GraphSON. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1274[TINKERPOP-1274], -link:http://tinkerpop.apache.org/docs/3.2.2/reference/#graphson-2-0-types[Reference Documentation - -GraphSON 2.0]. - -Log4j Dependencies -^^^^^^^^^^^^^^^^^^ - -There were a number of changes to the Log4j dependencies in the various modules. Log4j was formerly included as part -of the `slf4j-log4j12` in `gremlin-core`, however that "forced" use of Log4j as a logger implementation when that -really wasn't necessary or desired. If a project depended on `gremlin-core` or other TinkerPop project to get its -Log4j implementation then those applications will need to now include the dependency themselves directly. - -Note that Gremlin Server and Gremlin Console explicitly package Log4j in their respective binary distributions. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1151[TINKERPOP-1151] - -Default for gremlinPool -^^^^^^^^^^^^^^^^^^^^^^^ - -The `gremlinPool` setting in Gremlin Server is now defaulted to zero. When set to zero, Gremlin Server will use the -value provided by `Runtime.availableProcessors()` to set the pool size. Note that the packaged YAML files no longer +and can simplify any and/or-tree walking code in their respective <code>ProviderOptimizationStrategy</code>.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1470";>TINKERPOP-1470</a></p> +</div> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_tinkerpop_3_2_2">TinkerPop 3.2.2</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><strong>Release Date: September 6, 2016</strong></p> +</div> +<div class="paragraph"> +<p>Please see the <a href="https://github.com/apache/tinkerpop/blob/3.2.2/CHANGELOG.asciidoc#release-3-2-2";>changelog</a> for a complete list of all the modifications that are part of this release.</p> +</div> +<div class="sect2"> +<h3 id="_upgrading_for_users_2">Upgrading for Users</h3> +<div class="sect3"> +<h4 id="_graphson_2_0">GraphSON 2.0</h4> +<div class="paragraph"> +<p>GraphSON 2.0 has been introduced to improve and normalize the format of types embedded in GraphSON.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1274";>TINKERPOP-1274</a>, +<a href="http://tinkerpop.apache.org/docs/3.2.2/reference/#graphson-2-0-types";>Reference Documentation - +GraphSON 2.0</a>.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_log4j_dependencies">Log4j Dependencies</h4> +<div class="paragraph"> +<p>There were a number of changes to the Log4j dependencies in the various modules. Log4j was formerly included as part +of the <code>slf4j-log4j12</code> in <code>gremlin-core</code>, however that "forced" use of Log4j as a logger implementation when that +really wasn’t necessary or desired. If a project depended on <code>gremlin-core</code> or other TinkerPop project to get its +Log4j implementation then those applications will need to now include the dependency themselves directly.</p> +</div> +<div class="paragraph"> +<p>Note that Gremlin Server and Gremlin Console explicitly package Log4j in their respective binary distributions.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1151";>TINKERPOP-1151</a></p> +</div> +</div> +<div class="sect3"> +<h4 id="_default_for_gremlinpool">Default for gremlinPool</h4> +<div class="paragraph"> +<p>The <code>gremlinPool</code> setting in Gremlin Server is now defaulted to zero. When set to zero, Gremlin Server will use the +value provided by <code>Runtime.availableProcessors()</code> to set the pool size. Note that the packaged YAML files no longer contain the thread pool settings as all are now driven by sensible defaults. Obviously these values can be added -and overridden as needed. - -See: https://issues.apache.org/jira/browse/TINKERPOP-1373[TINKERPOP-1373] - -New Console Features -^^^^^^^^^^^^^^^^^^^^ - -The Gremlin Console can now have its text colorized. For example, you can set the color of the Gremlin ascii art to -the more natural color of green by using the `:set` command: - -[source,text] -gremlin> :set gremlin.color green - -It is also possible to colorize results, like vertices, edges, and other common returns. Please see the -link:http://tinkerpop.apache.org/docs/3.2.2/reference/#console-preferences[reference documentation] for more details -on all the settings. - -The console also now includes better multi-line support: - -[source,text]</pre> +and overridden as needed.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1373";>TINKERPOP-1373</a></p> </div> </div> +<div class="sect3"> +<h4 id="_new_console_features">New Console Features</h4> <div class="paragraph"> -<p>gremlin> g.V().out(). -……1> has(<em>name</em>,<em>josh</em>). -……2> out(<em>created</em>) -=⇒v[5] -=⇒v[3]</p> +<p>The Gremlin Console can now have its text colorized. For example, you can set the color of the Gremlin ascii art to +the more natural color of green by using the <code>:set</code> command:</p> </div> <div class="listingblock"> <div class="content"> -<pre> -This is a nice feature in that it can help you understand if a line is incomplete and unevaluated. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1285[TINKERPOP-1285], -link:https://issues.apache.org/jira/browse/TINKERPOP-1285[TINKERPOP-1037], -link:http://tinkerpop.apache.org/docs/3.2.2/reference/#console-preferences[Reference Documentation - -Console Preferences] - -Upgrading for Providers -~~~~~~~~~~~~~~~~~~~~~~~ - -Graph System Providers -^^^^^^^^^^^^^^^^^^^^^^ - -Deprecated Io.Builder.registry() -++++++++++++++++++++++++++++++++ - -The `Io.Builder.registry()` has been deprecated in favor of `Io.Builder.onMapper(Consumer<Mapper>)`. This change gives -the `Graph` implementation greater flexibility over how to modify the `Mapper` implementation. In most cases, the -implementation will simply add its `IoRegistry` to allow the `Mapper` access to custom serialization classes, but this -approach makes it possible to also set other specific settings that aren't generalized across all IO implementations. -A good example of this type of usage would be to provide a custom `ClassRessolver` implementation to a `GryoMapper`. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1402[TINKERPOP-1402] - -Log4j Dependencies -++++++++++++++++++ - -There were a number of changes to the Log4j dependencies in the various modules. Log4j was formerly included as part -of the `slf4j-log4j12` in `gremlin-core`, however that "forced" use of log4j as a logger implementation when that -really wasn't necessary or desired. The `slf4j-log4j12` dependency is now in "test" scope for most of the modules. The -exception to that rule is `gremlin-test` which prescribes it as "optional". That change means that developers -dependending on `gremlin-test` (or `gremlin-groovy-test`) will need to explicitly specify it as a dependency in their -`pom.xml` (or a different slf4j implementation if that better suits them). - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1151[TINKERPOP-1151] - -Drivers Providers -^^^^^^^^^^^^^^^^^ - -GraphSON 2.0 -++++++++++++ - -Drivers providers can exploit the new format of typed values JSON serialization offered by GraphSON 2.0. This format +<pre class="CodeRay"><code class="text language-text">gremlin> :set gremlin.color green</code></pre> +</div> +</div> +<div class="paragraph"> +<p>It is also possible to colorize results, like vertices, edges, and other common returns. Please see the +<a href="http://tinkerpop.apache.org/docs/3.2.2/reference/#console-preferences";>reference documentation</a> for more details +on all the settings.</p> +</div> +<div class="paragraph"> +<p>The console also now includes better multi-line support:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code class="text language-text">gremlin> g.V().out(). +......1> has('name','josh'). +......2> out('created') +==>v[5] +==>v[3]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>This is a nice feature in that it can help you understand if a line is incomplete and unevaluated.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1285";>TINKERPOP-1285</a>, +<a href="https://issues.apache.org/jira/browse/TINKERPOP-1285";>TINKERPOP-1037</a>, +<a href="http://tinkerpop.apache.org/docs/3.2.2/reference/#console-preferences";>Reference Documentation - +Console Preferences</a></p> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_upgrading_for_providers_2">Upgrading for Providers</h3> +<div class="sect3"> +<h4 id="_graph_system_providers_2">Graph System Providers</h4> +<div class="sect4"> +<h5 id="_deprecated_io_builder_registry">Deprecated Io.Builder.registry()</h5> +<div class="paragraph"> +<p>The <code>Io.Builder.registry()</code> has been deprecated in favor of <code>Io.Builder.onMapper(Consumer<Mapper>)</code>. This change gives +the <code>Graph</code> implementation greater flexibility over how to modify the <code>Mapper</code> implementation. In most cases, the +implementation will simply add its <code>IoRegistry</code> to allow the <code>Mapper</code> access to custom serialization classes, but this +approach makes it possible to also set other specific settings that aren’t generalized across all IO implementations. +A good example of this type of usage would be to provide a custom <code>ClassRessolver</code> implementation to a <code>GryoMapper</code>.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1402";>TINKERPOP-1402</a></p> +</div> +</div> +<div class="sect4"> +<h5 id="_log4j_dependencies_2">Log4j Dependencies</h5> +<div class="paragraph"> +<p>There were a number of changes to the Log4j dependencies in the various modules. Log4j was formerly included as part +of the <code>slf4j-log4j12</code> in <code>gremlin-core</code>, however that "forced" use of log4j as a logger implementation when that +really wasn’t necessary or desired. The <code>slf4j-log4j12</code> dependency is now in "test" scope for most of the modules. The +exception to that rule is <code>gremlin-test</code> which prescribes it as "optional". That change means that developers +dependending on <code>gremlin-test</code> (or <code>gremlin-groovy-test</code>) will need to explicitly specify it as a dependency in their +<code>pom.xml</code> (or a different slf4j implementation if that better suits them).</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1151";>TINKERPOP-1151</a></p> +</div> +</div> +</div> +<div class="sect3"> +<h4 id="_drivers_providers">Drivers Providers</h4> +<div class="sect4"> +<h5 id="_graphson_2_0_2">GraphSON 2.0</h5> +<div class="paragraph"> +<p>Drivers providers can exploit the new format of typed values JSON serialization offered by GraphSON 2.0. This format has been created to allow easy and agnostic parsing of a GraphSON payload without type loss. Drivers of non-Java -languages can then implement their own mapping of the GraphSON's language agnostic type IDs (e.g. `UUID`, `LocalDate`) -to the appropriate representation for the driver's language. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1274[TINKERPOP-1274], -link:http://tinkerpop.apache.org/docs/3.2.2/reference/#graphson-2.0-types[Reference Documentation - -GraphSON 2.0]. - -Traversal Serialization -+++++++++++++++++++++++ - -There was an "internal" serialization format in place for `Traversal` which allowed one to be submitted to Gremlin -Server directly over `RemoteGraph`. That format has been removed completely and is wholly replaced by the non-JVM -specific approach of serializing `Bytecode`. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1392[TINKERPOP-1392] - -TinkerPop 3.2.1 ---------------- - -*Release Date: July 18, 2016* - -Please see the link:https://github.com/apache/tinkerpop/blob/3.2.1/CHANGELOG.asciidoc#release-3-2-1[changelog] for a complete list of all the modifications that are part of this release. - -Upgrading for Users -~~~~~~~~~~~~~~~~~~~ - -Gephi Plugin -^^^^^^^^^^^^ - -The Gephi Plugin has been updated to support Gephi 0.9.x. Please upgrade to this latest version to use the Gephi Plugin -for Gremlin Console. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1297[TINKERPOP-1297] - -GryoMapper Construction -^^^^^^^^^^^^^^^^^^^^^^^ - -It is now possible to override existing serializers with calls to `addCustom` on the `GryoMapper` builder. This option +languages can then implement their own mapping of the GraphSON’s language agnostic type IDs (e.g. <code>UUID</code>, <code>LocalDate</code>) +to the appropriate representation for the driver’s language.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1274";>TINKERPOP-1274</a>, +<a href="http://tinkerpop.apache.org/docs/3.2.2/reference/#graphson-2.0-types";>Reference Documentation - +GraphSON 2.0</a>.</p> +</div> +</div> +<div class="sect4"> +<h5 id="_traversal_serialization">Traversal Serialization</h5> +<div class="paragraph"> +<p>There was an "internal" serialization format in place for <code>Traversal</code> which allowed one to be submitted to Gremlin +Server directly over <code>RemoteGraph</code>. That format has been removed completely and is wholly replaced by the non-JVM +specific approach of serializing <code>Bytecode</code>.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1392";>TINKERPOP-1392</a></p> +</div> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_tinkerpop_3_2_1">TinkerPop 3.2.1</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><strong>Release Date: July 18, 2016</strong></p> +</div> +<div class="paragraph"> +<p>Please see the <a href="https://github.com/apache/tinkerpop/blob/3.2.1/CHANGELOG.asciidoc#release-3-2-1";>changelog</a> for a complete list of all the modifications that are part of this release.</p> +</div> +<div class="sect2"> +<h3 id="_upgrading_for_users_3">Upgrading for Users</h3> +<div class="sect3"> +<h4 id="_gephi_plugin">Gephi Plugin</h4> +<div class="paragraph"> +<p>The Gephi Plugin has been updated to support Gephi 0.9.x. Please upgrade to this latest version to use the Gephi Plugin +for Gremlin Console.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1297";>TINKERPOP-1297</a></p> +</div> +</div> +<div class="sect3"> +<h4 id="_gryomapper_construction">GryoMapper Construction</h4> +<div class="paragraph"> +<p>It is now possible to override existing serializers with calls to <code>addCustom</code> on the <code>GryoMapper</code> builder. This option allows complete control over the serializers used by Gryo. Of course, this also makes it possible to produce completely -non-compliant Gryo files. This feature should be used with caution. - -TraversalVertexProgram -^^^^^^^^^^^^^^^^^^^^^^ - -`TraversalVertexProgram` always maintained a `HALTED_TRAVERSERS` `TraverserSet` for each vertex throughout the life +non-compliant Gryo files. This feature should be used with caution.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_traversalvertexprogram">TraversalVertexProgram</h4> +<div class="paragraph"> +<p><code>TraversalVertexProgram</code> always maintained a <code>HALTED_TRAVERSERS</code> <code>TraverserSet</code> for each vertex throughout the life of the OLAP computation. However, if there are no halted traversers in the set, then there is no point in keeping that -compute property around as without it, time and space can be saved. Users that have `VertexPrograms` that are chained off -of `TraversalVertexProgram` and have previously assumed that `HALTED_TRAVERSERS` always exists at each vertex, should no -longer assume that. - -[source,java] -// bad code -TraverserSet haltedTraversers = vertex.value(TraversalVertexProgram.HALTED_TRAVERSERS); -// good code -TraverserSet haltedTraversers = vertex.property(TraversalVertexProgram.HALTED_TRAVERSERS).orElse(new TraverserSet()); - -Interrupting Traversals -^^^^^^^^^^^^^^^^^^^^^^^ - -Traversals now better respect calls to `Thread.interrupt()`, which mean that a running `Traversal` can now be +compute property around as without it, time and space can be saved. Users that have <code>VertexPrograms</code> that are chained off +of <code>TraversalVertexProgram</code> and have previously assumed that <code>HALTED_TRAVERSERS</code> always exists at each vertex, should no +longer assume that.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code class="java language-java">TraverserSet haltedTraversers = vertex.value(TraversalVertexProgram.HALTED_TRAVERSERS); +<span class="comment">// good code</span> +TraverserSet haltedTraversers = vertex.property(TraversalVertexProgram.HALTED_TRAVERSERS).orElse(<span class="keyword">new</span> TraverserSet());</code></pre> +</div> +</div> +</div> +<div class="sect3"> +<h4 id="_interrupting_traversals">Interrupting Traversals</h4> +<div class="paragraph"> +<p>Traversals now better respect calls to <code>Thread.interrupt()</code>, which mean that a running <code>Traversal</code> can now be cancelled. There are some limitations that remain, but most OLTP-based traversals should cancel without issue. OLAP-based traversals for Spark will also cancel and clean up running jobs in Spark itself. Mileage may vary on other process implementations and it is possible that graph providers could potentially write custom step implementations that prevent interruption. If it is found that there are configurations or specific traversals that -do not respect interruption, please mention them on the mailing list. - -See: https://issues.apache.org/jira/browse/TINKERPOP-946[TINKERPOP-946] - -Gremlin Console Flags -^^^^^^^^^^^^^^^^^^^^^ - -Gremlin Console had several methods for executing scripts from file at the start-up of `bin/gremlin.sh`. There were -two options: - -[source,text] -bin/gremlin.sh script.groovy <b>(1)</b> -bin/gremlin.sh -e script.groovy <b>(2)</b> - -<1> The `script.groovy` would be executed as a console initialization script setting the console up for use and leaving -it open when the script completed successfully or closing it if the script failed. -<2> The `script.groovy` would be executed by the `ScriptExecutor` which meant that commands for the Gremlin Console, -such as `:remote` and `:>` would not be respected. - -Changes in this version of TinkerPop have added much more flexibility here and only a minor breaking change should be -considered when using this version. First of all, recognize that hese two lines are currently equivalent: - -[source,text] -bin/gremlin.sh script.groovy -bin/gremlin.sh -i script.groovy - -but users should start to explicitly specify the `-i` flag as TinkerPop will eventually remove the old syntax. Despite +do not respect interruption, please mention them on the mailing list.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-946";>TINKERPOP-946</a></p> +</div> +</div> +<div class="sect3"> +<h4 id="_gremlin_console_flags">Gremlin Console Flags</h4> +<div class="paragraph"> +<p>Gremlin Console had several methods for executing scripts from file at the start-up of <code>bin/gremlin.sh</code>. There were +two options:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code class="text language-text">bin/gremlin.sh script.groovy <b>(1)</b> +bin/gremlin.sh -e script.groovy <b>(2)</b></code></pre> +</div> +</div> +<div class="colist arabic"> +<ol> +<li> +<p>The <code>script.groovy</code> would be executed as a console initialization script setting the console up for use and leaving +it open when the script completed successfully or closing it if the script failed.</p> +</li> +<li> +<p>The <code>script.groovy</code> would be executed by the <code>ScriptExecutor</code> which meant that commands for the Gremlin Console, +such as <code>:remote</code> and <code>:></code> would not be respected.</p> +</li> +</ol> +</div> +<div class="paragraph"> +<p>Changes in this version of TinkerPop have added much more flexibility here and only a minor breaking change should be +considered when using this version. First of all, recognize that hese two lines are currently equivalent:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code class="text language-text">bin/gremlin.sh script.groovy +bin/gremlin.sh -i script.groovy</code></pre> +</div> +</div> +<div class="paragraph"> +<p>but users should start to explicitly specify the <code>-i</code> flag as TinkerPop will eventually remove the old syntax. Despite the one used beware of the fact that neither will close the console on script failure anymore. In that sense, this behavior represents a breaking change to consider. To ensure the console closes on failure or success, a script will -have to use the `-e` option. - -The console also has a number of new features in addition to `-e` and `-i`: - -* View the available flags for the console with `-h`. -* Control console output with `-D`, `-Q` and -`V` -* Get line numbers on script failures passed to `-i` and `-e`. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1268[TINKERPOP-1268], -link:https://issues.apache.org/jira/browse/TINKERPOP-1155[TINKERPOP-1155], link:https://issues.apache.org/jira/browse/TINKERPOP-1156[TINKERPOP-1156], -link:https://issues.apache.org/jira/browse/TINKERPOP-1157[TINKERPOP-1157], -link:http://tinkerpop.apache.org/docs/3.2.1/reference/#interactive-mode[Reference Documentation - Interactive Mode], -link:http://tinkerpop.apache.org/docs/3.2.1/reference/#execution-mode[Reference Documentation - Execution Mode] - -Upgrading for Providers -~~~~~~~~~~~~~~~~~~~~~~~ - -Graph System Providers -^^^^^^^^^^^^^^^^^^^^^^ - -VertexComputing API Change -++++++++++++++++++++++++++ - -The `VertexComputing` API is used by steps that wrap a `VertexProgram`. There is a method called -`VertexComputing.generateProgram()` that has changed which now takes a second argument of `Memory`. To upgrade, simply -fix the method signature of your `VertexComputing` implementations. The `Memory` argument can be safely ignored to -effect the exact same semantics as prior. However, now previous OLAP job `Memory` can be leveraged when constructing -the next `VertexProgram` in an OLAP traversal chain. - -Interrupting Traversals -+++++++++++++++++++++++ - -Several tests have been added to the TinkerPop test suite to validate that a `Traversal` can be cancelled with -`Thread.interrupt()`. The test suite does not cover all possible traversal scenarios. When implementing custom steps, -providers should take care to not ignore an `InterruptionException` that might be thrown in their code and to be sure -to check `Thread.isInterrupted()` as needed to ensure that the step remains cancellation compliant. - -See: https://issues.apache.org/jira/browse/TINKERPOP-946[TINKERPOP-946] - -Performance Tests -+++++++++++++++++ - -All "performance" tests have been deprecated. In the previous 3.2.0-incubating release, the `ProcessPerformanceSuite` -and `TraversalPerformanceTest` were deprecated, but some other tests remained. It is the remaining tests that have -been deprecated on this release: - -* `StructurePerformanceSuite -** `GraphReadPerformanceTest` -** `GraphWriterPerformanceTest` -* `GroovyEnvironmentPerformanceSuite` -** `SugarLoaderPerformanceTest` -** `GremlinExecutorPerformanceTest` -* Gremlin Server related performance tests -* TinkerGraph related performance tests - -Providers should implement their own performance tests and not rely on these deprecated tests as they will be removed -in a future release along with the "JUnit Benchmarks" dependency. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1294[TINKERPOP-1294] - -Graph Database Providers -^^^^^^^^^^^^^^^^^^^^^^^^ - -Transaction Tests -+++++++++++++++++ - -Tests and assertions were added to the structure test suite to validate that transaction status was in the appropriate -state following calls to close the transaction with `commit()` or `rollback()`. It is unlikely that this change would +have to use the <code>-e</code> option.</p> +</div> +<div class="paragraph"> +<p>The console also has a number of new features in addition to <code>-e</code> and <code>-i</code>:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>View the available flags for the console with <code>-h</code>.</p> +</li> +<li> +<p>Control console output with <code>-D</code>, <code>-Q</code> and -<code>V</code></p> +</li> +<li> +<p>Get line numbers on script failures passed to <code>-i</code> and <code>-e</code>.</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1268";>TINKERPOP-1268</a>, +<a href="https://issues.apache.org/jira/browse/TINKERPOP-1155";>TINKERPOP-1155</a>, <a href="https://issues.apache.org/jira/browse/TINKERPOP-1156";>TINKERPOP-1156</a>, +<a href="https://issues.apache.org/jira/browse/TINKERPOP-1157";>TINKERPOP-1157</a>, +<a href="http://tinkerpop.apache.org/docs/3.2.1/reference/#interactive-mode";>Reference Documentation - Interactive Mode</a>, +<a href="http://tinkerpop.apache.org/docs/3.2.1/reference/#execution-mode";>Reference Documentation - Execution Mode</a></p> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_upgrading_for_providers_3">Upgrading for Providers</h3> +<div class="sect3"> +<h4 id="_graph_system_providers_3">Graph System Providers</h4> +<div class="sect4"> +<h5 id="_vertexcomputing_api_change">VertexComputing API Change</h5> +<div class="paragraph"> +<p>The <code>VertexComputing</code> API is used by steps that wrap a <code>VertexProgram</code>. There is a method called +<code>VertexComputing.generateProgram()</code> that has changed which now takes a second argument of <code>Memory</code>. To upgrade, simply +fix the method signature of your <code>VertexComputing</code> implementations. The <code>Memory</code> argument can be safely ignored to +effect the exact same semantics as prior. However, now previous OLAP job <code>Memory</code> can be leveraged when constructing +the next <code>VertexProgram</code> in an OLAP traversal chain.</p> +</div> +</div> +<div class="sect4"> +<h5 id="_interrupting_traversals_2">Interrupting Traversals</h5> +<div class="paragraph"> +<p>Several tests have been added to the TinkerPop test suite to validate that a <code>Traversal</code> can be cancelled with +<code>Thread.interrupt()</code>. The test suite does not cover all possible traversal scenarios. When implementing custom steps, +providers should take care to not ignore an <code>InterruptionException</code> that might be thrown in their code and to be sure +to check <code>Thread.isInterrupted()</code> as needed to ensure that the step remains cancellation compliant.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-946";>TINKERPOP-946</a></p> +</div> +</div> +<div class="sect4"> +<h5 id="_performance_tests">Performance Tests</h5> +<div class="paragraph"> +<p>All "performance" tests have been deprecated. In the previous 3.2.0-incubating release, the <code>ProcessPerformanceSuite</code> +and <code>TraversalPerformanceTest</code> were deprecated, but some other tests remained. It is the remaining tests that have +been deprecated on this release:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>`StructurePerformanceSuite</p> +<div class="ulist"> +<ul> +<li> +<p><code>GraphReadPerformanceTest</code></p> +</li> +<li> +<p><code>GraphWriterPerformanceTest</code></p> +</li> +</ul> +</div> +</li> +<li> +<p><code>GroovyEnvironmentPerformanceSuite</code></p> +<div class="ulist"> +<ul> +<li> +<p><code>SugarLoaderPerformanceTest</code></p> +</li> +<li> +<p><code>GremlinExecutorPerformanceTest</code></p> +</li> +</ul> +</div> +</li> +<li> +<p>Gremlin Server related performance tests</p> +</li> +<li> +<p>TinkerGraph related performance tests</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>Providers should implement their own performance tests and not rely on these deprecated tests as they will be removed +in a future release along with the "JUnit Benchmarks" dependency.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1294";>TINKERPOP-1294</a></p> +</div> +</div> +</div> +<div class="sect3"> +<h4 id="_graph_database_providers">Graph Database Providers</h4> +<div class="sect4"> +<h5 id="_transaction_tests">Transaction Tests</h5> +<div class="paragraph"> +<p>Tests and assertions were added to the structure test suite to validate that transaction status was in the appropriate +state following calls to close the transaction with <code>commit()</code> or <code>rollback()</code>. It is unlikely that this change would cause test breaks for providers, unless the transaction status was inherently disconnected from calls to close the -transaction somehow. - -In addition, other tests were added to enforce the expected semantics for threaded transactions. Threaded transactions +transaction somehow.</p> +</div> +<div class="paragraph"> +<p>In addition, other tests were added to enforce the expected semantics for threaded transactions. Threaded transactions are expected to behave like manual transactions. They should be open automatically when they are created and once closed should no longer be used. This behavior is not new and is the typical expected method for working with these -types of transactions. The test suite just requires that the provider implementation conform to these semantics. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-947[TINKERPOP-947], -link:https://issues.apache.org/jira/browse/TINKERPOP-1059[TINKERPOP-1059] - -GraphFilter and GraphFilterStrategy -+++++++++++++++++++++++++++++++++++ - -`GraphFilter` has been significantly advanced where the determination of an edge direction/label legality is more stringent. -Along with this, `GraphFilter.getLegallyPositiveEdgeLabels()` has been added as a helper method to make it easier for `GraphComputer` -providers to know the space of labels being accessed by the traversal and thus, better enable provider-specific push-down predicates. - -Note that `GraphFilterStrategy` is now a default `TraversalStrategy` registered with `GraphComputer.` If `GraphFilter` is -expensive for the underlying `GraphComputer` implementation, it can be deactivated as is done for `TinkerGraphComputer`. - -[source,java]</pre> +types of transactions. The test suite just requires that the provider implementation conform to these semantics.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-947";>TINKERPOP-947</a>, +<a href="https://issues.apache.org/jira/browse/TINKERPOP-1059";>TINKERPOP-1059</a></p> +</div> </div> +<div class="sect4"> +<h5 id="_graphfilter_and_graphfilterstrategy">GraphFilter and GraphFilterStrategy</h5> +<div class="paragraph"> +<p><code>GraphFilter</code> has been significantly advanced where the determination of an edge direction/label legality is more stringent. +Along with this, <code>GraphFilter.getLegallyPositiveEdgeLabels()</code> has been added as a helper method to make it easier for <code>GraphComputer</code> +providers to know the space of labels being accessed by the traversal and thus, better enable provider-specific push-down predicates.</p> </div> <div class="paragraph"> -<p>static { +<p>Note that <code>GraphFilterStrategy</code> is now a default <code>TraversalStrategy</code> registered with <code>GraphComputer.</code> If <code>GraphFilter</code> is +expensive for the underlying <code>GraphComputer</code> implementation, it can be deactivated as is done for <code>TinkerGraphComputer</code>.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code class="java language-java"><span class="directive">static</span> { TraversalStrategies.GlobalCache.registerStrategies(TinkerGraphComputer.class, TraversalStrategies.GlobalCache.getStrategies(GraphComputer.class).clone().removeStrategies(GraphFilterStrategy.class)); -}</p> +}</code></pre> +</div> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1293";>TINKERPOP-1293</a></p> +</div> +</div> +</div> +<div class="sect3"> +<h4 id="_graph_language_providers">Graph Language Providers</h4> +<div class="sect4"> +<h5 id="_vertextest_signatures">VertexTest Signatures</h5> +<div class="paragraph"> +<p>The method signatures of <code>get_g_VXlistXv1_v2_v3XX_name</code> and <code>get_g_VXlistX1_2_3XX_name</code> of <code>VertexTest</code> were changed +to take arguments for the <code>Traversal</code> to be constructed by extending classes.</p> +</div> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_tinkerpop_3_2_0_2">TinkerPop 3.2.0</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><strong>Release Date: Release Date: April 8, 2016</strong></p> +</div> +<div class="paragraph"> +<p>Please see the <a href="https://github.com/apache/tinkerpop/blob/3.2.0-incubating/CHANGELOG.asciidoc#tinkerpop-320-release-date-april-8-2016";>changelog</a> for a complete list of all the modifications that are part of this release.</p> +</div> +<div class="sect2"> +<h3 id="_upgrading_for_users_4">Upgrading for Users</h3> +<div class="sect3"> +<h4 id="_hadoop_filesystem_variable">Hadoop FileSystem Variable</h4> +<div class="paragraph"> +<p>The <code>HadoopGremlinPlugin</code> defines two variables: <code>hdfs</code> and <code>fs</code>. The first is a reference to the HDFS <code>FileSystemStorage</code> +and the latter is a reference to the local <code>FileSystemStorage</code>. Prior to 3.2.x, <code>fs</code> was called <code>local</code>. However, +there was a variable name conflict with <code>Scope.local</code>. As such <code>local</code> is now <code>fs</code>. This issue existed prior to 3.2.x, +but was not realized until this release. Finally, this only effects Gremlin Console users.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_hadoop_configurations">Hadoop Configurations</h4> +<div class="paragraph"> +<p>Note that <code>gremlin.hadoop.graphInputFormat</code>, <code>gremlin.hadoop.graphOutputFormat</code>, <code>gremlin.spark.graphInputRDD</code>, and +<code>gremlin.spark.graphOuputRDD</code> have all been deprecated. Using them still works, but moving forward, users only need to +leverage <code>gremlin.hadoop.graphReader</code> and <code>gremlin.hadoop.graphWriter</code>. An example properties file snippet is provided +below.</p> </div> <div class="listingblock"> <div class="content"> -<pre> -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1293[TINKERPOP-1293] - -Graph Language Providers -^^^^^^^^^^^^^^^^^^^^^^^^ - -VertexTest Signatures -+++++++++++++++++++++ - -The method signatures of `get_g_VXlistXv1_v2_v3XX_name` and `get_g_VXlistX1_2_3XX_name` of `VertexTest` were changed -to take arguments for the `Traversal` to be constructed by extending classes. - -TinkerPop 3.2.0 ---------------- - -*Release Date: Release Date: April 8, 2016* - -Please see the link:https://github.com/apache/tinkerpop/blob/3.2.0-incubating/CHANGELOG.asciidoc#tinkerpop-320-release-date-april-8-2016[changelog] for a complete list of all the modifications that are part of this release. - -Upgrading for Users -~~~~~~~~~~~~~~~~~~~ - -Hadoop FileSystem Variable -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The `HadoopGremlinPlugin` defines two variables: `hdfs` and `fs`. The first is a reference to the HDFS `FileSystemStorage` -and the latter is a reference to the local `FileSystemStorage`. Prior to 3.2.x, `fs` was called `local`. However, -there was a variable name conflict with `Scope.local`. As such `local` is now `fs`. This issue existed prior to 3.2.x, -but was not realized until this release. Finally, this only effects Gremlin Console users. - -Hadoop Configurations -^^^^^^^^^^^^^^^^^^^^^ - -Note that `gremlin.hadoop.graphInputFormat`, `gremlin.hadoop.graphOutputFormat`, `gremlin.spark.graphInputRDD`, and -`gremlin.spark.graphOuputRDD` have all been deprecated. Using them still works, but moving forward, users only need to -leverage `gremlin.hadoop.graphReader` and `gremlin.hadoop.graphWriter`. An example properties file snippet is provided -below. - -``` -gremlin.graph=org.apache.tinkerpop.gremlin.hadoop.structure.HadoopGraph +<pre class="CodeRay"><code>gremlin.graph=org.apache.tinkerpop.gremlin.hadoop.structure.HadoopGraph gremlin.hadoop.graphReader=org.apache.tinkerpop.gremlin.hadoop.structure.io.gryo.GryoInputFormat gremlin.hadoop.graphWriter=org.apache.tinkerpop.gremlin.hadoop.structure.io.gryo.GryoOutputFormat gremlin.hadoop.jarsInDistributedCache=true -gremlin.hadoop.defaultGraphComputer=org.apache.tinkerpop.gremlin.spark.process.computer.SparkGraphComputer -``` - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1082[TINKERPOP-1082], -link:https://issues.apache.org/jira/browse/TINKERPOP-1222[TINKERPOP-1222] - -TraversalSideEffects Update -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -There were changes to `TraversalSideEffect` both at the semantic level and at the API level. Users that have traversals -of the form `sideEffect{...}` that leverage global side-effects should read the following carefully. If the user's traversals do -not use lambda-based side-effect steps (e.g. `groupCount("m")`), then the changes below will not effect them. Moreover, if user's -traversal only uses `sideEffect{...}` with closure (non-`TraversalSideEffect`) data references, then the changes below will not effect them. -If the user's traversal uses sideEffects in OLTP only, the changes below will not effect them. Finally, providers should not be -effected by the changes save any tests cases. - -TraversalSideEffects Get API Change -+++++++++++++++++++++++++++++++++++ - -`TraversalSideEffects` can now logically operate within a distributed OLAP environment. In order to make this possible, -it is necessary that each side-effect be registered with a reducing `BinaryOperator`. This binary operator will combine -distributed updates into a single global side-effect at the master traversal. Many of the methods in `TraversalSideEffect` -have been `Deprecated`, but they are backwards compatible save that `TraversalSideEffects.get()` no longer returns an `Optional`, -but instead throws an `IllegalArgumentException`. While the `Optional` semantics could have remained, it was deemed best to -directly return the side-effect value to reduce object creation costs and because all side-effects must be registered apriori, -there is never a reason why an unknown side-effect key would be used. In short: - -[source,java]</pre> +gremlin.hadoop.defaultGraphComputer=org.apache.tinkerpop.gremlin.spark.process.computer.SparkGraphComputer</code></pre> </div> </div> <div class="paragraph"> -<p>traversal.getSideEffects().get("m").get() -traversal.getSideEffects().get("m")</p> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1082";>TINKERPOP-1082</a>, +<a href="https://issues.apache.org/jira/browse/TINKERPOP-1222";>TINKERPOP-1222</a></p> +</div> +</div> +<div class="sect3"> +<h4 id="_traversalsideeffects_update">TraversalSideEffects Update</h4> +<div class="paragraph"> +<p>There were changes to <code>TraversalSideEffect</code> both at the semantic level and at the API level. Users that have traversals +of the form <code>sideEffect{...}</code> that leverage global side-effects should read the following carefully. If the user’s traversals do +not use lambda-based side-effect steps (e.g. <code>groupCount("m")</code>), then the changes below will not effect them. Moreover, if user’s +traversal only uses <code>sideEffect{...}</code> with closure (non-<code>TraversalSideEffect</code>) data references, then the changes below will not effect them. +If the user’s traversal uses sideEffects in OLTP only, the changes below will not effect them. Finally, providers should not be +effected by the changes save any tests cases.</p> +</div> +<div class="sect4"> +<h5 id="_traversalsideeffects_get_api_change">TraversalSideEffects Get API Change</h5> +<div class="paragraph"> +<p><code>TraversalSideEffects</code> can now logically operate within a distributed OLAP environment. In order to make this possible, +it is necessary that each side-effect be registered with a reducing <code>BinaryOperator</code>. This binary operator will combine +distributed updates into a single global side-effect at the master traversal. Many of the methods in <code>TraversalSideEffect</code> +have been <code>Deprecated</code>, but they are backwards compatible save that <code>TraversalSideEffects.get()</code> no longer returns an <code>Optional</code>, +but instead throws an <code>IllegalArgumentException</code>. While the <code>Optional</code> semantics could have remained, it was deemed best to +directly return the side-effect value to reduce object creation costs and because all side-effects must be registered apriori, +there is never a reason why an unknown side-effect key would be used. In short:</p> </div> <div class="listingblock"> <div class="content"> -<pre> -TraversalSideEffects Registration Requirement -+++++++++++++++++++++++++++++++++++++++++++++ - -All `TraversalSideEffects` must be registered upfront. This is because, in OLAP, side-effects map to `Memory` compute keys -and as such, must be declared prior to the execution of the `TraversalVertexProgram`. If a user's traversal creates a -side-effect mid-traversal, it will fail. The traversal must use `GraphTraversalSource.withSideEffect()` to declare -the side-effects it will use during its execution lifetime. If the user's traversals use standard side-effect Gremlin -steps (e.g. `group("m")`), then no changes are required. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1192[TINKERPOP-1192] - -TraversalSideEffects Add Requirement -++++++++++++++++++++++++++++++++++++ - -In a distributed environment, a side-effect can not be mutated and be expected to exist in the mutated form at the final, -aggregated, master traversal. For instance, if the side-effect "myCount" references a `Long`, the `Long` can not be updated -directly via `sideEffects.set("myCount", sideEffects.get("myCount") + 1)`. Instead, it must rely on the registered reducer -to do the merging and thus, the `Step` must do `sideEffect.add("mySet",1)`, where the registered reducer is `Operator.sum`. -Thus, the below will increment "a". If no operator was provided, then the operator is assumed `Operator.assign` and the -final result of "a" would be 1. Note that `Traverser.sideEffects(key,value)` uses `TraversalSideEffect.add()`. - -[source,groovy]</pre> +<pre class="CodeRay"><code class="java language-java"><span class="comment">// change</span> +traversal.getSideEffects().get(<span class="string"><span class="delimiter">"</span><span class="content">m</span><span class="delimiter">"</span></span>).get() +<span class="comment">// to</span> +traversal.getSideEffects().get(<span class="string"><span class="delimiter">"</span><span class="content">m</span><span class="delimiter">"</span></span>)</code></pre> +</div> +</div> +</div> +<div class="sect4"> +<h5 id="_traversalsideeffects_registration_requirement">TraversalSideEffects Registration Requirement</h5> +<div class="paragraph"> +<p>All <code>TraversalSideEffects</code> must be registered upfront. This is because, in OLAP, side-effects map to <code>Memory</code> compute keys +and as such, must be declared prior to the execution of the <code>TraversalVertexProgram</code>. If a user’s traversal creates a +side-effect mid-traversal, it will fail. The traversal must use <code>GraphTraversalSource.withSideEffect()</code> to declare +the side-effects it will use during its execution lifetime. If the user’s traversals use standard side-effect Gremlin +steps (e.g. <code>group("m")</code>), then no changes are required.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1192";>TINKERPOP-1192</a></p> </div> </div> +<div class="sect4"> +<h5 id="_traversalsideeffects_add_requirement">TraversalSideEffects Add Requirement</h5> <div class="paragraph"> -<p>gremlin> traversal = g.withSideEffect(<em>a</em>,0,sum).V().out().sideEffect{it.sideEffects(<em>a</em>,1)} -=⇒v[3] -=⇒v[2] -=⇒v[4] -=⇒v[5] -=⇒v[3] -=⇒v[3] -gremlin> traversal.getSideEffects().get(<em>a</em>) -=⇒6 -gremlin> traversal = g.withSideEffect(<em>a</em>,0).V().out().sideEffect{it.sideEffects(<em>a</em>,1)} -=⇒v[3] -=⇒v[2] -=⇒v[4] -=⇒v[5] -=⇒v[3] -=⇒v[3] -gremlin> traversal.getSideEffects().get(<em>a</em>) -=⇒1</p> +<p>In a distributed environment, a side-effect can not be mutated and be expected to exist in the mutated form at the final, +aggregated, master traversal. For instance, if the side-effect "myCount" references a <code>Long</code>, the <code>Long</code> can not be updated +directly via <code>sideEffects.set("myCount", sideEffects.get("myCount") + 1)</code>. Instead, it must rely on the registered reducer +to do the merging and thus, the <code>Step</code> must do <code>sideEffect.add("mySet",1)</code>, where the registered reducer is <code>Operator.sum</code>. +Thus, the below will increment "a". If no operator was provided, then the operator is assumed <code>Operator.assign</code> and the +final result of "a" would be 1. Note that <code>Traverser.sideEffects(key,value)</code> uses <code>TraversalSideEffect.add()</code>.</p> </div> <div class="listingblock"> <div class="content"> -<pre> -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1192[TINKERPOP-1192], -https://issues.apache.org/jira/browse/TINKERPOP-1166[TINKERPOP-1166] - -ProfileStep Update and GraphTraversal API Change -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The `profile()`-step has been refactored into 2 steps -- `ProfileStep` and `ProfileSideEffectStep`. Users who previously -used the `profile()` in conjunction with `cap(TraversalMetrics.METRICS_KEY)` can now simply omit the cap step. Users who -retrieved `TraversalMetrics` from the side-effects after iteration can still do so, but will need to specify a side-effect -key when using the `profile()`. For example, `profile("myMetrics")`. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-958[TINKERPOP-958] - -BranchStep Bug Fix -^^^^^^^^^^^^^^^^^^ - -There was a bug in `BranchStep` that also rears itself in subclass steps such as `UnionStep` and `ChooseStep`. -For traversals with branches that have barriers (e.g. `count()`, `max()`, `groupCount()`, etc.), the traversal needs to be updated. -For instance, if a traversal is of the form `g.V().union(out().count(),both().count())`, the result is now different +<pre class="CodeRay"><code class="groovy language-groovy">gremlin> traversal = g.withSideEffect(<span class="string"><span class="delimiter">'</span><span class="content">a</span><span class="delimiter">'</span></span>,<span class="integer">0</span>,sum).V().out().sideEffect{<span class="local-variable">it</span>.sideEffects(<span class="string"><span class="delimiter">'</span><span class="content">a</span><span class="delimiter">'</span></span>,<span class="integer">1</span>)} +==>v[<span class="integer">3</span>] +==>v[<span class="integer">2</span>] +==>v[<span class="integer">4</span>] +==>v[<span class="integer">5</span>] +==>v[<span class="integer">3</span>] +==>v[<span class="integer">3</span>] +gremlin> traversal.getSideEffects().get(<span class="string"><span class="delimiter">'</span><span class="content">a</span><span class="delimiter">'</span></span>) +==><span class="integer">6</span> +gremlin> traversal = g.withSideEffect(<span class="string"><span class="delimiter">'</span><span class="content">a</span><span class="delimiter">'</span></span>,<span class="integer">0</span>).V().out().sideEffect{<span class="local-variable">it</span>.sideEffects(<span class="string"><span class="delimiter">'</span><span class="content">a</span><span class="delimiter">'</span></span>,<span class="integer">1</span>)} +==>v[<span class="integer">3</span>] +==>v[<span class="integer">2</span>] +==>v[<span class="integer">4</span>] +==>v[<span class="integer">5</span>] +==>v[<span class="integer">3</span>] +==>v[<span class="integer">3</span>] +gremlin> traversal.getSideEffects().get(<span class="string"><span class="delimiter">'</span><span class="content">a</span><span class="delimiter">'</span></span>) +==><span class="integer">1</span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1192";>TINKERPOP-1192</a>, +<a href="https://issues.apache.org/jira/browse/TINKERPOP-1166";>TINKERPOP-1166</a></p> +</div> +</div> +</div> +<div class="sect3"> +<h4 id="_profilestep_update_and_graphtraversal_api_change">ProfileStep Update and GraphTraversal API Change</h4> +<div class="paragraph"> +<p>The <code>profile()</code>-step has been refactored into 2 steps — <code>ProfileStep</code> and <code>ProfileSideEffectStep</code>. Users who previously +used the <code>profile()</code> in conjunction with <code>cap(TraversalMetrics.METRICS_KEY)</code> can now simply omit the cap step. Users who +retrieved <code>TraversalMetrics</code> from the side-effects after iteration can still do so, but will need to specify a side-effect +key when using the <code>profile()</code>. For example, <code>profile("myMetrics")</code>.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-958";>TINKERPOP-958</a></p> +</div> +</div> +<div class="sect3"> +<h4 id="_branchstep_bug_fix">BranchStep Bug Fix</h4> +<div class="paragraph"> +<p>There was a bug in <code>BranchStep</code> that also rears itself in subclass steps such as <code>UnionStep</code> and <code>ChooseStep</code>. +For traversals with branches that have barriers (e.g. <code>count()</code>, <code>max()</code>, <code>groupCount()</code>, etc.), the traversal needs to be updated. +For instance, if a traversal is of the form <code>g.V().union(out().count(),both().count())</code>, the result is now different (the bug fix yields a different output). In order to yield the same result, the traversal should be rewritten as -`g.V().local(union(out().count(),both().count()))`. Note that if a branch does not have a barrier, then no changes are required. -For instance, `g.V().union(out(),both())` does not need to be updated. Moreover, if the user's traversal already used -the `local()`-form, then no change are required either. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1188[TINKERPOP-1188] - -MemoryComputeKey and VertexComputeKey -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users that have custom `VertexProgram` implementations will need to change their implementations to support the new -`VertexComputeKey` and `MemoryComputeKey` classes. In the `VertexPrograms` provided by TinkerPop, these changes were trivial, -taking less than 5 minutes to make all the requisite updates. - -* `VertexProgram.getVertexComputeKeys()` returns a `Set<VertexComputeKey>`. No longer a `Set<String>`. -Use `VertexComputeKey.of(String key,boolean transient)` to generate a `VertexComputeKey`. +<code>g.V().local(union(out().count(),both().count()))</code>. Note that if a branch does not have a barrier, then no changes are required. +For instance, <code>g.V().union(out(),both())</code> does not need to be updated. Moreover, if the user’s traversal already used +the <code>local()</code>-form, then no change are required either.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1188";>TINKERPOP-1188</a></p> +</div> +</div> +<div class="sect3"> +<h4 id="_memorycomputekey_and_vertexcomputekey">MemoryComputeKey and VertexComputeKey</h4> +<div class="paragraph"> +<p>Users that have custom <code>VertexProgram</code> implementations will need to change their implementations to support the new +<code>VertexComputeKey</code> and <code>MemoryComputeKey</code> classes. In the <code>VertexPrograms</code> provided by TinkerPop, these changes were trivial, +taking less than 5 minutes to make all the requisite updates.</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><code>VertexProgram.getVertexComputeKeys()</code> returns a <code>Set<VertexComputeKey></code>. No longer a <code>Set<String></code>. +Use <code>VertexComputeKey.of(String key,boolean transient)</code> to generate a <code>VertexComputeKey</code>. Transient keys were not supported in the past, so to make the implementation semantically equivalent, -the boolean transient should be false. - -* `VertexProgram.getMemoryComputeKeys()` returns a `Set<MemoryComputeKey>`. No longer a `Set<String>`. -Use `MemoryComputeKey.of(String key, BinaryOperator reducer, boolean broadcast, boolean transient)` to generate a `MemoryComputeKey`. +the boolean transient should be false.</p> +</li> +<li> +<p><code>VertexProgram.getMemoryComputeKeys()</code> returns a <code>Set<MemoryComputeKey></code>. No longer a <code>Set<String></code>. +Use <code>MemoryComputeKey.of(String key, BinaryOperator reducer, boolean broadcast, boolean transient)</code> to generate a <code>MemoryComputeKey</code>. Broadcasting and transients were not supported in the past so to make the implementation semantically equivalent, -the boolean broadcast should be true and the boolean transient should be false. - -An example migration looks as follows. What might currently look like: - -``` -public Set<String> getMemoryComputeKeys() { +the boolean broadcast should be true and the boolean transient should be false.</p> +</li> +</ul> +</div> +<div class="paragraph"> +<p>An example migration looks as follows. What might currently look like:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code>public Set<String> getMemoryComputeKeys() { return new HashSet<>(Arrays.asList("a","b","c")) -} -``` - -Should now look like: - -``` -public Set<MemoryComputeKey> getMemoryComputeKeys() { +}</code></pre> +</div> +</div> +<div class="paragraph"> +<p>Should now look like:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code>public Set<MemoryComputeKey> getMemoryComputeKeys() { return new HashSet<>(Arrays.asList( MemoryComputeKey.of("a", Operator.and, true, false), MemoryComputeKey.of("b", Operator.sum, true, false), MemoryComputeKey.of("c", Operator.or, true, false))) -} -``` - -A similar patterns should also be used for `VertexProgram.getVertexComputeKeys()`. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1162[TINKERPOP-1162] - -SparkGraphComputer and GiraphGraphComputer Persistence -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The `MapReduce`-based steps in `TraversalVertexProgram` have been removed and replaced using a new `Memory`-reduction model. -`MapReduce` jobs always created a persistence footprint, e.g. in HDFS. `Memory` data was never persisted to HDFS. -As such, there will be no data on the disk that is accessible. For instance, there is no more `~reducing`, `~traversers`, -and specially named side-effects such as `m` from a `groupCount('m')`. The data is still accessible via `ComputerResult.memory()`, -it simply does not have a corresponding on-disk representation. - -RemoteGraph -^^^^^^^^^^^ - -`RemoteGraph` is a lightweight `Graph` implementation that acts as a proxy for sending traversals to Gremlin Server for -remote execution. It is an interesting alternative to the other methods for connecting to Gremlin Server in that all -other methods involved construction of a `String` representation of the `Traversal` which is then submitted as a script -to Gremlin Server (via driver or REST). - -[source,groovy]</pre> +}</code></pre> +</div> +</div> +<div class="paragraph"> +<p>A similar patterns should also be used for <code>VertexProgram.getVertexComputeKeys()</code>.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1162";>TINKERPOP-1162</a></p> +</div> </div> +<div class="sect3"> +<h4 id="_sparkgraphcomputer_and_giraphgraphcomputer_persistence">SparkGraphComputer and GiraphGraphComputer Persistence</h4> +<div class="paragraph"> +<p>The <code>MapReduce</code>-based steps in <code>TraversalVertexProgram</code> have been removed and replaced using a new <code>Memory</code>-reduction model. +<code>MapReduce</code> jobs always created a persistence footprint, e.g. in HDFS. <code>Memory</code> data was never persisted to HDFS. +As such, there will be no data on the disk that is accessible. For instance, there is no more <code>~reducing</code>, <code>~traversers</code>, +and specially named side-effects such as <code>m</code> from a <code>groupCount('m')</code>. The data is still accessible via <code>ComputerResult.memory()</code>, +it simply does not have a corresponding on-disk representation.</p> </div> +</div> +<div class="sect3"> +<h4 id="_remotegraph">RemoteGraph</h4> <div class="paragraph"> -<p>gremlin> graph = RemoteGraph.open(<em>conf/remote-graph.properties</em>) -=⇒remotegraph[DriverServerConnection-localhost/127.0.0.1:8182 [graph='graph]] -gremlin> g = graph.traversal() -=⇒graphtraversalsource[remotegraph[DriverServerConnection-localhost/127.0.0.1:8182 [graph='graph]], standard] -gremlin> g.V().valueMap(true) -=⇒[name:[marko], label:person, id:1, age:[29]] -=⇒[name:[vadas], label:person, id:2, age:[27]] -=⇒[name:[lop], label:software, id:3, lang:[java]] -=⇒[name:[josh], label:person, id:4, age:[32]] -=⇒[name:[ripple], label:software, id:5, lang:[java]] -=⇒[name:[peter], label:person, id:6, age:[35]]</p> +<p><code>RemoteGraph</code> is a lightweight <code>Graph</code> implementation that acts as a proxy for sending traversals to Gremlin Server for +remote execution. It is an interesting alternative to the other methods for connecting to Gremlin Server in that all +other methods involved construction of a <code>String</code> representation of the <code>Traversal</code> which is then submitted as a script +to Gremlin Server (via driver or REST).</p> </div> <div class="listingblock"> <div class="content"> -<pre> -Note that `g.V().valueMap(true)` is executing in Gremlin Server and not locally in the console. - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-575[TINKERPOP-575], -link:http://tinkerpop.apache.org/docs/3.2.0-incubating/reference/#connecting-via-remotegraph[Reference Documentation - Remote Graph] - -Upgrading for Providers -~~~~~~~~~~~~~~~~~~~~~~~ - -Graph System Providers -^^^^^^^^^^^^^^^^^^^^^^ - -GraphStep Compilation Requirement -+++++++++++++++++++++++++++++++++ - -OLTP graph providers that have a custom `GraphStep` implementation should ensure that `g.V().hasId(x)` and `g.V(x)` compile +<pre class="CodeRay"><code class="groovy language-groovy">gremlin> graph = RemoteGraph.open(<span class="string"><span class="delimiter">'</span><span class="content">conf/remote-graph.properties</span><span class="delimiter">'</span></span>) +==>remotegraph[DriverServerConnection-localhost/<span class="float">127.0</span><span class="float">.0</span><span class="float">.1</span>:<span class="integer">8182</span> [graph=<span class="string"><span class="delimiter">'</span><span class="content">graph]]</span></span><span class="error"> +</span>gremlin> g = graph.traversal() +==>graphtraversalsource[remotegraph[DriverServerConnection-localhost/<span class="float">127.0</span><span class="float">.0</span><span class="float">.1</span>:<span class="integer">8182</span> [graph=<span class="string"><span class="delimiter">'</span><span class="content">graph]], standard]</span></span><span class="error"> +</span>gremlin> g.V().valueMap(<span class="predefined-constant">true</span>) +==>[<span class="key">name</span>:[marko], <span class="key">label</span>:person, <span class="key">id</span>:<span class="integer">1</span>, <span class="key">age</span>:[<span class="integer">29</span>]] +==>[<span class="key">name</span>:[vadas], <span class="key">label</span>:person, <span class="key">id</span>:<span class="integer">2</span>, <span class="key">age</span>:[<span class="integer">27</span>]] +==>[<span class="key">name</span>:[lop], <span class="key">label</span>:software, <span class="key">id</span>:<span class="integer">3</span>, <span class="key">lang</span>:[java]] +==>[<span class="key">name</span>:[josh], <span class="key">label</span>:person, <span class="key">id</span>:<span class="integer">4</span>, <span class="key">age</span>:[<span class="integer">32</span>]] +==>[<span class="key">name</span>:[ripple], <span class="key">label</span>:software, <span class="key">id</span>:<span class="integer">5</span>, <span class="key">lang</span>:[java]] +==>[<span class="key">name</span>:[peter], <span class="key">label</span>:person, <span class="key">id</span>:<span class="integer">6</span>, <span class="key">age</span>:[<span class="integer">35</span>]]</code></pre> +</div> +</div> +<div class="paragraph"> +<p>Note that <code>g.V().valueMap(true)</code> is executing in Gremlin Server and not locally in the console.</p> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-575";>TINKERPOP-575</a>, +<a href="http://tinkerpop.apache.org/docs/3.2.0-incubating/reference/#connecting-via-remotegraph";>Reference Documentation - Remote Graph</a></p> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_upgrading_for_providers_4">Upgrading for Providers</h3> +<div class="sect3"> +<h4 id="_graph_system_providers_4">Graph System Providers</h4> +<div class="sect4"> +<h5 id="_graphstep_compilation_requirement">GraphStep Compilation Requirement</h5> +<div class="paragraph"> +<p>OLTP graph providers that have a custom <code>GraphStep</code> implementation should ensure that <code>g.V().hasId(x)</code> and <code>g.V(x)</code> compile to the same representation. This ensures a consistent user experience around random access of elements based on ids -(as opposed to potentially the former doing a linear scan). A static helper method called `GraphStep.processHasContainerIds()` -has been added. `TinkerGraphStepStrategy` was updated as such: - -``` -((HasContainerHolder) currentStep).getHasContainers().forEach(tinkerGraphStep::addHasContainer); -``` - -is now - -``` -((HasContainerHolder) currentStep).getHasContainers().forEach(hasContainer -> { +(as opposed to potentially the former doing a linear scan). A static helper method called <code>GraphStep.processHasContainerIds()</code> +has been added. <code>TinkerGraphStepStrategy</code> was updated as such:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code>((HasContainerHolder) currentStep).getHasContainers().forEach(tinkerGraphStep::addHasContainer);</code></pre> +</div> +</div> +<div class="paragraph"> +<p>is now</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="CodeRay"><code>((HasContainerHolder) currentStep).getHasContainers().forEach(hasContainer -> { if (!GraphStep.processHasContainerIds(tinkerGraphStep, hasContainer)) tinkerGraphStep.addHasContainer(hasContainer); -}); -``` - -See: link:https://issues.apache.org/jira/browse/TINKERPOP-1219[TINKERPOP-1219] - -Step API Update -+++++++++++++++ - -The `Step` interface is fundamental to Gremlin. `Step.processNextStart()` and `Step.next()` both returned `Traverser<E>`. -We had so many `Traverser.asAdmin()` and direct typecast calls throughout (especially in `TraversalVertexProgram`) that -it was deemed prudent to have `Step.processNextStart()` and `Step.next()` return `Traverser.Admin<E>`. Moreover it makes -sense as this is internal logic where `Admins` are always needed. Providers with their own step definitions will simply -need to change the method signatures of `Step.processNextStart()` and `Step.next()`. No logic update is required -- save -that `asAdmin()` can be safely removed if used. Also, `Step.addStart()` and `Step.addStarts()` take `Traverser.Admin<S>` -and `Iterator<Traverser.Admin<S>>`, respectively. - -Traversal API Update -++++++++++++++++++++ - -The way in which `TraverserRequirements` are calculated has been changed (for the better). The ramification is that post +});</code></pre> +</div> +</div> +<div class="paragraph"> +<p>See: <a href="https://issues.apache.org/jira/browse/TINKERPOP-1219";>TINKERPOP-1219</a></p> +</div> +</div> +<div class="sect4"> +<h5 id="_step_api_update">Step API Update</h5> +<div class="paragraph"> +<p>The <code>Step</code> interface is fundamental to Gremlin. <code>Step.processNextStart()</code> and <code>Step.next()</code> both returned <code>Traverser<E></code>. +We had so many <code>Traverser.asAdmin()</code> and direct typecast calls throughout (especially in <code>TraversalVertexProgram</code>) that +it was deemed prudent to have <code>Step.processNextStart()</code> and <code>Step.next()</code> return <code>Traverser.Admin<E></code>. Moreover it makes +sense as this is internal logic where <code>Admins</code> are always needed. Providers with their own step definitions will simply +need to change the method signatures of <code>Step.processNextStart()</code> and <code>Step.next()</code>. No logic update is required — save +that <code>asAdmin()</code> can be safely removed if used. Also, <code>Step.addStart()</code> and <code>Step.addStarts()</code> take <code>Traverser.Admin<S></code> +and <code>Iterator<Traverser.Admin<S>></code>, respectively.</p> +</div> +</div> +<div class="sect4"> +<h5 id="_traversal_api_update">Traversal API Update</h5> +<div class="paragraph"> +<p>The way in which <code>TraverserRequirements</code> are calculated has been changed (for the better). The ramification is that post compilation requirement additions no longer make sense and should not be allowed. To enforce this, -`Traversal.addTraverserRequirement()` method has been removed from the interface. Moreover, providers/users should never be able +<code>Traversal.addTraverserRequirement()</code> method has been removed from the interface. Moreover, providers/users should never be able to add requirements manually (this should all be inferred from the end compilation). However, if need be, there is always -`RequirementStrategy` which will allow the provider to add a requirement at strategy application time -(though again, there should not be a reason to do so). - -ComparatorHolder API Change -+++++++++++++++++++++++++++ -
[... 2674 lines stripped ...]
