net.captp.tables
Class SwissTable

java.lang.Object
 |
 +--net.captp.tables.SwissTable

public class SwissTable

extends Object

Untamed:

mySelfishToSwiss

private final WeakKeyMap mySelfishToSwiss

Maps from NEAR Selfish objects to SwissNumbers.

mySwissToRef

private final WeakValueMap mySwissToRef

Maps from SwissNumber to anything.

Note: can't handle null values.

myEntropy

private final ESecureRandom myEntropy

Provides new unguessable SwissNumbers.

mySwissDBs

private final FlexSet mySwissDBs

OneArgFuncs that handle lookup faulting.

SwissTable

public SwissTable(ESecureRandom entropy)

Enabled:

lookupSwiss

public Object lookupSwiss(BigInteger swissNum)
 throws IndexOutOfBoundsException

Enabled: Lookup an object by SwissNumber.

If not found, throw an IndexOutOfBoundsException. This is necessary since null is a valid return value. (By decree, the SwissNumber 0 designates null.)

IndexOutOfBoundsException

addFaultHandler

public void addFaultHandler(OneArgFunc swissDB)

Enabled: A SwissDB is able to supplement the SwissTable's internal mySwissToRef table with further storage that gets faulted on demand.

When the SwissTable's lookupSwiss fails to find the swissNum in the internal table, it invokes each of its registered swissDBs with a hash of the swissNumber being looked up. This is known as a swissHash, and represents the identity of the object without providing any authority to access the object. A swissDB which has stored a representation of the object elsewhere should then register the object using registerIdentity or registerSwiss, both of which require the swissBase -- the archash of the swissNumber being looked up. In other words,

 swissBase cryptoHash() -> swissNum
 swissNum crytoHash() -> swissHash
 

If an already registered swissDB is re-registered, an exception is thrown.

removeFaultHandler

public void removeFaultHandler(OneArgFunc swissDB)

Enabled: Removes a registered (by addFaultHandler) swissDB.

If not there, this method does nothing.

getIdentity

public BigInteger getIdentity(Object obj)

Enabled: Returns the SwissNumber which represents the identity of this near Selfish object in this vat.

If not 'Ref.isSelfish(obj)", then this will throw an Exception.

This returns the unique SwissNumber which represents the designated near selfish object's unique identity within this vat. If the object wasn't yet associated with a SwissNumber, it will be now.

getNewSwiss

public BigInteger getNewSwiss(Object ref)

Enabled: Returns a SwissNumber with which this ref can be looked up.

This method always assigns and returns a new unique SwissNumber, even for NEAR Selfish objects that already have one, with one exception. The swissNumber for null is always 0.

registerIdentity

public BigInteger registerIdentity(Object obj,
 BigInteger swissBase)

Enabled: Registers obj to have the identity 'swissBase cryptoHash()'.

The cryptoHash of a SwissBase is a SwissNumber, so we also say that the archash of a SwissNumber is a SwissBase. (Of course, our security rests on the assumption that the archash is infeasible to compute.) Since an unconfined client of an object can often get its SwissNumber, something more is needed to establish authority to associate an object with a SwissNumber. For this "something more", we use knowledge of the archash of the number.

The object is given the new identity 'swissBase cryptoHash()', assuming this doesn't conflict with any existing registrations. If it does, an exception is thrown.

registerNewSwiss

public BigInteger registerNewSwiss(Object ref,
 BigInteger swissBase)

Enabled: Registers ref at 'swissBase.cryptoHash()'.

registerNewSwiss() is to registerIdentity() as getNewSwiss() is to getIdentity(). 'swissBase.cryptoHash()' must not already be registered, or an exception will be thrown. If ref is null, an exception is thrown (since we assume its infeasible to find the archash of zero).

nextSwiss

public BigInteger nextSwiss()

Enabled: A convenience method typically used to obtain new SwissBases (archashes of SwissNumbers). Since a client of SwissTable can obtain such entropy from the SwissTable anyway, by registering objects, there's no loss of security in providing this convenience method.