One Page Documentation

A - Overview

NeoDatis ODB is a new generation Object Oriented Database. ODB is a real transparent persistence layer that allows anyone to persist native objects with a single line of code.

ODB can be used as an embedded database engine that can be seamlessly integrated to any product as an embedded database or in client/server mode.

Simple

ODB is very simple and intuitive: the learning time is very short. Have a look at the ODB one minute tutorial to check this. The API is simple and does not require learning any mapping technique. There is no need for mapping between the native objects and the persistence store.

ODB simply stores objects the way they are.

ODB requires zero administration and zero installation.

Small

The ODB runtime is less than 550k and is distributed as a single jar/dll that can easily be packaged in any type of application.

Fast

Download the PolePosition performance Benchmark to check the performance of ODB. Click here for more information.

Safe and Robust

ODB supports ACID transactions to guarantee data integrity of the database. All committed work will be applied to the database even in case of hardware failure. This is done by automatic transaction recovery on the next startup.

One single database file

ODB uses a single file to store all data:

  • The Meta-model
  • The objects
  • The indexes

Multi platform

ODB runs on Java and .Net (Microsoft and Mono) platform*

*:It currently works on Java platform and is being ported to .Net platform.

Thread safety

ODB can be used in a multi-threaded environment. ODB only needs to be informed about the thread pool size (calling Configuration.useMultiThread(true, pool size)).

Data are always available

ODB lets you export all data to a standard XML Format ( Annex 1 of PDF Documentation: Xml Exported file of the tutorial ODB base) which guarantees that data are always available.

ODB can also import data from the same XMLformat.

Import and Export features are available via API or via the ODB Object Explorer.

Productivity

ODB lets you persist data with a very few lines of code. There is no need to modify the classes that must be persisted and no mapping is needed. So developers can concentrate on business logic implementation instead of wasting time with the persistence layer.

Easy to integrate

The only requirement to use ODB is to have a single jar/dll on the application classpath/path.

Refactoring

ODB currently supports 5 types of refactoring:

  • Adding a new Field (automatically detected)
  • Removing a field (automatically detected)
  • Renaming a class (Via API ou NeoDatis Object Explorer)
  • Renaming a Field (Via API ou NeoDatis Object Explorer)
  • Changing the type of a field (respect the ODB Matrix Type Compatibility) (not yet implemented)

Licence

ODB is distributed under the LGPL license.


B - One Minute Tutorial

Here is a simple example to demonstrate how it is easy to persist objects with ODB. Here, a java instance is created, the ODB database is opened, the store method is called to save the object and then the database is closed.

The Sport Class has one String attribute called name.

// Create the instance be stored
Sport sport = new Sport("volley-ball");
 
// Open the database
ODB odb = ODBFactory.open("tutorial.odb");
 
// Store the object
odb.store(sport);
 
// Close ODB
odb.close();

Here is how the object is displayed if the ODB Explorer Meta Model View. This view shows all the classes descriptions that are stored in the database. At the right the object view showing the objects.

Meta Model & Object View

1mtutorial_img1.png

Table View

Here is how the object is displayed if the ODB Explorer Table View. The table view shows objects in ab SQL-like table result:

1mtutorial_img2.png

Object Introspector

here is how the object is displayed if the ODB Explorer Introspector View. This view, that displays all the attributes of the object, permits updating fields value manually:

1mtutorial_img3.png

If you want to learn more about NeoDatis ODB, click here to have a look at the 5 minutes tutorial or here to download the full documentation in PDF format.

You can also diectly download the full ODB package that comes with the documentation here


C - Five Minutes Tutorial

Here is a 10 steps examples that demonstrate how to store, query and update objects with ODB.

Step 1: Create and store a Sport instance

    public void step1() throws Exception {
 
            // Create instance
            Sport sport = new Sport("volley-ball");
 
            ODB odb = null;
 
            try {
                // Open the database
                odb = ODBFactory.open(ODB_NAME);
 
                // Store the object
                odb.store(sport);
            } finally {
                if (odb != null) {
                    // Close the database
                    odb.close();
                }
            }
    }

Step 2: Create and store a Game instance

       public void step2() throws Exception {
 
        // Create instance
        Sport volleyball = new Sport("volley-ball");
 
        // Create 4 players
        Player player1 = new Player("olivier", new Date(), volleyball);
        Player player2 = new Player("pierre", new Date(), volleyball);
        Player player3 = new Player("elohim", new Date(), volleyball);
        Player player4 = new Player("minh", new Date(), volleyball);
 
        // Create two teams
        Team team1 = new Team("Paris");
        Team team2 = new Team("Montpellier");
 
        // Set players for team1
        team1.addPlayer(player1);
        team1.addPlayer(player2);
 
        // Set players for team2
        team2.addPlayer(player3);
        team2.addPlayer(player4);
 
        // Then create a volley ball game for the two teams
        Game game = new Game(new Date(), volleyball, team1, team2);
 
        ODB odb = null;
 
        try {
            // Open the database
            odb = ODBFactory.open(ODB_NAME);
 
            // Store the object
            odb.store(game);
        } finally {
            if (odb != null) {
                // Close the database
                odb.close();
            }
        }
    }

Step 3: Example of a simple CriteriaQuery

        /** Criteria Query */
    public void step3() throws Exception {
        ODB odb = null;
 
        try {
            // Open the database
            odb = ODBFactory.open(ODB_NAME);
            IQuery query = new CriteriaQuery(Player.class, Where.equal("name", "olivier"));
            Objects<Player> players = odb.getObjects(query);
 
            System.out.println("\nStep 3 : Players with name olivier");
 
            int i = 1;
            // display each object
            while (players.hasNext()) {
                System.out.println((i++) + "\t: " + players.next());
            }
        } finally {
            if (odb != null) {
                // Close the database
                odb.close();
            }
        }
    }

Step 4: Example of CriteriaQuery navigating between object relations

        /**
      * Restrictions query with relations
      * 
      */
     public void step4() throws Exception {
 
         ODB odb = null;
 
         try {
             // Open the database
             odb = ODBFactory.open(ODB_NAME);
             // Let's insert a tennis player
             Player agassi = new Player("André Agassi", new Date(), new Sport("Tennis"));
             odb.store(agassi);
 
             IQuery query = new CriteriaQuery(Player.class, Where.equal("favoriteSport.name", "volley-ball"));
 
             Objects<Player> players = odb.getObjects(query);
 
             System.out.println("\nStep 4 : Players of Voller-ball");
 
             int i = 1;
             // display each object
             while (players.hasNext()) {
                 System.out.println((i++) + "\t: " + players.next());
             }
         } finally {
             if (odb != null) {
                 // Close the database
                 odb.close();
             }
         }
    }

Step 5: Example of CriteriaQuery using object references

        /**
     * Criteria query with relations
     * 
     */
    public void step5() throws Exception {
 
        ODB odb = null;
 
        try {
            // Open the database
            odb = ODBFactory.open(ODB_NAME);
            // retrieve the volley ball sport object
            IQuery query = new CriteriaQuery(Sport.class, Where.equal("name", "volley-ball"));
            Sport volleyBall = (Sport) odb.getObjects(query).getFirst();
 
            // Now build a query to get all players that play volley ball, using
            // the volley ball object
            query = new CriteriaQuery(Player.class, Where.equal("favoriteSport", volleyBall));
 
            Objects<Player> players = odb.getObjects(query);
 
            System.out.println("\nStep 5: Players of Voller-ball");
 
            int i = 1;
            // display each object
            while (players.hasNext()) {
                System.out.println((i++) + "\t: " + players.next());
            }
 
        } finally {
            if (odb != null) {
                // Close the database
                odb.close();
            }
        }
    }

warning: to use this kind of query in Client/Server mode, the class Sport should implement Serializable.

Step 6: Example of CriteriaQuery using the OR operador

           /**
            * Criteria query with relations and OR
            * 
            */
           public void step6() throws Exception {
               ODB odb = null;
 
               try {
                   // Open the database
                   odb = ODBFactory.open(ODB_NAME);
                   IQuery query = new CriteriaQuery(Player.class, Where.or().add(Where.equal("favoriteSport.name", "volley-ball"))
                           .add(Where.like("favoriteSport.name", "%nnis")));
 
                   Objects<Player> players = odb.getObjects(query);
 
                   System.out.println("\nStep 6 : Volley-ball and Tennis Players");
 
                   int i = 1;
                   // display each object
                   while (players.hasNext()) {
                       System.out.println((i++) + "\t: " + players.next());
                   }
               } finally {
                   if (odb != null) {
                       // Close the database
                       odb.close();
                   }
               }
           }

Step 7: Example of CriteriaQuery using NOT and like

        /**
     * Criteria query with relations and NOT
     * 
     */
    public void step7() throws Exception {
        ODB odb = null;
 
        try {
            // Open the database
            odb = ODBFactory.open(ODB_NAME);
            IQuery query = new CriteriaQuery(Player.class, Where.not(Where.equal("favoriteSport.name", "volley-ball")));
 
            Objects<Player> players = odb.getObjects(query);
 
            System.out.println("\nStep 7 : Players that don't play Volley-ball");
 
            int i = 1;
            // display each object
            while (players.hasNext()) {
                System.out.println((i++) + "\t: " + players.next());
            }
 
        } finally {
            if (odb != null) {
                // Close the database
                odb.close();
            }
        }
    }

Step 8: Example of NativeQuery

        /**
     * Native query
     * 
     */
    public void step8() throws Exception {
        ODB odb = null;
 
        try {
            // Open the database
            odb = ODBFactory.open(ODB_NAME);
            IQuery query = new SimpleNativeQuery() {
                public boolean match(Player player) {
                    return player.getFavoriteSport().getName().toLowerCase().startsWith("volley");
                }
            };
 
            Objects<Player> players = odb.getObjects(query);
 
            System.out.println("\nStep 8 bis: Players that play Volley-ball");
 
            int i = 1;
            // display each object
            while (players.hasNext()) {
                System.out.println((i++) + "\t: " + players.next());
            }
 
        } finally {
            if (odb != null) {
                // Close the database
                odb.close();
            }
        }
    }

Step 9: CriteriaQuery with Where on List

    /**
     * Native query with Objectss,
     * 
     */
    public void step9() throws Exception {
        ODB odb = null;
 
        try {
            // Open the database
            odb = ODBFactory.open(ODB_NAME);
 
            // first retrieve the player Minh
            IQuery query = new CriteriaQuery(Player.class, Where.equal("name", "minh"));
            Objects<Player> players = odb.getObjects(query).getFirst();
            Player minh = players.getFirst();
 
            // builds a query to get all teams where mihn plays
            query = new CriteriaQuery(Team.class, Where.contain("players", minh));
            Objects<Team> teams = odb.getObjects(query);
 
            System.out.println("\nStep 9: Team where minh plays");
 
            int i = 1;
            // display each object
            while (teams.hasNext()) {
                System.out.println((i++) + "\t: " + teams.next());
            }
 
        } finally {
            if (odb != null) {
                // Close the database
                odb.close();
            }
        }
    }

Step 10: Ordering the query result

    /**
     * Ordering query result
     * 
     * @throws Exception
     */
    public void step10() throws Exception {
        ODB odb = null;
 
        try {
            // Open the database
            odb = ODBFactory.open(ODB_NAME);
            IQuery query = new CriteriaQuery(Player.class);
            query.orderByAsc("name");
 
            Objects<Player> players = odb.getObjects(query);
 
            System.out.println("\nStep 10: Players ordered by name asc");
 
            int i = 1;
            // display each object
            while (players.hasNext()) {
                System.out.println((i++) + "\t: " + players.next());
            }
 
            query.orderByDesc("name");
 
            players = odb.getObjects(query);
 
            System.out.println("\nStep 10: Players ordered by name desc");
 
            i = 1;
            // display each object
            while (players.hasNext()) {
                System.out.println((i++) + "\t: " + players.next());
            }
 
        } finally {
            if (odb != null) {
                odb.close();
            }
        }
    }

ODB Explorer

ODBExplorer is a tool to:

  • Browse objects
  • Query objects
  • Create objects
  • Update objects
  • Delete objects
  • Export/Import an ODB Database.
  • Refactor the database

To execute the ODB Explorer execute the odb-explorer.bat batch file or execute the following command:

$ cd $ODB-package$/
$ java -jar neodatis-odb.jar

To open a database, click on the ODB menu and choose the ‘Open Database’ item then point to the database file you want to open

odb-explorer-menu.png

Then ODB Explorer displays the meta-model of the database of the left of the window:

odb-explorer-meta-model.png
  • The ‘Table View’ item, displays data in an sql-like query result
  • The ‘Object View’ item displays all objects in a hierarchy mode
  • The ‘Query’ item opens a graphical wizard to build a CriteriaQuery
  • The ‘New Object’ item opens a window to create a new instance of the specific class
  • The Refactoring – Raname class allows renaming the class in the database.

Browsing Objects

To browse a database, simply open the database file. On the left of the screen, the meta-model of the database will be displayed.

Choose a class and a way to display data:

  • Table View: display the result as a SQL query result.
  • Object View: display objects as a tree respecting the object model

Query

The ODBExplorer offers a graphic interface to build a CriteriaQuery to query a subset of objects:

odb-explorer-query.png

If you want to learn more about NeoDatis ODB, click here to download the full documentation in PDF format.

You can also diectly download the full ODB package that comes with the documentation here


Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License