Do not waste time - get started and enjoy db4o and its benefits. Together with the download you will get our full Formula 1 Tutorial to get you up to speed within minutes.

If you prefer a PDF version of the tutorial check our options at the end of this page. You might also want to check our Getting Started Guide if you're not sure how to install a third party library in your favorite IDE.

Here's a glance at the "First Steps" chapter to give you an idea how simple it is to start using db4o in your own projects:

Chapter 2 | First Steps

Let us get started as simple as possible. We are going to learn how to open, store, retrieve, update and delete instances of a single class that only contains primitive and String members. In our example this will be a Formula One (F1) pilot whose attributes are his name and the F1 points he has already gained this season.

First we create a native class such as:

   package com.db4o.f1.chapter1;

   public class Pilot {    
       private String name;
       private int points;  

       public Pilot(String name,int points) {
           this.name=name;
           this.points=points;
       }

       public int getPoints() {
           return points;
       }

       public void addPoints(int points) {
           this.points+=points;
       }

       public String getName() {
           return name;
       }

       public String toString() {
           return name+"/"+points;
       }
   }	

Note that this class does not contain any db4o related code.

2.1. Opening the database

To access a db4o database file or create a new one, call Db4o.openFile() and provide the path to your database file as the parameter, to obtain an ObjectContainer instance. ObjectContainer represents "The Database", and will be your primary interface to db4o. Closing the ObjectContainer with the #close() method will close the database file and release all resources associated with it.

   
   // accessDb4o

   ObjectContainer db=Db4o.openFile(Util.DB4OFILENAME);
   try {
       // do something with db4o
   }
   finally {
       db.close(); 
   }
    

For the following examples we will assume that our environment takes care of opening and closing the ObjectContainer automagically, and stores the reference in a variable named 'db'.

2. 2. Storing objects

To store an object, we simply call set() on our database, passing any object as a parameter.

   // storeFirstPilot 

   Pilot pilot1=new Pilot("Michael Schumacher",100);
   db.set(pilot1); 
   System.out.println("Stored "+pilot1);

    OUTPUT: 
       Stored Michael Schumacher/100

We'll need a second pilot, too.

   // storeSecondPilot

   Pilot pilot2=new Pilot("Rubens Barrichello",99);
   db.set(pilot2);
   System.out.println("Stored "+pilot2);

    OUTPUT: 
       Stored Rubens Barrichello/99 
       

2.3. Retrieving objects

db4o supplies three different quering systems, Query by Example (QBE), Native Queries (NQ) and the SODA Query API (SODA). In this first example we will introduce QBE. Once you are familiar with storing objects, we encourage you to use Native Queries, the main db4o querying interface.

When using Query-By-Example, you create a prototypical object for db4o to use as an example of what you wish to retrieve. db4o will retrieve all objects of the given type that contain the same (non- default) field values as the example. The results will be returned as an ObjectSet instance. We will use a convenience method #listResult() to display the contents of our result ObjectSet :

   public static void listResult (ObjectSet result){
      System.out.println(result.size());
      while(result.hasNext()) {
          System.out.println(result.next());
      }
   }

To retrieve all pilots from our database, we provide an 'empty' prototype:

   // retrieveAllPilotQBE 
   
   Pilot proto=new Pilot(null,0);
   ObjectSet result=db.get(proto);
   listResult(result);

    OUTPUT: 
       2 
       Michael Schumacher/100 
       Rubens Barrichello/99 

Note that we specify 0 points, but our results were not constrained to only those Pilots with 0 points; 0 is the default value for int fields.

db4o also supplies a shortcut to retrieve all instances of a class:

   // retrieveAllPilots 
   
   ObjectSet result=db.get(Pilot.class); 
   listResult(result); 

    OUTPUT: 
       2 
       Michael Schumacher/100 
       Rubens Barrichello/99 

For JDK 5 there also is a generics shortcut, using the query method:

   List <pilots> = db.query(Pilot.class);

To query for a pilot by name:

   // retrievePilotByName 

   Pilot proto=new Pilot("Michael Schumacher",0);
   ObjectSet result=db.get(proto);
   listResult(result);

    OUTPUT: 
       1 
       Michael Schumacher/100 

And to query for Pilots with a specific number of points: 

   // retrievePilotByExactPoints 
   
   Pilot proto=new Pilot(null,100);
   ObjectSet result=db.get(proto);
   listResult(result);

    OUTPUT: 
       1 
       Michael Schumacher/100 

Of course there's much more to db4o queries. They will be covered in more depth in later chapters.

2.4. Updating objects

Updating objects is just as easy as storing them. In fact, you use the same set() method to update your objects: just call set() again after modifying any object. 

   // updatePilot 
   
   ObjectSet result=db.get(new Pilot("Michael Schumacher",0));
   Pilot found=(Pilot)result.next();
   found.addPoints(11);
   db.set(found);
   System.out.println("Added 11 points for "+found);
   retrieveAllPilots(db);

    OUTPUT: 
       Added 11 points for Michael Schumacher/111 
       2 
       Michael Schumacher/111 
       Rubens Barrichello/99 

Notice that we query for the object first. This is an importaint point. When you call set() to modify a stored object, if the object is not 'known' (having been previously stored or retrieved during the current session), db4o will insert a new object. db4o does this because it does not automatically match up objects to be stored, with objects previously stored. It assumes you are inserting a second object which happens to have the same field values.

To make sure you've updated the pilot, please return to any of the retrieval examples above and run them again.

2.5. Deleting objects

Objects are removed from the database using the delete() method.

   // deleteFirstPilotByName 
   
   ObjectSet result=db.get(new Pilot("Michael Schumacher",0));
   Pilot found=(Pilot)result.next();
   db.delete(found);
   System.out.println("Deleted "+found);
   retrieveAllPilots(db);

    OUTPUT: 
       Deleted Michael Schumacher/111 
       1 
       Rubens Barrichello/99 

Let's delete the other one, too.

   // deleteSecondPilotByName 

   ObjectSet result=db.get(new Pilot("Rubens Barrichello",0));
   Pilot found=(Pilot)result.next();
   db.delete(found);
   System.out.println("Deleted "+found);
   retrieveAllPilots(db);

    OUTPUT: 
       Deleted Rubens Barrichello/99 
       0 

Please check the deletion with the retrieval examples above.

As with updating objects, the object to be deleted has to be 'known' to db4o. It is not sufficient to provide a prototype object with the same field values.

2.6. Conclusion

That was easy, wasn't it? We have stored, retrieved, updated and deleted objects with a few lines of code. But what about complex queries? Let's have a look at the restrictions of QBE and alternative approaches in the next chapter.

2.7. Full source

    package com.db4o.f1.chapter1; 
     
     
    import java.io.File; 
     
    import com.db4o.Db4o; 
    import com.db4o.ObjectContainer; 
    import com.db4o.ObjectSet; 
    import com.db4o.f1.Util; 
     
     
    public class FirstStepsExample extends Util {   
        public static void main(String[] args) { 
            new File(Util.DB4OFILENAME).delete(); 
            accessDb4o(); 
            new File(Util.DB4OFILENAME).delete(); 
            ObjectContainer db=Db4o.openFile(Util.DB4OFILENAME); 
            try { 
                storeFirstPilot(db); 
                storeSecondPilot(db); 
                retrieveAllPilots(db); 
                retrievePilotByName(db); 
                retrievePilotByExactPoints(db); 
                updatePilot(db); 
                deleteFirstPilotByName(db); 
                deleteSecondPilotByName(db); 
            } 
            finally { 
                db.close(); 
            } 
        } 
       
        public static void accessDb4o() { 
            ObjectContainer db=Db4o.openFile(Util.DB4OFILENAME); 
            try { 
                // do something with db4o
            } 
            finally { 
                db.close(); 
            } 
        } 
       
        public static void storeFirstPilot(ObjectContainer db) { 
            Pilot pilot1=new Pilot("Michael Schumacher",100); 
            db.set(pilot1); 
            System.out.println("Stored "+pilot1); 
        } 
     
        public static void storeSecondPilot(ObjectContainer db) { 
            Pilot pilot2=new Pilot("Rubens Barrichello",99); 
            db.set(pilot2); 
            System.out.println("Stored "+pilot2); 
        } 
     
        public static void retrieveAllPilotQBE(ObjectContainer db) { 
            Pilot proto=new Pilot(null,0); 
            ObjectSet result=db.get(proto); 
            listResult(result); 
        } 
       
        public static void retrieveAllPilots(ObjectContainer db) { 
            ObjectSet result=db.get(Pilot.class); 
            listResult(result); 
        } 
     
        public static void retrievePilotByName(ObjectContainer db) { 
            Pilot proto=new Pilot("Michael Schumacher",0); 
            ObjectSet result=db.get(proto); 
            listResult(result); 
        } 
       
        public static void retrievePilotByExactPoints(ObjectContainer db) 
    { 
            Pilot proto=new Pilot(null,100); 
            ObjectSet result=db.get(proto); 
            listResult(result); 
        }            
        public static void updatePilot(ObjectContainer db) { 
            ObjectSet result=db.get(new Pilot("Michael Schumacher",0)); 
            Pilot found=(Pilot)result.next(); 
            found.addPoints(11); 
            db.set(found); 
            System.out.println("Added 11 points for "+found); 
            retrieveAllPilots(db); 
        } 
     
        public static void deleteFirstPilotByName(ObjectContainer db) { 
            ObjectSet result=db.get(new Pilot("Michael Schumacher",0)); 
            Pilot found=(Pilot)result.next(); 
            db.delete(found); 
            System.out.println("Deleted "+found); 
            retrieveAllPilots(db); 
        } 
     
        public static void deleteSecondPilotByName(ObjectContainer db) { 
            ObjectSet result=db.get(new Pilot("Rubens Barrichello",0)); 
            Pilot found=(Pilot)result.next(); 
            db.delete(found); 
            System.out.println("Deleted "+found); 
            retrieveAllPilots(db); 
        } 
    } 
       
       

The above is only the "First Steps" chapter of the tutorial. Please download the db4o distribution to access the full interactive tutorial.

Alternatively, you can just select one of these PDF downloads: