Introduction to Callbacks

SmartSockets makes heavy use of callbacks to allow you visibility into its internal processing. A callback is a mechanism that allows you to be notified when a specified event occurs, such as a message is placed into the input queue. The callback can be associated with a certain event or with all events of a certain type. Callbacks that are associated with all events of a given type are called global callbacks. When the event occurs, the specified callback object’s method is invoked to notify you that the event happened.

Your SmartSockets Java RTclient application contains classes that implement callback interfaces (either directly or through inheritance) and the specific code required for each handled event.

Table 2 Callback Interfaces
Callback Interface	Function
TipcCreateCb	The `create` method is called when an RTserver connection is successfully created
TipcDefaultCb	The `handle` method is called when no Process callback for a received message type is registered (see TipcProcessCb).
TipcDestroyCb	The `destroy` method is called when an RTserver connection is destroyed.
TipcErrorCb	The `error` method is called when certain SmartSockets errors occur.
TipcProcessCb	The `process` method is called when a message of a previously-specified matching type or subject is received.
TipcReadCb	The `read` method is called when a message is read and placed in the input queue.
TipcWriteCb	The `write` method is called when a message is written and removed from the output queue.

Only a very brief introduction to callback classes is provided in these lessons. See the online Javadoc format documentation for more detailed information about the specifics of SmartSockets Java callbacks.

They are used to affect the processing of a message or simply to receive notification of some event.

They have an associated priority. Priorities determine the order in which callback methods are invoked. Higher priority callbacks are called before lower priority ones. If two callbacks have the same priority, their relative calling order is undetermined. The getPriority and setPriority methods of the TipcCb class are used to retrieve and assign, respectively, callback priorities.

They are uniquely identified by method and argument within a given application. This means that two callbacks cannot be registered to use the same callback class and argument within the same program. Attempts to add the same callback multiple times are ignored.

Their action methods allow for an extra argument (of type Object) to be supplied when invoked. This parameter is not used by SmartSockets and is a convenient place to pass application-specific data to the callback operation.

Creating Callbacks

A callback is created by implementing the appropriate interface and then registering an instance of the event-handling class with the addTypeCb method of the active TipcSrv or TipcConn object. For example, to create an error callback (for example, MyErrorCb) that gets invoked when a non-recoverable error occurs on your program’s connection to RTserver, a class needs to be created that implements the TipcErrorCb interface, as illustrated below:

public class MyErrorCbClass implements TipcErrorCb { 
public error(int errNum, String errStr, Object obj) { 
  // error handling here 
  ...   
} 
}

Keep in mind that this does not necessarily have to be a new, single-purpose object; Java classes can easily implement multiple interfaces.

You also need to add code similar to this to the main program to register the new callback with SmartSockets:

// the add method returns a reference to the callback 
// used later; you don’t want this to go out of scope, 
// so this next line, the reference declaration, would 
// probably be placed at the class level, if this class 
// isn’t transient 
TipcCb MyErrorCbRef; 
 
// in this example, srv is the current TipcSrv object 
MyErrorCbClass MyErrorCb = new MyErrorCbClass; 
MyErrorCbRef = srv.addErrorCb(MyErrorCb, srv); 
if (null == MyErrorCbRef) { 
  // error 
}

In general, you should always check to make sure the callback is successfully registered. You also need to write the code for the error method in MyErrorCbClass to actually handle the event.

Manipulating Callbacks

To manipulate the various attributes of a callback, a handle (of type TipcCb) to the callback must first be acquired. An application retrieves this handle in one of two ways. First, the handle can be produced with the lookupTypeCb method of a TipcConn or TipcSrv object, where Type is replaced with one of: Create, Destroy, Default, Process, Error, Read, or Write. Alternately, the return value of the various callback add methods can be used; it is also the TipcCb corresponding to the added callback. Event callback properties can then be manipulated using the SmartSockets TipcCb.* utility functions:


getArgument	returns the callback’s `Object` argument.
getCallback	returns the class that implements this callback’s interface.
getPriority	returns this callback’s priority.
setArgument	sets the callback’s `Object` argument to the specified value.
setCallback	sets the class that implements this callback’s interface.
setPriority	sets the callback’s priority.

See the online documentation of the TipcCb class for more details on these methods.

Destroying Callbacks

Event callbacks may be unregistered by calling the removeTypeCb method with the TipcCb reference returned by the addTypeCb method.