How to Install Orientdb Onto Linux

Introducing OrientDB

December 2016 -- email any questions to [email protected]

OrientDB and Java

OrientDB offers many advantages to Java software developers including the ability to run their applications inside the same Java Virtual Machine (JVM) as OrientDB. As no ORM (object-relational mapping) layer exists between your POJO classes and OrientDB’s object schema, there is no impedance mismatch to drag down productivity.

In brief we will install OrientDB and then get familiar with its object.load(), object.save(), and object.update() features of its object database through its Java Object API. Running OrientDB in a production environment however requires more knowledge.

The A to Z of OrientDB

These are the key knowledge buckets that lead to an expert grasp of OrientDB from both a Java Developer and System Administrator’s point of view is to

1. Install OrientDB onto a local or cloud Linux server 2. Configure OrientDB to run as a service (startup after reboot) 3. Learn to talk to OrientDB through its command console 4. Learn to talk to OrientDB through its web interface 5. Learn to connect to OrientDB via its Java Object API 6. Learn to copy, backup, replicate and recover OrientDB 7. Run OrientDB behind an Apache web server proxy

There is more to OrientDB than initially meets the eye. It has an “in memory” feature so that your unit tests can work with OrientDB using memory based instead of disk based storage.

You can also talk to its RESTful Web Services interface to simply create, read, update and delete both documents and objects with simple HTTP GET, PUT and POST commands.

1 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Where to put OrientDB

Running OrientDB in the Amazon AWS or Google clouds is a popular choice. If you do this you can skip the section that walks through the OrientDB install on Linux.

Running OrientDB Inside Docker

Docker is a popular virtual container for running OrientDB. If deploying your database to multiple environments with different configurations – Docker will result in significant efficiency / complexity savings. If performance is key then the Docker layer is a container that wraps a container.

All JAVA software runs within a container that is abstracted away from the operating environment. The JVM container starts, stops and manages Java applications in much the same way as Docker (which abstracts middleware away from the operating environment).

The JVM lacks an enterprise grade deployment tool which is where Docker excels. However if you don’t need that and you want to milk every gram of performance out of your OrientDB installation – it pays to register (install) OrientDB with your server’s JVM.

Use Cases Unsuitable in Clouds

Even though OrientDB can be wrapped by cloud managed and/or Docker containers, some use cases are ineffective within a cloud OrientDB installation. The cloud’s cost model can be the problem.

Suppose your use case requires high bandwidth, massive storage and/or super-fast multi- core CPU processors – whilst not needing internet visibility.

A local server still makes a lot of sense. No one counts the CPU cycles and charges you. No one monitors the bandwidth in your intranet (and charges you). Once your multi-terrabyte solid state drive is installed – no one charges you.

In these instances it makes sense to install the middleware instance yourself. You must install OrientDB to process big data, deploy multiple developer sandboxes and run CPU intensive algorithms – perhaps in search of the next prime number.

2 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

OrientDB in your App’s Stack

OrientDB is perfect for use inside developer sandboxes and within the Jenkins Continuous Integration Server. OrientDB is happy running within the confines of an IDE that is executing unit tests. And you can call it directly making the likes of HSQL redundant?

You can run your app inside OrientDB or you can run OrientDB inside your app!

As was mentioned earlier there are an unprecedented number of ways to communicate with OrientDB preferably with (but also without) Java. You can communicate with OrientDB

1. with RESTful web services (try Curl) 2. with direct API calls within the same JVM 3. by dropping in JARs that access its API 4. using the standard JDBC or other drivers 5. through a web console on port 2480 6. using the provided command line console

How you can talk to OrientDB is one thing, where (what climates) OrientDB can happily survive in, is quite another.

Where can OrientDB Live and Breathe

You couldn’t run MySQL or Oracle inside your IDE – but you can with OrientDB. The good news is that OrientDB also performs on the big stage and its 100% Java tag allows it to run within Android smartphones and tablets, IDE’s, but also on top-end compute and storage optimized hardware.

3 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

The 7 OrientDB Data Model Choices

Once you’ve chosen OrientDB, you are spoilt for choice in terms of your database model. OrientDB gives you

1. either NOSQL (or SQL-like) database queries 2. an object database (for Java, Scala and C#) 3. a graph database with vertices and nodes 4. an EAV (entity, attributes and values) database 5. a document database for JSON, CSV, XML and HTML 6. either a schemaless or a schemafull database 7. an in-memory database with few RAM(ifications)

OrientDB is good, but it is not all things to all men. It isn’t suitable in certain situations.

Don’t Use OrientDB when …

OrientDB is not well-suited when

1. you already have a mature application with a stable schema 2. the application software is not predominantly Java (or Scala or Groovy) 3. things are strictly SQL – no web services, no API calls

Please drop us a comment letting us know if the install went well. Also make a request for a post on any aspect of OrientDB or indeed any other technology.

4 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

How to Install OrientDB on Linux

Email any questions to [email protected]

OrientDB and Java

Let’s install OrientDB and then visit its object.load(), object.save(), and object.update() features. There are 5 steps to perform in order to install OrientDB.

How to Install OrientDB on Linux

Use the below steps.

1. Install Oracle’s Java 1.8 with apt-get install 2. Create an orientdb operating system user 3. Download and Unpack the archive into orientdb home 4. Start the Orient database server with ./bin/server.sh 5. Launch the OrientDB console with ./bin/console.sh

1. Install the Oracle Java 8 Runtime To install Oracle JRE 8 run this command and then update your local repository before running the apt-get install command. sudo add-apt-repository ppa:webupd8team/java sudo apt-get update sudo apt-get install oracle-java8-set-default

5 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Once you have given the go-ahead again. You will see a line that includes the following text.

(3.53 MB/s) - ‘jdk-8u77-linux-x64.tar.gz’ saved

It is important to check that Java version 1.8 is running. Just type in and run this simple command in Microsoft's Windows, Linux, Apple's iOS or Google's Android. java -version The output saying that Java 1.8 has been installed on Ubuntu will be similar to this. java version "1.8.0_77" Java(TM) SE Runtime Environment (build 1.8.0_77-b03) Java HotSpot(TM) 64-Bit Server VM (build 25.77-b03, mixed mode)

2. Create an orientdb operating system user

Best practice is to create an orientdb operating system user so that the database does not run as root. sudo adduser orientdb Don’t worry, orientdb has been built to run this way so creating an orientdb user helps you run into fewer problems down the line.

Verify by checking /home. Does an orientdb directory exist?

3. Download and Unpack the OrientDB Archive

Download OrientDB via your browser or use wget to avoid moving files here there and everywhere. We unpack orientdb into a temporary location and then copy the contents into the newly created /home/orientdb home. 1. wget https://orientdb.com/download.php?file=orientdb-community- 2.2.9.tar.gz 2. sudo tar -xf download.php?file=orientdb-community-2.2.9.tar.gz - C /tmp 3. su - orientdb 4. cd $HOME 5. cp -R /tmp/orientdb-community-2.2.9/* . (mind the dot)

6 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

All the file ownership and permissions are correct as we copied the files as the orientdb user. If you didn’t use the above commands, remember to chown the orientdb directory tree.

4. Start the Orientdb Database Server

Navigate to the home of OrientDB and fire it up. sudo bin/server.sh

OrientDB should now prompt for the database administrator’s password with a message like the one below.

After entering the password look at the console output for a line like the one below. OrientDB uses port 2480 by default. OrientDB Studio available at http://192.168.1.70:2480/studio/index.html [OServer]

Use the URL to verify that your OrientDB web service is operational. But how do I login?

With your browser OrientDB will show you a database called GratefulDeadConcerts and prompt for a username and password.

In the username field type in “root”. Then use the password you entered when the server started up for the first time. This combination should give you access into the OrientDB Server admin area.

7 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

5. Start the Orientdb Console

Now that you can interact with the server process with a web browser, it is time to fire up the inimitable console and start interacting with OrientDB. sudo bin/console.sh There is an unprecedented number of ways to communicate with OrientDB especially if you use Java. You can talk to it with RESTful web services, you can directly call its API classes and methods whilst running in the same JVM. You can access its API by adding dependent JARs. You can query OrientDB with a JDBC driver, you can manage it through its web console, and let’s not forget the (command line) console. Well done – OrientDB is now running with Oracle’s fast and furious Java 8 runtime. Your OrientDB is lights out and away you go.

8 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Running OrientDB as a Service You can e-mail [email protected] with any questions.

Running OrientDB as a service picks up where the Orient-DB database install left off.

How to Run OrientDB as a Service

Like all middleware, it pays to run OrientDB as a service because

. after a reboot OrientDB starts up ready to service requests . we can follow convention with sudo service orientdb start . why login and change directory just to start or stop a service . OrientDB will now run as the correct user regardless

Do not worry – to get OrientDB running as a service is simple on Ubuntu and OrientDB is designed to run this way. Starting OrientDB with sudo will cause you many problems down the line.

OrientDB as a Service | Pre-Conditions

The pre-conditions before you configure OrientDB to run as a service.

Make sure you have followed the advice and have

1. created an operating system user (usually called “orientdb”) 2. run OrientDB with its user using sudo bin/console.sh

You are good to go if the above pre-conditions have been met.

9 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

OrientDB as a Service | Steps

The orientdb.sh script comes into play when installing Orientdb as a service. All in all, we make 3 distinct moves and these are

1. Edit the bin/orientdb.sh adding the install folder and run as user.

2. Copy it (chopping off .sh) into the /etc/init.d services launch pad.

3. Run the update-rc.d “servicifier” command to register the script.

1. Editing the bin/orientdb.sh script

Edit these 2 lines in your bin/orientdb.sh script

ORIENTDB_DIR="/home/orientdb" ORIENTDB_USER="orientdb"

#!/bin/sh # OrientDB service script # # Copyright (c) OrientDB LTD (http://orientdb.com/)

# chkconfig: 2345 20 80 # description: OrientDb init script # processname: orientdb.sh

# You have to SET the OrientDB installation directory here ORIENTDB_DIR="YOUR_ORIENTDB_INSTALLATION_PATH" ORIENTDB_USER="USER_YOU_WANT_ORIENTDB_RUN_WITH" LOG_DIR="../log" usage() { echo "Usage: `basename $0`: " exit 1 }

Look at the above script and note the 2 line changes we have made.

10 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

ORIENTDB_HOME="/var/lib/orientdb" RUN_AS_USER="orientdb" Now we can place the orientdb script into /etc/init.d Note that we change the name! Note that we change the script name slightly so bin/orientdb.sh is copied to /etc/init.d/orientdb The script is renamed so that we can run sudo service orientdb start

2. Copy orientdb.sh to /etc/init.d/orientdb

Once you are happy with the line changes go ahead and copy your orientdb script. sudo cp /home/orientdb/bin/orientdb.sh /etc/init.d/orientdb Using sudo will create a file owned by root. That is fine – Orientdb still runs as the orientdb user.

However we need to add execute permissions so that the orientdb user can run a file owned by root. sudo chmod a+x /etc/init.d/orientdb

3. Run the update-rc.d Command

The heavy lifting is done by update-rc.d. Run it with sudo. cd /etc/init.d sudo update-rc.d orientdb defaults

The output should resemble update-rc.d: warning: /etc/init.d/orientdb missing LSB information

That’s it. You are done.

To test it run sudo service orientdb start and then reboot your machine. After both actions check the service is running with sudo service orientdb status

Well done – Orientdb is installed as a service – running with the Orientdb user. So lights out and away you go.

11 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

The OrientDB Java API

Transparent Object to Database Binding is the key feature used by the clueless and transparent mappers within laundry4j.

The laundry4j mappers can handle almost every world to object (and object to world) mapping scenario. It maps content rich documents in JSON, XML, HTTP POST, CSV, HTML TABLES and many other content encapsulation data formats to domain model

Why Clueless?

Clueless means that the mappers have no idea which domain objects they are creating. This is a good thing because the same mappers can therefore be reused in any and every domain model.

The domain objects are clueless too. If they knew they were being mapped to and from a database, or XML file, or web page HTML template, or a JSON document – they wouldn’t take too kindly to being mapped in a manner they are not used to. This restricts reuse of domain model objects especially in enterprise applications where the same Person object will likely be carried within XML, JSON, a web page and so on.

The OrientDB Java API?

The OrientDB Java API is the preferred (and go-to reference implementation) when sizeable transaction level data requires management by a modern DBMS engine.

The relevant and most frequently used OrientDB Java API classes and methods are now documented.

12 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

How to use the OrientDB Object Database API

The OrientDB Object Interface works on top of the Document-Database and works like an Object Database that manages Java objects directly.

It uses the Java Reflection to register the classes and the Javassist tool to manage the Object- to-Document conversion.

The database proxy objects registered and used have an ODocument bounded to them and transparently replicate object modifications. It also allows lazy loading of the fields which will not be loaded from the document until the first access.

So the object MUST implement getters and setters since the Javassist Proxy is bounded to them. In case of object load, edit an update all non-loaded fields won't be lost.

The database instance has an API to generate new objects from the registered proxy classes and the content held within OrientDB. More is available in the section - Binding between Java Objects and Records.

How to Create and Open the Database

To use a database you first create it – then you open it.

// CREATE AN IN MEMORY DATABASE OObjectDatabaseTx db1 = new OObjectDatabaseTx("memory:petshop").create();

// OPEN A REMOTE DATABASE OObjectDatabaseTx db2 = new OObjectDatabaseTx("remote:localhost/petshop").open("admin", "admin");

Now to get a reference to the current user use this …

OUser user = db.getUser();

And once you are finished do not forget to close the database and free precious resources. db.close();

13 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Your First OrientDB Java API Example

// OPEN THE DATABASE OObjectDatabaseTx db = new OObjectDatabaseTx ("remote:localhost/petshop").open("admin", "admin");

// REGISTER THE CLASS ONLY ONCE AFTER THE DB IS OPEN/CREATED db.getEntityManager().registerEntityClasses("foo.domain");

// CREATE A NEW PROXIED OBJECT AND FILL IT Account account = db.newInstance(Account.class); account.setName( "Luke" ); account.setSurname( "Skywalker" ); City rome = db.newInstance(City.class,"Rome", db.newInstance(Country.class,"Italy")); account.getAddresses().add(new Address("Residence", rome, "Piazza Navona, 1")); db.save( account );

// CREATE A NEW OBJECT AND FILL IT Account account = new Account(); account.setName( "Luke" ); account.setSurname( "Skywalker" ); City rome = new City("Rome", new Country("Italy")); account.getAddresses().add(new Address("Residence", rome, "Piazza Navona, 1"));

// SAVE THE ACCOUNT: THE DATABASE WILL SERIALIZE THE OBJECT AND GIVE THE PROXIED INSTANCE account = db.save( account );

Connection Pools

Connection pools circumvent the need to build and destroy expensive database connections every time that one is needed. OrientDB implements connection pools for us so we do not need to hunt for a connection pool implementation like we would when working with MySQL and/or Oracle.

// OPEN THE DATABASE OObjectDatabaseTx db= OObjectDatabasePool.global().acquire("remote:localhost/petshop", "admin", "admin");

// REGISTER THE CLASS ONLY ONCE AFTER THE DB IS OPEN/CREATED db.getEntityManager().registerEntityClass("org.petshop.domain"); try { ... } finally { db.close(); }

The close() method doesn't close the database but release it to the owner pool. It could be reused in the future.

14 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Inheritance

OrientDB supports the Inheritance. public class Account { private String name; // getters and setters } public class Company extends Account { private int employees; // getters and setters }

When you save a Company object, OrientDB will save the object as unique Document in the cluster specified for Company class. When you search between all the Account instances using the query “SELECT FROM account” – the search will find all the Account and the Company documents that satisfy the query.

15 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Working in Schema(Full) Mode

We need a robust schema so we opt not to work in schema-less mode. We prefer to pre- declare the objects and have OrientDB create the schema from our objects and indeed packages.

Declaring Classes and Creating New Objects?

The best practice to create a Java object is to use the OObjectDatabaseTx.newInstance() API. Let’s start with a simple Person class that is declared with two string arguments.

public class Person {

private String name; private String surname;

public Person() { }

public Person(String name) { this.name = name; }

public Person(String name, String surname) { this.name = name; this.surname = surname; }

}

// The getters and the setters.

16 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Create a Person Schema

Then add 2 People to It

OObjectDatabaseTx db = new OObjectDatabaseTx("remote:localhost/petshop").open("admin", "admin"); db.getEntityManager().registerEntityClass(Person.class);

// CREATES A NEW PERSON FROM THE EMPTY CONSTRUCTOR Person person = db.newInstance(Person.class); person.setName( "Antoni" ); person.setSurname( "Gaudi" ); db.save( person );

// CREATES A NEW PERSON FROM A PARAMETRIZED CONSTRUCTOR Person person = db.newInstance(Person.class, "Antoni"); person.setSurname( "Gaudi" ); db.save( person );

// CREATES A NEW PERSON FROM A PARAMETRIZED CONSTRUCTOR Person person = db.newInstance(Person.class,"Antoni","Gaudi"); db.save( person );

Note that above – we delegated object creation to OrientDB. We just told it which class we wanted to load and it created the empty objects for us to fill.

If on the other hand we created the object ourselves – we would need to assign the result of the db.save() call in order to retrieve the proxied instance of the saved object.

Let’s look at that next.

17 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Use the DB Instance to Update Objects

To create the “to-be-saved” object ourselves – we would need to assign the result of the db.save() call in order to retrieve the proxied instance of the saved object.

If this is not done – OrientDB treats the object as a new one and creates it.

In order to update the record in the database we need to have the object that is the proxied instance of the class under inspection.

// REGISTER THE CLASS ONLY ONCE AFTER THE DB IS OPEN/CREATED db.getEntityManager().registerEntityClass(Animal.class); Animal animal = new Animal(); animal.setName( "Gaudi" ); animal.setLocation( "Madrid" ); animal = db.save( animal );

Iterate (Read) All Records of a Class

To iterate over all the records (objects) under OrientDB’s wing for a given class needs us to state the class name and then manage the iterable collection result.

This example does just that. for ( Animal animal : database.browseClass( Animal.class ) ) { System.out.println( animal.getName() ); }

Count the number of class entries

Do this to count the number of records logged against a class. I am guessing that inheritance is factored into the count.

If there was a Trapezium and a Rectangle that extended the Quadrilateral class and there were 3 Trapezias and 4 Rectangles – the below counts would be returned.

1. Trapezia (Count 3) 2. Rectangles (Count 4) 3. Quadrilaterals (Count 7) long populationCount = database.countClass( "Person" ); -- also we could use long populationCount = database.countClass( objectClass.getSimpleName() );

18 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

How to Update and/or Delete Objects

Instead of updating and/or deleting objects - here at www.build-business-websites.co.uk we prefer to add a finalizer record, or add a continuation record, or both.

Why? – to avoid the expense of table searches trying to find the row to delete. Large and especially EAV (entity attribute value) databases do not bode well with deletes.

More importantly – the audit trail is wiped-out (or at least smudged) on every delete. This loss of audit tracks comes with the delete command territory.

Updates and Sparse Data

Let’s pretend that a Person object – created when a baby is born – has a “graduation date” and a “menstruation cycle start date” record.

That’s strange. We normally just expect to see name, date of birth, sex and so on.

This accentuated example highlights some issues. The 7 most common are that

 the baby may not go to university  the menstruation cycle property is superfluous for baby boys  wasted sparse rows create unbalanced tables  searching by graduation date < less than 1950 peeks at empty grad date records  updates and deletes are unnecessarily expensive as they must find the row  no undo! – so updating or deleting a graduation date cannot be reversed  bulk updates and deletes just add to the performance problem

The above rules should dissuade against using updates and deletes. Normalization comes to the rescue.

Football Match Scores

A football match record created months before the match is played would have empty “home team and away team goals” columns until the match is played. During the match we would need to do large rangey table scans whenever a team scores.

Let’s normalize this to another match goals table. This way we can insert a score row whenever a team scores. This insert action comes with no expense.

19 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Update Table Example

Any proxied object can be updated using the Java language and then calling the db.save() method to synchronize the changes. Note that OrientDB updates only the properties that have been changed.

animal.setLocation( "Nairobi" ); db.save( animal );

Bulk Updates

Bulk updates are often used (although we discourage it and counsel the use of bulk inserts instead). However if you need to do it try this update loop that changes every record belonging to the Animal class. for ( final Animal animal : database.browseClass( Animal.class ) ) { animal.setPrice( animal.getPrice() * 105 / 100 ); database.save( animal ); }

It is important to note that calling db.save() for a non-proxied object causes OrientDB to create a new record rather than update an existing one (whether or not one exists).

Deleting Objects

Nothing happens if one calls db.delete() with a non-proxied object.

On the contrary, calling db.delete( animal ) will delete the one record as long as the record exists and the animal object is proxied – originates from - your carefully cultivated database.

for ( final Animal animal : database.browseClass( Animal.class ) ) database.delete( animal );

The above deletes every object belonging not to just the Animal class, but also any objects that consider the animal class as a parent or ancestor.

20 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Execute a query

This example will return a list of Animals with an ID of 10 and a name that starts with the letter “G”.

List result = db.query ( new OSQLSynchQuery("select * from Animal where ID = 10 and name like 'G%'") ) ;

Schema Generation

OrientDB can generate a schema from a declared class and/or package. This can be done manually as and when necessary or automatically up-front before any content is ready to be injected into the database.

Automatic up-front generation should occur before unit tests run on an empty “in-memory” database. Manual generation is useful during the design phase.

When upgrading test and production systems the schema increment should be completed up- front at deploy time. The release process should create a database mirror and then add the increment onto that. The released software then overlaps with its “managed-out” counterpart until the mirrored database becomes the main database.

Manual Changes to the Schema

Not all schema change aspects can be done automatically. All, on the other hand, can be done manually. The automatic option is not available when

 changing class (table) and/or property (field/column) names  changing a property type like string to date or float to integer  adding new properties or removing old ones from registered types  changing the inheritance and / or the object graph structure

21 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/

Manual and Automatic Schema Generation

To manually generate the schema you must make an explicit call with either a class or a package parameter. db.getMetadata().getSchema().generateSchema( Person.class ); db.getMetadata().getSchema().generateSchema( "com.laundry4j.teams" );

Automatic schema generation requires us to set a flag to true. The schema is then generated whenever a call to register a class or the classes in a package is made.

Setting the "automaticSchemaGeneration" property to true is done this way. db.setAutomaticSchemaGeneration( true );

Hence generating the schema on either of these registration commands.Automatic schema generation requires us to set a flag to true. The schema is then generated db.getEntityManager().registerClass( Person.class ); db.getEntityManager().registerEntityClasses( "com.laundr4h.matches " );

Transient Variables are Ignored

If you mark a variable as transient – OrientDB will ignore it and will not create a property for it on the resulting schema. public class Foo { private transient String field1; // ignore this field private Integer field2; // create a Integer }

22 | https://www.build-business-websites.co.uk/how-to-install-orientdb-on-linux/