net.captp.jcomm
Class IdentityMgr

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.

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

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

makeSturdyRef

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.

makeKnown

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.

makeKnownAs

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