Niklas Mehner
October 3, 2007
Client.openLocalStore(String configFile);
Client openLocalStore(String configFile,
boolean create);
ConfigFile contains the path to a configuration file for the database. The first method creates a new store, if the store does not exist. The second method allows to specify wether or not to create the database.
Upon success a client ( org.siebengeisslein.Client) instance is returned that is used for all further work on the database.
After finishing work on the database the method
client.close();
should be called.
java org.siebengeisslein.Server -c netdb.config
Client.openRemoteStore(host, port, username, password)
Upon success a client ( org.siebengeisslein.org.siebengeisslein.Client) instance is returned that is used for all further work on the database.
Before making any changes to the data contained in the datastore, a transaction has to be created. This is done by calling the createTransaction() of the client:
ClientTransaction ct = client.createTransaction();
After working on the persistent objects, the changes are committed by calling
ct.commit();or discarded by calling
ct.abort();
After a transaction is closed, all persistent objects become invalid and may not be used again. Doing so may lead to erratic behavior. Despite this fact references to persistent objects can be held accross transactions. This is described in detail in section 6.
CommitDependency cd = ct.commitOptimistic();
The commit dependency can be used to track when durability is achieved:
cd.waitCommit()
Optimistic transactions allow to certain performance optimizations. They exspecially improve performance on high latency network connections and when many small transactions are used.
These objects face some restrictions (which are verified while loading the classes):
The first three restrictions are needed to be able to track changes to the persistent objects. The fourth ensures, that all objects referred to by a persistent object can be made persistent.
Assigning instances of classes, that do not extend Persistent, to fields of interface type, will result in a runtime exception.
Nesting constructors will result in VerifyErrors, when the class is loaded. These errors can be removed by changing the code:
Object obj = new Class1(new Class2());
to
Class2 temp = new Class2(); Object obj = new Class1(temp);
Also if there exists a strong reference (StrongRef) to the object, the transient fields are guaranteed not to be cleared.
A user local variable is declared using the UserScope ( org.siebengeisslein.client.UserScope) annotation.
private @UserScope PString value;
The type of a user local variable has to be a persistent class.
client.setRoot(name, object);is called. This makes object, and all objects, that are referred to by object persistent.
An existing root object can be loaded from the datastore by calling
client.getRoot(name);
Ref ref = pObject.getRef();
In a later transaction the persistent obejct can be loaded by calling:
ref.get();Note that ths may result in an UnknownOIDException
Instead of starting the application by executing:
java -classpath classpath classname arguments
the application is now started by executing:
java -javaagent:instrument.jar
-classpath SiebenGeisslein.jar:bcel.jar:classpath
classname arguments
package org.siebengeissleinexample.hello;
import org.siebengeisslein.client.Client;
import org.siebengeisslein.client.ClientTransaction;
import org.siebengeisslein.client.Persistent;
import org.siebengeisslein.server.UnknownRootException;
public class HelloWorld extends Persistent {
private int count;
public HelloWorld() {
count = 0;
}
public void run() {
System.out.println("Hello World!");
System.out.println("Called " + count + " times.");
count++;
}
public static void main(String[] args) throws Exception {
if (args.length != 1) {
throw new IllegalArgumentException("Please specify a " +
"configuration file.");
}
// Open a connection to the datastore
Client client = Client.openLocalStore(args[0]);
// Create a transaction
ClientTransaction ct = client.createTransaction();
// Get the HelloWorld object, if it does not exist:
// Create a new object.
HelloWorld hw;
try {
hw = (HelloWorld) client.getRoot("HelloWorld");
} catch (UnknownRootException ure) {
hw = new HelloWorld();
client.setRoot("HelloWorld", hw);
}
// Ready to run
hw.run();
// Commit transaction
ct.commit();
// Close database.
client.close();
}
}
To start the program the ApplicationStarter ( org.siebengeisslein.client.ApplicationStarter) is used:
java org.siebengeisslein.client.ApplicationStarter \
org.siebengeissleinexample.hello.HelloWorld \
db.conf