Package org.jcsp.lang

# Interface ConnectionClient

All Known Subinterfaces:
  `SharedConnectionClient`

All Known Implementing Classes:
  `AltingConnectionClient`, `AltingConnectionClientImpl`, `SharedAltingConnectionClient`

public interface ConnectionClient

This is an interface to be implemented by classes that wish to act as a client to connect to a `ConnectionServer`.

Users of classes implementing this interface should call `request(Object)` to initiate a conversation and to send some data to the server. Implementations may decide to return immediately or to wait until the server accepts the connection and then return. The Connection is not guaranteed to be open until a call to `reply()` has returned. The `reply()` method should be called soon after the call to `reqeust(Object)`. Some computation may be done between the calls but any external process synchronization is potentially hazardous.

After calling `reply()`, clients can check whether the server closed the connection by calling `isOpen()`. If it returns `true`, then the connection has been kept open. If the connection has been kept open then the client may assume that a call to `request(Object)` will not block and that the connection will soon be dealt with by the server.

This is an example of typical code structure for using a ConnectionClient:

     //have a variable client of type ConnectionClient
     do {
         client.request(some_data);
         some_variable = client.receive();
     } while (client.isOpen())

Author:
  Quickstone Technologies Limited

## Method Summary

Modifier and Type
Method
Description
`boolean`
`isOpen()`
Returns whether the server has kept its end of the Connection open.
`Object`
`reply()`
Receives some data back from the server after `request(Object)` has been called.
`void`
`request(Object data)`
This method is used to send data to a `ConnectionServer` in a client/server conversation.

## Method Details

### request

void request(Object data) throws IllegalStateException

This method is used to send data to a `ConnectionServer` in a client/server conversation. If a connection has not yet been established, then this method will open the connection as necessary.

Once this method has returned, the client may do some computation but must then guarantee to call `reply()`. This will obtain a server's response to the request. In between calling this method and `reply()`, doing pure computation is safe. Performing synchronization with other process is potentially hazardous.

Once a server replies, if the connection has been kept open, then this method should be called again to make a further request.

Programs using `Connection`s need to adopt a protocol so that the server knows when a conversation with a client has finished and will then drop the connection.

Parameters:
  `data` - the `Object` to send to the server.
Throws:
  `IllegalStateException` - if the method is called when it is not meant to be.

### reply

Object reply() throws IllegalStateException

Receives some data back from the server after `request(Object)` has been called.

After calling this method, `isOpen()` may be called to establish whether the server dropped the connection after replying.

Implementations may make this operation ALTable.

Returns:
  the `Object` sent from the server.
Throws:
  `IllegalStateException` - if the method is called when it is not meant to be.

### isOpen

boolean isOpen() throws IllegalStateException

Returns whether the server has kept its end of the Connection open. This should only be called after a call to `reply()` and before any other Connection method is called.

Returns:
  `true` iff the server has kept the connection open.
Throws:
  `IllegalStateException`