CallbackHandler API

The CallbackHandler interface is invoked when any database event occurs. A default callback handler is provided, which basically does nothing. You should implement a custom CallbackHandler to register important events. The callback is invoked on the thread that is processing the event. To receive callbacks for database changes, you must register a CallBackHandler with the generated database class, the entity class, or both. You can create a handler by extending the DefaultCallbackHandler class or by implementing the com.sybase.persistence.CallbackHandler interface.

In your handler, override the particular callback that you are interested in (for example, void onReplayFailure(java.lang.Object entity) ). The callback is executed in the thread that is performing the action (for example, replay). When you receive the callback, the particular activity is already complete.

Callbacks in the CallbackHandler Interface
Callback Description
void onImport(java.lang.Object entity)

This method is invoked when an import message is successfully applied to the local database. However, it is not committed. One message from server may have multiple import entities and they would be committed in one transaction for the whole message.

Note:
  1. Stale data may be read from the database at this time before commit of the whole message. Developers are encouraged to wait until the next onTransactionCommit() is invoked, then to read from the database to obtain the updated data.
  2. Both CallbackHandlers registered for the MBO class of the entity and Package DB will be invoked.
Parameters:
  • entity – the Mobile Business Object that was just imported.
void onLoginFailure()

This method will be invoked when login failed for a beginOnlineLogin call.

Note: Only the CallbackHandler registered for package DB will be invoked.
void onLoginSuccess()

This method is invoked when login succeeds for a beginOnlineLogin call.

Note: Only the CallbackHandler registered for package DB is invoked.
void onReplayFailure(java.lang.Object entity)

This method is invoked when a replay request fails.

Note: CallbackHandlers registered for both the MBO class of the entity and the Package DB are invoked.
Parameters:
  • entity – the Mobile Business Object to replay.
void onReplaySuccess(java.lang.Object entity)

This method is invoked when a replay request succeeds.

Note: CallbackHandlers registered for both the MBO class of the entity and the Package DB are invoked.
Parameters:
  • entity – the Mobile Business Object to replay.
void onSearchFailure(java.lang.Object entity)

This method is invoked when a back-end search fails.

Note: CallbackHandlers registered for both the MBO class of the entity and the Package DB are invoked.
Parameters:
  • entity – the back-end search object.
void onSearchSuccess(java.lang.Object entity)

This method is invoked when a back end search succeeds.

Note: CallbackHandlers registered for both the MBO class of the entity and the Package DB are invoked.
Parameters:
  • entity – the back-end search object.
void onSubscribeFailure()

This method is invoked when subscribe fails.

Note: CallbackHandlers registered for both the MBO class of the entity and the Package DB are invoked.
void onSubscribeSuccess()

This method is invoked when subscribe succeeds.

Note: Only the CallbackHandler registered for the Package DB is invoked.
int onSynchronize(GenericList<SynchronizationGroup> groups, SynchronizationContext context)

This method is invoked at different stages of the synchronization. This method is called by the database class synchronize or beginSynchronize methods when the client initiates a synchronization, and is called again when the server responds to the client that synchronization has finished, or that synchronization failed. The status of the synchronization context, context.Status, specifies the stage of the synchronization.

Parameters:
  • groups – a list of synchronization groups.
  • context – the synchronization context.
Returns: Either SynchronizationAction.CONTINUE or Synchronization.CANCEL. If SynchronizationAction.CANCEL is returned, the synchronize is cancelled if the status of the synchronization context is one of the following.
  • SynchronizationStatus.STARTING
  • SynchronizationStatus.ASYNC_REPLAY_COMPLETED
  • SynchronizationStatus.STARTING_ON_NOTIFICATION
The return value has no effect if the status is not in the above list.
void onSuspendSubscriptionFailure()

This method is invoked when suspend subscription fails.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onSuspendSubscriptionSuccess()

This method is invoked when suspend subscription succeeds.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onResumeSubscriptionFailure()

This method is invoked when resume subscription fails.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onResumeSubscriptionSuccess()

This method is invoked when resume subscription succeeds.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onUnsubscribeFailure()

This method is invoked when unsubscribe fails.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onUnsubscribeSuccess()

This method is invoked when unsubscribe succeeds.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onMessageException(java.lang.Exception ex)

This method is invoked when an exception occurs in the processing of a message.

Note: In DefaultCallbackHandlers, onMessageException re-throws the Exception so that the messaging layer can retry the message. The application developer has the option to implement a custom CallbackHandler that does not re-throw the exception, based on exception types or other conditions, so that the message is not retried.
Parameters:
  • ex – the exception thrown when processing a message.
void onTransactionCommit()

This method is invoked after a message is processed and committed.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onTransactionRollback()

This method is invoked after a message is rolled back. It only happens when an Exception was thrown when processing the message, or from a custom Callback method.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onResetSuccess()

This method is invoked when all data is cleared by the reset.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onRecoverSuccess()

This method is invoked when recover succeeds.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onRecoverFailure()

This method is invoked when recover fails.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onSubscriptionEnd()

This method is invoked when a subscription is re-registered or unsubscribed. This method deletes all MBO data on the device.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void onImportSuccess()

This method is invoked when all data has been successfully imported.

Note: Only the CallbackHandler registered for the Package DB is invoked.
void beforeImport(java.lang.Object entity)

This method is invoked before importing the specified entity.

Note: Only the CallbackHandler registered for the Package DB is invoked.
Parameters:
  • entity – the Mobile Business Object to be imported.
void onMessageStart(int size, String method, String mbo);
This method is called at the beginning of processing a message from the server, before the message transaction starts. Only the callback handler registered with the package database class is invoked. Parameters:
  • size – The size of the incoming message content in bytes.
  • method – The method string from the message header.
  • mbo – If this message is for a specific MBO, the name of the MBO; otherwise null.

This method is for DOE-based applications only.

This code shows how to create and register a handler to receive callbacks:

public class MyCallbackHandler extends DefaultCallbackHandler
{
    // implementation
}

CallbackHandler handler = new MyCallbackHandler();
<PkgName>DB.registerCallbackHandler(handler);
Parent topic: Callback and Listener APIs