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. This method is for DOE-based applications only.
  3. 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:
  1. This method is for DOE-based application only.
  2. Only the CallbackHandler registered for package DB will be invoked.
void onLoginSuccess()

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

Note:
  1. Only the CallbackHandler registered for package DB is invoked.
  2. This method is for DOE-based application only.
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:
  1. CallbackHandlers registered for both the MBO class of the entity and the Package DB are invoked.
  2. This method is for DOE-based application only.
Parameters:
  • entity – the back-end search object.
void onSearchSuccess(java.lang.Object entity)

This method is invoked when a back end search succeeds.

Note:
  1. CallbackHandlers registered for both the MBO class of the entity and the Package DB are invoked.
  2. This method is for DOE-based application only.
Parameters:
  • entity – the back-end search object.
void onSubscribeFailure()

This method is invoked when subscribe fails.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onSubscribeSuccess()

This method is invoked when subscribe succeeds.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
int onSynchronize(GenericList<SynchronizationGroup> groups, SynchronizationContext context)

This method is invoked at different stages of the synchronization. The status of the synchronization context 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:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onSuspendSubscriptionSuccess()

This method is invoked when suspend subscription succeeds.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onResumeSubscriptionFailure()

This method is invoked when resume subscription fails.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onResumeSubscriptionSuccess()

This method is invoked when resume subscription succeeds.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onUnsubscribeFailure()

This method is invoked when unsubscribe fails.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onUnsubscribeSuccess()

This method is invoked when unsubscribe succeeds.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
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:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
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:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onResetSuccess()

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

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onRecoverSuccess()

This method is invoked when recover succeeds.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onRecoverFailure()

This method is invoked when recover fails.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onSubscriptionEnd()

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

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void onImportSuccess()

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

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
void beforeImport(java.lang.Object entity)

This method is invoked before importing the specified entity.

Note:
  1. Only the CallbackHandler registered for the Package DB is invoked.
  2. This method is for DOE-based application only.
Parameters:
  • entity – the Mobile Business Object to be imported.

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