diff --git a/src/docbkx/reference/neo4j-server.xml b/src/docbkx/reference/neo4j-server.xml index d9f26aef1..491eb8fd1 100644 --- a/src/docbkx/reference/neo4j-server.xml +++ b/src/docbkx/reference/neo4j-server.xml @@ -3,107 +3,113 @@ Neo4j Server - Neo4j is not only available in embedded mode, it can also be installed and run as a server that is accessed - via a REST API. Spring Data Graph provides two-fold integration for infrastructure. + Neo4j is not only available in embedded mode. It can also be installed and run as a stand-alone server + accessible via a REST API. Developers can integrate Spring Data Graph into the Neo4j server infrastructure + in two ways: in an unmanaged server extension, or via the REST API.
Server Extension - What is the use-case for writing server extensions? The REST API is a pretty generic representation of the - Neo4j core API. It is nice for getting started and simple scenarios. For more involved solutions that require - high speed and high volume access to the embedded graph database, writing a server extension that is able to - process external parameters and return just the relevant information to the calling client is preferrable. + When should you write a server extension? The default REST API is essentially a REST'ified representation + of the Neo4j core API. It is nice for getting started, and for simpler scenarios. For more involved + solutions that require high-volume access or more complex operations, writing a server extension that + is able to process external parameters, do all the computations locally in the plugin, and then return + just the relevant information to the calling client is preferable. - The Neo4j server has two built in extension mechanisms. - It is possible to add extensions to existing endpoints - like the graph database, nodes or relationships - add new URIs or methods to those. This is achieved by - writing Server Plugins. + The Neo4j Server has two built-in extension mechanisms. It is possible to extend existing URI endpoints + like the graph database, nodes, or relationships, adding new URIs or methods to those. This is achieved + by writing a server plugin. + This plugin type has some restrictions though. - For complete freedom in your implementation an unmanaged extension - might be the right solution. Unmanaged - extensions are Jersey resource implementations. - The resources constructors or methods can get the GraphDatabaseService injected to execute the - necessary operations and return appropriate Representations. + For complete freedom in the implementation, an + unmanaged extension + can be used. Unmanaged extensions are essentially Jersey + resource implementations. The resource constructors or methods can get the + GraphDatabaseService injected to execute the necessary operations and return appropriate + Representations. - Both kinds of extensions have to be packaged as a jar and added to the Neo4j-Server's plugin directory. - Server Plugins are picked up at server startup when they provide the necessary - META-INF.services/org.neo4j.server.plugins.ServerPlugin file for Javas service loader mechanism. - Unmanaged extensions have to be registered with the Neo4j Server configuration. - + Both kinds of extensions have to be packaged as JAR files and added to the Neo4j Server's plugin + directory. Server Plugins are picked up by the server at startup if they provide the necessary + META-INF.services/org.neo4j.server.plugins.ServerPlugin file for Java's ServiceLoader + facility. Unmanaged extensions have to be registered with the Neo4j Server configuration. + + Configuring an unmanaged extension + + - Running Spring Data Graph on the server is easy. You need to tell the server where to find the Spring Context - file, and which beans from it to expose, using what type: - + Server plugin initialization + - Now, your resources can be annotated with the beans they need, like this: - - - The SpringPluginInitializer merges the graph database service - with the spring configuration and registers the named beans as jersey Injectables. - It is still necessary to list the initializer fully qualified class name in a - file named META-INF/services/org.neo4j.server.plugins.PluginLifecycle. Then the Neo4j Server can pick up - and run the initialization classes before the the extensions are loaded. + + + Now, your resources can be annotated with the beans they need, like this: + + Jersey resource + + + The SpringPluginInitializer merges the GraphDatabaseService with the Spring configuration + and registers the named beans as Jersey Injectables. It is still necessary to list the + initializer's fully qualified class name in a file named + META-INF/services/org.neo4j.server.plugins.PluginLifecycle. The Neo4j Server can then pick + up and run the initialization classes before the extensions are loaded.
- Using Spring Data Graph as a REST-Client + Using Spring Data Graph as a REST client - Spring Data Graph can use the Java Rest Bindings which come as a drop in replacement for the - GraphDatabaseService API. Just by configuring the graphDatabaseService to be a - RestGraphDatabaseService pointing to the correct URL, a Neo4j-REST server can be used. + Spring Data Graph can use a set of Java REST bindings which come as a drop in replacement for the + GraphDatabaseService API. By simply configuring the graphDatabaseService to be a + RestGraphDatabase pointing to a Neo4j Server instance. - The Neo4j REST API does not allow keeping transactions open, which means that SDG is not transactional - when running against REST. + The Neo4j Server REST API does not allow for transactions to span across requests, which means + that Spring Data Graph is not transactional when running with a RestGraphDatabase. - To set up your project to use the REST bindings, add this dependency to your pom.xml: - - REST-Client configuration - pom.xml - - org.springframework.data - spring-data-neo4j-rest - 1.0.0.RC1 + To set up your project to use the REST bindings, add this dependency to your pom.xml: + + REST client configuration - pom.xml + + org.springframework.data + spring-data-neo4j-rest + 1.0.0.RC1 ]]> - - Now, you set up the normal SDG configuration, but point the database to an URL instead of a local file, like this: - - REST-Client configuration - application context - + + Now, you set up the normal Spring Data Graph configuration, but point the database to an URL instead + of a local directory, like so: + + REST client configuration - application context + ]]> - - Your project is now set up to work against a remote Neo4j Server. + + Your project is now set up to work against a remote Neo4j Server.