This section provides details about LMDBJava releases, such as code migrations for breaking changes, that are not covered in the Change Log.

DbiFlags.MDB_UNSIGNEDKEY was added in v0.9.1 to address a change to comparator behaviour that was made in v0.8.3. The change in 0.8.3 made the default comparator signed, which is inconsistent with LMDB's iteration order. DbiFlags.MDB_UNSIGNEDKEY was added to allow the user to use unsigned comparators. v1.0.0 has removed this flag as the default comparators are now all unsigned and consistent with LMDB's mdb_cmp comparator.

Simply remove this flag from your code. No other change is required.

All uses of flag enum varags parameters have been deprecated, i.e. ,DbiFlags... flags).

You are now required to use one of these collection interfaces instead:

• EnvFlagSet
• DbiFlagSet
• PutFlagSet
• TxnFlagSet
• CopyFlagSet

These flag collections pre-compute the combined mask value that is passed down to LMDB. This saves repeated work on high use methods like put(...). Flag sets are immutable and should ideally be held as static final fields for re-use.

Each flag enum implements the corresponding XxxFlagSet interface, e.g. PutFlags.MDB_APPEND can be used in place of PutFlagSet.of(PutFlags.MDB_APPEND), so if your code is using zero or one flags you should not have to change any code.

The simplest way to build a flag set is like PutFlagSet.of(PutFlags.MDB_APPEND, PutFlags.MDB_RESERVE), but there are various factor methods and a builder for creating flag sets.

The static factory method org.lmdbjava.Env#open has been deprecated. Now, the only way to create/open an Env is to use the Env.Builder via the existing create methods:

• org.lmdbjava.Env#create()
• org.lmdbjava.Env#create(org.lmdbjava.BufferProxy<T>)

The following open methods on the builder have been deprecated:

• org.lmdbjava.Env.Builder#open(java.io.File)
• org.lmdbjava.Env.Builder#open(java.io.File, org.lmdbjava.EnvFlags...)

You now need to use org.lmdbjava.Env.Builder#open(java.nio.file.Path).

The following new methods have been added to Env.Builder:

• org.lmdbjava.Env.Builder#setMapSize(long, org.lmdbjava.ByteUnit)
• org.lmdbjava.Env.Builder#setFilePermissions(int)
• org.lmdbjava.Env.Builder#setEnvFlags(java.util.Collection<org.lmdbjava.EnvFlags>)
• org.lmdbjava.Env.Builder#setEnvFlags(org.lmdbjava.EnvFlags...)
• org.lmdbjava.Env.Builder#setEnvFlags(org.lmdbjava.EnvFlagSet)
• org.lmdbjava.Env.Builder#addEnvFlag(org.lmdbjava.EnvFlags)
• org.lmdbjava.Env.Builder#addEnvFlags(org.lmdbjava.EnvFlagSet)
• org.lmdbjava.Env.Builder#addEnvFlags(java.util.Collection<org.lmdbjava.EnvFlags>)

All Env.openDbi(...) methods have been deprecated. The only way to create/open a Dbi is via the new DbiBuilder, which is accessed via:

org.lmdbjava.Env#createDbi().

The new staged builder replaces the many overloaded methods and makes comparator choice clearer.

The following is a typical example of how to create/open a Dbi.

    final Dbi<ByteBuffer> db = env.createDbi()
        .setDbName("db1")
        .withDefaultComparator()
        .setDbiFlags(MDB_CREATE)
        .open();

The staged builder offers the following comparator choices:

• withDefaultComparator() - The default option. Use this if in doubt. The default java comparators are used for cursor start/stop key comparisons.
• withNativeComparator() - All comparator duties are handled by LMDB. Slightly slower than withDefaultComparator().
• withCallbackComparator(ComparatorFactory<T>) - All comparator duties are handled by the Comparator created by the passed ComparatorFactory (only created once during Dbi initialisation).
• withIteratorComparator(ComparatorFactory<T>) - Use the comparator created by the supplied factory for start/stop key comparisons. It MUST match the behaviour of the comparator LMDB uses for iteration order. Don't use this unless you understand the risks.

The ComparatorFactory looks like this:

  @FunctionalInterface
  public interface ComparatorFactory<T> {

    /**
     * Creates a comparator for the supplied {@link DbiFlagSet}. This will only be called once
     * during the initialisation of the {@link Dbi}.
     *
     * @param dbiFlagSet The flags set on the DB that the returned {@link Comparator} will be used
     *     by. The flags in the set may impact how the returned {@link Comparator} should behave.
     * @return A {@link Comparator} applicable to the passed DB flags.
     */
    Comparator<T> create(final DbiFlagSet dbiFlagSet);
  }