Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

rationale in README updated

  • Loading branch information...
commit 3602ac4b6895e97f31c37337aaff19dc790a7d90 1 parent 21930ea
Jozef Wagner wagjo authored

Showing 1 changed file with 54 additions and 44 deletions. Show diff stats Hide diff stats

  1. +54 44 README.md
98 README.md
Source Rendered
@@ -9,73 +9,83 @@ use Blueprints interface.
9 9 ## Rationale
10 10
11 11 I've decided to create my own Neo4j wrapper, because I was not happy
12   -with the current state (01/2011) of existing ones. While I initially
  12 +with the current state _(01/2011)_ of existing ones. While I initially
13 13 forked from late
14 14 [hgavin/clojure-neo4j](http://github.com/hgavin/clojure-neo4j), I
15 15 quickly realized that drastic changes will be needed. This chapter
16 16 summarizes my motivation behind changes and decisions I made.
17 17
18   -I believe that wrappers are a sub-optimal solution. See some recent
19   -Clojure talks on protocols where they compare wrappers, monkey
20   -patching and protocols. Main problem with wrappers is that they are no
21   -longer original types so you will not be able to use existing
22   -functions which accept original type. That is why borneo works mainly
23   -with Neo4j classes (Node, Relationship), and does not automatically
24   -convert nodes to property maps.
  18 +I believe that adapters are a sub-optimal solution (see
  19 +[Chris Housers talk on the Expression
  20 +Problem](http://www.infoq.com/presentations/Clojure-Expression-Problem)). Problem
  21 +with adapters is that they are no longer original types so you will
  22 +not be able to use existing functions which accept original type. That
  23 +is why borneo works mainly with Neo4j classes _(Node,
  24 +Relationship)_, and does not automatically convert nodes to property
  25 +maps.
25 26
26 27 It is tedious to provide a connection for every operation on
27 28 database. That is why I chose to have a dedicated Var for storing
28 29 current connection. That of course brings several problems to the
29 30 scene. Sometimes you want to have a connection which is shared between
30 31 threads and sometimes you want to have parallel connections to
31   -multiple databases. (Embedded Neo4j does not allow for parallel
32   -connections to single database). Both cases are supported in
33   -borneo. You can use with-db! for a connection accessible from every
34   -thread, and by using with-local-db!, you can have a tread local
35   -connection. One drawback is that you cannot have both at one moment,
36   -so be careful.
37   -
38   -Because I like simple things (see Halloways talk on simplicity), I
39   -tried to provide functions that do simple things, simple. That is why
40   -properties handling function are divided into two separate ones, one for
41   -reading and one for mutating. I also provide some "compound"
42   -functions, like props, create-child! or delete-node!, but they are
43   -here only for convenience and their simple counterparts are also
44   -provided.
45   -
46   -While mentioned in previous section, I'd like to stress that I
47   -consider separation of mutable and immutable world very important in
  32 +multiple databases. _(Embedded Neo4j does not allow for parallel
  33 +connections to single database)_. Both cases are supported in
  34 +borneo. You can use
  35 +[with-db!](http://wagjo.github.com/borneo/borneo.core-api.html#borneo.core/with-db!)
  36 +for a connection accessible from every thread, and by using
  37 +[with-local-db!](http://wagjo.github.com/borneo/borneo.core-api.html#borneo.core/with-local-db!),
  38 +you can have a thread local connection. One drawback is that you
  39 +cannot have both at one moment, so be careful.
  40 +
  41 +Because I like simple things _(see [Stuart Halloways talk on
  42 +simplicity](http://clojure.blip.tv/file/4824610/))_, I tried to
  43 +provide simple functions. That is why properties handling function are
  44 +divided into two separate ones, one for reading and one for
  45 +mutating. I also provide some "compound" functions, like
  46 +[props](http://wagjo.github.com/borneo/borneo.core-api.html#borneo.core/props),
  47 +[create-child!](http://wagjo.github.com/borneo/borneo.core-api.html#borneo.core/create-child!)
  48 +or
  49 +[delete-node!](http://wagjo.github.com/borneo/borneo.core-api.html#borneo.core/delete-node!),
  50 +but they are here only for convenience and their simple counterparts
  51 +are also provided.
  52 +
  53 +While mentioned in previous section, I'd like to stress that
  54 +separation of mutable and immutable world is very important in
48 55 Clojure. That is why all mutable functions in borneo are clearly
49 56 separated from their read-only parts and cannot be used in
50   -transactions.
  57 +Clojure transactions.
51 58
52 59 I have added support for custom Returnable and Stop evaluators through
53   -protocols. I think it will allow for greater flexibility (see last
54   -example at the bottom of this page).
  60 +protocols. I think it will allow for greater flexibility _(see last
  61 +example at the bottom of this page)_.
55 62
56 63 Another thing I wanted very much in a Neo4j wrapper was to use
57 64 keywords instead of custom static types/enums, to feel more like you
58 65 are in Clojure and not in Java... It turned out to be fairly easy to
59 66 implement.
60 67
61   -All mutable operations are automatically wrapped in transactions (read
62   -only operations don't need transactions in recent Neo4j). By the way
  68 +All mutable operations are automatically wrapped in transactions _(read
  69 +only operations don't need transactions in recent Neo4j)_. By the way
63 70 Neo4j handles transactions, it should be pretty cheap to have nested
64   -transactions so you can use with-tx to group mutable operations into
65   -one big transactions if you need it. Needs some field testing to prove
66   -this design decision though.
67   -
68   -If you get properties for a node with props function, you fetch all
69   -properties at once. This may be very resource intensive, when you have
70   -large binary data stored in nodes properties. One big wish I had is to
71   -have some king of lazy PersistentMap, where value would be fetched on
72   -demand. I've thougt of using delay/lazy-seq on values to achieve that,
  71 +transactions so you can use
  72 +[with-tx](http://wagjo.github.com/borneo/borneo.core-api.html#borneo.core/with-tx)
  73 +to group mutable operations into one big transactions if you need
  74 +it. Needs some field testing to prove this design decision though.
  75 +
  76 +If you get properties for a node with
  77 +[props](http://wagjo.github.com/borneo/borneo.core-api.html#borneo.core/props)
  78 +function, you fetch all properties at once. This may be very resource
  79 +intensive, when you have large binary data stored in nodes
  80 +properties. One big wish I had is to have some king of lazy
  81 +PersistentMap, where value would be fetched on demand. I've thougt of
  82 +using delay/lazy-seq on values to achieve that,
73 83 but user would have to manually deref the value, which is not very
74   -intuitive and does not look good. I didn't have time to implement such
75   -lazy map by myself yet. This data structure could also allow for even
76   -less intrusive interface so you could work with data stored in Neo4j
77   -more like working with traditional Clojure map, without serious
78   -performance impact. Who knows. More hammock time needed.
  84 +intuitive and does not look good. This data structure could also allow
  85 +for even less intrusive interface so you could work with data stored
  86 +in Neo4j more like working with traditional Clojure map, without
  87 +serious performance impact. I didn't have time to seriously think
  88 +about this approach yet. More hammock time needed.
79 89
80 90 ## Usage
81 91

0 comments on commit 3602ac4

Please sign in to comment.
Something went wrong with that request. Please try again.