net.captp.jcomm
Class SturdyRef

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

All Implemented Interfaces:

Marker, PassByConstruction, Persistent, Serializable

public final class SturdyRef

extends Object

implements Persistent, PassByConstruction

Safe: An object reference that can be checkpointed and/or externalized and which can survive network partitions.

See Also:

Serialized Form

Field Summary

private long	myExpiration How long is the object obligated to stay around?
private String	myHostID the Vat in which mySwissNum is bound to something
private LocatorUnum	myLocatorUnum The LocatorUnum that links us to the outside world.
private ConstList	mySearchPath Hints about how our vat might be located.
private BigInteger	mySwissNum Bound to an object in the vat identified by myHostID
(package private) static long	serialVersionUID

Fields inherited from interface org.erights.e.elib.serial.Persistent

HONORARY, HONORED_NAMES

Fields inherited from interface org.erights.e.elib.serial.PassByConstruction

HONORARY, HONORED_NAMES

Constructor Summary

(package private)

SturdyRef(LocatorUnum locatorUnum, ConstList searchPath, String hostID, BigInteger swissNum, long expiration) Package scope constructor for a new SturdyRef.

Method Summary

void	__printOn(TextWriter out) Enabled:
double	compareTo(SturdyRef other) Enabled: Test if this SturdyRef and another designate the same object.
boolean	equals(Object obj) Suppressed: Test if this SturdyRef and another are fully equivalent SturdyRefs.
(package private) String	exportRef() Package scope method to produce a URI string for this SturdyRef.
Object	getRcvr() Enabled: Return a (live) reference to the object which this SturdyRef designates.
Object	getRcvr(long pollMillis, long timeout) Enabled: Like getRcvr() but doesn't resolve the result until we connect to the object's hosting vat.
int	hashCode() Suppressed: Return a hashcode for this SturdyRef.

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

static final long serialVersionUID

myLocatorUnum

private final LocatorUnum myLocatorUnum

The LocatorUnum that links us to the outside world.

mySearchPath

private final ConstList mySearchPath

Hints about how our vat might be located.

myHostID

private final String myHostID

the Vat in which mySwissNum is bound to something

mySwissNum

private final BigInteger mySwissNum

Bound to an object in the vat identified by myHostID

myExpiration

private final long myExpiration

How long is the object obligated to stay around?

Constructor Detail

SturdyRef

SturdyRef(LocatorUnum locatorUnum,
          ConstList searchPath,
          String hostID,
          BigInteger swissNum,
          long expiration)
    throws MalformedURLException

Package scope constructor for a new SturdyRef.

Parameters:

locatorUnum - The LocatorUnum which maintains the new ref's registration, and which gives the SturdyRef the authority to obtain the live object. This component serialized specially, so that only those that had a LocatorUnum when they were serialized can obtain a new one when unserialized.

searchPath - Hints about how to find the new ref's home vat

swissNum - Swiss number of the object that the new ref designates

Method Detail

compareTo

public double compareTo(SturdyRef other)

Enabled: Test if this SturdyRef and another designate the same object.

In the E language,

    x <=> y

is syntactic sugar for approximately

    x.compareTo(y) == 0.0

Note that we could have provided a full order for the other cases, but since SturdyRefs are supposed to hold their cryptographic bits opaqely, for all non-same cases we always return NaN (incomparable).

Parameters:

other - SturdyRef against which we are to be tested for equality

Returns:

0.0 iff this and other designate the same object. Otherwise NaN.

equals

public boolean equals(Object obj)

Suppressed: Test if this SturdyRef and another are fully equivalent SturdyRefs.

If you wish to test instead whether they designate the same object by virtue of the comparing VatID and SwissNumbers, but not comparing incidentals like searchPath or expiration, then use "<=>".

Overrides:

equals in class Object

Parameters:

obj - SturdyRef against which we are to be tested for equality

Returns:

true iff this and obj are fully equivalent SturdyRefs.

See Also:

Object.hashCode(), java.util.Hashtable

hashCode

public int hashCode()

Suppressed: Return a hashcode for this SturdyRef.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

java.lang.Object#equals(java.lang.Object), java.util.Hashtable

exportRef

String exportRef()
           throws MalformedURLException

Package scope method to produce a URI string for this SturdyRef.

Returns:

A URI string that refers to the same object as this SturdyRef designates.

MalformedURLException

getRcvr

public Object getRcvr()
               throws IOException

Enabled: Return a (live) reference to the object which this SturdyRef designates.

The result may be either a direct or eventual reference. If we cannot currently connect to the object's hosting vat, then the result will resolve to broken.

getRcvr only works when we're onTheAir.

IOException

getRcvr

public Object getRcvr(long pollMillis,
                      long timeout)
               throws IOException

Enabled: Like getRcvr() but doesn't resolve the result until we connect to the object's hosting vat.

Note that the result may still resolve to broken, if the object's hosting vat, for example, no longer has this object registered for lookup by this SturdyRef (no longer has an entry for this SturdyRef's SwissNumber).

getRcvr only works when we're onTheAir.

Parameters:

pollMillis - A polling interval hint. Until we have VLS rendezvous support, the best we can do is poll the attempt to connect to the hosting vat. pollMillis says how often we should do so, and thereby tradeoff CPU/comm against promptness. Once we have VLS rendezvous support, then we will post a long-lived query with the relevant VLSs, and refresh this query at a frequency determined by those VLSs, not by our client. This refreshing is also a polling loop, but can be long without impeding the responsiveness of getting connected.

timeout - The time in absMillis (since the epoch) at which we should give up trying to connect. Once the time has passed, we should resolve the result to broken rather than continuing to poll or refresh. A value of -1 means to keep trying forever.

IOException

__printOn

public void __printOn(TextWriter out)
               throws IOException

Enabled:

IOException