1.2.2. Setting up a plugin project

This section describes how to prepare a project for writing user-defined procedures and functions for Neo4j.

The example described in this section is available as a repository on GitHub. To get started quickly you can fork the repository and work with the code as you follow along in the guide below.

The following example shows the steps to create and deploy a new procedure:

  1. Set up a project with Maven.

    A project can be set up in any way that allows for compiling a procedure and producing a jar file. Below is an example configuration using the Maven build system. For readability, only excerpts from the Maven pom.xml file are shown here, the whole file is available from the Neo4j Procedure Template repository.

    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                         http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
    
     <groupId>org.neo4j.example</groupId>
     <artifactId>procedure-template</artifactId>
     <version>1.0.0-SNAPSHOT</version>
    
     <packaging>jar</packaging>
     <name>Neo4j Procedure Template</name>
     <description>A template project for building a Neo4j Procedure</description>
    
     <properties>
       <neo4j.version>3.5.12</neo4j.version>
     </properties>
  2. Define build dependencies.

    1. Add a dependency section that includes the procedure and function APIs, which procedures and functions use at runtime.

      The scope is set to provided, because once the procedure is deployed to a Neo4j instance, this dependency is provided by Neo4j. If non-Neo4j dependencies are added to the project, their scope should normally be compile.

         <dependency>
           <groupId>org.neo4j</groupId>
           <artifactId>neo4j</artifactId>
           <version>${neo4j.version}</version>
           <scope>provided</scope>
         </dependency>
    2. Add dependencies that are necessary for testing the procedure.

      • Neo4j Harness, a utility that allows for starting a lightweight Neo4j instance. It is used to start Neo4j with a specific procedure or function deployed, which greatly simplifies testing.
      • The Neo4j Java driver, used to send Cypher statements that call the procedure or function.
      • JUnit, a common Java test framework.

           <dependency>
             <groupId>org.neo4j.test</groupId>
             <artifactId>neo4j-harness</artifactId>
             <version>${neo4j.version}</version>
             <scope>test</scope>
           </dependency>
        
           <dependency>
             <groupId>org.neo4j.driver</groupId>
             <artifactId>neo4j-java-driver</artifactId>
             <version>1.7.5</version>
             <scope>test</scope>
           </dependency>
        
           <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
             <version>4.12</version>
             <scope>test</scope>
           </dependency>
  3. Define the steps that Maven will go through to build the project.

    The goal is first to compile the source, then to package it in a jar that can be deployed to a Neo4j instance.

    Procedures and functions require at least Java 8, so the version 1.8 should be defined as the source and target version in the configuration for the Maven compiler plugin.

    The Maven Shade plugin is used to package the compiled procedure. It also includes all dependencies in the package, unless the dependency scope is set to test or provided.

    Once the procedure has been deployed to the plugins directory of each Neo4j instance and the instances have restarted, the procedure is available for use.

      <build>
       <plugins>
         <plugin>
           <artifactId>maven-compiler-plugin</artifactId>
           <version>3.1</version>
           <configuration>
             <source>1.8</source>
             <target>1.8</target>
           </configuration>
         </plugin>
         <plugin>
           <artifactId>maven-shade-plugin</artifactId>
           <executions>
             <execution>
               <phase>package</phase>
               <goals>
                 <goal>shade</goal>
               </goals>
             </execution>
           </executions>
         </plugin>
       </plugins>
      </build>