You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by ok...@apache.org on 2016/01/05 23:54:54 UTC
[22/50] incubator-tinkerpop git commit: TINKERPOP-1065: fix some
typos and clarify some wording.
TINKERPOP-1065: fix some typos and clarify some wording.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/3eb47265
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/3eb47265
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/3eb47265
Branch: refs/heads/TINKERPOP-1033
Commit: 3eb472654a88bd1f6f4947244c6e16c05433768d
Parents: 2f16c77
Author: Jeremy Hanna <jh...@datastax.com>
Authored: Wed Dec 23 14:27:25 2015 -0800
Committer: Jeremy Hanna <jh...@datastax.com>
Committed: Wed Dec 23 14:27:25 2015 -0800
----------------------------------------------------------------------
docs/src/reference/intro.asciidoc | 23 +++++++++-------
docs/src/reference/the-graph.asciidoc | 44 ++++++++++++++++--------------
2 files changed, 36 insertions(+), 31 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/3eb47265/docs/src/reference/intro.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/reference/intro.asciidoc b/docs/src/reference/intro.asciidoc
index 2affc01..8fb82e3 100644
--- a/docs/src/reference/intro.asciidoc
+++ b/docs/src/reference/intro.asciidoc
@@ -67,7 +67,7 @@ link:http://en.wikipedia.org/wiki/Graph_traversal[traversal].
** `MapReduce`: a computations that analyzes all vertices in the graph in parallel and yields a single reduced result.
IMPORTANT: TinkerPop3 is licensed under the popular link:http://www.apache.org/licenses/LICENSE-2.0.html[Apache2]
-free software license. However, note that the underlying graph engine used with TinkerPop3 may have a difference
+free software license. However, note that the underlying graph engine used with TinkerPop3 may have a different
license. Thus, be sure to respect the license caveats of the graph system product.
image:tinkerpop-enabled.png[width=135,float=left] When a graph system implements the TinkerPop3 structure and process
@@ -92,7 +92,7 @@ between its vertices, edges, and properties. A vertex has incident edges. A vert
they share an incident edge. A property is attached to an element and an element has a set of properties. A property
is a key/value pair, where the key is always a character `String`. The graph structure API of TinkerPop3 provides the
methods necessary to create such a structure. The TinkerPop graph previously diagrammed can be created with the
-following Java8 code. Note that this graph is available as an in-memory TinkerGraph using
+following Java 8 code. Note that this graph is available as an in-memory TinkerGraph using
`TinkerFactory.createClassic()`.
[source,java]
@@ -122,20 +122,20 @@ with the provided key/value pair properties appended to it.
CAUTION: Many graph systems do not allow the user to specify an element ID and in such cases, an exception is thrown.
NOTE: In TinkerPop3, vertices are allowed a single immutable string label (similar to an edge label). This
-functionality did not exist in TinkerPop2. Likewise, element id's are immutable as they were in TinkerPop2.
+functionality did not exist in TinkerPop2. Element ids are still immutable in TinkerPop3 as they were in TinkerPop2.
Mutating the Graph
~~~~~~~~~~~~~~~~~~
-Below is a sequence of basic graph mutation operations represented in Java8. One of the major differences between
+Below is a sequence of basic graph mutation operations represented in Java 8. One of the major differences between
TinkerPop2 and TinkerPop3 is that in TinkerPop3, the Java convention of using setters and getters has been abandoned
in favor of a syntax that is more aligned with the syntax of Gremlin-Groovy in TinkerPop2. Given that Gremlin-Java8
-and Gremlin-Groovy are nearly identical due to the inclusion of Java8 lambdas, a big efforts was made to ensure that
+and Gremlin-Groovy are nearly identical due to the inclusion of Java 8 lambdas, a big effort was made to ensure that
both languages are as similar as possible.
CAUTION: In the code examples presented throughout this documentation, either Gremlin-Java8 or Gremlin-Groovy is used.
-It is possible to determine which derivative of Gremlin is being used by "mousing over" on the code block and see
-either "JAVA" or "GROOVY" pop up in the top right corner of the code block.
+It is possible to determine which derivative of Gremlin is being used by mousing over the code block. The word "JAVA"
+or "GROOVY" will appear in the top right corner of the code block.
image:basic-mutation.png[width=240,float=right]
[source,java]
@@ -207,7 +207,7 @@ gremlin> gremlin.addEdge('dependsOn',blueprints)
gremlin> blueprints.property('created',2010)
==>vp[created->2010]
gremlin> blueprints.property('created').remove()
-==>null
+==>null <1>
gremlin> gremlin.addEdge('encapsulates',blueprints)
==>e[7][0-encapsulates->3]
gremlin> blueprints.remove()
@@ -216,6 +216,9 @@ gremlin> gremlin.remove()
==>null
----
+<1> A `==>null` output is usually from a `void` method call and simply indicates that there was no problem with the
+invocation. If there were a problem, an error would be output or an exception would be thrown.
+
IMPORTANT: TinkerGraph is not a transactional graph. For more information on transaction handling (for those graph
systems that support them) see the section dedicated to <<transactions,transactions>>.
@@ -338,7 +341,7 @@ may alter the flow).
On Gremlin Language Variants
----------------------------
-Gremlin is written in Java8. There are various language variants of Gremlin such as Gremlin-Groovy (packaged with
+Gremlin is written in Java 8. There are various language variants of Gremlin such as Gremlin-Groovy (packaged with
TinkerPop3), link:https://github.com/mpollmeier/gremlin-scala[Gremlin-Scala], Gremlin-JavaScript, Gremlin-Clojure
(known as link:https://github.com/clojurewerkz/ogre[Ogre]), etc. It is best to think of Gremlin as a style of graph
traversing that is not bound to a particular programming language per se. Within a programming language familiar to
@@ -346,7 +349,7 @@ the developer, there is a Gremlin variant that they can use that leverages the i
a programming language providing a Gremlin implementation must support
link:http://en.wikipedia.org/wiki/Method_chaining[function chaining] (with
link:http://en.wikipedia.org/wiki/Anonymous_function[lambdas/anonymous functions] being a "nice to have" if the
-variants wishes to offer arbitrary computations beyond the provided Gremlin steps).
+variant wishes to offer arbitrary computations beyond the provided Gremlin steps).
Throughout the documentation, the examples provided are primarily written in Gremlin-Groovy. The reason for this is
the <<gremlin-console,Gremlin Console>> whereby an interactive programming environment exists that does not require
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/3eb47265/docs/src/reference/the-graph.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/reference/the-graph.asciidoc b/docs/src/reference/the-graph.asciidoc
index d03ca67..a97907b 100644
--- a/docs/src/reference/the-graph.asciidoc
+++ b/docs/src/reference/the-graph.asciidoc
@@ -63,17 +63,18 @@ pairs. Moreover, while an `Edge` can only have one property of key "name" (for e
"name" properties. With the inclusion of vertex properties, two features are introduced which ultimately advance the
graph modelers toolkit:
-. Multiple properties (*multi-properties*): a vertex property key can have multiple values (i.e. a vertex can have
-multiple "name" properties).
+. Multiple properties (*multi-properties*): a vertex property key can have multiple values. For example, a vertex can have
+multiple "name" properties.
. Properties on properties (*meta-properties*): a vertex property can have properties (i.e. a vertex property can
have key/value data associated with it).
-A collection of use cases are itemized below:
+Possible use cases for meta-properties:
. *Permissions*: Vertex properties can have key/value ACL-type permission information associated with them.
. *Auditing*: When a vertex property is manipulated, it can have key/value information attached to it saying who the
creator, deletor, etc. are.
-. *Provenance*: The "name" of a vertex can be declared by multiple users.
+. *Provenance*: The "name" of a vertex can be declared by multiple users. For example, there may be multiple spellings
+of a name from different sources.
A running example using vertex properties is provided below to demonstrate and explain the API.
@@ -180,15 +181,15 @@ important to note that the `Transaction` object does not represent a "transactio
methods for working with transactions (e.g. committing, rolling back, etc).
Most `Graph` implementations that `supportsTransactions` will implement an "automatic" `ThreadLocal` transaction,
-which means that when a read or write occurs after the `Graph` is instantiated a transaction is automatically
+which means that when a read or write occurs after the `Graph` is instantiated, a transaction is automatically
started within that thread. There is no need to manually call a method to "create" or "start" a transaction. Simply
modify the graph as required and call `graph.tx().commit()` to apply changes or `graph.tx().rollback()` to undo them.
When the next read or write action occurs against the graph, a new transaction will be started within that current
thread of execution.
When using transactions in this fashion, especially in web application (e.g. REST server), it is important to ensure
-that transaction do not leak from one request to the next. In other words, unless a client is somehow bound via
-session to process every request on the same server thread, ever request must be committed or rolled back at the end
+that transactions do not leak from one request to the next. In other words, unless a client is somehow bound via
+session to process every request on the same server thread, every request must be committed or rolled back at the end
of the request. By ensuring that the request encapsulates a transaction, it ensures that a future request processed
on a server thread is starting in a fresh transactional state and will not have access to the remains of one from an
earlier request. A good strategy is to rollback a transaction at the start of a request, so that if it so happens that
@@ -275,9 +276,9 @@ or other read operations executed in the context of that open transaction.
<7> Explicitly open a transaction.
<8> Adding a vertex now succeeds as the transaction was manually opened.
-NOTE: It may be important to consult the documentation of the `Graph` implementation when it comes to the specifics of
-how transactions will behave. TinkerPop allows some latitude in this area and implementations may not have the exact
-same behaviors and link:https://en.wikipedia.org/wiki/ACID[ACID] guarantees.
+NOTE: It may be important to consult the documentation of the `Graph` implementation you are using when it comes to the
+specifics of how transactions will behave. TinkerPop allows some latitude in this area and implementations may not have
+the exact same behaviors and link:https://en.wikipedia.org/wiki/ACID[ACID] guarantees.
Retries
~~~~~~~
@@ -387,10 +388,10 @@ for the serialization process, it is always best to utilize the methods on the `
have to be configured manually by the user to do the serialization.
It is up to the implementations of the `GraphReader` and `GraphWriter` interfaces to choose the methods they
-implement and the manner in which they work together. The only semantics enforced and expected is that the write
-methods should produce output that is compatible with the corresponding read method (e.g. the output of
+implement and the manner in which they work together. The only characteristic enforced and expected is that the write
+methods should produce output that is compatible with the corresponding read method. For example, he output of
`writeVertices` should be readable as input to `readVertices` and the output of `writeProperty` should be readable as
-input to `readProperty`).
+input to `readProperty`.
GraphML Reader/Writer
~~~~~~~~~~~~~~~~~~~~~
@@ -404,17 +405,18 @@ applications outside of TinkerPop, GraphML may be the best choice to do that. Co
* Produce a subgraph and export it to GraphML to be consumed by and visualized in link:https://gephi.org/[Gephi].
* Migrate the data of an entire graph to a different graph database not supported by TinkerPop.
-As GraphML is a specification for the serialization of an entire graph and not the individual elements of a graph,
-methods that support input and output of single vertices, edges, etc. are not supported.
+As GraphML is a specification for the serialization of an entire graph and not the individual elements of a graph.
+Methods that support input and output of single vertices, edges, etc. are not supported.
CAUTION: GraphML is a "lossy" format in that it only supports primitive values for properties and does not have
support for `Graph` variables. It will use `toString` to serialize property values outside of those primitives.
-CAUTION: GraphML, as a specification, allows for `<edge>` and `<node>` elements to appear in any order. The
-`GraphMLReader` will support that, however, that capability comes with a limitation. TinkerPop does not allow the
-vertex label to be changed after the vertex has been created. Therefore, if an `<edge>` element comes before the
-`<node>` the label on the vertex will be ignored. It is thus better to order `<node>` elements in the GraphML to
-appear before all `<edge>` elements if vertex labels are important to the graph.
+CAUTION: GraphML as a specification allows for `<edge>` and `<node>` elements to appear in any order. Most software
+that writes GraphML (including as TinkerPop's `GraphMLWriter`) write `<node>` elements before `<edge>` elements. However it
+is important to note that `GraphMLReader` will read this data in order and order can matter. This is because TinkerPop
+does not allow the vertex label to be changed after the vertex has been created. Therefore, if an `<edge>` element
+comes before the `<node>`, the label on the vertex will be ignored. It is thus better to order `<node>` elements in the
+GraphML to appear before all `<edge>` elements if vertex labels are important to the graph.
The following code shows how to write a `Graph` instance to file called `tinkerpop-modern.xml` and then how to read
that file back into a different instance:
@@ -769,5 +771,5 @@ leverage _qualified namespaces_ particular to their domain (e.g. `mydomain.myver
IMPORTANT: TinkerPop uses `tinkerpop.` and `gremlin.` as the prefixes for provided strategies, vertex programs, map
reduce implementations, and plugins.
-The only truly protected namespace is the _hidden namespace_ provided to graph systems. From there, its up to
+The only truly protected namespace is the _hidden namespace_ provided to graph systems. From there, it's up to
engineers to respect the namespacing conventions presented.