us.ihmc.mockets
Class Mocket

java.lang.Object
  extended by us.ihmc.mockets.Mocket

public class Mocket
extends java.lang.Object

The main class for a client application to use the Mockets communication library. Similar in functionality to a socket. Used by a client to establish a connection to a server and then communicate with the server.


Nested Class Summary
 class Mocket.Sender
          The class used to send messages over Mockets.
 class Mocket.Statistics
          The class that contains statistics about an active mocket connection.
 
Constructor Summary
Mocket()
          Creates a new, unconnected Mocket endpoint.
 
Method Summary
 int bind(java.net.SocketAddress addr)
          Binds the local end point to a particular address (interface) and port.
 int cancel(boolean reliable, boolean sequenced, int tagId)
          Cancels (deletes) previously enqueued messages that have been tagged with the specified tag.
 int close()
          Closes the current open connection to a remote endpoint.
 int connect(java.net.InetSocketAddress addr)
          Attempts to connect to a ServerMocket, address and port are specified using an IP Socket Address.
 int connect(java.net.SocketAddress addr, long timeout)
          Attempts to connect to a ServerMocket, address and port are specified as a Socket Address.
 int connect(java.lang.String remoteHost, int remotePort)
          Attempts to connect to a ServerMocket at the specified remote host on the specified remote port.
 int connect(java.lang.String remoteHost, int remotePort, long timeout)
          Attempts to connect to a ServerMocket at the specified remote host on the specified remote port, and choosing the connection attempt timeout.
 int enableCrossSequecing(boolean enable)
          Enables or disables cross sequencing across the reliable sequenced and unreliable sequenced packets.
protected  void finalize()
          Native method that removes mocket object.
 long getConnectionLingerTime()
          Returns the current setting for the connection linger time.
 java.lang.String getIdentifier()
          Returns the identifier for this mocket instance.
static int getMaximumMTU()
          Returns the maximum MTU that may be used.
 int getNextMessageSize(long Timeout)
          Returns the size of the next message that is ready to be delivered to the application.
 java.net.SocketAddress getPeerName()
          Extract the address of the peer in the form Socket Address.
 long getRemoteAddress()
          Native method that returns the IP addess of the remote host.
 int getRemotePort()
          Native method that returns the remote port to which the connection has been established.
 Mocket.Sender getSender(boolean reliable, boolean sequenced)
          Obtains a new sender with the specified combination of reliability and sequencing.
 Mocket.Statistics getStatistics()
          Returns a pointer to the Statistics class that maintains statistics about this mocket connection.
 int gsend(boolean reliable, boolean sequenced, byte[] buffer, int offset, int length, int tag, short priority, long enqueueTimeout, long retryTimeout, java.lang.String valist1, java.lang.String valist2)
           
 int gsend(boolean reliable, boolean sequenced, byte[] buffer, int tag, short priority, long enqueueTimeout, long retryTimeout, java.lang.String valist1, java.lang.String valist2)
           
 boolean isCrossSequencingEnabled()
          Returns the current setting for cross sequencing.
 int receive(byte[] buffer)
          Retrieves the data from next message that is ready to be delivered to the application.
 int receive(byte[] buffer, int offset, int length)
          Retrieves the data from next message that is ready to be delivered to the application.
 int receive(byte[] buffer, int offset, int length, long timeout)
          Retrieves the data from next message that is ready to be delivered to the application.
 int receive(byte[] buffer, long timeout)
          Retrieves the data from next message that is ready to be delivered to the application.
 byte[] receive(long timeout)
          Retrieves the data from next message that is ready to be delivered to the application.
 int replace(boolean reliable, boolean sequenced, byte[] buffer, int offset, int length, int oldTag, int newTag, short priority, long enqueueTimeout, long retryTimeout)
          First cancels any previously enqueued messages that have been tagged with the specified OldTag value and then transmits the new message using the specified parameters.
 int replace(boolean reliable, boolean sequenced, byte[] buffer, int oldTag, int newTag, short priority, long enqueueTimeout, long retryTimeout)
          First cancels any previously enqueued messages that have been tagged with the specified OldTag value and then transmits the new message using the specified parameters.
 int send(boolean reliable, boolean sequenced, byte[] buffer, int offset, int length, int tag, short priority, long enqueueTimeout, long retryTimeout)
          Enqueues the specified data for transmission.
 int send(boolean reliable, boolean sequenced, byte[] buffer, int tag, short priority, long enqueueTimeout, long retryTimeout)
          Enqueues the specified data for transmission.
 int setConnectionLingerTime(long lingerTime)
          Sets the length of time (in milliseconds) for which a connection should linger before closing in case there is unsent data.
 void setIdentifier(java.lang.String identifier)
          Sets a string to use as the application or user friendly identifier for this mocket instance.
 void setStatusListener(MocketStatusListener msl)
          Register a callback function to be invoked when no data (or keepalive) has been received from the peer mocket.
 int sreceive(byte[] buf1, byte[] buf2, byte[] buf3, byte[] buf4, long timeout)
          Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers.
 int sreceive(byte[] buf1, byte[] buf2, byte[] buf3, long timeout)
          Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers.
 int sreceive(byte[] buf1, byte[] buf2, long timeout)
          Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers.
 int sreceive(byte[] buf1, int offset1, int length1, byte[] buf2, int offset2, int length2, byte[] buf3, int offset3, int length3, byte[] buf4, int offset4, int length4, long timeout)
          Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers.
 int sreceive(byte[] buf1, int offset1, int length1, byte[] buf2, int offset2, int length2, byte[] buf3, int offset3, int length3, long timeout)
          Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers.
 int sreceive(byte[] buf1, int offset1, int length1, byte[] buf2, int offset2, int length2, long timeout)
          Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Mocket

public Mocket()
Creates a new, unconnected Mocket endpoint.

Method Detail

setStatusListener

public void setStatusListener(MocketStatusListener msl)
Register a callback function to be invoked when no data (or keepalive) has been received from the peer mocket. The callback will indicate the time (in milliseconds) since last contact. If the callback returns true, the mocket connection will be closed. The peer is declared unreachable and the callback is invoked if no messages are received from the peer for more than 2 seconds. This waiting time is twice the default interval between keep-alive messages.

Parameters:
msl - callback function to register.

connect

public int connect(java.lang.String remoteHost,
                   int remotePort)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException
Attempts to connect to a ServerMocket at the specified remote host on the specified remote port. The host may be a hostname that can be resolved to an IP address or an IP address in string format (e.g. "127.0.0.1"). The default connection timeout is 30 seconds.

Parameters:
remoteHost - hostname of the remote host. It can be an IP address a string hostname that will be resolved.
remotePort - port where the ServerMocket is listening.
Returns:
  • 0 if the connection is successfully established;
  • -1 if the state of the mocket is not closed. The connection has already been established;
  • -2 if the port to connect to is null;
  • -3 if the lookup of the IP address failed;
  • -4 if the initialization of datagram socket failed;
  • -5 if setting UDP receiver buffer failed;
  • -6 if setting UDP timeout failed;
  • -7 if mocket state machine is in illegal state when receiving InitAck;
  • -8 if the connection timed out while waiting for InitAck;
  • -9 if mocket state machine is in illegal state when receiving CookieAck;
  • -10 if the connection timed out while waiting for CookieAck;
  • -20 if remotePort has an illegal value (less then zero);
  • -21 if remoteHost has an illegal value, host is null;
  • -22 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

connect

public int connect(java.lang.String remoteHost,
                   int remotePort,
                   long timeout)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException
Attempts to connect to a ServerMocket at the specified remote host on the specified remote port, and choosing the connection attempt timeout. The host may be a hostname that can be resolved to an IP address or an IP address in string format (e.g. "127.0.0.1").

Parameters:
remoteHost - hostname of the remote host. It can be an IP address a string hostname that will be resolved.
remotePort - port where the ServerMocket is listening.
timeout - time in milliseconds while mocket will attempt to connect to ServerMocket.
Returns:
  • 0 if the connection is successfully established;
  • -1 if the state of the mocket is not closed. The connection has already been established;
  • -2 if the port to connect to is null;
  • -3 if the lookup of the IP address failed;
  • -4 if the initialization of datagram socket failed;
  • -5 if setting UDP receiver buffer failed;
  • -6 if setting UDP timeout failed;
  • -7 if mocket state machine is in illegal state when receiving InitAck;
  • -8 if the connection timed out while waiting for InitAck;
  • -9 if mocket state machine is in illegal state when receiving CookieAck;
  • -10 if the connection timed out while waiting for CookieAck;
  • -20 if remotePort has an illegal value (less then zero);
  • -21 if remoteHost has an illegal value, host is null;
  • -22 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

connect

public int connect(java.net.InetSocketAddress addr)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException
Attempts to connect to a ServerMocket, address and port are specified using an IP Socket Address. The default connection timeout is 30 seconds.

Parameters:
addr - remote host address specified as an IP Socket Address.
Returns:
  • 0 if the connection is successfully established;
  • -1 if the state of the mocket is not closed. The connection has already been established;
  • -2 if the port to connect to is null;
  • -3 if the lookup of the IP address failed;
  • -4 if the initialization of datagram socket failed;
  • -5 if setting UDP receiver buffer failed;
  • -6 if setting UDP timeout failed;
  • -7 if mocket state machine is in illegal state when receiving InitAck;
  • -8 if the connection timed out while waiting for InitAck;
  • -9 if mocket state machine is in illegal state when receiving CookieAck;
  • -10 if the connection timed out while waiting for CookieAck;
  • -20 if remotePort has an illegal value (less then zero);
  • -21 if remoteHost has an illegal value, host is null;
  • -22 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
See Also:
InetSocketAddress

connect

public int connect(java.net.SocketAddress addr,
                   long timeout)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException
Attempts to connect to a ServerMocket, address and port are specified as a Socket Address. Allows to choose the connection attempt timeout.

Parameters:
addr - remote host address specified as a SocketAddress.
timeout - time in milliseconds while mocket will attempt to connect to ServerMocket.
Returns:
  • 0 if the connection is successfully established;
  • -1 if the state of the mocket is not closed. The connection has already been established;
  • -2 if the port to connect to is null;
  • -3 if the lookup of the IP address failed;
  • -4 if the initialization of datagram socket failed;
  • -5 if setting UDP receiver buffer failed;
  • -6 if setting UDP timeout failed;
  • -7 if mocket state machine is in illegal state when receiving InitAck;
  • -8 if the connection timed out while waiting for InitAck;
  • -9 if mocket state machine is in illegal state when receiving CookieAck;
  • -10 if the connection timed out while waiting for CookieAck;
  • -20 if remotePort has an illegal value (less then zero);
  • -21 if remoteHost has an illegal value, host is null;
  • -22 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

bind

public int bind(java.net.SocketAddress addr)
         throws java.io.IOException,
                java.lang.IllegalArgumentException
Binds the local end point to a particular address (interface) and port. Calls to this method will work if invoked before calling connect otherwise, it will return an error code.

Parameters:
addr - remote host address specified as a SocketAddress.
Returns:
0 if success; <0 if error.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

getRemoteAddress

public long getRemoteAddress()
                      throws java.io.IOException,
                             java.lang.IllegalArgumentException
Native method that returns the IP addess of the remote host. The address is represented as a long value.

Returns:
remote host address. -1 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

getRemotePort

public int getRemotePort()
                  throws java.io.IOException,
                         java.lang.IllegalArgumentException
Native method that returns the remote port to which the connection has been established.

Returns:
remote port as an int value. -1 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

close

public int close()
          throws java.io.IOException,
                 java.lang.IllegalArgumentException
Closes the current open connection to a remote endpoint.

Returns:
0 if it ends successfully or if the connection was already closed; -1 if the connection we are attempting to close is not in the ESTABLISHED state. -10 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

enableCrossSequecing

public int enableCrossSequecing(boolean enable)
                         throws java.io.IOException,
                                java.lang.IllegalArgumentException
Enables or disables cross sequencing across the reliable sequenced and unreliable sequenced packets.

Parameters:
enable - boolean value to indicate if we want to enable (true) or disable (false) the cross sequencing.
Returns:
0 if ends with success. -1 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

isCrossSequencingEnabled

public boolean isCrossSequencingEnabled()
                                 throws java.io.IOException,
                                        java.lang.IllegalArgumentException
Returns the current setting for cross sequencing.

Returns:
boolean value that indicates if cross sequencing is enabled. -1 if the object mocket is not initialized, mocket is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
See Also:
enableCrossSequecing(boolean)

getSender

public Mocket.Sender getSender(boolean reliable,
                               boolean sequenced)
Obtains a new sender with the specified combination of reliability and sequencing.

Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
Returns:
a Sender object to be used to send messages; NULL if the objects mocket or sender are not initialized, mocket or sender is null.
See Also:
Mocket.Sender

send

public int send(boolean reliable,
                boolean sequenced,
                byte[] buffer,
                int tag,
                short priority,
                long enqueueTimeout,
                long retryTimeout)
         throws java.io.IOException,
                java.lang.IllegalArgumentException
Enqueues the specified data for transmission.

Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
buffer - the buffer to be sent. The buffer is going to be sent entirely.
tag - used to identify the type of the packet.
priority - indicates the priority of the packet. The range of priority values is 0-255.
enqueueTimeout - indicates the length of time in milliseconds for which the method will wait if there is no room in the outgoing buffer (a zero value indicates wait forever).
retryTimeout - indicates the length of time for which the transmitter will retransmit the packet to ensure successful delivery (a zero value indicates retry with no time limit).
Returns:
0 if ends with success. <0 if an error occurs.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

send

public int send(boolean reliable,
                boolean sequenced,
                byte[] buffer,
                int offset,
                int length,
                int tag,
                short priority,
                long enqueueTimeout,
                long retryTimeout)
         throws java.io.IOException,
                java.lang.IllegalArgumentException,
                java.lang.IndexOutOfBoundsException
Enqueues the specified data for transmission.

Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
buffer - the buffer to be sent.
offset - the position in the buffer we start to send from. E.g. offset=10, we send buffer starting at the 10th byte in the array.
length - the length for which we send. E.g. length=50 we send 50 bytes of the buffer, starting at offset. If offset=10, length=50 we send bytes from position 10 in the buffer through position 60.
tag - used to identify the type of the packet.
priority - indicates the priority of the packet. The range of priority values is 0-255.
enqueueTimeout - indicates the length of time in milliseconds for which the method will wait if there is no room in the outgoing buffer (a zero value indicates wait forever).
retryTimeout - indicates the length of time for which the transmitter will retransmit the packet to ensure successful delivery (a zero value indicates retry with no time limit).
Returns:
0 if ends with success. <0 if an error occurs.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

gsend

public int gsend(boolean reliable,
                 boolean sequenced,
                 byte[] buffer,
                 int tag,
                 short priority,
                 long enqueueTimeout,
                 long retryTimeout,
                 java.lang.String valist1,
                 java.lang.String valist2)
          throws java.io.IOException,
                 java.lang.IllegalArgumentException
Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
buffer - the buffer to be sent. The buffer is going to be sent entirely.
tag - used to identify the type of the packet.
priority - indicates the priority of the packet. The range of priority values is 0-255.
enqueueTimeout - indicates the length of time in milliseconds for which the method will wait if there is no room in the outgoing buffer (a zero value indicates wait forever).
retryTimeout - indicates the length of time for which the transmitter will retransmit the packet to ensure successful delivery (a zero value indicates retry with no time limit).
valist1 -
valist2 -
Returns:
Throws:
java.io.IOException
java.lang.IllegalArgumentException

gsend

public int gsend(boolean reliable,
                 boolean sequenced,
                 byte[] buffer,
                 int offset,
                 int length,
                 int tag,
                 short priority,
                 long enqueueTimeout,
                 long retryTimeout,
                 java.lang.String valist1,
                 java.lang.String valist2)
          throws java.io.IOException,
                 java.lang.IllegalArgumentException,
                 java.lang.IndexOutOfBoundsException
Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
buffer - the buffer to be sent. The buffer is going to be sent entirely.
offset - the position in the buffer we start to send from. E.g. offset=10, we send buffer starting at the 10th byte in the array.
length - the length for which we send. E.g. length=50 we send 50 bytes of the buffer, starting at offset. If offset=10, length=50 we send bytes from position 10 in the buffer through position 60.
tag - used to identify the type of the packet.
priority - indicates the priority of the packet. The range of priority values is 0-255.
enqueueTimeout - indicates the length of time in milliseconds for which the method will wait if there is no room in the outgoing buffer (a zero value indicates wait forever).
retryTimeout - indicates the length of time for which the transmitter will retransmit the packet to ensure successful delivery (a zero value indicates retry with no time limit).
valist1 -
valist2 -
Returns:
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

getNextMessageSize

public int getNextMessageSize(long Timeout)
                       throws java.io.IOException,
                              java.lang.IllegalArgumentException
Returns the size of the next message that is ready to be delivered to the application. If no message is available, the call will block based on the timeout parameter. A timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely.

Parameters:
Timeout - milliseconds to wait for a message available. A 0 value means use the default timeout (-1). A -1 value means wait indefinitely.
Returns:
size of the message waiting to be read, in bytes; 0 if no data is available in the specified timeout; -1 if the connection has been closed.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

receive

public int receive(byte[] buffer)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException
Retrieves the data from next message that is ready to be delivered to the application. At most buffer.length bytes are copied into the specified buffer. NOTE: Any additional data in the packet that will not fit in the buffer is discarded. The receive is a blocking function, waits until there are data to be received or the timeout expires. The timeout is not specified, the default value is going to be used. The default value is -1. A timeout of -1 implies wait indefinitely.

Parameters:
buffer - byte array where the data is copied for delivery.
Returns:
  • returns the number of bytes that were copied into the buffer;
  • -1 if an error occurred;
  • -10 if the object mocket is not initialized, mocket is null;
  • -11 if the parameter buffer is invalid, buffer is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

receive

public int receive(byte[] buffer,
                   int offset,
                   int length)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException,
                   java.lang.IndexOutOfBoundsException
Retrieves the data from next message that is ready to be delivered to the application. The bytes are copied into the specified buffer starting at the specified offset. At most length bytes are copied. NOTE: Any additional data in the packet that will not fit in the buffer is discarded. The receive is a blocking function, waits until there are data to be received or the timeout expires. The timeout is not specified, the default value is going to be used. The default value is -1. A timeout of -1 implies wait indefinitely.

Parameters:
buffer - byte array where the data is copied for delivery.
offset - the point in the buffer where we start to copy the data.
length - the number of bytes that are copied into the buffer.
Returns:
  • returns the number of bytes that were copied into the buffer;
  • -1 if an error occurred;
  • -10 if the object mocket is not initialized, mocket is null;
  • -11 if the parameter buffer is invalid, buffer is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

receive

public int receive(byte[] buffer,
                   long timeout)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException
Retrieves the data from next message that is ready to be delivered to the application. At most buffer.length bytes are copied into the specified buffer. NOTE: Any additional data in the packet that will not fit in the buffer is discarded. The receive is a blocking function, waits until there are data to be received or the timeout expires. This function allows to specify a value for the timeout. Specifying a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The default timeout is -1.

Parameters:
buffer - byte array where the data is copied for delivery.
timeout - milliseconds to wait for data.
Returns:
  • returns the number of bytes that were copied into the buffer;
  • -1 if an error occurred;
  • -10 if the object mocket is not initialized, mocket is null;
  • -11 if the parameter buffer is invalid, buffer is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

receive

public int receive(byte[] buffer,
                   int offset,
                   int length,
                   long timeout)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException,
                   java.lang.IndexOutOfBoundsException
Retrieves the data from next message that is ready to be delivered to the application. The bytes are copied into the specified buffer starting at the specified offset. At most length bytes are copied. NOTE: Any additional data in the packet that will not fit in the buffer is discarded. The receive is a blocking function, waits until there are data to be received or the timeout expires. This function allows to specify a value for the timeout. Specifying a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The default timeout is -1.

Parameters:
buffer - byte array where the data is copied for delivery.
offset - the point in the buffer where we start to copy the data.
length - the number of bytes that are copied into the buffer.
timeout - milliseconds to wait for data.
Returns:
  • returns the number of bytes that were copied into the buffer;
  • -1 if an error occurred;
  • -10 if the object mocket is not initialized, mocket is null;
  • -11 if the parameter buffer is invalid, buffer is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

receive

public byte[] receive(long timeout)
               throws java.io.IOException,
                      java.lang.IllegalArgumentException
Retrieves the data from next message that is ready to be delivered to the application. The bytes are returned as return value. The receive is a blocking function, waits until there are data to be received or the timeout expires. This function allows to specify a value for the timeout. Specifying a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The default timeout is -1.

Parameters:
timeout - milliseconds to wait for data.
Returns:
a buffer containing the data read; NULL if an error occurred.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

sreceive

public int sreceive(byte[] buf1,
                    byte[] buf2,
                    long timeout)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException
Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The data is scattered into the buffers that are passed into the method. Note: Any additional data in the packet that will not fit in the buffers is discarded.

E.g.: if the caller passes in two buffers, sreceive (pBufOne, pBufTwo, iTimeout), and the method returns 4000, the implication is that pBufOne.length bytes were read into pBufOne, pBufTwo.length bytes into pBufTwo. If pBufOne.length+pBufTwo.length<4000 all the data are read, otherwise some data is lost.

Parameters:
buf1 - first byte array where data is copied for delivery.
buf2 - second byte array where additional data is copied for delivery.
timeout - milliseconds to wait for data.
Returns:
returns the total number of bytes that were copied into all the buffers; -1 in case of the connection being closed; 0 in case no data is available within the specified timeout.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

sreceive

public int sreceive(byte[] buf1,
                    int offset1,
                    int length1,
                    byte[] buf2,
                    int offset2,
                    int length2,
                    long timeout)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException,
                    java.lang.IndexOutOfBoundsException
Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The data is scattered into the buffers that are passed into the method. The pointer to the buffer and the buffer size arguments must be passed in pairs. Note: Any additional data in the packet that will not fit in the buffers is discarded.

E.g.: if the caller passes in two buffers, sreceive (pBufOne, 0, 8, pBufTwo, 0, 1024, iTimeout), and the method returns 500, the implication is that 8 bytes were read into pBufOne and 492 bytes into pBufTwo.

Parameters:
buf1 - first byte array where data is copied for delivery.
offset1 - the point in the first buffer where we start to copy the data.
length1 - the number of bytes that are copied into the first buffer.
buf2 - second byte array where additional data is copied for delivery.
offset2 - the point in the second buffer where we start to copy the data.
length2 - the number of bytes that are copied into the second buffer.
timeout - milliseconds to wait for data.
Returns:
returns the total number of bytes that were copied into all the buffers; -1 in case of the connection being closed; 0 in case no data is available within the specified timeout.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

sreceive

public int sreceive(byte[] buf1,
                    byte[] buf2,
                    byte[] buf3,
                    long timeout)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException
Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The data is scattered into the buffers that are passed into the method. The pointer to the buffer and the buffer size arguments must be passed in pairs. Note: Any additional data in the packet that will not fit in the buffers is discarded.

E.g.: if the caller passes in three buffers, sreceive (pBufOne, pBufTwo, pBufThree, iTimeout), and the method returns 4000, the implication is that pBufOne.length bytes were read into pBufOne, pBufTwo.length bytes into pBufTwo, and the remaining pBufThree.length bytes into pBufThree. If pBufOne.length+pBufTwo.length+pBufThree.length<4000 all the data are read, otherwise some data is lost.

Parameters:
buf1 - first byte array where data is copied for delivery.
buf2 - second byte array where additional data is copied for delivery.
buf3 - third byte array where additional data is copied for delivery.
timeout - milliseconds to wait for data.
Returns:
returns the total number of bytes that were copied into all the buffers; -1 in case of the connection being closed; 0 in case no data is available within the specified timeout.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

sreceive

public int sreceive(byte[] buf1,
                    int offset1,
                    int length1,
                    byte[] buf2,
                    int offset2,
                    int length2,
                    byte[] buf3,
                    int offset3,
                    int length3,
                    long timeout)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException,
                    java.lang.IndexOutOfBoundsException
Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The data is scattered into the buffers that are passed into the method. The pointer to the buffer and the buffer size arguments must be passed in pairs. Note: Any additional data in the packet that will not fit in the buffers is discarded.

E.g.: If the caller passes in three buffers, sreceive (pBufOne, 0, 8, pBufTwo, 0, 1024, pBufThree, 0, 4096, iTimeout), and the method returns 4000, the implication is that 8 bytes were read into pBufOne, 1024 bytes into pBufTwo, and the remaining 2968 bytes into pBufThree.

Parameters:
buf1 - first byte array where data is copied for delivery.
offset1 - the point in the first buffer where we start to copy the data.
length1 - the number of bytes that are copied into the first buffer.
buf2 - second byte array where additional data is copied for delivery.
offset2 - the point in the second buffer where we start to copy the data.
length2 - the number of bytes that are copied into the second buffer.
buf3 - third byte array where additional data is copied for delivery.
offset3 - the point in the third buffer where we start to copy the data.
length3 - the number of bytes that are copied into the third buffer.
timeout - milliseconds to wait for data.
Returns:
returns the total number of bytes that were copied into all the buffers; -1 in case of the connection being closed; 0 in case no data is available within the specified timeout.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

sreceive

public int sreceive(byte[] buf1,
                    byte[] buf2,
                    byte[] buf3,
                    byte[] buf4,
                    long timeout)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException
Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The data is scattered into the buffers that are passed into the method. The pointer to the buffer and the buffer size arguments must be passed in pairs. Note: Any additional data in the packet that will not fit in the buffers is discarded.

E.g.: if the caller passes in four buffers, sreceive (pBufOne, pBufTwo, pBufThree, pBufFour, iTimeout), and the method returns 4000, the implication is that pBufOne.length bytes were read into pBufOne, pBufTwo.length bytes into pBufTwo, pBufThree.length bytes into pBufThree, and the remaining pBufFour.length bytes into pBufFour. If pBufOne.length+pBufTwo.length+pBufThree.length+pBufFour.length<4000 all the data are read, otherwise some data is lost.

Parameters:
buf1 - first byte array where data is copied for delivery.
buf2 - second byte array where additional data is copied for delivery.
buf3 - third byte array where additional data is copied for delivery.
buf4 - fourth byte array where additional data is copied for delivery.
timeout - milliseconds to wait for data.
Returns:
returns the total number of bytes that were copied into all the buffers; -1 in case of the connection being closed; 0 in case no data is available within the specified timeout.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

sreceive

public int sreceive(byte[] buf1,
                    int offset1,
                    int length1,
                    byte[] buf2,
                    int offset2,
                    int length2,
                    byte[] buf3,
                    int offset3,
                    int length3,
                    byte[] buf4,
                    int offset4,
                    int length4,
                    long timeout)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException,
                    java.lang.IndexOutOfBoundsException
Retrieves the data from the next message that is ready to be delivered to the application splitting the data in different buffers. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The data is scattered into the buffers that are passed into the method. The pointer to the buffer and the buffer size arguments must be passed in pairs. Note: Any additional data in the packet that will not fit in the buffers is discarded.

E.g.: If the caller passes in four buffers, sreceive (pBufOne, 0, 8, pBufTwo, 0, 1024, pBufThree, 0, 1024, pBufFour, 0 4096, iTimeout), and the method returns 4000, the implication is that 8 bytes were read into pBufOne, 1024 bytes into pBufTwo, 1024 bytes into pBufThree, and the remaining 1944 bytes into pBufFour.

Parameters:
buf1 - first byte array where data is copied for delivery.
offset1 - the point in the first buffer where we start to copy the data.
length1 - the number of bytes that are copied into the first buffer.
buf2 - second byte array where additional data is copied for delivery.
offset2 - the point in the second buffer where we start to copy the data.
length2 - the number of bytes that are copied into the second buffer.
buf3 - third byte array where additional data is copied for delivery.
offset3 - the point in the third buffer where we start to copy the data.
length3 - the number of bytes that are copied into the third buffer.
buf4 - fourth byte array where additional data is copied for delivery.
offset4 - the point in the fourth buffer where we start to copy the data.
length4 - the number of bytes that are copied into the fourth buffer.
timeout - milliseconds to wait for data.
Returns:
returns the total number of bytes that were copied into all the buffers; -1 in case of the connection being closed; 0 in case no data is available within the specified timeout.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

replace

public int replace(boolean reliable,
                   boolean sequenced,
                   byte[] buffer,
                   int oldTag,
                   int newTag,
                   short priority,
                   long enqueueTimeout,
                   long retryTimeout)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException
First cancels any previously enqueued messages that have been tagged with the specified OldTag value and then transmits the new message using the specified parameters. Note that there may be no old messages to cancel, in which case this call behaves just like a send.

Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
buffer - the buffer to be sent. The buffer is going to be sent entirely.
oldTag - tag of the messages to replace. Messages tagged with oldTag will be canceled.
newTag - tag of the new message to be enqueued. The value has to be >0.
priority - indicates the priority of the packet. The range of priority values is 0-255.
enqueueTimeout - indicates the length of time in milliseconds for which the method will wait if there is no room in the outgoing buffer (a zero value indicates wait forever).
retryTimeout - indicates the length of time for which the transmitter will retransmit the packet to ensure successful delivery (a zero value indicates retry with no time limit).
Returns:
  • 0 if ends with success;
  • -1 if an error occurred;
  • -2 if the cancel function ended with error;
  • -3 if the send function ended with error.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

replace

public int replace(boolean reliable,
                   boolean sequenced,
                   byte[] buffer,
                   int offset,
                   int length,
                   int oldTag,
                   int newTag,
                   short priority,
                   long enqueueTimeout,
                   long retryTimeout)
            throws java.io.IOException,
                   java.lang.IllegalArgumentException,
                   java.lang.IndexOutOfBoundsException
First cancels any previously enqueued messages that have been tagged with the specified OldTag value and then transmits the new message using the specified parameters. Note that there may be no old messages to cancel, in which case this call behaves just like a send.

Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
buffer - the buffer to be sent.
offset - the position in the buffer we start to send from. E.g. offset=10, we send buffer starting at the 10th byte in the array
length - the length for which we send. E.g. length=50 we send 50 bytes of the buffer, starting at offset. If offset=10, length=50 we send bytes from position 10 in the buffer through position 60.
oldTag - tag of the messages to replace. Messages tagged with oldTag will be canceled.
newTag - tag of the new message to be enqueued. The value has to be >0.
priority - indicates the priority of the packet. The range of priority values is 0-255.
enqueueTimeout - indicates the length of time in milliseconds for which the method will wait if there is no room in the outgoing buffer (a zero value indicates wait forever).
retryTimeout - indicates the length of time for which the transmitter will retransmit the packet to ensure successful delivery (a zero value indicates retry with no time limit).
Returns:
  • 0 if ends with success;
  • -1 if an error occurred;
  • -2 if the cancel function ended with error;
  • -3 if the send function ended with error.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
java.lang.IndexOutOfBoundsException - if the parameters offset or length are illegal for buffer.

cancel

public int cancel(boolean reliable,
                  boolean sequenced,
                  int tagId)
           throws java.io.IOException,
                  java.lang.IllegalArgumentException
Cancels (deletes) previously enqueued messages that have been tagged with the specified tag. Note that the messages may be pending transmission (which applies to all flows) or may have already been transmitted but not yet acknowledged (which only applies to reliable flows).

Parameters:
reliable - select the type of flow: reliable (true) or unreliable (false).
sequenced - select the type of flow: sequenced (true) or unsequenced (false).
tagId - used to identify the packets to delete.
Returns:
number of messages removed form the queues; -1 if an error occurred.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
See Also:
to obtain the same result specifying less parameters.

setConnectionLingerTime

public int setConnectionLingerTime(long lingerTime)
                            throws java.io.IOException,
                                   java.lang.IllegalArgumentException
Sets the length of time (in milliseconds) for which a connection should linger before closing in case there is unsent data. A timeout value of 0 implies that the connection should wait indefinitely until all data has been sent.

Parameters:
lingerTime - milliseconds for which the connection should linger.
Returns:
0 if success.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

getConnectionLingerTime

public long getConnectionLingerTime()
                             throws java.io.IOException,
                                    java.lang.IllegalArgumentException
Returns the current setting for the connection linger time. The linger time represents the amount of time (in milliseconds) for which a connection should linger before closing in case there is unsent data. A value of zero means wait indefinitely.

Returns:
long representing the connection linger time in milliseconds.
Throws:
java.io.IOException
java.lang.IllegalArgumentException
See Also:
setConnectionLingerTime(long)

getStatistics

public Mocket.Statistics getStatistics()
                                throws java.io.IOException,
                                       java.lang.IllegalArgumentException
Returns a pointer to the Statistics class that maintains statistics about this mocket connection.

Returns:
an object of class Statistic. NULL if the objects mocket or statistic are not initialized, mocket or statistic is null.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

getMaximumMTU

public static int getMaximumMTU()
                         throws java.io.IOException,
                                java.lang.IllegalArgumentException
Returns the maximum MTU that may be used.

Returns:
integer representing the maximum MTU that may be used.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

getPeerName

public java.net.SocketAddress getPeerName()
                                   throws java.io.IOException,
                                          java.lang.IllegalArgumentException
Extract the address of the peer in the form Socket Address.

Returns:
the address, in the form Socket Address, of the peer; NULL if an error occurred.
Throws:
java.io.IOException
java.lang.IllegalArgumentException

finalize

protected void finalize()
Native method that removes mocket object.

Overrides:
finalize in class java.lang.Object

setIdentifier

public void setIdentifier(java.lang.String identifier)
Sets a string to use as the application or user friendly identifier for this mocket instance. The identifier is used when sending out statistics and when logging information. Some suggestions include the name of the application, the purpose for this mocket, etc. May be set to NULL to clear a previously set identifier. NOTE: The string is copied internally, so the caller does not need to preserve the string

Parameters:
identifier - string to be used to identify this mocket instance.

getIdentifier

public java.lang.String getIdentifier()
Returns the identifier for this mocket instance.

Returns:
identifier of this mocket instance; NULL if no identifier is set.
See Also:
setIdentifier(java.lang.String)