Documenting work to rebase Titanium to use Archimedes.

[zmaril]

This isn't an issue so much as an ongoing log of the work to rebase Titanium to use Archimedes. Commit messages are only so helpful and there are definitely some undocumented philosophies present in Archimedes.

[zmaril]

The first thing to note is that Archimedes uses a var to store the current state being accessed. The reasoning being that while it might be useful in some cases to have methods that can take arbitrary graph objects as input, most of the time that will be over engineering in the extreme. I think that (tev/add-vertex) is just as clear as (tev/add-vertex g). archimedes.core has a macro called with-graph that can allow a developer to use an arbitrary graph whenever they want that addresses the arbitrary use case.

[zmaril]

Second, there will probably be more deletions than additions here. I'm using mikera/clojure-utils pull-all function that imports all of the functions and defs into a namespace from another namespace. That means that lots of code from archimedes will just be there in most of the namespaces. After the rebase is working, I'll go back and comment or use the import-fn and import-def commands to give a clearer picture of just what exactly is coming over from Archimedes.

[zmaril]

Namespaces work differently than in Archimedes than they do in Titanium.

• archimedes.vertex contains all of the functions for creating, updating, finding, and deleting vertices.
• archimedes.edge contains all of the functions for creating, updating, finding, deleting, and asking questions about edges.
• Both of the above libraries pull in archimedes.element and use all of the definitions in there as their own. It's a small distinction, but it becomes a pain to think about a vertex both as a vertex and as an element after a while. It's just a vertex and there should only be one namespace to deal with it as an object.
• archimedes.core has all of the functions that deal with the graph object itself. That means transaction management (see later comment) and functions for setting the *graph* var all live in there.
  *archimedes.io has ways of printing out and reading various file formats.

And that's about it. Those namespaces cover much of the core parts of the blueprints library. I've found this separation very useful in my own work and intend to carry this pattern over into Titanium. It will mean changing many parts of the library though and restructuring much of the testing. In particular, there is no way of copying the graph var over. That means you will need to reference archimedes.core/*graph* whenever you want to use it directly (not titanium.core/*graph*).

[zmaril]

Property keys and labels are keywords. Reasoning is not much more than aesthetics at this point. For property keys though, I've had a burning desire to be able to call (:prop v1) where v1 is a vertex object. That would be awesome.

[zmaril]

(ted/connect! v1 :label v2) looks better to me than (ted/connect! v1 v2 :label) and so that is how Archimedes works.

[zmaril]

TitanInMemoryGraph is getting removed in the next version of Titan it looks like and so most of the tests will have to be rewritten to use embedded cassandra or berkelydb.

[zmaril]

clojurewerkz.titanium.gpipe will be deleted and replaced with Ogre. clojurewerkz.titanium.elements will stick around and probably stay it's own namespace. It deals with abstract properties of elements and so isn't something I think of as associated with working with a vertex or an edge.

[zmaril]

Not touching clojurewerkz.titanium.query.

[zmaril]

Removing gpipe means that about half of clojurewerkz.titanium.conversion will be removed as well.

[zmaril]

I'll probably pull get-vertex, head-vertex, and tail-vertex into Archimedes as well. Those are Tinkerpop dependent. clojurewerkz.titanium.edges looks like it will be pretty empty.

[zmaril]

Same with most of the functions in clojurewerkz.titanium.vertices. Those all depend on Tinkerpop and can be abstracted out into Archimedes. There really isn't anything special about Titan vertices or edges yet that isn't exposed in the Tinkerpop API.

[zmaril]

Bring over https://github.com/zmaril/hermes/blob/master/src/hermes/type.clj would probably be smart as well.

[zmaril]

Take a look at Hermes source actually for how empty the library will be after it depends on Archimedes:
https://github.com/zmaril/hermes/tree/master/src/hermes

There is a huge amount of stuff that is just Tinkerpop.

[zmaril]

The most important thing coming in from Archimedes is transaction management.
https://github.com/zmaril/hermes/wiki/Transaction-Management

This lets us do awesome stuff like retry-transact!:
https://github.com/zmaril/hermes/blob/master/test/hermes/core_test.clj#L55

[michaelklishin]

Oh, fantastic, thanks for starting this discussion.

So, point by point:

• Having a var for implicit state is fine. Some ClojureWerkz projects do that, it works well in practice. For Titanium, binding should be more than sufficient for features such as explicit transactions.
• I'm not familiar with those tools but we don't mind reasonable and well maintained 3rd party dependencies.
• Namespaces organization sounds very similar to what Titanium has or at least what was the plan when I was designing namespaces. Sounds excellent.
• Agree on (ted/connect! v1 :label v2). I always wanted to do (ted/connect! v1 -label-> v2), possibly via a separate graph population DSL.
• For tests, if it's not hard, let try embedded Cassandra. Part of the appeal of Titan is that it can be backed by Cassandra and HBase. But if that takes more effort than it's worth, we'll just provide a few monger.testkit kind of functions to make working with BerkeleyDB and unique path generation trivial. ClojureWerkz Support depends on Guava that has very nice utilities for temporary directories.
• Agreed on gpipe.
• If some namespaces in Titanium largely copy Archimedes, feel free to pull functions from them and remove them altogether. We will simply update the docs.
• I did not get to the types, if you feel Hermes' implementation is nice and doesn't have much room for improvement, just bring it in as is.
• Having all Blueprints-related stuff in Archimedes makes total sense to me
• Again, I did not get to more sophisticated transaction operations before Titan 0.3 was announced. Sounds good. We may tweak the API a bit as I (for some reason I can't easily articulate) liked Titanium's API names a bit better.

Thanks Zach!