<commit_before># Object API

*Note: The object database has been refactored since the release 1.0. If you use the previous one look at: [Old Implementation ODatabaseObjectTx](#Old_Implementation_ODatabaseObjectTx).*

# Requirements

To use the Object APi include the following jars in your classpath:
```java
orient-commons-*.jar
orientdb-core-*.jar
orientdb-object-*.jar
```

If you're using the Object Database interface connected to a remote server (not local/embedded mode) include also:
```java
orientdb-client-*.jar
orientdb-enterprise-*.jar
```

# Introduction

The OrientDB **Object Interface** works on top of the [Document-Database](Document-Database.md) and works like an Object Database: manages Java objects directly. It uses the Java Reflection to register the classes  and [Javassist tool](http://www.jboss.org/javassist) to manage the Object-to-Document conversion. Please consider that the Java Reflection in modern Java Virtual Machines is really fast and the discovering of Java meta data is made only at first time.

Future implementation could use also the byte-code enhancement techniques in addition.

The proxied objects have a ODocument bounded to them and transparently replicate object modifications. It also allows lazy loading of the fields: they won't be loaded from the document until the first access. To do so the object MUST implement [getters and setters](http://en.wikipedia.org/wiki/Mutator_method) since the [Javassist Proxy](http://www.jboss.org/javassist) 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 already proxied, in case a non-proxied instance is passed it will be serialized, wrapped around a proxied instance and returned.

Read more about the [Binding between Java Objects and Records](Object-2-Record-Java-Binding.md).

Quick example of usage:
```java
// 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 Pool

One of most common use case is to reuse the database avoiding to create it every time. It's also the typical scenario of the Web applications.
```java
// 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.

## Database URL

In the example above a database of type Database Object Transactional has been created using the storage: remote:localhost/petshop. This address is a [URL](http://it.wikipedia.org/wiki/Uniform_Resource_Locator). To know more about database and storage types go to [Database URL](Concepts.md#database_url).

In this case the storage resides in the same computer of the client, but we're using the **remote** storage type. For this reason we need a OrientDB Server instance up and running. If we would open the database directly bypassing the server we had to use the **local** storage type such as "plocal:/usr/local/database/petshop/petshop" where, in this case, the storage was located in the /usr/local/database/petshop folder on the local file system.

## Multi-threading

The OObjectDatabaseTx class is non thread-safe. For this reason use different OObjectDatabaseTx instances by multiple threads. They will share local cache once transactions are committed.

## Inheritance

Starting from the release 0.9.19 OrientDB supports the [Inheritance](Inheritance.md). Using the ObjectDatabase the inheritance of Documents fully matches the Java inheritance.

When registering a new class Orient will also generate the correct inheritance schema if not already generated.

Example:
```java
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 with:
```java
SELECT FROM account
```

The search will find all the Account and Company documents that satisfy the query.

# Use the database

Before to use a database you need to open or create it:
```java
// CREATE AN IN MEMORY DATABASE
OObjectDatabase db1 = new OObjectDatabaseTx("memory:petshop").create();

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

The database instance will share the connection versus the storage. if it's a local storage, then all the database instances will be synchronized on it. If it's a remote storage then the network connection will be shared among all the database instances.

To get the reference to the current user use:
```java
OUser user = db.getUser();
```

Once finished remember to close the database to free precious resources.
```java
db.close();
```

# Working with POJO

Please read the [POJO binding guide](Object-2-Record-Java-Binding.md) containing all the information about the management of POJO.

## Work in schema-less mode

The Object Database can be used totally in schema-less mode as long as the [POJO binding guide](Object-2-Record-Java-Binding.md) requirements are followed. Schema less means that the class must be created but even without properties. Take a look to this example:

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

Person p = db.newInstance(Person.class);
p.setName( "Luca" );
p.setSurname( "Garulli" );
p.setCity( new City( "Rome", "Italy" ) );

db.save( p );
db.close();
```

This is the very first example. While the code it's pretty clear and easy to understand please note that we didn't declared "Person" structure before now. However Orient has been able to recognize the new object and save it in persistent way.

## Work in schema-full mode

In the schema-full mode you need to declare the classes you're using. Each class contains one or multiple properties. This mode is similar to the classic Relational DBMS approach where you need to create tables before to store records. To work in schema-full mode take a look to the [Schema APIs](JavaSchemaAPI.md) page.

## Create a new object

The best practice to create a Java object is to use the OObjectDatabase.newInstance() API:

```java
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;
  }
// getters and setters
}

OObjectDatabase 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);
animal.setName( "Antoni" );<commit_msg>Fixed the Java Schema API link.<commit_after># Object API

*Note: The object database has been refactored since the release 1.0. If you use the previous one look at: [Old Implementation ODatabaseObjectTx](#Old_Implementation_ODatabaseObjectTx).*

# Requirements

To use the Object APi include the following jars in your classpath:
```java
orient-commons-*.jar
orientdb-core-*.jar
orientdb-object-*.jar
```

If you're using the Object Database interface connected to a remote server (not local/embedded mode) include also:
```java
orientdb-client-*.jar
orientdb-enterprise-*.jar
```

# Introduction

The OrientDB **Object Interface** works on top of the [Document-Database](Document-Database.md) and works like an Object Database: manages Java objects directly. It uses the Java Reflection to register the classes  and [Javassist tool](http://www.jboss.org/javassist) to manage the Object-to-Document conversion. Please consider that the Java Reflection in modern Java Virtual Machines is really fast and the discovering of Java meta data is made only at first time.

Future implementation could use also the byte-code enhancement techniques in addition.

The proxied objects have a ODocument bounded to them and transparently replicate object modifications. It also allows lazy loading of the fields: they won't be loaded from the document until the first access. To do so the object MUST implement [getters and setters](http://en.wikipedia.org/wiki/Mutator_method) since the [Javassist Proxy](http://www.jboss.org/javassist) 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 already proxied, in case a non-proxied instance is passed it will be serialized, wrapped around a proxied instance and returned.

Read more about the [Binding between Java Objects and Records](Object-2-Record-Java-Binding.md).

Quick example of usage:
```java
// 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 Pool

One of most common use case is to reuse the database avoiding to create it every time. It's also the typical scenario of the Web applications.
```java
// 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.

## Database URL

In the example above a database of type Database Object Transactional has been created using the storage: remote:localhost/petshop. This address is a [URL](http://it.wikipedia.org/wiki/Uniform_Resource_Locator). To know more about database and storage types go to [Database URL](Concepts.md#database_url).

In this case the storage resides in the same computer of the client, but we're using the **remote** storage type. For this reason we need a OrientDB Server instance up and running. If we would open the database directly bypassing the server we had to use the **local** storage type such as "plocal:/usr/local/database/petshop/petshop" where, in this case, the storage was located in the /usr/local/database/petshop folder on the local file system.

## Multi-threading

The OObjectDatabaseTx class is non thread-safe. For this reason use different OObjectDatabaseTx instances by multiple threads. They will share local cache once transactions are committed.

## Inheritance

Starting from the release 0.9.19 OrientDB supports the [Inheritance](Inheritance.md). Using the ObjectDatabase the inheritance of Documents fully matches the Java inheritance.

When registering a new class Orient will also generate the correct inheritance schema if not already generated.

Example:
```java
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 with:
```java
SELECT FROM account
```

The search will find all the Account and Company documents that satisfy the query.

# Use the database

Before to use a database you need to open or create it:
```java
// CREATE AN IN MEMORY DATABASE
OObjectDatabase db1 = new OObjectDatabaseTx("memory:petshop").create();

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

The database instance will share the connection versus the storage. if it's a local storage, then all the database instances will be synchronized on it. If it's a remote storage then the network connection will be shared among all the database instances.

To get the reference to the current user use:
```java
OUser user = db.getUser();
```

Once finished remember to close the database to free precious resources.
```java
db.close();
```

# Working with POJO

Please read the [POJO binding guide](Object-2-Record-Java-Binding.md) containing all the information about the management of POJO.

## Work in schema-less mode

The Object Database can be used totally in schema-less mode as long as the [POJO binding guide](Object-2-Record-Java-Binding.md) requirements are followed. Schema less means that the class must be created but even without properties. Take a look to this example:

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

Person p = db.newInstance(Person.class);
p.setName( "Luca" );
p.setSurname( "Garulli" );
p.setCity( new City( "Rome", "Italy" ) );

db.save( p );
db.close();
```

This is the very first example. While the code it's pretty clear and easy to understand please note that we didn't declared "Person" structure before now. However Orient has been able to recognize the new object and save it in persistent way.

## Work in schema-full mode

In the schema-full mode you need to declare the classes you're using. Each class contains one or multiple properties. This mode is similar to the classic Relational DBMS approach where you need to create tables before storing records. To work in schema-full mode take a look at the [Schema APIs](Java-Schema-Api.md) page.

## Create a new object

The best practice to create a Java object is to use the OObjectDatabase.newInstance() API:

```java
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;
  }
// getters and setters
}

OObjectDatabase 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);
animal.setName( "Antoni" );
{'fraction_non_alphanumeric': 0.08617159873441281, 'fraction_numerical': 0.0016130032880451641, 'mean_word_length': 4.7860732232591525, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5478798', 'n_tokens_mistral': 4498, 'n_tokens_neox': 4254, 'n_words': 2010}