7 Champ is an abstraction from underlying graph storage systems that A&AI would otherwise interface with.
12 Good ol' 'mvn clean install' does the trick.
17 Champ has CRUD methods for:
21 3) Partitions (subgraphs)
22 3) Indices (on object and relationship properties)
25 For each of these types, we offer builders and a more user-friendly fluent interface.
27 In the future we plan on adding in traversals, but at the moment that is outside the scope of Champ. If you have suggestions on how this should be implemented, we look forward to your pull request.
32 Champ ships with a simple in-memory implementation as well as a Titan implementation. We recommend the in-memory implementation for unit testing and prototyping. If you would like to have your implementation referenced in this readme, please create a pull-request. Please note that all implementations will reside in their own repository - not in the Champ repository.
39 The ChampAPI interface is basically just for tracking and properly shutting down multiple graph instances. If you need this functionality, use the ChampAPI. However, if you only ever access 1 graph, you may choose to use a single ChampGraph.
41 For getting started quickly, use the ChampAPI.Factory or ChampGraph.Factory to create either an In-memory implementation (for dev/test) or if you're running Titan locally, you can start a Titan instance. For complex environments, each ChampGraph implementation will vary - the Titan implementation is described below.
45 This is the meat and potatoes of Champ. It contains all of the CRUD methods mentioned above for Objects, Relationships, Partitions, Indices, and Schemas. Each implementation varies in how you instantiate it. The ones that ship with Champ are described below.
47 #### In-memory ChampGraph
52 final ChampGraph graph = ChampGraph.Factory.newInstance(ChampGraph.Type.IN_MEMORY, "someGraphName");
63 final ChampAPI api = ChampAPI.Factory.newInstance(ChampGraph.Type.IN_MEMORY);
64 final ChampGraph dogsGraph = api.getGraph("dogsGraph");
65 final ChampGraph catsGraph = api.getGraph("catsGraph");
67 api.shutdown(); //This will shutdown all graphs started by api.getGraph(String)
73 For a Titan instance running on top of Cassandra locally, simply:
76 final ChampGraph graph = ChampGraph.Factory.newInstance(ChampGraph.Type.TITAN, "dogsGraph");
86 final ChampAPI api = ChampAPI.Factory.newInstance(ChampGraph.Type.TITAN);
87 final ChampGraph dogsGraph = api.getGraph("dogsGraph");
88 final ChampGraph cats Graph = api.getGraph("catsGraph");
90 api.shutdown(); //This will shutdown all graph started by api.getGraph(String);
94 For more complex/customized configurations:
97 final ChampGraph graph = new TitanChampGraphImpl.Builder(graphName)
98 .property("storage.backend", "cassandrathrift")
99 .property("storage.hostname", "localhost")
103 The calls to .property(String, String) accept all configuration options found [here](http://s3.thinkaurelius.com/docs/titan/1.0.0/titan-config-ref.html)
105 You could also implement the ChampAPI interface to manage multiple graphs connected to this Titan cluster. See the ChampAPIImpl class for an example of how to do this.
109 #### Create a new object
113 .ofType("foo") //The "foo" type of object can be constrained by a ChampObjectConstraint
114 .withoutKey() //No key for this object indicates that the underlying Champ implementation should create this object
115 .withProperty("bar", "string") //Zero or more properties can be set on a ChampObject
116 .withProperty("baz", 30)
120 #### Copy an existing object
124 .from(foo) //'foo' is a reference to a ChampObject
126 .withProperty("pi", 3.14f)
130 #### Persisting an object
133 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
134 graph.storeObject(foo); //'foo' is a reference to a ChampObject
135 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
136 //Once your application is finished using it, call shutdown()
137 //to cleanup any loose ends
140 #### Retrieve an object
143 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
144 final Optional<ChampObject> object = graph.retrieveObject("329847"); //Note that the key is usually only known by virtue of previously storing/retrieving/querying it
153 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
154 final Stream<ChampObject> objects = graph.queryObjects(Collection.singletonMap("favoriteDog", "Ace"));
156 objects.close(); //You must close the stream when you are finished with it
161 ### Creating Relationships
163 #### Create a new relationship
165 In this example we create the relationship:
170 ChampRelationship.create()
176 .withProperty("name", "champ")
179 .ofType("dogPellets")
181 .withProperty("brand", "costco")
183 .withProperty("at", System.currentTimeMillis())
187 #### Persisting a relationship
190 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
191 graph.storeRelationship(champEatsCostcoFood); //'champEatsCostcoFood' is a reference to a ChampRelationship
192 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
193 //Once your application is finished using it, call shutdown()
194 //to cleanup any loose ends
197 #### Retrieving incident relationships
200 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
201 final Stream<ChampRelationship> relationships = graph.retrieveRelationships(ChampObject.create().withKey("foo").build());
203 relationships.close(); //You must close the stream when you are done with it
204 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
208 #### Querying relationship
211 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
212 final Stream<ChampRelationship> relationships = graph.queryRelationships(Collections.singletonMap("favoriteHydrant", 42);
214 relationships.close(); //You must close the stream when you are done with it
215 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
219 ### Creating partitions
220 #### Create a new partition
222 Champ partitions are subgraphs (i.e. a collection of objects and relationships)
223 ** Note: We are still in the proces of creating a fluent API for partitions **
227 ChampPartition.create()
246 ChampRelationship.create()
253 #### Persisting a partition
256 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
257 graph.storePartition(dogsOnMyBlock); //'dogsOnMyBlock' is a reference to a ChampPartition
258 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
259 //Once your application is finished using it, call shutdown()
260 //to cleanup any loose ends
264 #### Create an object index
267 ChampObjectIndex.create()
274 #### Create a relationship index
277 ChampRelationshipIndex.create()
278 .ofName("eatsAtTime")
284 #### Persisting an object index
287 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
288 graph.storeObjectIndex(dogName); //'dogName' is a reference to a ChampObjectIndex
289 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
290 //Once your application is finished using it, call shutdown()
291 //to cleanup any loose ends
294 #### Persisting a relationship index
297 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
298 graph.storeRelationshipIndex(eatsAtTime); //'eatsAtTime' is a reference to a ChampObjectIndex
299 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
300 //Once your application is finished using it, call shutdown()
301 //to cleanup any loose ends
303 #### Retrieving an object index
306 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
307 graph.retrieveObjectIndex("dogName");
312 #### Retrieving a relationship index
315 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
316 graph.retrieveRelationshipIndex("eatsAtTime");
324 The following schema restricts objects of type foo to have a required property "property1" as an Integer, and optional property "property2" as a String (Strings are the default type for object properties). It also restricts relationships of type bar to only be allowed to originate from the object type foo.
328 .withObjectConstraint()
330 .withPropertyConstraint()
331 .onField("property1")
332 .ofType(Integer.class)
335 .withPropertyConstraint()
336 .onField("property2")
340 .withRelationshipConstraint()
342 .withPropertyConstraint()
344 .ofType(String.class)
347 .withConnectionConstraint()
355 #### Persisting a schema
358 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
359 graph.storeSchema(neighborhoodDogsSchema); //'neighborhoodDogsSchema' is a reference to a ChampObjectIndex
360 graph.updateSchema(neighborhoodDogConstraint); //'neighborhoosDogConstraint' is a reference to a ChampObjectConstraint
361 graph.updateSchema(eatsAtConstraint); //'eatsAtConstraint' is a reference to a ChampRelationshipIndex
362 graph.shutdown(); //The ChampGraph is thread-safe, and only one needs to be created
363 //Once your application is finished using it, call shutdown()
364 //to cleanup any loose ends
367 #### Retrieving a schema
370 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
372 final ChampSchema schema = graph.retrieveSchema();
378 ### Champ Performance Testing
380 There is a jar-with-dependencies provided in maven that contains a performance test you can move around and get some idea of how well Champ is running on a cluster of your choice. At the moment, the test only runs against a Titan implementation.
382 #### Example running an in-memory test
386 java -cp champ-0.0.1-SNAPSHOT-jar-with-dependencies.jar org.onap.aai.champ.perf.ChampAPIPerformanceTest --champ.graph.type=IN_MEMORY
391 #### Example running a Titan test
393 Note that after the --champ.graph.type=TITAN parameter is provided, you may provide any configuration that is specified by Titan (see link above for the documentation)
397 java -cp champ-0.0.1-SNAPSHOT-jar-with-dependencies.jar org.onap.aai.champ.perf.ChampAPIPerformanceTest --champ.graph.type=TITAN --storage.backend=cassandrathrift --storage.hostname=localhost