#Embedded OrientDB server for dropwizard

About

Embeds OrientDB server into dropwizard.

Simplifies development environment (no need to maintain separate server) without sacrificing functionality (embedded server is 100% the same as usual server). Also, simplifies production deployment and allows to slightly reduce memory consumption on server due to single (shared) vm. To switch application to external server simply switch off embedded server in configuration.

Features:

• For orient 2.2 and dropwizard 1.0
• Embedded orient server, managed by dropwizard (using Managed object)
• Configuration in main yaml configuration file or with external orient xml configuration file
• Console command (interactive mode, command execution, commands file execution)
• Optional embedded orient studio
• Full support of orient plugins (and enterprise edition)

Setup

Releases are published to bintray jcenter (package appear immediately after release) and then to maven central (require few days after release to be published).

Maven:

<dependency>
  <groupId>ru.vyarus</groupId>
  <artifactId>dropwizard-orient-server</artifactId>
  <version>1.4.0</version>
</dependency>

Gradle:

compile 'ru.vyarus:dropwizard-orient-server:1.4.0'

• For orient 2.0, 2.1 and dropwizard 0.8-1.0 use version 1.3.0 (see old docs)
• For orient 1.x and dropwizard 0.8 use version 1.1.1 (see old docs)
• For orient 1.x and dropwizard 0.7 use version 1.1.0 (see old docs)

Snapshots

You can use snapshot versions through JitPack:

• Go to JitPack project page
• Select Commits section and click Get it on commit you want to use (top one - the most recent)
• Follow displayed instruction: add repository and change dependency (NOTE: due to JitPack convention artifact group will be different)

Usage

Configuration class must implement HasOrientServerConfiguration:

public class MyConfiguration extends Configuration implements HasOrientServerConfiguration {

    @NotNull
    @Valid
    private OrientServerConfiguration orientServerConfiguration;

    @Override
    public OrientConfiguration getOrientServerConfiguration() {
        return orientServerConfiguration;
    }

    @JsonProperty("orient-server")
    public void setOrientServer(OrientServerConfiguration orientServerConfiguration) {
        this.orientServerConfiguration = orientServerConfiguration;
    }
}

NOTE: It's not required to have not null orient configuration. If OrientServerConfiguration is null server will simply not start.

Register orient bundle in application class:

@Override
public void initialize(final Bootstrap<MyConfiguration> bootstrap) {
    bootstrap.addBundle(new OrientServerBundle(getConfigurationClass()));
}

Example application could be found in tests

Client initialization

Server lifecycle is managed using Managed object, so embedded server will start only together with jetty (server command) or with environment command. Managed instances are started after all bundles run methods and even after application run method, so server will be unreachable if you try to access it from these methods.

It's better to do your orient client initialization inside your own Managed object, to make sure this logic run after server start. (for example, when you use remote connection, the only whey to properly check database existence on startup would be using Managed object)

You can use plocal connection together with embedded server: plocal doesn't requires started server and it's faster than remote connection, but with embedded server you would be able to use studio together with your application (win-win).

Server stores database files in '${files-path}/databases' folder, so plocal connection for server managed database would be:

plocal:${files-path}/databases/dbname

where ${files-path} should be replaced with path from server configuration and dbname is database name.

Configuration

Define orient section in application config yaml file:

orient-server:
  start: true
  files-path: $TMP/db/
  
  config:
    ...

You can start with this configuration file.

• start enables or disables orient server start (the same effect will be if orient configuration section will not exist, this option exist to allow disabling server without removing entire config section)
• admin-servlet enables or disables orient admin servlet installation (/orient). Enabled by default.
• files-path defines folder, where orient will store database files. May be not existent directory - orient will create it when necessary. Support special placeholder '$TMP', which is replaced to 'java.io.tmpdir'.
• config section defines orient server configuration. Orient use xml format for configuration files and this section is simply yaml representation of xml config.
• config-file used to specify path to xml configuration file instead of direct yaml configuration in 'config' section. See example xml config (taken from orient distribution)

IMPORTANT: user root must be defined in configuration, because orient 2 asks for root user password on start, and in embedded mode it can't save it (so will ask on each start). To avoid this case, error is thrown if no 'root' user defined.

Also, note that server users and database users are different! In default configuration root and guest users defined for server. When new database created, orient will create default database users: admin, reader, writer.

Graph server

By default, server supports document and object databases. If graph db required you'll need to add graph dependency: com.orientechnologies:orientdb-graphdb:2.2.10.

Graph related sections are commented in default yaml config:

Enable this section if gremlin support required

clazz: com.orientechnologies.orient.graph.handler.OGraphServerHandler
        parameters:
        ...

Enable this section if gephi support required (requires OGraphServerHandler if gremlin queries used)

pattern: 'GET|gephi/*'
implementation: com.orientechnologies.orient.graph.server.command.OServerCommandGetGephi

If gremlin not used, it's better to remove gremlin dependencies (mainly because of groovy size)

compile ("com.orientechnologies:orientdb-graphdb:2.2.10") {
    exclude module: 'gremlin-java'
    exclude module: 'gremlin-groovy'
}

Lucene plugin

Orient 2 distribution includes lucene plugin out of the box. To enable lucene indexes in embedded server add dependency: com.orientechnologies:orientdb-lucene:2.2.10.

And register lucene plugin in handlers section:

handlers:
    - clazz: com.orientechnologies.lucene.OLuceneIndexPlugin

Example

This registration is completely equivalent to default lucene plugin registration in orient distribution.

Lucene plugin includes dependency on graph, so explicit graph dependency could be avoided.

ETL

To use ETL add dependency com.orientechnologies:orientdb-etl:2.2.10

ETL plugin includes dependency on graph, so explicit graph dependency could be avoided.

Admin servlet

If embedded server is started, special orient info servlet is available in admin context: http://localhost:8081/orient. It shows basic info about server configuration, link to embedded studio and links to most useful orient documentation pages.

Special url http://localhost:8081/orient/studio/ redirects to embedded studio.

Servlet installation may be disabled in configuration:

orient-server:
    admin-servlet: false

Console

Internally bundle registers orient console command (ConsoleCommand). Console may be used in interactive mode, to execute command(s) or to process commands file.

Console is very efficient for learning orient (playing with queries) and may be used to easily run predefined scripts.

If started without additional parameters, console will be in interactive mode:

$ [..] console config.yml

Where [..] is main class definition (like java MyApp or java -jar app.jar MyApp) and config.yml is your application yaml config.

NOTE: console launching will not start orient server, but you can use it alongside with started application. Also, you can use plocal connection to work with db from console even without server (see console output, it will suggest connection commands)

To execute command directly, write it as additional argument:

$ [..] console config.yaml help

This will start console, execute help command and exit. More than one command may be executed (commands must be separated with ';')

And the last option is to launch sql fie, for example commands.sql:

set echo true;
create database memory:test;
select from OUser;
drop database;

$ [..] console config.yaml commands.sql

Will execute all commands in file and exit. Note that set echo true enables additional logs (may be useful for debug). Another useful flag is set ignoreErrors true.

For complete documentation see orient console wiki

Orient studio

Orient studio is irreplaceable tool for both learning and development. You will need it to validate schema, do manual schema changes and migrations, debug sql queries (all the things you usually do in external applications like SqlDeveloper for relational databases).

Studio could be embedded using webjar (by default, it is not included).

Add dependency:

compile 'org.webjars:orientdb-studio:2.2.0'

Studio is usually the same for minor orient versions. Use version 2.0.12 for orient 2.0.x, 2.1.0 for orient 2.1.x and 2.2.0 for orient 2.2.x. If required studio version is not published yet request it by creating new issue.

After jetty server start (usual dropwizard startup):

$ [..] server config.yml

Studio will be available on url: http://localhost:2480/studio/. Port number depends on orient configuration. You can use universal url in admin servlet: http://localhost:8081/orient/studio/, which will redirect to actual studio location.

NOTE: Studio will not start if static content listener is not defined in configuration (defined in example configuration)

commands:
  - pattern: 'GET|www GET|studio/ GET| GET|*.htm GET|*.html GET|*.xml GET|*.jpeg GET|*.jpg GET|*.png GET|*.gif GET|*.js GET|*.css GET|*.swf GET|*.ico GET|*.txt GET|*.otf GET|*.pjs GET|*.svg'
    implementation: 'com.orientechnologies.orient.server.network.protocol.http.command.get.OServerCommandGetStaticContent'
    parameters:
        - name: 'http.cache:*.htm *.html'
          value: 'Cache-Control: no-cache, no-store, max-age=0, must-revalidate\r\nPragma: no-cache'
        - name: 'http.cache:default'
          value: 'Cache-Control: max-age=120'

Studio github repository.

Might also like

• dropwizard-guicey - dropwizard guice integration
• guice-persist-orient - guice integration for orient