mondrian.util
Class LockBox

java.lang.Object
  mondrian.util.LockBox

public class LockBox
extends Object

Provides a way to pass objects via a string moniker.

This is useful if you are passing an object over an API that admits only strings (such as DriverManager.getConnection(String, java.util.Properties)) and where tricks such as ThreadLocal do not work. The callee needs to be on the same JVM, but other than that, the object does not need to have any special properties. In particular, it does not need to be serializable.

First, register the object to obtain a lock box entry. Every lock box entry has a string moniker that is very difficult to guess, is unique, and is not recycled. Pass that moniker to the callee, and from that moniker the callee can retrieve the entry and with it the object.

The entry cannot be forged and cannot be copied. If you lose the entry, you can no longer retrieve the object, and the entry will eventually be garbage-collected. If you call deregister(Entry), callees will no longer be able to look up an entry from its moniker.

The same is not true of the moniker string. Having the moniker string does not guarantee that the entry will not be removed. Therefore, the creator who called register(Object) and holds the entry controls the lifecycle.

The moniker consists of the characters A..Z, a..z, 0..9, $, #, and is thus a valid (case-sensitive) identifier.

All methods are thread-safe.

Since:

2010/11/18

Author:

jhyde

Nested Class Summary

static interface

LockBox.Entry Entry in a LockBox.

Constructor Summary

LockBox()
Creates a LockBox.

Method Summary

boolean	deregister(LockBox.Entry entry) Removes an entry from the lock box.
LockBox.Entry	get(String moniker) Retrieves an entry using its string moniker.
LockBox.Entry	register(Object o) Adds an object to the lock box, and returns a key for it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LockBox

public LockBox()

Creates a LockBox.

Method Detail

register

public LockBox.Entry register(Object o)

Adds an object to the lock box, and returns a key for it.

The object may be null. The same object may be registered multiple times; each time it is registered, a new entry with a new string moniker is generated.

Parameters:

o - Object to register. May be null.

Returns:

Entry containing the object's string key and the object itself

deregister

public boolean deregister(LockBox.Entry entry)

Removes an entry from the lock box.

It is safe to call this method multiple times.

Parameters:

entry - Entry to deregister

Returns:

Whether the object was removed

get

public LockBox.Entry get(String moniker)

Retrieves an entry using its string moniker. Returns null if there is no entry with that moniker.

Successive calls for the same moniker do not necessarily return the same Entry object, but those entries' LockBox.Entry.getValue() will nevertheless return the same value.

Parameters:

moniker - Moniker of the lock box entry

Returns:

Entry, or null if there is no entry with this moniker