org.yawlfoundation.yawl.procletService.connect

Class JavaCPN

java.lang.Object

org.yawlfoundation.yawl.procletService.connect.JavaCPN

All Implemented Interfaces:

JavaCPNInterface

public class JavaCPN
extends java.lang.Object
implements JavaCPNInterface

JavaCPN

(otherwise known as Comms/Java) - The java implmentation of a peer entity matching the Comms/Java implementation for Design/CPN. (See http://www.daimi.au.dk/designCPN/libs/commscpn/ for more details.) The purpose of Java/CPN is to allow Java processes to communicate with Design/CPN through Comms/CPN. The current implementation of Java/CPN is the minimal implementation necessary to enable communication. It incorporates the equivalent functionality of the Messaging and Communication layers from Comms/CPN. The Communication Layer functionality from Comms/CPN and TCP/IP is already encapsulated in Socket objects provided by Java.

No connection management has been implemented within Java/CPN as this is a minimal implementation, however the important thing is that it implements the same protocol at the Messaging Layer as the peer entity. Generic send and receive functions have been provided at the level of the Messaging Layer, meaning that sequences of bytes are passed to the send method and returned from the receive method. The connect, accept, and disconnect methods have been provided at the level of the Communication Layer from Comms/CPN. The deliberate attempt was made to make the interface as close to that of Comms/CPN as possible.

Methods external to the Java/CPN class must be used to convert from data (i.e. a string) into a ByteArrayInputStream object, and from a ByteArrayOutputStream object back into data. This is akin to the encoding and decoding functions passed into the send and receive functions of the Connection Management Layer in Comms/CPN. They are contained within the EncodeDecode class.

Version:

0.6 Change Log: 10th February 2002: - Improved robustness of Receive method - reads multiple times from the socket in a loop if not all bytes can be read on the first attempt.

Author:

Guy Gallasch

Constructor Summary

Constructors

Constructor and Description
JavaCPN() Constructor to create a new JavaCPN object.

Method Summary

Modifier and Type	Method and Description
void	accept(int port) Method to passively open a connection.
void	connect(java.lang.String hostName, int port) Method to actively establish a connection.
void	disconnect() Method to disconnect the established connection.
java.io.ByteArrayOutputStream	receive() Method used to receive a ByteArrayOutputStream from an established connection.
void	send(java.io.ByteArrayInputStream sendBytes) Method used to send a ByteArrayInputStream via an established connection.

Methods inherited from class java.lang.Object

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

Constructor Detail

JavaCPN

public JavaCPN()

Constructor to create a new JavaCPN object. Simply initialises the internal references. In order to establish a connection either the connect or the accept methods need to be called.

Method Detail

connect

public void connect(java.lang.String hostName,
                    int port)
             throws java.io.IOException,
                    java.net.UnknownHostException

Method to actively establish a connection. It takes a host name and port number as arguments, and attempts to establish a connection as a client to the given port on the given host. Once the connection has been established (i.e. the socket opened) input and output streams are extracted from the socket to enable the transmission and reception of bytes.

Specified by:

connect in interface JavaCPNInterface

Parameters:

hostName - The host to attempt to connect to

port - The port number to attempt to connect to

Throws:

java.io.IOException - Thrown when there is a communication error

java.net.UnknownHostException - Thrown when the host name provided as the argument cannot be resolved into an IP address

accept

public void accept(int port)
            throws java.io.IOException

Method to passively open a connection. It takes a port number as an argument and, acting as a server, listens on the given port number for an incoming connection request. When received, it establishes the connection. Again, once the connection has been established, input and output streams are extracted from the socket to enable the transmission and reception of bytes. The method will block until a connection is established.

Specified by:

accept in interface JavaCPNInterface

Parameters:

port - The port number to attempt to connect to

Throws:

java.io.IOException - Thrown when there is a communication error

send

public void send(java.io.ByteArrayInputStream sendBytes)
          throws java.net.SocketException

Method used to send a ByteArrayInputStream via an established connection. This method takes a ByteArrayInputStream object as the argument. The segmentation into packets occurs in this method. Bytes are read from the ByteArrayInputStream object, a maximum of 127 at a time, and a single byte header is added indicating the number of payload bytes (header is 1 to 127) or that there is more data in a following packet (header is 255). The data packets formed are then transmitted to the external process through methods acting on the output stream of the socket.

Specified by:

send in interface JavaCPNInterface

Parameters:

sendBytes - The byte stream to be sent to the receiving end of the connection

Throws:

java.net.SocketException - Thrown if there is a problem sending the byte stream

receive

public java.io.ByteArrayOutputStream receive()
                                      throws java.net.SocketException

Method used to receive a ByteArrayOutputStream from an established connection. This method has no arguments. It uses methods that act on the input stream of the socket to firstly receive a header byte, and then receive the number of payload bytes specified in the header, from the external process. The payload bytes are stored in a ByteArrayOutputStream object as each segment of payload data is received. This process is repeated until all data has been received for the current transmission.

Specified by:

receive in interface JavaCPNInterface

Returns:

sendBytes The byte stream received from the other end of the connection

Throws:

java.net.SocketException - Thrown if there is a problem sending the byte stream

disconnect

public void disconnect()
                throws java.io.IOException

Method to disconnect the established connection. This method has no arguments, and returns no value. It closes the input and output streams from the socket before closing the socket itself.

Specified by:

disconnect in interface JavaCPNInterface

Throws:

java.io.IOException - if there is a problem closing the connection