<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<link rel="stylesheet" type="text/css" href="docs.css">
<!--[if gte IE 5]>
<link href="docs_ie.css" rel="stylesheet" type="text/css">
<![endif]-->
</head>
<body><div id="pagecontainer"><table><tr><td width="5"> </td><td><a name="First"></a><br>
<a name="outline131"></a><br><h1>2. First Steps</h1><br>
Let's get started as simple as possible. We are going to demonstrate how to 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.<br>
<br>
First we create a class to hold our data. It looks like this:<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>namespace Db4odoc.Tutorial.F1.Chapter1<br>
{<br>
public class Pilot<br>
{<br>
string _name;<br>
int _points;<br>
<br>
public Pilot(string name, int points)<br>
{<br>
_name = name;<br>
_points = points;<br>
}<br>
<br>
public string Name<br>
{<br>
get<br>
{<br>
return _name;<br>
}<br>
}<br>
<br>
public int Points<br>
{<br>
get<br>
{<br>
return _points;<br>
}<br>
} <br>
<br>
public void AddPoints(int points)<br>
{<br>
_points += points;<br>
} <br>
<br>
override public string ToString()<br>
{<br>
return string.Format("{0}/{1}", _name, _points);<br>
}<br>
}<br>
}<br>
</code></td></tr></table>
<br>
<br>
Notice that this class does not contain any db4o-related code.<br>
<br>
<ul>
<a name="outline132"></a><br><h2>2.1. Opening the database</h2><br>
To access a db4o database file or create a new one, call DB4OEMBEDDED.OPENFILE() and provide Db4oEmbedded.newConfiguration() as a configuration template and the path to your database file as the second parameter, to obtain an IObjectContainer instance. IObjectContainer represents "The Database", and will be your primary interface to db4o. Closing the IObjectContainer with the #Close() method will close the database file and release all resources associated with it.<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// accessDb4o<br>
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))<br>
{<br>
// do something with db4o<br>
}</code></td></tr></table>
<br>
<br>
Db4oFileName is just a string value representing any filename. If the file with this name already exists, it will be opened as db4o database, otherwise a new db4o database will be created.<br>
For the following examples we will assume that our environment takes care of opening and closing the IObjectContainer automagically, and stores the reference in a variable named 'db'.<br>
<br>
<a name="outline133"></a><br><h2>2.2. Storing objects</h2><br>
To store an object, we simply call #Store() on our database, passing any object as a parameter.<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// storeFirstPilot<br>
Pilot pilot1 = new Pilot("Michael Schumacher", 100);<br>
db.Store(pilot1);<br>
Console.WriteLine("Stored {0}", pilot1);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "storeFirstPilot")' /></td></tr></table>
<br>
<br>
We'll need a second pilot, too.<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// storeSecondPilot<br>
Pilot pilot2 = new Pilot("Rubens Barrichello", 99);<br>
db.Store(pilot2);<br>
Console.WriteLine("Stored {0}", pilot2);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "storeSecondPilot")' /></td></tr></table>
<br>
<br>
<a name="outline134"></a><br><h2>2.3. Retrieving objects</h2><br>
The easiest way to see the content of our database is to use Object Manager Enterprise, which will be introduced in the <a href="ObjectManagerOverview.html#ObjectManagerOverview">next chapter</a> . For now let's continue with the API overview and learn how to build db4o queries.<br>
db4o supplies several different querying systems, <em>Query by Example</em> (QBE), <em>LINQ</em>, <em>Native Queries</em> (NQ) and the <em>SODA Query API</em> (SODA). In this first example we will introduce QBE. Once you are familiar with storing objects, we encourage you to use <a href="Linq.html#LINQ">LINQ</a> .<br>
<br>
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 IObjectSet instance. We will use a convenience method #ListResult() to display the contents of our result IObjectSet :<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>public static void ListResult(IObjectSet result)<br>
{<br>
Console.WriteLine(result.Count);<br>
foreach (object item in result)<br>
{<br>
Console.WriteLine(item);<br>
}<br>
}</code></td></tr></table>
<br>
<br>
To retrieve all pilots from our database, we provide an 'empty' prototype:<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// retrieveAllPilotQBE<br>
Pilot proto = new Pilot(null, 0);<br>
IObjectSet result = db.QueryByExample(proto);<br>
ListResult(result);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "retrieveAllPilotQBE")' /></td></tr></table>
<br>
<br>
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.<br>
<br>
db4o also supplies a shortcut to retrieve all instances of a class:<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// retrieveAllPilots<br>
IObjectSet result = db.QueryByExample(typeof(Pilot));<br>
ListResult(result);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "retrieveAllPilots")' /></td></tr></table>
<br>
<br>
For .NET there also is a generics shortcut, using the query method:<br>
<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>IList <Pilot> pilots = db.Query<Pilot>(typeof(Pilot));</code></td></tr></table>
<br>
<br>
To query for a pilot by name:<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// retrievePilotByName<br>
Pilot proto = new Pilot("Michael Schumacher", 0);<br>
IObjectSet result = db.QueryByExample(proto);<br>
ListResult(result);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "retrievePilotByName")' /></td></tr></table>
<br>
<br>
And to query for Pilots with a specific number of points:<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// retrievePilotByExactPoints<br>
Pilot proto = new Pilot(null, 100);<br>
IObjectSet result = db.QueryByExample(proto);<br>
ListResult(result);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "retrievePilotByExactPoints")' /></td></tr></table>
<br>
<br>
<br>
Of course there's much more to db4o queries. They will be covered in more depth in later chapters.<br>
<br>
<a name="outline135"></a><br><h2>2.4. Updating objects</h2><br>
Updating objects is just as easy as storing them. In fact, you use the same #Store() method to update your objects: just call #Store() again after modifying any object.<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// updatePilot<br>
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));<br>
Pilot found = (Pilot)result.Next();<br>
found.AddPoints(11);<br>
db.Store(found);<br>
Console.WriteLine("Added 11 points for {0}", found);<br>
RetrieveAllPilots(db);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "updatePilot")' /></td></tr></table>
<br>
<br>
Notice that we query for the object first. This is an importaint point. When you call #Store() 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.<br>
<br>
To make sure you've updated the pilot, please return to any of the retrieval examples above and run them again.<br>
<br>
<a name="outline136"></a><br><h2>2.5. Deleting objects</h2><br>
Objects are removed from the database using the #Delete() method.<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// deleteFirstPilotByName<br>
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));<br>
Pilot found = (Pilot)result.Next();<br>
db.Delete(found);<br>
Console.WriteLine("Deleted {0}", found);<br>
RetrieveAllPilots(db);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "deleteFirstPilotByName")' /></td></tr></table>
<br>
<br>
Let's delete the other one, too.<br>
<br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>// deleteSecondPilotByName<br>
IObjectSet result = db.QueryByExample(new Pilot("Rubens Barrichello", 0));<br>
Pilot found = (Pilot)result.Next();<br>
db.Delete(found);<br>
Console.WriteLine("Deleted {0}", found);<br>
RetrieveAllPilots(db);</code></td><td class="lg" align="left" valign="bottom" width=43><input type='button' class='button' value='Run' onclick='window.external.RunExample("com.db4odoc.f1.chapter1.FirstStepsExample", "deleteSecondPilotByName")' /></td></tr></table>
<br>
<br>
Please check the deletion with the retrieval examples above.<br>
<br>
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.<br>
<br>
<a name="outline137"></a><br><h2>2.6. Conclusion</h2><br>
That was easy, wasn't it? We have stored, retrieved, updated and deleted objects with a few lines of code. Now you are probably interested to see how the database looks like. Let's have a look using db4o graphical tool - Object Manager in the <a href="ObjectManagerOverview.html#ObjectManagerOverview">next chapter</a> .<br>
<br>
<a name="outline138"></a><br><h2>2.7. Full source</h2><br>
<table width="100%" cellpadding="3" cellspacing="0" border="0"><tr><td class="lg">
<code>using System;<br>
using System.IO;<br>
using Db4objects.Db4o;<br>
using Db4objects.Db4o.Query;<br>
using Db4odoc.Tutorial;<br>
namespace Db4odoc.Tutorial.F1.Chapter1<br>
{<br>
public class FirstStepsExample : Util<br>
{<br>
readonly static string YapFileName = Path.Combine(<br>
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),<br>
"formula1.yap");<br>
public static void Main(string[] args)<br>
{<br>
File.Delete(YapFileName);<br>
AccessDb4o();<br>
File.Delete(YapFileName);<br>
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))<br>
{<br>
StoreFirstPilot(db);<br>
StoreSecondPilot(db);<br>
RetrieveAllPilots(db);<br>
RetrievePilotByName(db);<br>
RetrievePilotByExactPoints(db);<br>
UpdatePilot(db);<br>
DeleteFirstPilotByName(db);<br>
DeleteSecondPilotByName(db);<br>
}<br>
}<br>
public static void AccessDb4o()<br>
{<br>
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))<br>
{<br>
// do something with db4o<br>
}<br>
}<br>
public static void StoreFirstPilot(IObjectContainer db)<br>
{<br>
Pilot pilot1 = new Pilot("Michael Schumacher", 100);<br>
db.Store(pilot1);<br>
Console.WriteLine("Stored {0}", pilot1);<br>
}<br>
public static void StoreSecondPilot(IObjectContainer db)<br>
{<br>
Pilot pilot2 = new Pilot("Rubens Barrichello", 99);<br>
db.Store(pilot2);<br>
Console.WriteLine("Stored {0}", pilot2);<br>
}<br>
public static void RetrieveAllPilotQBE(IObjectContainer db)<br>
{<br>
Pilot proto = new Pilot(null, 0);<br>
IObjectSet result = db.QueryByExample(proto);<br>
ListResult(result);<br>
}<br>
public static void RetrieveAllPilots(IObjectContainer db)<br>
{<br>
IObjectSet result = db.QueryByExample(typeof(Pilot));<br>
ListResult(result);<br>
}<br>
public static void RetrievePilotByName(IObjectContainer db)<br>
{<br>
Pilot proto = new Pilot("Michael Schumacher", 0);<br>
IObjectSet result = db.QueryByExample(proto);<br>
ListResult(result);<br>
}<br>
public static void RetrievePilotByExactPoints(IObjectContainer db)<br>
{<br>
Pilot proto = new Pilot(null, 100);<br>
IObjectSet result = db.QueryByExample(proto);<br>
ListResult(result);<br>
}<br>
public static void UpdatePilot(IObjectContainer db)<br>
{<br>
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));<br>
Pilot found = (Pilot)result.Next();<br>
found.AddPoints(11);<br>
db.Store(found);<br>
Console.WriteLine("Added 11 points for {0}", found);<br>
RetrieveAllPilots(db);<br>
}<br>
public static void DeleteFirstPilotByName(IObjectContainer db)<br>
{<br>
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));<br>
Pilot found = (Pilot)result.Next();<br>
db.Delete(found);<br>
Console.WriteLine("Deleted {0}", found);<br>
RetrieveAllPilots(db);<br>
}<br>
public static void DeleteSecondPilotByName(IObjectContainer db)<br>
{<br>
IObjectSet result = db.QueryByExample(new Pilot("Rubens Barrichello", 0));<br>
Pilot found = (Pilot)result.Next();<br>
db.Delete(found);<br>
Console.WriteLine("Deleted {0}", found);<br>
RetrieveAllPilots(db);<br>
}<br>
}<br>
}<br>
</code></td></tr></table>
<br>
<br><br><div id="footer"><p align="center">Do you have any questions, suggestions or feedback? Ask your questions in the <a href="http://developer.db4o.com/Forums.aspx" target=_top>db4o forums</a>. Join the <a href="http://developer.db4o.com" target=_top>db4o community</a> for addional resources and news.<br><br><a href="http://www.db4o.com/" target=_top><small>www.db4o.com</small></a></p>.</div><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br></td></tr></table></div></body></html>
