I2P Notes: This is the database used by the BlockfileNamingService class. It is heavily modified from the original 0.1.1 version. Not for direct use by apps, clients, or plugins. This package is not currently intended for general use, as the API may be subject to change. Contact I2P developers if you are considering use in another application. Following is the original documentation copied from metanotion website.
A 100% Java 1.3, BSD Licensed, embeddable single file database engine in 32KB. This database was designed for PDA based and J2ME applications.
A good, ACID database is a nice thing to work with. Unfortunately, in the goal to make this small, fast, and work with minimal dependencies, something had to give. So I list things which this database will likely never have. Of course, since it is BSD Licensed, patches welcome...
There are still bugs(none known...). The app that this was written for is still in testing, but we should most of the issues sorted by the time we deploy it in a few weeks(early November, 2006). Some loading speed issues on large record sets, and memory usage could still be improved. All this and feedback from other uses will direct this products evolution.
What is currently up here is not "1.0" code, but we will release a labeled "1.0" version once we feel happy with the state of the codebase.
You probably store at least part of your application data in memory in a class from the Java Collections Framework. The BlockFile database stores data in a Skip List that almost implements java.util.SortedMap. You can create and store as many named(with a string) SkipList in the database as you want.
To serialize your data, you have to either extend our SerialStreams class or implement our Serializer interface. We could have done something cool and fancy with reflection(and other cool stuff with Java 1.5), but that would probably not do the Right Thing™ most of the time. As you can see, there's not a lot to it anyway:
public abstract class SerialStreams implements Serializer {
// ...
abstract public void writeOut(DataOutputStream dos, Object o) throws IOException;
abstract public Object readIn(DataInputStream dis) throws IOException;
}
public interface Serializer {
public byte[] getBytes(Object o);
public Object construct(byte[] b);
}
Now, about those skip lists. They implement a java.util.ListIterator so you can get "nearby" values, and you can use anything for a key that implements java.lang.Comparable. So, here's the interface to a SkipList:
public class SkipList {
...
public void put(Comparable key, Object val) ...
public Object remove(Comparable key) ...
public Object get(Comparable key) ...
public ListIterator iterator() ...
public ListIterator min() ...
public ListIterator max() ...
// Find the first key bigger than or equal to key,
// or the biggest key less than key if there is no bigger or equal.
public ListIterator find(Comparable key) ...
}
Better documentation is forthcoming, but there really isn't much to know. The entire public interface to the library is on this page. Where possible, it sticks to idiomatic Java and standard interfaces.
import net.metanotion.io.block.BlockFile;
...
try {
BlockFile db = new BlockFile(new File("my.db"), false); // true will create
} catch (IOException ioe) {
System.out.println("Bummer");
}
import net.metanotion.util.skiplist.SkipList;
import net.metanotion.io.Serializer;
...
class KeySerializer implements Serializer ...
class ValueSerializer implements Serializer ...
...
// Open preexisting
SkipList index = db.getIndex("My Index", new KeySerializer(), new ValueSerializer());
// Create
SkipList index = db.makeIndex("My Index", new KeySerializer(), new ValueSerializer());
public class BlockFile implements Closeable {
public BlockFile(RandomAccessInterface rai) ...
public BlockFile(RandomAccessFile raf) ...
public BlockFile(RandomAccessFile raf, boolean init) ...
public BlockFile(File f, boolean init) ...
public BlockFile(RandomAccessInterface rai, boolean init) ...
public SkipList getIndex(String name, Serializer key, Serializer val) ...
public SkipList makeIndex(String name, Serializer key, Serializer val) ...
public void delIndex(String name) ...
public void close() ...
}
Basically, its an interface version of java.io.RandomAccessFile(which itself implements DataInput, DataOutput and a few methods for getting/setting the file pointer).
So, in other words, if you can provide an implementation of this interface, you can use the BlockFile database. This frees it from dependence on the RandomAccessFile class. If you don't see why this is useful and you're going to be using "files" on PDA's and phone's, well, you'll understand soon enough...
An unnecessary class was removed, some junk methods removed, and a couple of JDK compatability issues were fixed. The StringBytes class was switched to ASCII(from UTF-8) for better compatibility.