de.ocarthon.libArcus

Class ArcusSocket

java.lang.Object

de.ocarthon.libArcus.ArcusSocket

public class ArcusSocket
extends Object

ArcusSocket creates a socket in a thread to send and receive message based on the Protocol Buffers library developed by Google. This implementation is based on libArcus by ltimaker and resembles the original implementation as close as possible.

Protocol

The protocol used consists of four parts:

• Header: 0x28BAD0100 (32 bits) containing the signature (0x2BAD), major protocol version (0x01) and minor protocol version (0x00).
• Size: 32 bits containing the size of the serialized protobuf message
• Type: 32 bits containing the FNV-1a hash of the full protobuf message typename. This typename consists of the protobuf package (defined in the protobuf file) and the name of the message concatenated together.
• Message: the serialized message. Number of bytes is equal to the defined size

There are also two special headers. A keep-alive header (0x00000000) is being sent every 250 ms to check if the connection is still alive and a close header (0xF0F0F0F0) is sent when the connection is closing.

SocketListener

A SocketListener can be added via addListener(SocketListener) and removed by calling removeListener(SocketListener). All registered listeners get notified when:

• a new message has been received: SocketListener.messageReceived(ArcusSocket)
• the socket's state changes: SocketListener.stateChanged(ArcusSocket, SocketState)
• an error occurs: SocketListener.error(ArcusSocket, Error)

SocketListeners can only be added or removed when the socket is in it's initial state.

Registering message types

New message types can be registered as long as the socket is in it's initial state. By calling registerMessageType(Message) the message type (more particularly the parser) will be stored to identify and parse incoming messages. This method returns a boolean value indicating if the type has been added.

Using the socket

The socket can either be started as a server or a client. By calling listen(int), it listens on the given port and waits for a client to connect. If the port is set to 0, a port will automatically be allocated. With connect(String, int), a connection to the given address will be established. All other methods affect the socket in both cases in the same way.

Once the socket is connected it will send and receive message on another thread. Messages can be sent by calling sendMessage(Message). They will be added to an internal Queue. The separate Thread will check for messages in the Queue and send them to the other side. After all messages are sent it tries to read incoming messages. If a valid message has been received and successfully parsed, all registered SocketListeners will get notified and the message gets added to the internal Queue. Messages can be chronically obtained by successive calls to takeNextMessage().

Possible socket states

In the life-cycle of an ArcusSocket, it can go through the following states:

• Initial: The socket has not yet been started. At this point SocketListeners can be modified and message types can be added
• Connecting: The socket has been started with a call to connect(String, int) and is not connecting to the given address
• Opening: The socket has been started with a call to listen(int) and is starting an internal ServerSocket
• Listening: The internal ServerSocket is waiting for a client to connect
• Connected: The socket is connected and messages can be sent and received
• Closing: The socket is closing the connection. Before actually closing the connection, all messages in the queue are being sent and the socket waits for a response from the other side
• Closed: The socket has successfully closed the connection
• Error: An error occurred and the socket got shut down

Errors

If an error occurs, all registered listeners get notified. In case of a fatal error, the socket will be forcefully closed. Every error contains an ErrorCode and a message describing what happened.

Reusing the socket

If the socket has been closed or was forcefully closed and in now in an error state, it can be reset by calling reset(). The socket will be reset to default values and can now be used as if it was newly constructed. SocketListeners and message types will not be reset and remain the same.

Author:

Philip Standt

Constructor Summary

Constructors

Constructor and Description
ArcusSocket()

Method Summary

Modifier and Type	Method and Description
void	addListener(SocketListener listener) Adds a listener to the internal List.
void	close() Closes the socket.
void	connect(String address, int port) Connects to a remote address.
int	getPort() This will return the ports specified by calls to listen(int) or connect(String, int).
int	getSocketTimeout() Returns the time until the socket times out while connecting, reading or writing.
SocketState	getState() Returns the current state the socket is in.
void	listen(int port) Listens for a new incoming connection on the specified port.
boolean	registerMessageType(com.google.protobuf.Message message) Registers a new message type to receive and parse messages of the same type later.
void	removeAllListeners() Removes all listeners from the internal list.
void	removeListener(SocketListener listener) Removes a listener from the internal list.
void	reset() Resets the socket and the socket's state to use it again.
void	sendMessage(com.google.protobuf.Message message) Adds a message to the internal send queue.
void	setSocketTimeout(int socketTimeout) Sets the time until the socket times out while connecting, reading or writing.
com.google.protobuf.Message	takeNextMessage() Polls the first message in the receive queue.

Methods inherited from class java.lang.Object

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

Constructor Detail

ArcusSocket

public ArcusSocket()

Method Detail

registerMessageType

public boolean registerMessageType(com.google.protobuf.Message message)

Registers a new message type to receive and parse messages of the same type later.

Although you can use any instance of a message type, it is recommended for readability and null-safety purposes to use the default instance (MessageLiteOrBuilder.getDefaultInstanceForType()) of the message type.

Parameters:

message - the message whose type will be registered

Returns:

True if the message type got registered. False if message is null, the socket is not in it's initial state or the type has already been registered.

getSocketTimeout

public int getSocketTimeout()

Returns the time until the socket times out while connecting, reading or writing.

Returns:

time in ms

setSocketTimeout

public void setSocketTimeout(int socketTimeout)

Sets the time until the socket times out while connecting, reading or writing. This can only be set when the socket is in it's initial state.

Parameters:

socketTimeout - time in ms

addListener

public void addListener(SocketListener listener)

Adds a listener to the internal List. If events like state changes occur, the corresponding methods will be called. This will only work if the socket is in the initial state. Otherwise an error will occur.

Parameters:

listener - SocketListener that will be added

removeListener

public void removeListener(SocketListener listener)

Removes a listener from the internal list. This will only work if the socket is in the initial state. Otherwise an error will occur.

Parameters:

listener - SocketListener that will be removed

removeAllListeners

public void removeAllListeners()

Removes all listeners from the internal list. This will only work if the socket is in the initial state. Otherwise an error will occur.

connect

public void connect(String address,
                    int port)

Connects to a remote address. This is only possible if the socket is in the initial state. Otherwise an will occur. Additional checks are in place to ensure the arguments are valid. The address must not be null and the port must be valid (0 ≤ port ≤ 65535).

Parameters:

address - remote address

port - remote port

listen

public void listen(int port)

Listens for a new incoming connection on the specified port. This is only possible if the socket is in the initial state and the port is valid (0 ≤ port ≤ 65535). Otherwise an will occur. The socket will go into the Opening state.

If the specified port is 0, the port number is automatically allocated, typically from an ephemeral port range. This port number can then be retrieved by calling getPort().

Parameters:

port - port to listen on. If 0, the port is automatically allocated.

sendMessage

public void sendMessage(com.google.protobuf.Message message)

Adds a message to the internal send queue.

Parameters:

message - message to be sent

takeNextMessage

public com.google.protobuf.Message takeNextMessage()

Polls the first message in the receive queue. This message is then no longer in the queue.

Returns null if there are no new messages

Returns:

message from receive queue. Null if no new messages are present

reset

public void reset()

Resets the socket and the socket's state to use it again. This is only possible if the socket is closed or a fatal error occurred. SocketListeners and message types will not be reset and remain the same.

close

public void close()

Closes the socket. All messages in the send queue will be sent before finally sending a closing message.

getState

public SocketState getState()

Returns the current state the socket is in.

Returns:

current state of the socket

See Also:

ArcusSocket

getPort

public int getPort()

This will return the ports specified by calls to listen(int) or connect(String, int). If none of them have been called, 0 will be returned.

If listen(int) has been called with the port 0, this will return the automatically allocated port

Returns:

port that is used for the connection.