| CONTENTS |PREV |NEXT | Java Remote Method Invocation |
Anendpoint isone of the two users of a connection using the multiplexingprotocol.
The multiplexingprotocol must layer on top of one existing bidirectional, reliablebyte stream, presumably initiated by one of the endpoints to theother. In current RMI usage, this is always a TCP connection, madewith ajava.net.Socket object. This connection will bereferred to as theconcrete connection.
The multiplexingprotocol facilitates the use ofvirtual connections, whichare themselves bidirectional, reliable byte streams, representing aparticular session between two endpoints. The set of virtualconnections between two endpoints over a single concrete connectioncomprises amultiplexed connection. Using the multiplexingprotocol, virtual connections can be opened and closed by eitherendpoint. The state of an virtual connection with respect to agiven endpoint is defined by the elements of the multiplexingprotocol that are sent and received over the concrete connection.Such state involves if the connection is open or closed, the actualdata that has been transmitted across, and the related flow controlmechanisms. If not otherwise qualified, the termconnection used in the remainder of this section meansvirtual connection.
A virtual connectionswithin a given multiplexed connection is identified by a 16 bitinteger, known as theconnection identifier. Thus, thereexist 65,536 possible virtual connections in one multiplexedconnection. The implementation may limit the number of thesevirtual connections that may be used simultaneously.
The OPEN, CLOSE, andCLOSEACK operations control connections becoming opened and closed,while the REQUEST and TRANSMIT operations are used to transmit dataacross an open connection within the constraints of the flowcontrol mechanism.
A virtual connection ispending close with respect to a particular endpoint if theendpoint has sent a CLOSE operation for that connection, but it hasnot yet received a subsequent CLOSE or CLOSEACK operation for thatconnection.
A virtual connection isclosed with respect to a particular endpoint if it hasnever been opened, or if it has received a CLOSE or a CLOSEACKoperation for that connection (and it has not been subsequentlyopened).
Each endpoint has twostate values associated with each connection: how many bytes ofdata the endpoint has requested but not received (input requestcount) and how many bytes the other endpoint has requested buthave not been supplied by this endpoint (output requestcount).
An endpoint's outputrequest count is increased when it receives a REQUEST operationfrom the other endpoint, and it is decreased when it sends aTRANSMIT operation. An endpoint's input request count isincreased when it sends a REQUEST operation, and it is decreasedwhen it receives a TRANSMIT operation. It is a protocol violationif either of these values becomes negative.
It is a protocolviolation for an endpoint to send a REQUEST operation that wouldincrease its input request count to more bytes that it cancurrently handle without blocking. It should, however, make surethat its input request count is greater than zero if the user ofthe connection is waiting to read data.
It is a protocolviolation for an endpoint to send a TRANSMIT operation containingmore bytes that its output request count. It may buffer outgoingdata until the user of the connection requests that data written tothe connection be explicitly flushed. If data must be sent over theconnection, however, by either an explicit flush or because theimplementation's output buffers are full, then the user of theconnection may be blocked until sufficient TRANSMIT operations canproceed.
Beyond the rulesoutlined above, implementations are free to send REQUEST andTRANSMIT operations as deemed appropriate. For example, an endpointmay request more data for a connection even if its input buffer isnot empty.
value | name |
|---|---|
0xE1 | OPEN |
0xE2 | CLOSE |
0xE3 | CLOSEACK |
0xE4 | REQUEST |
0xE5 | TRANSMIT |
It is a protocolviolation if the first byte of a record is not one of the definedoperation codes. The following sections describe the format of therecords for each operation code.
size (bytes) | name | description |
|---|---|---|
1 | opcode | operation code (OPEN) |
2 | ID | connection identifier |
An endpoint sends anOPEN operation to open the indicated connection. It is a protocolviolation ifID refers to a connection that is currentlyopen or pending close with respect to the sending endpoint. Afterthe connection is opened, both input and request count states forthe connection are zero for both endpoints.
Receipt of an OPENoperation indicates that the other endpoint is opening theindicated connection. After the connection is opened, both inputand output request count states for the connection are zero forboth endpoints.
To prevent identifiercollisions between the two endpoints, the space of valid connectionidentifiers is divided in half, depending on the value of the mostsignificant bit. Each endpoint is only allowed to open connectionswith a particular value for the high bit. The endpoint thatinitiated the concrete connection must only open connections withthe high bit set in the identifier and the other endpoint must onlyopen connections with a zero in the high bit. For example, if anRMI applet that cannot create a server socket initiates amultiplexed connection to its codebase host, the applet may openvirtual connections in the identifier range 0x8000-7FFF, and theserver may open virtual connection in the identifier range0-0x7FFF.
size (bytes) | name | description |
|---|---|---|
1 | opcode | operation code (OPEN) |
2 | ID | connection identifier |
An endpoint sends aCLOSE operation to close the indicated connection. It is a protocolviolation ifID refers to a connection that is currentlyclosed or pending close with respect to the sending endpoint (itmay be pending close with respect to the receiving endpoint if ithas also sent a CLOSE operation for this connection). After sendingthe CLOSE, the connection becomes pending close for the sendingendpoint. Thus, it may not reopen the connection until it hasreceived a CLOSE or a CLOSEACK for it from the other endpoint.
Receipt of a CLOSEoperation indicates that the other endpoint has closed theindicated connection, and it thus becomes closed on the receivingendpoint. Although the receiving endpoint may not send any moreoperations for this connection (until it is opened again), it stillshould provide data in the implementation's input buffers toreaders of the connection. If the connection had previously beenopen instead of pending close, the receiving endpoint must respondwith a CLOSEACK operation for the connection.
size (bytes) | name | description |
|---|---|---|
1 | opcode | operation code (OPEN) |
2 | ID | connection identifier |
An endpoint sends aCLOSEACK operation to acknowledge a CLOSE operation from thereceiving endpoint. It is a protocol violation if ID refers to aconnection that is not pending close for the receiving endpointwhen the operation is received.
Receipt of a CLOSEACKoperation changes the state of the indicated connection frompending close to closed, and thus the connection may be reopened inthe future.
size (bytes) | name | description |
|---|---|---|
1 | opcode | operation code (OPEN) |
2 | ID | connection identifier |
4 | count | number of additional bytes requested |
An endpoint sends aREQUEST operation to increase its input request count for theindicated connection. It is a protocol violation ifIDdoes not refer to a connection that is open with respect to thesending endpoint. The endpoint's input request count isincremented by the valuecount. The value ofcount is a signed 32 bit integer, and it is a protocolviolation if it is negative or zero.
Receipt of a REQUESToperation causes the output request count for the indicatedconnection to increase bycount. If the connection ispending close by the receiving endpoint, then any REQUESToperations may be ignored.
size (bytes) | name | description |
|---|---|---|
1 | opcode | operation code (OPEN) |
2 | ID | connection identifier |
4 | count | number of bytes in transmission |
count | data | transmission data |
An endpoint sends aTRANSMIT operation to actually transmit data over the indicatedconnection. It is a protocol violation if ID does not refer to aconnection that is open with respect to the sending endpoint. Theendpoint's output request count is decremented by the valuecount. The value ofcount is a signed 32 bitinteger, and it is a protocol violation if it is negative or zero.It is also a protocol violation if the TRANSMIT operation wouldcause the sending endpoint's output request count to becomenegative.
Receipt of a TRANSMIToperation causes the count bytes of data to be added to the queueof bytes available for reading from the connection. The receivingendpoint's input request count is decremented bycount. If this causes the input request count to becomezero and the user of the connection is trying to read more data,the endpoint should respond with another REQUEST operation. If theconnection is pending close by the receiving endpoint, then anyTRANSMIT operations may be ignored.