net.captp.jcomm
Class IdentityMgr

java.lang.Object
  |
  +--net.captp.jcomm.IdentityMgr

public class IdentityMgr

extends Object

Untamed: An instance of the object is accessible in the privileged scope under the name "identityMgr".

It represents both more and less authority than the makeSturdyRef function. It has more authority in that it allows a form of conversion between capabilities and bits -- specifically SwissBases -- and can therefore not be given to objects you wish to confine in a distributed confinement box.

It allows less authority, in that by itself it cannot cause an object to survive a checkpoint/revive cycle. However, by making the SwissBases available, it allows its clients to manually revive such objects.

An IdentityMgr isn't itself Persistent, but the relevant instance is expected to be a scalpel-key, so a persistent object holding a persistent pointer to that IdentityMgr will likely revive holding instead an appropriate substitute IdentityMgr.

Author:

Mark S. Miller

Field Summary

private Introducer	myIntroducer
private Timer	myTimer

Constructor Summary

(package private)

IdentityMgr(Introducer introducer, Timer timer)

Method Summary

void	__printOn(TextWriter out) Enabled:
void	addFaultHandler(OneArgFunc swissDB) Enabled:
Object[]	makeKnown(Object obj) Enabled: optExpirationDate defaults to forever
Object[]	makeKnown(Object obj, long optExpirationDate) Enabled: Produce a SturdyRef, and a swissBase so in a later incarnation of this vat a newly created object can be made to be the reincarnation of this one (from the perspective of those holding the SturdyRef).
Object[]	makeKnownAs(Object obj, BigInteger swissBase) Enabled: optExpirationDate defaults to forever
Object[]	makeKnownAs(Object obj, BigInteger swissBase, long optExpirationDate) Enabled: Cause 'obj' to be the object designated by 'swissHash cryptoHash()' in this vat.
SturdyRef	makeSturdyRef(Object obj, BigInteger swissBase, long optExpirationDate) Enabled: Given an obj-swissNum association, make a SturdyRef that designates this object across space (between vats, even after partitions) and possibly across time (checkpoint/revives).
BigInteger	nextSwiss() Enabled: Returns an unguessable random number suitable for use as a swissBase.
BigInteger	registerNewSwiss(Object obj, BigInteger swissBase) Enabled: Just delegates to SwissTable.registerNewSwiss(java.lang.Object, java.math.BigInteger)
void	removeFaultHandler(OneArgFunc swissDB) Enabled:

Methods inherited from class java.lang.Object

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

Field Detail

myIntroducer

private final Introducer myIntroducer

myTimer

private final Timer myTimer

Constructor Detail

IdentityMgr

IdentityMgr(Introducer introducer,
            Timer timer)

Parameters:

introducer -

timer -

Method Detail

nextSwiss

public BigInteger nextSwiss()

Enabled: Returns an unguessable random number suitable for use as a swissBase.

Returns:

registerNewSwiss

public BigInteger registerNewSwiss(Object obj,
                                   BigInteger swissBase)

Enabled: Just delegates to SwissTable.registerNewSwiss(java.lang.Object, java.math.BigInteger)

Parameters:

obj -

swissBase -

Returns:

makeSturdyRef

public SturdyRef makeSturdyRef(Object obj,
                               BigInteger swissBase,
                               long optExpirationDate)
                        throws MalformedURLException

Enabled: Given an obj-swissNum association, make a SturdyRef that designates this object across space (between vats, even after partitions) and possibly across time (checkpoint/revives).

This method doesn't itself arrange for the object to be retained. That's up to its callers. They must arrange for the object to last until the expiration time, so that the weak association in the SwissTable will last till then as well. If the object is to survive this incarnation, its caller must arrange to revive or reconstruct the object itself, and then to call makeKnownAs(java.lang.Object, java.math.BigInteger) to re-establish the association between the object and its swissNumber. The CapTP package does not provide such functionality itself. But org.erights.e.extern.persist.SturdyRefMaker builds this functionality on top of the API listed here.

Parameters:

obj - The object for which a SturdyRef is desired

swissBase - The hash of which will be the swissNum associated with this object.

optExpirationDate - The date after which the SturdyRef will not longer be guaranteed to be valid. If Long.MAX_VALUE, then it's always valid.

Returns:

A new SturdyRef for the indicated object

MalformedURLException

makeKnown

public Object[] makeKnown(Object obj)
                   throws MalformedURLException

Enabled: optExpirationDate defaults to forever

MalformedURLException

makeKnown

public Object[] makeKnown(Object obj,
                          long optExpirationDate)
                   throws MalformedURLException

Enabled: Produce a SturdyRef, and a swissBase so in a later incarnation of this vat a newly created object can be made to be the reincarnation of this one (from the perspective of those holding the SturdyRef).

An object is that which object references to it designate. From one vat incarnation to another, the only intervat references which survive are SturdyRefs. When doing identity-persistence (as opposed to object persistence), the application creates the first SturdyRef to a persistent object using makeKnown(..), and makes sure to store the swissBase somewhere for use during this vat's next incarnation. (In identity-persistence, where this precious information is stored is up to the app.)

On the next incarnation of the vat, the app creates a fresh object to serve as the reincarnation of the original object, and calls makeKnownAs(..) so the old SturdyRef will now designate the new object.

Parameters:

obj - The object for which a SturdyRef is desired

optExpirationDate - The date after which the SturdyRef will not longer be guaranteed to be valid. If Long.MAX_VALUE, then it's always valid.

Returns:

A triple of

• a new SturdyRef for 'obj',
• a org.erights.e.extern.timer.Timeout for cancelling this sturdiness of the object. Though, once a SturdyRef has been given out promising a given expirationDate, it's considered rude to cancel it without coordinating with those other parties.

  Note that if an object is sturdified multiple times, cancelling a registration only cancels that one registration, leaving the others intact.

• a swissBase for reincarnating the identity assigned to 'obj', and

MalformedURLException

makeKnownAs

public Object[] makeKnownAs(Object obj,
                            BigInteger swissBase)
                     throws MalformedURLException

Enabled: optExpirationDate defaults to forever

MalformedURLException

makeKnownAs

public Object[] makeKnownAs(Object obj,
                            BigInteger swissBase,
                            long optExpirationDate)
                     throws MalformedURLException

Enabled: Cause 'obj' to be the object designated by 'swissHash cryptoHash()' in this vat.

Used by an identity-persistent app (as opposed to an object-persistent app) to cause old SturdyRefs that were given out by a previous incarnation of this vat to continue to function. It's polite for an identity-peristent app to use an expiration date that's at least as big as the ones used in previous incarnations. To do otherwise is to not honor the previously implied obligation.

Returns:

A pair of a new SturdyRef for obj and a Timeout for cancelling this sturdiness of the object, as explained at makeKnown(Object, long).

MalformedURLException

addFaultHandler

public void addFaultHandler(OneArgFunc swissDB)

Enabled:

Parameters:

swissDB -

See Also:

SwissTable.addFaultHandler(org.erights.e.elib.util.OneArgFunc)

removeFaultHandler

public void removeFaultHandler(OneArgFunc swissDB)

Enabled:

Parameters:

swissDB -

See Also:

SwissTable.removeFaultHandler(org.erights.e.elib.util.OneArgFunc)

__printOn

public void __printOn(TextWriter out)
               throws IOException

Enabled:

IOException