OmniMessage

The OmniMessage is the base class of all protocol messages. You don't have to write message classes from scratch, it's done automatically by the omni compiler (omnic) from a protocol description you provide in message definition language (mdl). You simply override the run() method of each message class to implement an appropriate message handler. When a message is received on an OmniSocket, the socket creates and runs an OmniMessage of the appropriate type. This relieves you from having to develop program logic to receive, parse and handle messages. Since the messages are run in separate threads, you can perform virtually anything in a message run() method. Just bear in mind that other messages may be running simultaneously, so exercise appropriate care in accessing shared data.

OmniSocket

The OmniSocket is a communications endpoint like a java.net.Socket, but enhances the vanilla Socket in a couple of useful ways. When an OmniSocket is created, it runs itself in a thread to receive messages sent on the socket. Then when a message is received, the OmniSocket creates and runs an OmniMessage of the corresponding type. In essence, your progam never has to worry about receiving a message, unmarshalling message data, and dispatching to an appropriate message handler; all of that is performed automatically by the OmniSocket. To send a message on an OmniSocket, simply create a message of some type, set its fields appropriately, and call s.send(m) where s is an OmniSocket and m is an OmniMessage. The OmniSocket takes care of marshalling the message data and sending it on the socket.

OmniListener

The OmniListener is used on the server side only to wait for connections like a java.net.ServerSocket. However, the OmniListener enhances the vanilla ServerSocket in a couple of useful ways. When an OmniListener is created, it runs itself in a thead to accept connections from remote hosts. Then when a connection is made, the OmniListener notifies you by running an OmniEventHandler (see below). This relieves you from having to develop program logic to accept connections and spawn threads to handle them.

OmniEventHandler

The OmniEventHandler is the base class for your protocol's event handlers. The easiest way to extend OmniEventHandler is to modify the individual event handlers, connected(), disconnected(), message(), and badMessage(). Connected() is invoked by an OmniListener when a connection is made by a remote host. Disconnected() is called by an OmniSocket when a connection is broken. Message() is called whenever an OmniMessage is received; you probably don't want to implement message type-specific logic here, generic activity such as message logging is more appropriate in message(). BadMessage() is called whenever an unrecognized message type is received. The base class has access methods for the OmniListener and OmniSocket to enable your event handler to figure out which listener and socket the event happened on. The OmniEventHandler also contains a data member and access methods for a cookie. A cookie is an object you use for correlation. To use a cookie, first create the correlation object and pass it to the constructor for your event handler class. Then pass the event handler to the OmniListener (server) or OmniSocket (client) constructor, and on subsequent events the OmniSockets framework runs your acceptor. When the acceptor is run, you can get the cookie, downcast it to the appropriate type and use it in any way you wish. Note that the event handler is run in a separate thread, so you can perform virtually any action in its run() method. Just bear in mind that other event handlers or messages may be running simultaneously, so use appropriate care when accessing shared data.