Embedded OrientDB server for dropwizard
Java Groovy
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
gradle/wrapper
src
.gitignore
.travis.yml
.yo-rc.json
CHANGELOG.md
LICENSE
README.md
build.gradle
gradle.properties
gradlew
gradlew.bat
settings.gradle

README.md

Embedded OrientDB server for dropwizard

Gitter License Build Status Coverage Status

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:

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).

JCenter Maven Central

Maven:

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

Gradle:

compile 'ru.vyarus:dropwizard-orient-server:2.1.0'
  • For orient < 2.2.17 (studio webjar, lucene as plugin) see old docs
  • 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 OrientServerConfiguration 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 a Managed object, so the embedded server will start only together with jetty (server 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.

Connecting using plocal

The most efficient way to connect to the embedded database is using plocal. This engine writes to the file system to store data. There is a LOG of changes to restore the storage in case of a crash.

plocal doesn't require a started server and it's faster than remote connection. With an embedded server you would be able to use studio (remote connection) together with your application using plocal (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.

Connecting using sockets

If you want to connect to your embedded instance over sockets, it's best to have your orient client initialization inside your own Managed object. This is the best way to make sure the connection logic is run after server start.

Configuration

Define orient section in application config yaml file:

orient-server:
  start: true
  files-path: $TMP/db/
  
  config:
    ...
  
  # optional orient security configuration  
  security:
    ...

You can start with example 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 existing directory - orient will create it when necessary. Will be set as value for ORIENTDB_HOME environment variable.
  • config section defines orient server configuration. Orient use xml format for configuration files and this section is simply yaml representation of xml config. Special shortcuts supported for properties and parameters sections (see example configuration).
  • 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)
  • security section defines orient security configuration. In orient distribution security configured with security.json file. This section is implicitly converted to json file and configured for orient. Optional: when no server configuration defined, orient only prints error log message, but everything works.
  • security-file used to specify path to security.json file instead of direct yaml configuration in 'security' section. See example json config
  • auto-ssl used to enable automatic ssl configuration for orient listeners, when dropwizard main context is configured to use https. This is experimental feature.

Path properties files-path, config-file and security-file may use special symbols:

  • $TMP - system temp directory (java.io.tmpdir)
  • $APP_HOME - application starting directory ('.')
  • $FILES_HOME - directory configured by files-path property
  • ${prop} - where prop is any system property or environment variable

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. Security section configures database security (not server).

Distribution configuration reference

Configuration folder (config/) in orient distribution reference:

file name description configured as
orientdb-server-config.xml Main configuration config (yaml) or config-file (xml)
security.json Database security configuration security (yaml) or security-file (json)
automatic-backup.json Backup configuration Reference to file may be set OAutomaticBackup handler property. May be configured directly with handler properties (old way).
hazelcast.xml and default-distributed-db-config.json Distributed configuration Requires additional dependency (orientdb-distributed). Links to files set in OHazelcastPlugin handler properties.
orientdb-client-log.properties and orientdb-server-log.properties Logging configuration Not needed.

EXAMPLE: If you want to replicate orientdb server layout (merge it with your app folder), you can do it like this:

APP HOME/
    config/
        config.xml
        security.json
        backup.json
orient-server:
    files-path: $APP_HOME
    config-file: $APP_HOME/config/config.xml
    security-file: $APP_HOME/config/security.json

Correct reference to backup.json set in config.xml (OAutomaticBackup handler configuration).

Orient will create databases in: $APP_HOME/databases/name.

Of course, config.xml, security.json and backup.json may be configured in yaml. It's just an example to better understand configuration.

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.17.

Graph related sections are commented in default yaml config:

Enable this section if gremlin support required

- clazz: com.orientechnologies.orient.graph.handler.OGraphServerHandler
  parameters:
    - enabled: true

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

Note that Gremlin has become optional since 2.2.0. You will have to add an additional explicit dependency to enable Gremlin.

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

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.17.

Plugin will be automatically registered. Note: it's actually not an "orient plugin" anymore and so not shown in registered orient plugins (in orient servlet).

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.17

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 official orient jar (by default, it is not included).

Add dependency:

compile 'com.orientechnologies:orientdb-studio:2.2.17'

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:
        - http.cache:*.htm *.html: 'Cache-Control: no-cache, no-store, max-age=0, must-revalidate\r\nPragma: no-cache'
        - http.cache:default: 'Cache-Control: max-age=120'

Studio github repository.

Might also like


java lib generator