net.captp.jcomm
Class CapTPConnection

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

All Implemented Interfaces:

MsgHandler

class CapTPConnection

extends Object

implements MsgHandler

Field Summary

private static byte	DELIVER_ONLY_OP Queue delivery of message, no answer expected.
private static byte	DELIVER_OP Queue delivery of message, resolve answer to the outcome.
private static byte	GC_ANSWER_OP A question on the other has gone away.
private static byte	GC_EXPORT_OP An import on the other has gone away dropping some number of wireCounts.
private AnswersTable	myAnswers The Answers table: this is the counterpart to the Questions table at the other end of the connection.
private CapTPMgr	myCapTPMgr The CapTPMgr for our vat
private VatTPConnection	myDataConnection Means of communication with our partner at the other end of the line.
private ESecureRandom	myEntropy Generates new swiss numbers
private ExportsTable	myExports The Exports table: this is the counterpart to the Imports table at the other end of the connection.
private ImportsTable	myImports The Imports table: these are handles to objects the other end exported.
private NonceLocator	myLocalNonceLocator At incoming position 0, for bringing about 3-vat introductions using nonces.
private NearGiftTable	myNGifts For bringing about 3-vat introductions of Near references using nonces.
private Resolver	myOptBufferedLookups Resolver of the promise used to buffer lookup requests made in midst of connection shutdown.
private Throwable	myOptProblem If the connection died, anybody who talks to us will get this.
private PromiseGiftTable	myPGifts For bringing about 3-vat introductions of unresolved references using nonces.
private QuestionsTable	myQuestions The Questions table: these are handlers this end created and is expecting the other end to hook up to the relevent objects themselves (e.g., results of sendAll()s).
private int	myReceiveCount Number of messages received on this connection
private Object	myRemoteNonceLocator A remote reference to the other side's myLocalNonceLocator, at outgoing position 0, for bringing about 3-vat introductions using nonces.
private int	mySendCount Number of messages sent on this connection
private boolean	myShuttingDownFlag Flag indicating we are in the midst of shutting down the connection
private int	myUseCount Number of things (XXX what's a "thing"?) which are currently holding the connection open
private static byte	SHUTDOWN_OP Please shut down the connection if you have no messages pending.

Constructor Summary

(package private)

CapTPConnection(CapTPMgr capTPMgr, VatTPConnection dataConn, ESecureRandom entropy) Makes a CapTPConnection for a particular CapTP instance (capTPMgr) and a particular VatTP connection (dataConn).

Method Summary

private static String	argsString(Object[] args) Pretty print the args of a message send, for debugging purposes.
void	connectionDead(VatTPConnection dataConn, Throwable problem) Receive notification that our VatTPConnection has died.
private void	decrementUseCount() Decrement the use count.
(package private) void	dropQuestion(int pos) Drop this index in our own Questions table, and in the other vat's Answers table.
private void	execDeliverOnlyOp(int recipPos, String verb, Object[] args)
private void	execDeliverOp(int answerPos, Object rdr, int recipPos, String verb, Object[] args)
private void	execGCAnswerOp(int answerPos)
private void	execGCExportOp(int exportPos, int wireCount)
private void	execShutdownOp(int receivedCount) Receive a shutdown message from the other end.
(package private) Ref	getImport(int importPos) Dereferencing of an ImportDesc.
(package private) Object	getIncoming(int incomingPos) Dereferencing of an IncomingDesc Return an Exports or Answers table entry.
(package private) LocatorUnum	getLocatorUnum()
(package private) Ref	getLookup(ConstList searchPath, String vatID, BigInteger nonce, BigInteger swissHash, Object optFarVine) Dereferencing of a Far3Desc
(package private) Ref	getLookup(ConstList searchPath, String vatID, BigInteger nonce, Object optFarVine) Dereferencing of a Promise3Desc
(package private) NearGiftTable	getNearGiftTable()
(package private) Throwable	getOptProblem() If non-null, this is a dead connection
(package private) PromiseGiftTable	getPromiseGiftTable()
(package private) Object	getRemoteNonceLocator()
(package private) Sealer	getSealer()
(package private) Unsealer	getUnsealer()
private void	killConnection(Throwable problem, boolean deliberate) Terminate this connection in the case where something unrecoverable has gone wrong.
(package private) String	localVatID() Return our identity.
(package private) Object	makeEventualDesc(Ref ref) Figure out what kind of eventual reference 'ref' is, and return an appropriate descriptor for encoding it over the wire.
(package private) ObjectRefDesc	makeImportingDesc(Object obj) Returns a NewFarDesc, NewRemotePromiseDesc, or an ImportDesc for exporting obj, which is assumed to be suitable for being in our exports table.
private SerializationStream	makeMsg(ByteArrayOutputStream bos, byte cmd)
(package private) ProxyResolver	makeQuestion()
private NewFarDesc	newFarDesc(Object obj)
(package private) Ref	newFarRef(int importPos, BigInteger swissHash) Dereferencing of a NewFarDesc.
(package private) Ref	newRemotePromise(int importPos, int rdrPos, BigInteger rdrBase) Dereferencing of a NewRemotePromiseDesc.
private NewRemotePromiseDesc	newRemotePromiseDesc(Object promise)
void	processMessage(byte[] message, VatTPConnection dataConn) Process an incoming message from the VatTPConnection.
private void	receiveMsg(byte cmd, UnserializationStream uns)
(package private) ConstList	remoteSearchPath()
(package private) String	remoteVatID() Return the identity of the party to whom we are speaking.
(package private) void	sendDeliverOnlyOp(int recipPos, String verb, Object[] args)
(package private) void	sendDeliverOp(int answerPos, Object rdr, int recipPos, String verb, Object[] args)
private void	sendGCAnswerOp(int answerPos)
(package private) void	sendGCExportOp(int exportPos, int wireCount)
private void	sendMsg(ByteArrayOutputStream bos, SerializationStream ser) Send a message via our VatTPConnection.
private void	sendShutdownOp(int receivedCount)
(package private) void	submitLookups(Resolver bufferedLookups)
private void	whyNoDeliverOnlyOp(int recipPos, String verb, Throwable problem)
private void	whyNoDeliverOp(int answerPos, Object rdr, int recipPos, String verb, Throwable problem)

Methods inherited from class java.lang.Object

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

Field Detail

DELIVER_ONLY_OP

private static final byte DELIVER_ONLY_OP

Queue delivery of message, no answer expected.

Start counting at 8 since the previous version of the protocol (0.8.9) stopped at 7.

DELIVER_OP

private static final byte DELIVER_OP

Queue delivery of message, resolve answer to the outcome.

DELIVER_OP as 9 had a different argument order

GC_EXPORT_OP

private static final byte GC_EXPORT_OP

An import on the other has gone away dropping some number of wireCounts. Clean up the export table.

GC_ANSWER_OP

private static final byte GC_ANSWER_OP

A question on the other has gone away. Clean up the answer table.

SHUTDOWN_OP

private static final byte SHUTDOWN_OP

Please shut down the connection if you have no messages pending.

myCapTPMgr

private final CapTPMgr myCapTPMgr

The CapTPMgr for our vat

myDataConnection

private final VatTPConnection myDataConnection

Means of communication with our partner at the other end of the line.

myUseCount

private int myUseCount

Number of things (XXX what's a "thing"?) which are currently holding the connection open

mySendCount

private int mySendCount

Number of messages sent on this connection

myReceiveCount

private int myReceiveCount

Number of messages received on this connection

myShuttingDownFlag

private boolean myShuttingDownFlag

Flag indicating we are in the midst of shutting down the connection

myOptProblem

private Throwable myOptProblem

If the connection died, anybody who talks to us will get this.

This should be null exactly when the connection is still alive.

myOptBufferedLookups

private Resolver myOptBufferedLookups

Resolver of the promise used to buffer lookup requests made in midst of connection shutdown.

myEntropy

private final ESecureRandom myEntropy

Generates new swiss numbers

myQuestions

private QuestionsTable myQuestions

The Questions table: these are handlers this end created and is expecting the other end to hook up to the relevent objects themselves (e.g., results of sendAll()s).

myAnswers

private AnswersTable myAnswers

The Answers table: this is the counterpart to the Questions table at the other end of the connection.

Messages sent through a handler in the questions table will be delivered to the corresponding answer.

myImports

private ImportsTable myImports

The Imports table: these are handles to objects the other end exported.

We just hook up the handler in the specified location.

myExports

private ExportsTable myExports

The Exports table: this is the counterpart to the Imports table at the other end of the connection.

These are objects that have been exported from this end (i.e., mentioned by us in the parameters of a message). The other end installs them in the same spot in its Imports table.

myLocalNonceLocator

private final NonceLocator myLocalNonceLocator

At incoming position 0, for bringing about 3-vat introductions using nonces.

myRemoteNonceLocator

private final Object myRemoteNonceLocator

A remote reference to the other side's myLocalNonceLocator, at outgoing position 0, for bringing about 3-vat introductions using nonces.

myPGifts

private PromiseGiftTable myPGifts

For bringing about 3-vat introductions of unresolved references using nonces.

myNGifts

private NearGiftTable myNGifts

For bringing about 3-vat introductions of Near references using nonces.

Constructor Detail

CapTPConnection

CapTPConnection(CapTPMgr capTPMgr,
                VatTPConnection dataConn,
                ESecureRandom entropy)
          throws IOException

Makes a CapTPConnection for a particular CapTP instance (capTPMgr) and a particular VatTP connection (dataConn).

Parameters:

capTPMgr - The CapTPMgr managing this connection.

dataConn - The VatTP-level data connection to be associated with this CapTPConnection.

entropy - Where new swiss numbers come from.

Method Detail

getPromiseGiftTable

PromiseGiftTable getPromiseGiftTable()

getNearGiftTable

NearGiftTable getNearGiftTable()

getRemoteNonceLocator

Object getRemoteNonceLocator()

getSealer

Sealer getSealer()

getUnsealer

Unsealer getUnsealer()

getOptProblem

Throwable getOptProblem()

If non-null, this is a dead connection

localVatID

String localVatID()

Return our identity.

remoteVatID

String remoteVatID()

Return the identity of the party to whom we are speaking.

remoteSearchPath

ConstList remoteSearchPath()

makeQuestion

ProxyResolver makeQuestion()

dropQuestion

void dropQuestion(int pos)

Drop this index in our own Questions table, and in the other vat's Answers table.

newFarDesc

private NewFarDesc newFarDesc(Object obj)

newRemotePromiseDesc

private NewRemotePromiseDesc newRemotePromiseDesc(Object promise)

makeImportingDesc

ObjectRefDesc makeImportingDesc(Object obj)

Returns a NewFarDesc, NewRemotePromiseDesc, or an ImportDesc for exporting obj, which is assumed to be suitable for being in our exports table.

obj is assumes to be a Near reference to a PassByProxy object (actual or HONORARY), or eventual.

makeEventualDesc

Object makeEventualDesc(Ref ref)

Figure out what kind of eventual reference 'ref' is, and return an appropriate descriptor for encoding it over the wire.

newFarRef

Ref newFarRef(int importPos,
              BigInteger swissHash)

Dereferencing of a NewFarDesc.

On entry, importPos may be free, or may be allocated to an entry with a zero wireCount. (XXX we don't currently check the wirecount.) In the latter case, the entry is overwritten.

Parameters:

importPos - The import position at which a new FarRef should be created.

swissHash - The sameness identity of that FarRef.

Returns:

The newly created FarRef.

newRemotePromise

Ref newRemotePromise(int importPos,
                     int rdrPos,
                     BigInteger rdrBase)

Dereferencing of a NewRemotePromiseDesc.

On entry, importPos may be free, or may be allocated to an entry with a zero wireCount. In the latter case, the entry is overwritten.

Parameters:

importPos - The import position at which the new RemotePromise should be created.

rdrPos - The answers position at which the Redirector of that new RemotePromise is made available.

rdrBase - The sameness identity of that Redirector must be the cryptohash of rdrBase.

Returns:

The newly created RemotePromise.

getImport

Ref getImport(int importPos)

Dereferencing of an ImportDesc.

On entry, importPos must be allocated, but may be allocated to an entry with a zero wireCount.

Return an imported Proxy, or its resolution, and, if it still has a handler (ie, it isn't resolved) increment its wire count.

Parameters:

importPos - The position of the import in the Imports table

Returns:

Whatever the resolution is of the Proxy in the appropriate table at importPos

getIncoming

Object getIncoming(int incomingPos)

Dereferencing of an IncomingDesc Return an Exports or Answers table entry.

Parameters:

incomingPos - A positive pos refer to the Exports table, a negative one to the Answers table.

Returns:

Whatever object was in the appropriate table at incomingPos.

getLookup

Ref getLookup(ConstList searchPath,
              String vatID,
              BigInteger nonce,
              Object optFarVine)

Dereferencing of a Promise3Desc

Parameters:

searchPath - hints to find the vat identified by vatID

vatID - The fingerprint of the public key of the vat hosting the object to be looked up.

nonce - Identifies the object in that vat's appropriate gift table.

optFarVine - Hold on to this until the object has been retrieved.

Returns:

A promise for the looked up object.

getLookup

Ref getLookup(ConstList searchPath,
              String vatID,
              BigInteger nonce,
              BigInteger swissHash,
              Object optFarVine)

Dereferencing of a Far3Desc

Parameters:

searchPath - hints to find the vat identified by vatID

vatID - The fingerprint of the public key of the vat hosting the object to be looked up.

nonce - Identifies the object in that vat's appropriate gift table.

swissHash - Identity of object being looked up. getLookup returns a resolved reference with that identity. If it can't return a FarRef with that identity, then it returns a DisconnectedRef with that identity.

optFarVine - Hold on to this until the object has been retrieved.

Returns:

A promise for the looked up object.

getLocatorUnum

LocatorUnum getLocatorUnum()

processMessage

public void processMessage(byte[] message,
                           VatTPConnection dataConn)

Process an incoming message from the VatTPConnection.

Specified by:

processMessage in interface MsgHandler

Parameters:

message - The incoming message.

dataConn - The VatTPConnection on which the message arrived

See Also:

net.vattp.data.MsgHandler

receiveMsg

private void receiveMsg(byte cmd,
                        UnserializationStream uns)
                 throws IOException,
                        ClassNotFoundException,
                        OptionalDataException

IOException

ClassNotFoundException

OptionalDataException

argsString

private static String argsString(Object[] args)

Pretty print the args of a message send, for debugging purposes.

execDeliverOnlyOp

private void execDeliverOnlyOp(int recipPos,
                               String verb,
                               Object[] args)

whyNoDeliverOnlyOp

private void whyNoDeliverOnlyOp(int recipPos,
                                String verb,
                                Throwable problem)

execDeliverOp

private void execDeliverOp(int answerPos,
                           Object rdr,
                           int recipPos,
                           String verb,
                           Object[] args)

whyNoDeliverOp

private void whyNoDeliverOp(int answerPos,
                            Object rdr,
                            int recipPos,
                            String verb,
                            Throwable problem)

execGCExportOp

private void execGCExportOp(int exportPos,
                            int wireCount)

execGCAnswerOp

private void execGCAnswerOp(int answerPos)

execShutdownOp

private void execShutdownOp(int receivedCount)

Receive a shutdown message from the other end. If we don't have any messages in flight, we shutdown the connection.

makeMsg

private SerializationStream makeMsg(ByteArrayOutputStream bos,
                                    byte cmd)
                             throws IOException

IOException

sendMsg

private void sendMsg(ByteArrayOutputStream bos,
                     SerializationStream ser)
              throws IOException

Send a message via our VatTPConnection.

IOException

sendDeliverOnlyOp

void sendDeliverOnlyOp(int recipPos,
                       String verb,
                       Object[] args)

sendDeliverOp

void sendDeliverOp(int answerPos,
                   Object rdr,
                   int recipPos,
                   String verb,
                   Object[] args)

sendGCExportOp

void sendGCExportOp(int exportPos,
                    int wireCount)

sendGCAnswerOp

private void sendGCAnswerOp(int answerPos)

sendShutdownOp

private void sendShutdownOp(int receivedCount)

submitLookups

void submitLookups(Resolver bufferedLookups)

decrementUseCount

private void decrementUseCount()

Decrement the use count. If it reaches 0, we have no references active over this connection and the connection can (and should) be shut down.

connectionDead

public void connectionDead(VatTPConnection dataConn,
                           Throwable problem)

Receive notification that our VatTPConnection has died.

Specified by:

connectionDead in interface MsgHandler

Parameters:

dataConn - The VatTPConnection object which has just died.

problem - The cause-of-death to report.

See Also:

net.vattp.data.MsgHandler

killConnection

private void killConnection(Throwable problem,
                            boolean deliberate)

Terminate this connection in the case where something unrecoverable has gone wrong.

"A coward dies a thousand deaths, a hero dies but once."

Our error handling is cowardly -- if anything goes wrong during I/O we assume we are dead. Thus we can be caused to die more than once, but we need to actually die only once...

Parameters:

problem - What went wrong