Getting Started
The Rexster distribution comes with a Grateful Dead dataset. The raw data is located here. This dataset is accompanied by a collection of traversals. These traversals are provided in order to help developers create custom traversers for their custom domain models. This section will describe the basics of loading up the Rexster web server and triggering the provided demo Grateful Dead traversals.
There is a shell script called rexster.sh. When that script is evaluated at the command line, it starts up the Rexster web server. Please be aware of the rexster.xml file that is provided with Rexster (see rexster.xml). It is possible to make use of different properties by calling
rexster.sh other.xml[INFO] WebServer - .:Welcome to Rexster:.
[INFO] GraphConfigurationContainer - Graph emptygraph - tinkergraph[vertices:0 edges:0] loaded
[INFO] GraphConfigurationContainer - Graph tinkergraph - tinkergraph[vertices:6 edges:6] loaded
[INFO] GraphConfigurationContainer - Graph gratefulgraph - tinkergraph[vertices:809 edges:8049] loaded
[INFO] GraphConfigurationContainer - Graph orientdbsample - not enabled and not loaded.
[INFO] GraphConfigurationContainer - Graph neo4jsample - not enabled and not loaded.
[INFO] RexsterApplication - loading traversal: /tinkergraph/traversal/gremlin [com.tinkerpop.rexster.traversals.gremlin.GremlinTraversal]
[INFO] RexsterApplication - loading traversal: /gratefulgraph/traversal/gremlin [com.tinkerpop.rexster.traversals.gremlin.GremlinTraversal]
[INFO] RexsterApplication - loading traversal: /gratefulgraph/traversal/grateful/co-follows-rank [com.tinkerpop.rexster.traversals.grateful.CoFollowsRank]
[INFO] RexsterApplication - loading traversal: /gratefulgraph/traversal/grateful/artist-rank [com.tinkerpop.rexster.traversals.grateful.ArtistRank]
[INFO] RexsterApplication - loading traversal: /gratefulgraph/traversal/grateful/singer-writer-rank [com.tinkerpop.rexster.traversals.grateful.SingerWriterRank]
[INFO] RexsterApplication - loading traversal: /gratefulgraph/traversal/grateful/follows-score [com.tinkerpop.rexster.traversals.grateful.FollowsScore]
[INFO] RexsterApplication - Traversal initialization completed.
[INFO] MapResultObjectCache - Cache constructed with a maximum size of 1000
[INFO] WebServer - Web Server configured with com..sun..jersey..config..property..packages: com.tinkerpop.rexster
[INFO] WebServer - Server running on http://localhost:8182
[INFO] WebServer - Hit <enter> to shutdown RexsterWhen the Rexster web server starts up, it makes use of the ServiceLoader pattern and loads all classes that implement the Traversal interface and are specified in the file (see com.tinkerpop.rexster.traversals.Traversal). These Traversal services are tied to the various graphs configured in the XML configuration file.
META-INF/services/com.tinkerpop.rexster.traversals.Traversal Once the graphs are loaded with their associated Traversal services, they can be interacted with through HTTP. It’s possible, at any time when the web server is loaded, to see the number of currently loaded graphs by dereferencing the base-URI http://localhost:8182/. The result of GETing this base-URI should look as follows:
{
"version":"0.1",
"name":"Rexster: A RESTful Graph Shell",
"graphs":["tinkergraph","gratefulgraph","emptygraph"],
"query_time":2.659367,
"up_time":"0[d]:00[h]:00[m]:04[s]"
}To see the Traversal services loaded for any given graph simple access http://localhost:8182/gratefulgraph where “gratefulgraph” is the unique graph name configured in the XML configuration file. The result of GETing this URI should appear as follows:
{
"version":"0.1",
"name":"gratefulgraph",
"graph":"tinkergraph[vertices:809 edges:8049]",
"query_time":0.756218,
"up_time":"0[d]:00[h]:02[m]:06[s]"
}A list of all Traversal services configured to a graph can be listed by referencing:
http://localhost:8182/{graphname}/traversals{
"version":"0.1",
"results":[
{"path":"grateful\/follows-score","class":"com.tinkerpop.rexster.traversals.grateful.FollowsScore"},
{"path":"grateful\/singer-writer-rank","class":"com.tinkerpop.rexster.traversals.grateful.SingerWriterRank"},
{"path":"grateful\/co-follows-rank","class":"com.tinkerpop.rexster.traversals.grateful.CoFollowsRank"},
{"path":"gremlin","class":"com.tinkerpop.rexster.traversals.gremlin.GremlinTraversal"},
{"path":"grateful\/artist-rank","class":"com.tinkerpop.rexster.traversals.grateful.ArtistRank"}
],
"total_size":5,
"query_time":3.48173
}The Traversal services loaded can be interacted with by dereferencing their URI and providing appropriate query parameters. With respect to Rexster, the important structural aspects of the URI are below.
http://localhost:8182/{graphname}/traversals/{traversal}?key1=value1&key2=value2The graphname component is the name of the graph. It must be unique within the configured set of graphs in the XML configuration file. The configured graphs may each be of any supported Blueprints implementations.
The traversal component is the name of the traversal (which directly references a Traversal class - e.g. grateful/co-follows-rank). The query parameters are provided after the ? component of the URI and are a set of key/value pairs called parameters. Each Traversal (by design) will have a set of key/value pairs that are used to parametrize the evaluated traversal.
Now that the basic structure of a URI is understood, the remainder of this section will demonstrate the evaluation of a provided Grateful Dead traversals. The CoFollowsRank traversal ranks all songs relative to a source song. The more songs that a song co-follows in common with the source song, the higher the ranking. Before evaluating the traversal for a particular song, lets view its API. To view the API of a traversal, simple deference the URI without an query parameters.
http://localhost:8182/gratefulgraph/traversals/grateful/co-follows-rank{
"message":"song not found",
"query_time":1,
"api":{
"description":"rank all songs relative to the source song by the number of times they co-follow the source song",
"parameters":{
"sort":"regular, reverse, or none sort the ranked results (default is none)",
"allow_cached":"allow a previously cached result to be provided (default is true)",
"sort_key":"the name of the element key to use in the sorting (default is the rank value)",
"song.<key>":"the source song, where <key> is the song vertex property key",
"return_keys":"the element property keys to return (default is to return all element properties)",
"offset.end":"the end integer of a page of results (default is infinity)",
"offset.start":"the start integer of a page of results (default is 0)"
}
},
"success":false
}Using the information in the provided API, it is possible to co-follows rank all songs relative to the song Dark Star, then reverse sort the results, and return only the top 10 songs.
http://localhost:8182/gratefulgraph/traversals/grateful/co-follows-rank?song.name=DARK%20STAR&return_key=name&sort=reverse&offset.end=10{
"version":"0.1",
"total_rank":1670,
"ranks":[
{"_type":"vertex","_id":"13","name":"PLAYING IN THE BAND","song_type":"original","performances":582,"type":"song","grateful\/co-follows-rank":27},
{"_type":"vertex","_id":"148","name":"THE OTHER ONE","song_type":"original","performances":583,"type":"song","grateful\/co-follows-rank":23},
{"_type":"vertex","_id":"153","name":"SUGAR MAGNOLIA","song_type":"original","performances":594,"type":"song","grateful\/co-follows-rank":21},
{"_type":"vertex","_id":"3","name":"NOT FADE AWAY","song_type":"cover","performances":531,"type":"song","grateful\/co-follows-rank":21},
{"_type":"vertex","_id":"101","name":"LET IT GROW","song_type":"original","performances":276,"type":"song","grateful\/co-follows-rank":21},
{"_type":"vertex","_id":"96","name":"DRUMS","song_type":"original","performances":1386,"type":"song","grateful\/co-follows-rank":21},
{"_type":"vertex","_id":"26","name":"PROMISED LAND","song_type":"cover","performances":427,"type":"song","grateful\/co-follows-rank":20},
{"_type":"vertex","_id":"187","name":"I KNOW YOU RIDER","song_type":"cover","performances":550,"type":"song","grateful\/co-follows-rank":20},
{"_type":"vertex","_id":"74","name":"UNCLE JOHNS BAND","song_type":"original","performances":332,"type":"song","grateful\/co-follows-rank":20},
{"_type":"vertex","_id":"21","name":"TRUCKING","song_type":"original","performances":519,"type":"song","grateful\/co-follows-rank":19}
],
"size":10,
"success":true,
"query_time":73.509876
}To shutdown the web server, simply hit <enter>. This will properly shutdown the graph and exit.
[INFO] WebServer - Shutting down Rexster
[INFO] RexsterApplication - Shutting down tinkergraph - tinkergraph[vertices:6 edges:6]
[INFO] RexsterApplication - Shutting down gratefulgraph - tinkergraph[vertices:809 edges:8049]
[INFO] RexsterApplication - Shutting down emptygraph - tinkergraph[vertices:0 edges:0]