org.erights.e.elib.ref
Class Proxy

java.lang.Object
  |
  +--org.erights.e.elib.ref.Ref
        |
        +--org.erights.e.elib.ref.Proxy

All Implemented Interfaces:

Amplifiable, Callable

Direct Known Subclasses:

FarRef, RemotePromise

abstract class Proxy

extends Ref

A Proxy is intended to be the arrowtail of a Ref whose arrowhead is in another vat, and which will therefore pass messages sent on to that other vat.

However, a Proxy delegates most of its behavior to its ProxyHandler, which may be untrusted code. Therefore, the Proxy itself has responsibility for adhering to the Ref contract despite arbitrary behavior by its handler. This is a step toward reimplementing CapTP in the E language.

A ProxyHandler should create and point at its Proxy only using ProxyResolver, so it can find out when the Proxy has been GCed, be able to resolve it, and be able to transparently revive it.

A Settled Proxy (one with sameness identity) is represented by the subclass FarRef. An Unsettled Proxy (one without such identity, and therefore a Promise) is represented by the subclass RemotePromise.

Author:

Mark S. Miller

Field Summary

(package private) ProxyHandler	myOptHandler While I'm handled, I delegate many of my decisions to my handler.
(package private) Ref	myOptTarget Once I'm not handled, I'm resolved to myOptTarget

Fields inherited from class org.erights.e.elib.ref.Ref

BROKEN, EVENTUAL, NEAR, TheViciousRef

Constructor Summary

(package private)

Proxy(ProxyHandler handler)

Method Summary

Object	callAll(String verb, Object[] args) Suppressed: Use E.callAll(obj, verb, args) rather than obj.callAll(verb, args).
(package private) void	commit() ignored
ProxyHandler	getOptProxyHandler(Class handlerClass) If this is a handled Proxy whose handler is an instance of handlerClass, then return that handler; else null.
Throwable	optProblem() If handled, return null; else return the target's problem.
SealedBox	optSealedDispatch(Brand brand) If handled, ask our handler; else delegate to our target.
(package private) Ref	resolutionRef() If this proxy is still being handled, return this; else return whatever it's been shortened to.
Ref	sendAll(String verb, Object[] args) Suppressed: Use E.sendAll(obj, verb, args) rather than obj.sendAll(verb, args).
Throwable	sendAllOnly(String verb, Object[] args) Suppressed: Use E.sendAllOnly(obj, verb, args) rather than obj.sendAllOnly(verb, args).
String	state() If handled, returns EVENTUAL; else returns the target's state().

Methods inherited from class org.erights.e.elib.ref.Ref

broken, disconnected, getAllegedType, GetRefMaker, ignore, isBroken, isDeepFrozen, isDeepPassByCopy, isEventual, isFar, isNear, isPassByProxy, isPBC, isPersistent, isResolved, isResolved, isSameEver, isSelfish, isSelfless, isSettled, makeBufferingPromise, makeSwitchablePromise, optBroken, optProblem, optSealedDispatch, optShorten, promise, resolution, resolution, respondsTo, sendMsg, setTarget, state, toCallable, toRef, toString, whenBroken, whenBrokenOnly, whenResolved, whenResolvedOnly

Methods inherited from class java.lang.Object

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

Field Detail

myOptHandler

ProxyHandler myOptHandler

While I'm handled, I delegate many of my decisions to my handler.

myOptTarget

Ref myOptTarget

Once I'm not handled, I'm resolved to myOptTarget

Constructor Detail

Proxy

Proxy(ProxyHandler handler)

Method Detail

optSealedDispatch

public SealedBox optSealedDispatch(Brand brand)

If handled, ask our handler; else delegate to our target.

Specified by:

optSealedDispatch in interface Amplifiable

Overrides:

optSealedDispatch in class Ref

getOptProxyHandler

public ProxyHandler getOptProxyHandler(Class handlerClass)

If this is a handled Proxy whose handler is an instance of handlerClass, then return that handler; else null.

All implementations of getOptProxyHandler/1 must be thread safe, in order for BootRefHandler.getOptBootRefHandler/1 to be thread safe: myOptHandler only makes one transition from non-null to null. This implementation samples it once, and then proceeds with the possibly slightly stale sample.

Overrides:

getOptProxyHandler in class Ref

optProblem

public Throwable optProblem()

If handled, return null; else return the target's problem.

All implementations of optProblem/0 must be thread safe, in order for Ref.state/0 to be thread safe.

Specified by:

optProblem in class Ref

See Also:

Ref.optProblem(Object)

resolutionRef

Ref resolutionRef()

If this proxy is still being handled, return this; else return whatever it's been shortened to.

All implementations of resolutionRef/0 must be thread safe, in order for Ref.resolution/0 to be thread safe: If resolutionRef/0 is called from another thread while this proxy is in the middle of being shortened, then resolutionRef/0 must return either this or what this proxy is being shortened to.

XXX Although the implementation doesn't synchronize, it is inductively thread safe given a simple memory model. Is it safe in Java's complex memory model? Do we care -- are any Java implementations not faithful to the simple memory model?

Specified by:

resolutionRef in class Ref

state

public String state()

If handled, returns EVENTUAL; else returns the target's state().

All implementations of state/0 must be thread safe, in order for Ref.isNear/1 to be thread safe.

Overrides:

state in class Ref

See Also:

Ref.state(Object)

callAll

public Object callAll(String verb,
                      Object[] args)

Description copied from class: Ref

Suppressed: Use E.callAll(obj, verb, args) rather than obj.callAll(verb, args).

Specified by:

callAll in interface Callable

Specified by:

callAll in class Ref

sendAll

public Ref sendAll(String verb,
                   Object[] args)

Description copied from class: Ref

Suppressed: Use E.sendAll(obj, verb, args) rather than obj.sendAll(verb, args).

Specified by:

sendAll in class Ref

sendAllOnly

public Throwable sendAllOnly(String verb,
                             Object[] args)

Description copied from class: Ref

Suppressed: Use E.sendAllOnly(obj, verb, args) rather than obj.sendAllOnly(verb, args).

Specified by:

sendAllOnly in class Ref

Returns:

Why wasn't this event queued? It isn't queued if this vat or comm connection is shut down, in which case the returned problem explains why. If null is returned, then the event was queued, though it may still not arrive.

commit

void commit()

ignored

Specified by:

commit in class Ref