Package net.metanotion

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.

Metanotion BlockFile Database

A 100% Java 1.3, BSD Licensed, embeddable single file database engine in 32KB. This database was designed for PDA based and J2ME applications.

Table of Contents

Features

  • 100% Java 1.3. No JNI.
  • Will work with any "file" as long as you can approximate something like java.io.RandomAccessFile, you can use this.
  • BSD Licensed. Yes, this means you can use it for free in a commercial project. However, if you base some really cool mobile technology startup on this code we'll gladly accept stock options...
  • No dependence on file API's(useful for mobile apps)
  • Small. 32KB in a JAR file. <2000 lines of code.
  • Reasonably fast. This is used in an app running on a sub 200MHz StrongARM PocketPC, and quite handily deals with 70,000 records. The load time is a little slow, but its been tested with a CDC 1.0/Personal Profile device.

Unfeatures

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...

  • No transactions.
  • No SQL.
  • No JDBC.
  • No use of reflection or automagical serialization tricks.

Future Plans

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.

What KIND of database is this?

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:

net.metanotion.io.SerialStreams

public abstract class SerialStreams implements Serializer {
// ...
        abstract public void writeOut(DataOutputStream dos, Object o) throws IOException;
        abstract public Object readIn(DataInputStream dis) throws IOException;
}

net.metanotion.io.Serializer

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) ...
}

Examples

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.

  • Open a database: 
    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");
        }
  • Load or Create a SkipList: 
    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());

net.metanotion.io.block.BlockFile

All the public interface methods: 
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() ...
}

What's this "net.metanotion.io.RandomAccessInterface"?

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...

Download

Bugfix and cleanup Release 10/6/2006

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.

Initial Release 9/28/2006

© 2006 Metanotion Software