README.md

   1 Champ
   2 =====
   3
   4 What is Champ?
   5 --------------
   6
   7 Champ is an abstraction from underlying graph storage systems that A&AI would otherwise interface with.
   8
   9 Building Champ
  10 --------------
  11
  12 Good ol' 'mvn clean install' does the trick.
  13
  14 API Specification
  15 -----------------
  16
  17 Champ has CRUD methods for:
  18
  19 1) Objects
  20 2) Relationships
  21 3) Partitions (subgraphs)
  22 3) Indices (on object and relationship properties)
  23 4) Schemas
  24
  25 For each of these types, we offer builders and a more user-friendly fluent interface.
  26
  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.
  28
  29 API Implementations
  30 -------------------
  31
  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.
  33
  34 Usage
  35 -----
  36
  37 ### ChampAPI
  38
  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.
  40
  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.
  42
  43 ### ChampGraph
  44
  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.
  46
  47 #### In-memory ChampGraph
  48
  49 Simply:
  50
  51 ```
  52 final ChampGraph graph = ChampGraph.Factory.newInstance(ChampGraph.Type.IN_MEMORY, "someGraphName");
  53
  54 //Do stuff with graph
  55
  56 graph.shutdown();
  57
  58 ```
  59
  60 or:
  61
  62 ```
  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");
  66
  67 api.shutdown(); //This will shutdown all graphs started by api.getGraph(String)
  68
  69 ```
  70
  71 #### Titan ChampGraph
  72
  73 For a Titan instance running on top of Cassandra locally, simply:
  74
  75 ```
  76 final ChampGraph graph = ChampGraph.Factory.newInstance(ChampGraph.Type.TITAN, "dogsGraph");
  77
  78 //Do stuff with graph
  79
  80 graph.shutdown();
  81
  82 ```
  83 or:
  84
  85 ```
  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");
  89
  90 api.shutdown(); //This will shutdown all graph started by api.getGraph(String);
  91
  92 ```
  93
  94 For more complex/customized configurations:
  95
  96 ```
  97         final ChampGraph graph = new TitanChampGraphImpl.Builder(graphName)
  98                                                         .property("storage.backend", "cassandrathrift")
  99                                                         .property("storage.hostname", "localhost")
 100                                                         .build();
 101 ```
 102
 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)
 104
 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.
 106
 107 ### Creating Objects
 108
 109 #### Create a new object
 110
 111 ```
 112 ChampObject.create()
 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)
 117            .build()
 118 ```
 119
 120 #### Copy an existing object
 121
 122 ```
 123 ChampObject.create()
 124            .from(foo) //'foo' is a reference to a ChampObject
 125            .withoutKey()
 126            .withProperty("pi", 3.14f)
 127            .build()
 128 ```
 129
 130 #### Persisting an object
 131
 132 ```
 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
 138 ```
 139
 140 #### Retrieve an object
 141
 142 ```
 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
 145
 146 graph.shutdown();
 147
 148 ```
 149
 150 #### Query objects
 151
 152 ```
 153 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
 154 final Stream<ChampObject> objects = graph.queryObjects(Collection.singletonMap("favoriteDog", "Ace"));
 155
 156 objects.close(); //You must close the stream when you are finished with it
 157 graph.shutdown();
 158
 159 ```
 160
 161 ### Creating Relationships
 162
 163 #### Create a new relationship
 164
 165 In this example we create the relationship:
 166
 167 dog eats dogPellets
 168
 169 ```
 170 ChampRelationship.create()
 171                  .ofType("eats")
 172                  .withoutKey()
 173                  .withSource()
 174                         .ofType("dog")
 175                         .withoutKey()
 176                         .withProperty("name", "champ")
 177                         .build()
 178                  .withTarget()
 179                         .ofType("dogPellets")
 180                         .withoutKey()
 181                         .withProperty("brand", "costco")
 182                         .build()
 183                  .withProperty("at", System.currentTimeMillis())
 184                  .build()
 185 ```
 186
 187 #### Persisting a relationship
 188
 189 ```
 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
 195 ```
 196
 197 #### Retrieving incident relationships
 198
 199 ```
 200 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
 201 final Stream<ChampRelationship> relationships = graph.retrieveRelationships(ChampObject.create().withKey("foo").build());
 202
 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
 205
 206 ```
 207
 208 #### Querying relationship
 209
 210 ```
 211 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
 212 final Stream<ChampRelationship> relationships = graph.queryRelationships(Collections.singletonMap("favoriteHydrant", 42);
 213
 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
 216
 217 ```
 218
 219 ### Creating partitions
 220 #### Create a new partition
 221
 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 **
 224
 225
 226 ```
 227 ChampPartition.create()
 228               .withObject(
 229                         ChampObject.create()
 230                                    .ofType("dog")
 231                                    .withoutKey()
 232                                    .build()
 233               )
 234               .withObject(
 235                         ChampObject.create()
 236                                    .ofType("cat")
 237                                    .withoutKey()
 238                                    .build()
 239               .withObject(
 240                         ChampObject.create()
 241                                    .ofType("bird")
 242                                    .withoutKey()
 243                                    .build()
 244               )
 245               .withRelationship(
 246                         ChampRelationship.create()
 247                                                 ...
 248                                          .build()
 249               )
 250               .build()
 251 ```
 252
 253 #### Persisting a partition
 254
 255 ```
 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
 261 ```
 262
 263 ### Creating indices
 264 #### Create an object index
 265
 266 ```
 267 ChampObjectIndex.create()
 268                 .ofName("dogName")
 269                 .onType("dog")
 270                 .forField("name")
 271                 .build()
 272 ```
 273
 274 #### Create a relationship index
 275
 276 ```
 277 ChampRelationshipIndex.create()
 278                       .ofName("eatsAtTime")
 279                       .onType("eats")
 280                       .forField("at")
 281                       .build()
 282 ```
 283
 284 #### Persisting an object index
 285
 286 ```
 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
 292 ```
 293
 294 #### Persisting a relationship index
 295
 296 ```
 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
 302 ```
 303 #### Retrieving an object index
 304
 305 ```
 306 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
 307 graph.retrieveObjectIndex("dogName");
 308 graph.shutdown();
 309
 310 ```
 311
 312 #### Retrieving a relationship index
 313
 314 ```
 315 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
 316 graph.retrieveRelationshipIndex("eatsAtTime");
 317 graph.shutdown();
 318
 319 ```
 320
 321 ### Creating schemas
 322 #### Create a schema
 323
 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.
 325
 326 ```
 327 ChampSchema.create()
 328         .withObjectConstraint()
 329                 .onType("foo")
 330                 .withPropertyConstraint()
 331                         .onField("property1")
 332                         .ofType(Integer.class)
 333                         .required()
 334                         .build()
 335                 .withPropertyConstraint()
 336                         .onField("property2")
 337                         .optional()
 338                         .build()
 339                 .build()
 340         .withRelationshipConstraint()
 341                 .onType("bar")
 342                 .withPropertyConstraint()
 343                         .onField("at")
 344                         .ofType(String.class)
 345                         .optional()
 346                         .build()
 347                 .withConnectionConstraint()
 348                         .sourcedFrom("foo")
 349                         .targetToAny()
 350                         .build()
 351                 .build()
 352         .build();
 353 ```
 354
 355 #### Persisting a schema
 356
 357 ```
 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
 365 ```
 366
 367 #### Retrieving a schema
 368
 369 ```
 370 final ChampGraph graph = ChampGraph.Factory.newInstance(graphType, "neighborhoodDogsGraph");
 371
 372 final ChampSchema schema = graph.retrieveSchema();
 373
 374 graph.shutdown();
 375
 376 ```
 377
 378 ### Champ Performance Testing
 379
 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.
 381
 382 #### Example running an in-memory test
 383
 384 ```
 385
 386 java -cp champ-0.0.1-SNAPSHOT-jar-with-dependencies.jar org.openecomp.aai.champ.perf.ChampAPIPerformanceTest --champ.graph.type=IN_MEMORY
 387
 388
 389 ```
 390
 391 #### Example running a Titan test
 392
 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)
 394
 395 ```
 396
 397 java -cp champ-0.0.1-SNAPSHOT-jar-with-dependencies.jar org.openecomp.aai.champ.perf.ChampAPIPerformanceTest --champ.graph.type=TITAN --storage.backend=cassandrathrift --storage.hostname=localhost
 398
 399
 400 ```