home.textile

LogiSima – Neo4j database support

This module allows you to use an embedded Neo4j database and managed your model with annotation (like JPA). This module is similar as Spring data neo4j, it’s the same philosophy.

Installation

Enabled Neo4j module

For play < 1.2

In the conf/application.conf file, enable LogiSima Neo4j module with this line :

    
    # The logisima play cas module
    module.neo4j=${play.path}/modules/neo4j-1.0RC1
    

For play >= 1.2

In the conf/dependencies.yml file, enable LogiSima Neo4j module depency by adding this line :

    
        require:    
          - play -> neo4j 1.0RC1
    

Module configuration

In the conf/application.conf file, you can specify the path of neo4j embedded database by adding this line (by default it’s “db”) :

    
        neo4j.path=dbProd
    

How to use it

Declare your model

To create a Model you just have to create a class that extend play.modules.neo4j.model.Neo4jModel, that’s all !
Exemple :

    
        public class User extends Neo4jModel {
            public String     login;
            public String     email;
            public String     firstname;
            public String     lastname;
        }
    

Supported types

Neo4j doesn’t support all kind of attributes (see http://docs.neo4j.org/chunked/snapshot/graphdb-neo4j-properties.html), so do my module. This is a list of supported (and tested) type :

• String
• Long (the object not the primitive type, see issue #11)
• java.util.Date
• Integer
• Boolean
• play.db.jpa.Blob

NB:In general, use Object instead of primitive type (Float vs float, Integer vs int, Boolean vs boolean …).

Basics methods

Models come with some basics methods :

• getByKey(Long key) : in neo4j there is no id field but a key one. It’s the unique identifier of the object. This key is automaticly generate by the module. You can retrieve an Model simly by calling the getByKey method. Exemple : User user = User.getByKey(3);
• save() : Save and index the object to the database
• delete() : Delete the object to the database
• findAll() : Retrieve all model object into the database. Becarefull there is no limitationwith this method. So if you have a million of object, this method return a million of object. Exemple : List<User> user = User.findAll();
• queryIndex() : Do a lucene query on a specific index, and return a list of Object that match your query. Exemple : List<User> user = User.queryIndex("lastname", "lastname:*s* AND firstname:*s*");

Add a relation to your model

To create a relation between a node and others, you have to :

• Create a field of type java.util.List
• Annotate your filed this the @Neo4jRelatedTo annotation and specify the name of the relation

Exemple :

    
        public class User extends Neo4jModel {
            public String     login;
            public String     email;
            public String     firstname;
            public String     lastname;
            
            @Neo4jRelatedTo("IS_FRIEND")
            public List<User> friends;
        }
    

With Neo4jRelatedTo annotation, you can also defined some attributes :

• lazy : like hibernate, you can do lazy loading for relation. By default, it’s value is “true” to avoid circular reference and avoid loop that produce “Java Heap Space”.
• direction :to specified the direction of the relation. By default, it’s OUTGOING, but you can change it to INCOMING or BOTH.

Create an index

You can create a neo4j index simply by adding an annotation on fields : @Neo4jIndex
Exemple :

    
        public class User extends Neo4jModel {
            public String     login;
            public String     email;
            
            @Neo4jIndex("name")
            public String     firstname;
            
            @Neo4jIndex("name")
            public String     lastname;
            
            @Neo4jRelatedTo("IS_FRIEND")
            public List<User> friends;
        }
    

This will create an index named name, and for each user when we save it, firstname and lastanme value will be index into name index.

Moreover, you can customize lucene configuration with the annotation :

• type: exact is the default value, it uses a Lucene keyword analyzer. fulltext type uses a white-space tokenizer in its analyzer
• lowerCase: This parameter goes together with type: fulltext and converts values to lower case during both additions and querying, making the index case insensitive. Defaults value is true.

Import / Export your database

Export

Neo4j module comes with a command line tool to export your database into an yml file. To do it, you just have to type this line into a console :

    play neo4j:export

By default, this will generate a file into your conf application folder with the name data.yml. Of course, you can change it. Type play neo4j:help to khnow how to do it.

Import

You can import an yml file into your database. To do it, yo can choose between :

• Commmand line, by calling play neo4j:import
• Java, by calling the load(String filename) method from play.modules.neo4j.util.Fixtures class. It will be usefull for unit test !

Yml format

The yml format for this module is very simple. There is two kind of “yml object” : model & relation.

For model, the format is the same as play! standard. First line contains the model class and an identifier. Other lne are simply attribute name with their value.

Exemple :

    
        User(User_2):
         login: ben
         email: logisima@gmail.com
         firstname: Benoît
         lastname: SIMARD
    

For relation, there is a special format. All relation must begin with Relation(id) where id is a unique identifier of the relation.
After, all relation must have three attributes :

• Type Correspond to the name of the relation
• From is the identifier of the start node
• To is the identifier of the end node

Exemple :

    
        Relation(15):
         Type: IS_A_COLLEAGE
         From: User_2
         To: User_1
    

See neo4j console

Neo4j get a console to browse the database and to get usefull informations. To see it, just type this url into your browser, and youo will see the console :

http://localhost:9000/@neo4j/console

NB:Console is only avaible when play! is in DEV mode !