You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2016/10/06 18:15:33 UTC
[11/14] tinkerpop git commit: Add IO Reference docs
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/docs/src/dev/io/gryo.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/io/gryo.asciidoc b/docs/src/dev/io/gryo.asciidoc
new file mode 100644
index 0000000..61afdb0
--- /dev/null
+++ b/docs/src/dev/io/gryo.asciidoc
@@ -0,0 +1,63 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+////
+[[gryo]]
+Gryo
+====
+
+image:gremlin-kryo.png[width=400,float=left] Gryo uses the popular link:https://github.com/EsotericSoftware/kryo[Kryo]
+library to handle binary serialization for the JVM. There currently aren't any Kryo implementations in other languages
+so the binding of this format to the JVM is a bit of a limitation, but if building a system on the JVM the use of
+Gryo over other serialization format should yield smaller data sizes than other formats like GraphSON or GraphML,
+improved serialization speed, as well as better support for the various Java data types that might not be supported
+otherwise.
+
+Gryo is useful both as a "graph" serialization format and as a generalized serialization format that can read or
+write any object. This characteristic makes it ideal for use in Gremlin Server, which is designed to return arbitrary
+results of varying types.
+
+It is unlikely that Gryo users will try to consume or produce Gryo without using TinkerPop and Kryo classes to help do
+it. Attempting to read or write a byte stream of Gryo without those tools would be challenging, so the depths of
+what the Gryo format looks like in a byte-by-byte perspective will not be discussed here. It is enough to know that
+TinkerPop has Kryo-based serializers for certain classes that it supports and that the bytes written or read must be
+Kryo compliant.
+
+While there is only one version of Gryo at the moment, 1.0, the format has generally expanded as new releases of
+TinkerPop have been produced. "Expansion" has generally meant that new types have come to be supported over time. The
+addition of new types means that while Gryo has remained at 1.0, older releases that produced Gryo files will not
+be compatible with newer TinkerPop releases if the newer types are utilized. On the flip side, newer release of
+TinkerPop are fully backward compatible with Gryo produced on older versions of TinkerPop.
+
+The full list of Gryo 1.0 types can be found in the `GryoMapper` source code. Looking at the source code for a specific
+release tag would show what types were compatible for a specific release. For example, the type listing for 3.2.2
+can be found link:https://github.com/apache/tinkerpop/blob/3.2.2/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoMapper.java#L249[here].
+
+One of the key aspects of Gryo is that, by default, it requires that all types expected to be used to be registered
+with the `GryoMapper`. There are two ways to do that:
+
+* On the `GryoMapper.Builder`, use the `addCustom` methods. These methods allow registration of single classes with
+an optional custom serializer.
+* Add a custom `IoRegistry` implementation with the `addRegistry` method on `GryoMapper.Builder`. The `IoRegistry`
+contains registrations that will be supplied to the `GryoMapper`. There is additional documentation on how this works
+in the link:http://tinkerpop.apache.org/docs/current/dev/provider/#io-implementations[provider documentation].
+
+When using `addCustom` or `addRegistry`, it is important to remember that the order in which those methods are called
+is important. The registrations get numeric "registration ids" and their order must match if the the Gryo is expected
+to be compatible. Calls to `addCustom` will be applied first, prior to calls to `addRegistry` (which internally call
+`addCustom`).
+
+It is possible to disable registration by setting `registrationRequired` on the `GryoMapper.Builder` to `false`, but
+Gryo is less efficient with this feature is turned off.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/docs/src/dev/io/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/io/index.asciidoc b/docs/src/dev/io/index.asciidoc
new file mode 100644
index 0000000..9eaf02a
--- /dev/null
+++ b/docs/src/dev/io/index.asciidoc
@@ -0,0 +1,37 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+////
+image::apache-tinkerpop-logo.png[width=500,link="http://tinkerpop.apache.org"]
+
+*x.y.z*
+
+:toc-position: left
+
+IO Reference
+============
+
+image:gremlin-io2.png[width=300]
+
+IO features, capabilities and use cases are initially discussed in the TinkerPop
+link:http://tinkerpop.apache.org/docs/x.y.z/reference/#_gremlin_i_o[Reference Documentation]. This document focuses
+more on the details of the implementations for both production and consumption of the various formats. It contains
+samples of the various formats and development details that provide deeper insight for their usage.
+
+include::graphml.asciidoc[]
+
+include::graphson.asciidoc[]
+
+include::gryo.asciidoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/docs/src/dev/provider/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/provider/index.asciidoc b/docs/src/dev/provider/index.asciidoc
index bb41241..af1be4f 100644
--- a/docs/src/dev/provider/index.asciidoc
+++ b/docs/src/dev/provider/index.asciidoc
@@ -785,6 +785,9 @@ Gremlin Server will send:
|599 |SERVER SERIALIZATION ERROR |The server was not capable of serializing an object that was returned from the script supplied on the request. Either transform the object into something Gremlin Server can process within the script or install mapper serialization classes to Gremlin Server.
|=========================================================
+NOTE: Please refer to the link:http://tinkerpop.apache.org/docs/current/dev/io[IO Reference Documentation] for more
+examples of `RequestMessage` and `ResponseMessage` instances.
+
OpProcessors Arguments
~~~~~~~~~~~~~~~~~~~~~~
@@ -827,6 +830,7 @@ evaluated and is committed when the script completes (or rolled back if an error
|=========================================================
|Key |Type |Description
|sasl |byte[] | *Required* The response to the server authentication challenge. This value is dependent on the SASL authentication mechanism required by the server.
+|saslMechanism |String | The SASL mechanism: `PLAIN` or `GSSAPI`. Note that it is up to the server implementation to use or disregard this setting (default implementation in Gremlin Server ignores it).
|=========================================================
'`eval` operation arguments'
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/docs/src/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/index.asciidoc b/docs/src/index.asciidoc
index 51d2105..09ffc2f 100644
--- a/docs/src/index.asciidoc
+++ b/docs/src/index.asciidoc
@@ -88,4 +88,6 @@ Developer
Provides information on ways to contribute to TinkerPop as well as details on building the project and other specific information for contributors.
|image:tinkerpop-enabled.png[width=200] |link:http://tinkerpop.apache.org/docs/x.y.z/dev/provider/[Providers] +
Documentation for providers who implement the TinkerPop interfaces, develop plugins or drivers, or provide other third-party libraries for TinkerPop.
+|image:gremlin-io2.png[width=200] |link:http://tinkerpop.apache.org/docs/x.y.z/dev/io/[IO Reference] +
+Reference Documentation for providers and users of the various IO formats that TinkerPop has: GraphML, GraphSON and Gryo.
|=========================================================
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/docs/src/upgrade/release-3.2.x-incubating.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/upgrade/release-3.2.x-incubating.asciidoc b/docs/src/upgrade/release-3.2.x-incubating.asciidoc
index 5fbf4fe..c21f1a5 100644
--- a/docs/src/upgrade/release-3.2.x-incubating.asciidoc
+++ b/docs/src/upgrade/release-3.2.x-incubating.asciidoc
@@ -152,6 +152,15 @@ there is no need to do that manually.
See: link:https://issues.apache.org/jira/browse/TINKERPOP-790[TINKERPOP-790]
+IO Reference Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is new reference documentation for the various IO formats. The documentation provides more details and samples
+that should be helpful to users and providers who intend to work directly with the TinkerPop supported serialization
+formats: GraphML, GraphSON and Gryo.
+
+See: link:http://tinkerpop.apache.org/docs/3.2.3/dev/io/[IO Reference Documentation]
+
Upgrading for Providers
~~~~~~~~~~~~~~~~~~~~~~~
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/docs/static/images/gremlin-io2.png
----------------------------------------------------------------------
diff --git a/docs/static/images/gremlin-io2.png b/docs/static/images/gremlin-io2.png
new file mode 100755
index 0000000..99b8a30
Binary files /dev/null and b/docs/static/images/gremlin-io2.png differ
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONModule.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONModule.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONModule.java
index 787867f..5fb84f1 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONModule.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONModule.java
@@ -101,7 +101,7 @@ abstract class GraphSONModule extends TinkerPopJacksonModule {
put(Property.class, "Property");
put(Path.class, "Path");
put(VertexProperty.class, "VertexProperty");
- put(Metrics.class, "metrics");
+ put(Metrics.class, "Metrics");
put(TraversalMetrics.class, "TraversalMetrics");
put(Traverser.class, "Traverser");
put(Tree.class, "Tree");
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 632ed60..2e67eda 100644
--- a/pom.xml
+++ b/pom.xml
@@ -856,6 +856,31 @@ limitations under the License.
</configuration>
</execution>
<execution>
+ <id>io-book</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <sourceDirectory>${asciidoc.input.dir}/dev/io</sourceDirectory>
+ <sourceDocumentName>index.asciidoc</sourceDocumentName>
+ <outputDirectory>${htmlsingle.output.dir}/dev/io</outputDirectory>
+ <backend>html5</backend>
+ <doctype>book</doctype>
+ <attributes>
+ <imagesdir>../../images</imagesdir>
+ <encoding>UTF-8</encoding>
+ <toc>true</toc>
+ <toclevels>3</toclevels>
+ <toc-position>left</toc-position>
+ <stylesdir>${asciidoctor.style.dir}</stylesdir>
+ <stylesheet>tinkerpop.css</stylesheet>
+ <source-highlighter>coderay</source-highlighter>
+ <basedir>${project.basedir}</basedir>
+ </attributes>
+ </configuration>
+ </execution>
+ <execution>
<id>provider-book</id>
<phase>generate-resources</phase>
<goals>
http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/17449e22/tinkergraph-gremlin/src/main/java/org/apache/tinkerpop/gremlin/tinkergraph/structure/TinkerIoRegistryV2d0.java
----------------------------------------------------------------------
diff --git a/tinkergraph-gremlin/src/main/java/org/apache/tinkerpop/gremlin/tinkergraph/structure/TinkerIoRegistryV2d0.java b/tinkergraph-gremlin/src/main/java/org/apache/tinkerpop/gremlin/tinkergraph/structure/TinkerIoRegistryV2d0.java
index da9edb5..0681ff1 100644
--- a/tinkergraph-gremlin/src/main/java/org/apache/tinkerpop/gremlin/tinkergraph/structure/TinkerIoRegistryV2d0.java
+++ b/tinkergraph-gremlin/src/main/java/org/apache/tinkerpop/gremlin/tinkergraph/structure/TinkerIoRegistryV2d0.java
@@ -130,7 +130,7 @@ public final class TinkerIoRegistryV2d0 extends AbstractIoRegistry {
@Override
public String getTypeNamespace() {
- return "gremlin";
+ return "tinker";
}
}