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


comments?