{"__v":0,"_id":"57d3bad9a50e780e008e40ac","category":{"project":"566c97797831040d003eb3bc","version":"566c97797831040d003eb3bf","_id":"57cd74d2873de50e00724a2f","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-09-05T13:36:18.948Z","from_sync":false,"order":5,"slug":"extending-neo4j","title":"Extending Neo4j"},"parentDoc":null,"project":"566c97797831040d003eb3bc","user":"57167c775d90dc170060ef97","version":{"__v":10,"_id":"566c97797831040d003eb3bf","project":"566c97797831040d003eb3bc","createdAt":"2015-12-12T21:54:01.970Z","releaseDate":"2015-12-12T21:54:01.970Z","categories":["566c977a7831040d003eb3c0","5716338cb5af590e00a0ff1d","57163947893cbe0e002d75fc","57163f41b5af590e00a0ff35","57cd74d2873de50e00724a2f","57cd7de8baaee30e0093ecc3","57d6ada046dcc30e007dd15e","57fdc2b31646dc0e0010480a","57fdd8b86c9d141900d87bf1","58767da4d89ef20f003b6f1e"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-10T07:48:41.089Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Server extensions allow new surfaces to be created in the REST API. Use them if you want fine-grained control over your application's interactions with Neo4j than Cypher provides.\n\nTo know more about how to write and test your extensions please read the [Neo4j unmanaged server extensions documentation](http://neo4j.com/docs/java-reference/current/#server-unmanaged-extensions).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Please be careful with server extensions. You will be able to deploy JAX-RS classes to the server and it’s easy to consume lots of heap space and degrade performance.\\n\\n**We highly encourage to test your server extensions in staging environments before uploading them into production.**\",\n  \"title\": \"Keep in mind\"\n}\n[/block]\nOnce you have written or downloaded an extension, you will need to pack it in a compressed file. As part of the compressed file you’ll need to add a neo4j-server.properties file, where you’ll put all the needed configuration for your extension,  such as where Neo4j will look for it.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"org.neo4j.server.thirdparty_jaxrs_classes=com.graphaware.server=/graphaware\",\n      \"language\": \"text\",\n      \"name\": \"Before Neo4j 3.0\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"dbms.unmanaged_extension_classes=com.graphaware.server=/graphaware\",\n      \"language\": \"text\",\n      \"name\": \"As of Neo4j 3.0\"\n    }\n  ]\n}\n[/block]\n### Further considerations\n\nPlease take the following considerations into account while preparing your server extension to be uploaded:d\n\n- Supported formats: zip, tar, cpio, gz, bz2 and xz.\n- Size is limited to 100MB.\n- A file can contain multiple .jar files in the top-level directory.\n- Only files with jar format or neo4j-server.properties are extracted, the rest will be ignored.\n- If a neo4j-server.properties file is found, its content is added to the neo4j-server.properties of the Neo4j process.\n- neo4j-server.properties can contain $PLUGIN_ROOT, which will be replaced with the path of the plug-in. This can be used to reference files in the archive.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Graphaware extensions use a neo4j.properties file instead of a neo4j-server.properties file for their configuration. **GrapheneDB takes care of this for you automatically**. Read more in [Graphaware extensions section](#section-graphaware-server-extensions).\",\n  \"title\": \"Note\"\n}\n[/block]\n## Adding server extensions\n\nFollow these instructions to add a new server extension to your database:\n\n1. Navigate to the *Extensions* tab of your database dashboard, and click on the *New server extension* button from the dropdown menu *New extension*.\n2. Name your extension in order to be able to identify it afterwards.\n3. Select the compressed file from your local path and click. \n4. **Do not close your browser window!** The upload will stop if you close your browser. If the upload fails, you can click on the *Retry* button to start it again. \n5. When the upload completes successfully, you will see a new row in your Extensions list with the status *ENABLED - PENDING*.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5b0a792-server_extensions_enable.png\",\n        \"server_extensions_enable.png\",\n        959,\n        191,\n        \"#5d9ab3\"\n      ]\n    }\n  ]\n}\n[/block]\n6. Before the extension can be available for use, it is necessary to restart the database. To perform this operation, click on the *Apply changes* button.\n7. A new window will show you a list of the changes you are going to perform. Please review them and click on *Apply changes*.\n\nOnce the changes are applied, you will see the final status (*ENABLED or DISABLED*) in the list.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Server extensions and stored procedures are shown together in your Extensions list.\",\n  \"title\": \"Note\"\n}\n[/block]\n## Remove unmanaged server extensions\n\nTo remove your unmanaged server extensions, navigate to the *Extensions* tab of your database dashboard,  and just click on the *Remove* link next to the extension.\n\nTo remove an extension, it should be DISABLED before you can perform this operation.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Danger\",\n  \"body\": \"This action cannot be undone and will delete your server extension permanently.\"\n}\n[/block]\n## GraphAware server extensions\n\nGraphAware is a Neo4j Solution Partner that specializes in Neo4j consultancy, training, and development. They develop open-source tools and generic graph database extensions. Below, you can find more specific information about how to integrate GraphAware extensions.\n\n### Downloading GraphAware extensions\n\nTake into account that you will need to download a compatible version for your database. You can see all the available versions by clicking on the *Older Versions* link. For instance if your database is running Neo4j 2.2.4, you will need to look for a 2.2.4 version of your GraphAware extension.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bb96f75-graphaware.png\",\n        \"graphaware.png\",\n        562,\n        309,\n        \"#d3d8dc\"\n      ]\n    }\n  ]\n}\n[/block]\n### Configure your GraphAware extension\n\nPlease read the extension readme file carefully. This file will contain all of the needed instructions on how to configure the extension properly. \n\nGraphAware extensions use neo4j.properties instead of neo4j-server.properties because their extensions work both in Server as well as in Embedded mode. You don't have to worry about that, because when a GraphAware plugin is detected, the proper properties file will be used.\n\nBefore uploading to GrapheneDB, please ensure you have packaged the extension tarball, the neo4j.properties file, and the framework tarball (if it's required) in a valid format (zip, tar, cpio, gz, bz2 or xz).\n\n### Add your GraphAware extension\n\nFollow the steps described in [Server extensions](doc:server-extensions) to upload and enable the GraphAware extension.\n\n## Spatial server extension\n\nNeo4j Spatial is a library of utilities for Neo4j that facilitates the enabling of spatial operations on data. Source page: https://github.com/neo4j-contrib/spatial\n\nFor some versions of Neo4j, GrapheneDB comes out of the box with the spatial server extension installed.\n\nIf you want to use it, you need to enable it from your *Extensions* area by clicking first on *Enable* and then on *Apply changes*.","excerpt":"","slug":"server-extensions","type":"basic","title":"Server extensions"}
Server extensions allow new surfaces to be created in the REST API. Use them if you want fine-grained control over your application's interactions with Neo4j than Cypher provides. To know more about how to write and test your extensions please read the [Neo4j unmanaged server extensions documentation](http://neo4j.com/docs/java-reference/current/#server-unmanaged-extensions). [block:callout] { "type": "warning", "body": "Please be careful with server extensions. You will be able to deploy JAX-RS classes to the server and it’s easy to consume lots of heap space and degrade performance.\n\n**We highly encourage to test your server extensions in staging environments before uploading them into production.**", "title": "Keep in mind" } [/block] Once you have written or downloaded an extension, you will need to pack it in a compressed file. As part of the compressed file you’ll need to add a neo4j-server.properties file, where you’ll put all the needed configuration for your extension, such as where Neo4j will look for it. [block:code] { "codes": [ { "code": "org.neo4j.server.thirdparty_jaxrs_classes=com.graphaware.server=/graphaware", "language": "text", "name": "Before Neo4j 3.0" } ] } [/block] [block:code] { "codes": [ { "code": "dbms.unmanaged_extension_classes=com.graphaware.server=/graphaware", "language": "text", "name": "As of Neo4j 3.0" } ] } [/block] ### Further considerations Please take the following considerations into account while preparing your server extension to be uploaded:d - Supported formats: zip, tar, cpio, gz, bz2 and xz. - Size is limited to 100MB. - A file can contain multiple .jar files in the top-level directory. - Only files with jar format or neo4j-server.properties are extracted, the rest will be ignored. - If a neo4j-server.properties file is found, its content is added to the neo4j-server.properties of the Neo4j process. - neo4j-server.properties can contain $PLUGIN_ROOT, which will be replaced with the path of the plug-in. This can be used to reference files in the archive. [block:callout] { "type": "info", "body": "Graphaware extensions use a neo4j.properties file instead of a neo4j-server.properties file for their configuration. **GrapheneDB takes care of this for you automatically**. Read more in [Graphaware extensions section](#section-graphaware-server-extensions).", "title": "Note" } [/block] ## Adding server extensions Follow these instructions to add a new server extension to your database: 1. Navigate to the *Extensions* tab of your database dashboard, and click on the *New server extension* button from the dropdown menu *New extension*. 2. Name your extension in order to be able to identify it afterwards. 3. Select the compressed file from your local path and click. 4. **Do not close your browser window!** The upload will stop if you close your browser. If the upload fails, you can click on the *Retry* button to start it again. 5. When the upload completes successfully, you will see a new row in your Extensions list with the status *ENABLED - PENDING*. [block:image] { "images": [ { "image": [ "https://files.readme.io/5b0a792-server_extensions_enable.png", "server_extensions_enable.png", 959, 191, "#5d9ab3" ] } ] } [/block] 6. Before the extension can be available for use, it is necessary to restart the database. To perform this operation, click on the *Apply changes* button. 7. A new window will show you a list of the changes you are going to perform. Please review them and click on *Apply changes*. Once the changes are applied, you will see the final status (*ENABLED or DISABLED*) in the list. [block:callout] { "type": "info", "body": "Server extensions and stored procedures are shown together in your Extensions list.", "title": "Note" } [/block] ## Remove unmanaged server extensions To remove your unmanaged server extensions, navigate to the *Extensions* tab of your database dashboard, and just click on the *Remove* link next to the extension. To remove an extension, it should be DISABLED before you can perform this operation. [block:callout] { "type": "danger", "title": "Danger", "body": "This action cannot be undone and will delete your server extension permanently." } [/block] ## GraphAware server extensions GraphAware is a Neo4j Solution Partner that specializes in Neo4j consultancy, training, and development. They develop open-source tools and generic graph database extensions. Below, you can find more specific information about how to integrate GraphAware extensions. ### Downloading GraphAware extensions Take into account that you will need to download a compatible version for your database. You can see all the available versions by clicking on the *Older Versions* link. For instance if your database is running Neo4j 2.2.4, you will need to look for a 2.2.4 version of your GraphAware extension. [block:image] { "images": [ { "image": [ "https://files.readme.io/bb96f75-graphaware.png", "graphaware.png", 562, 309, "#d3d8dc" ] } ] } [/block] ### Configure your GraphAware extension Please read the extension readme file carefully. This file will contain all of the needed instructions on how to configure the extension properly. GraphAware extensions use neo4j.properties instead of neo4j-server.properties because their extensions work both in Server as well as in Embedded mode. You don't have to worry about that, because when a GraphAware plugin is detected, the proper properties file will be used. Before uploading to GrapheneDB, please ensure you have packaged the extension tarball, the neo4j.properties file, and the framework tarball (if it's required) in a valid format (zip, tar, cpio, gz, bz2 or xz). ### Add your GraphAware extension Follow the steps described in [Server extensions](doc:server-extensions) to upload and enable the GraphAware extension. ## Spatial server extension Neo4j Spatial is a library of utilities for Neo4j that facilitates the enabling of spatial operations on data. Source page: https://github.com/neo4j-contrib/spatial For some versions of Neo4j, GrapheneDB comes out of the box with the spatial server extension installed. If you want to use it, you need to enable it from your *Extensions* area by clicking first on *Enable* and then on *Apply changes*.