Getting Started Guide

From NeoWiki

Jump to: navigation, search

This document will guide you through your very first Neo application. It assumes that you're familiar with Java development and with the basic Neo concepts (for example as described on the Neo4j front page). The whole tutorial will take roughly 10 minutes out of your life and at the end, you will have written, compiled and run a simple but complete "hello world"-like application based on Neo. If you're impatient, check out the compressed Getting Started In One Minute Guide.

Let's get started!

Contents

[edit] Download the jar file and add it to your classpath

[edit] If you use Maven

If you use Maven2, simply add Neo as a dependency after you've enabled the neo4j m2 repository in your POM. In your pom.xml, add the following: 

<project>
...
   <repositories>
      <repository>
         <id>neo4j-public-repository</id>
         <url>http://m2.neo4j.org</url>
      </repository>
   </repositories>
...
   <dependencies>
      <dependency>
         <groupId>org.neo4j</groupId>
         <artifactId>neo</artifactId>
         <version>SOME_VERSION</version> <!-- for example 1.0-b6 -->
      </dependency>
      ...
   </dependencies>
...
</project>

See also a complete example. To see valid releases, check http://neo4j.org/download or browse to the m2 repository with your web browser.

The book Better Builds with Maven is a good starting point if you want to begin using Maven but find the official documentation overwhealming.

[edit] If you don't use Maven

First, download the latest Neo jar from the download page. Second, add it to your classpath as appropriate in your environment: append to -classpath if you use the bare JDK tools, add to a lib/ dir if you use ant, right-click and add to build path in Eclipse, etc. Neo has a dependency on the Java Transaction API, so add the JTA jar to your classpath as well (it's included in the distro). This step is completed when you can import import classes from the org.neo4j.api.core package without any compilation errors.

[edit] Initialize and start an EmbeddedNeo instance

Neo is an embedded database, which means that it runs in the same JVM as your application. You start Neo by creating an instance of the EmbeddedNeo class. The EmbeddedNeo constructor takes an argument of a directory for storing data files. The directory is simply a string defining a directory relative to the JVM's current working directory. It will be created if it doesn't already exist.

Remember from the introduction that a Neo node space consists of three basic elements: nodes, relationships that connect nodes and properties attached to both nodes and relationships. All relationships have a type, for example if the node space represents a social network, a relationship type could be KNOWS. If a relationship of the type KNOWS connects two nodes, that probably represents two people that know each other. A lot of the semantics, the meaning, of a node space is encoded in the relationship types of the application.

For our small example, we need only one relationship type and here's how we define it: 

public enum MyRelationshipTypes implements RelationshipType
{
    KNOWS
}

Then we should embed Neo into our aplication as follows: 

NeoService neo = new EmbeddedNeo( "var/neo" );

When the constructor returns, Neo has started and immediately loaded the data files in the directory "var/neo" (if the directory doesn't exist, Neo will create and initialize it). All we need to remember is to shutdown Neo before exiting: 

neo.shutdown();

We're set to go!

[edit] Create a small node space

Now, let's create a few nodes. The API is very intuitive. Feel free to have a look at the javadocs at http://api.neo4j.org/current (they're included in the distribution as well). Here's how to create a small node space consisting of two nodes connected with one relationship and some properties: 

Node firstNode = neo.createNode();
Node secondNode = neo.createNode();
Relationship relationship = firstNode.createRelationshipTo( secondNode, MyRelationshipTypes.KNOWS );

firstNode.setProperty( "message", "Hello, " );
secondNode.setProperty( "message", "world!" );
relationship.setProperty( "message", "brave Neo " );

We now have a node space that looks like this: 

(firstNode )---KNOWS--->(secondNode)

[edit] Wrap everything in a transaction

We done? No. The above code snippets will compile, but they will not run. Neo will reject them immediately because they're not part of a transaction. This is a conscious design decision, since we believe transaction demarcation to be an important part of working with a real enterprise database. Now, transaction handling in Neo is very easy: 

Transaction tx = Transaction.begin();
try
{
   // all Neo operations that work with the node space, for example:
   // Node firstNode = neo.createNode();
   // ... etc ...
   tx.success();
}
finally
{
   tx.finish();
}

The tx.finish() method will either commit or rollback the transaction. It decides what to do based on whether tx.success() or tx.failure() has been invoked previously. A transaction is assumed to be a failure until tx.succses() is explicitly invoked, which means that the finally block in the above idiom will commit the transaction only if the last statement in the try block (tx.success()) has been invoked. If an exception is thrown anywhere before then, the transaction will be rolled back.

[edit] Print the result

After we've created our node space, let's read from it and print the result. 

System.out.print( firstNode.getProperty( "message" ) );
System.out.print( relationship.getProperty( "message" ) );
System.out.print( secondNode.getProperty( "message" ) );

Running this code will give the following output: 

Hello, brave Neo world!

[edit] Conclusion

Ok, our 10 minutes are out! The full source code for this short example is here. Now you are familiar with how to build a node space -- one of the two fundamentals of Neo (the other being the traverser framework). How to proceed from here?

  • Your next stop is definitely the basic code snippets PDF, which through a few slides will give you a code-level introduction to the traverser framework.
  • There are some articles linked to from http://neo4j.org/doc that introduce the high level concepts of Neo. They're from 2 to 8 pages and they do a pretty good of putting the concepts into perspective but also include some source code level details.
  • The NeoShell is an interactive command-line tool for browsing the node space. Very useful during development! Check out the NeoShell guide.
  • Sign up to the mailing list and ask questions. We love questions, particularly from Neo newcomers!
  • Lastly, the Main Page tries to gather most of our documentation in one place.
Retrieved from "http://wiki.neo4j.org/content/Getting_Started_Guide"
Personal tools