oracle.opensync.syncagent

Class BGSession

java.lang.Object

oracle.opensync.syncagent.BGSession

All Implemented Interfaces:

BGExceptionConstants, BGMessageConstants

public final class BGSession
extends java.lang.Object
implements BGExceptionConstants, BGMessageConstants

This class represents background sync control APIs. It allows application to control sync agent (such as start, stop, pause and resume) as well as to get various background sync status information and also to specify custom handlers for events that occur in background sync.

Example:

      BGSession sess = new BGSession();
      try {
          sess.start();
          sess.waitForStatus(BGAgentStatus.RUNNING);
          BGAgentStatus s = sess.getAgentStatus();
          System.out.println("User name: " + s.clientId);
          sess.addMessageHandler(new MyMessageHandler());
          ...
      }
      finally {
          sess.close();
      }
 

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DISABLE_PROP

Fields inherited from interface oracle.opensync.syncagent.BGExceptionConstants

ACTIVE_CONNECTIONS_PRESENT, AGENT_DEFUNCT, AGENT_DISABLED, AGENT_NOT_RUNNING, ANOTHER_INSTANCE, CONTROL_CONNECTION_CLOSED, INVALID_COMMAND, INVALID_COND_SUBTYPE, INVALID_COND_TYPE, INVALID_DATE_FORMAT, INVALID_EVENT_SUBTYPE, INVALID_EVENT_TYPE, INVALID_NUMERIC_PARAMETER, INVALID_PARAMETER, INVALID_RULE_CLASS, INVALID_RULE_SUBTYPE, INVALID_RULE_SUBTYPE_TYPE, INVALID_RULE_TYPE, INVALID_SESSION, INVALID_STRING_PARAMETER, INVALID_WAIT_STATUS, NO_BG_PUBS, OPERATION_NOT_ALLOWED, PAUSE_FAILED, READER_CANCELED, RESUME_FAILED, SQL_RULE_MISSING_QUERY, START_FAILED, STOP_FAILED, TOO_MANY_READERS, UNSUPPORTED, WAIT_TIMEOUT

Fields inherited from interface oracle.opensync.syncagent.BGMessageConstants

AGENT_PAUSED, AGENT_RESUMED, AGENT_STARTED, AGENT_STOPPED, APPLY_FAILED, APPLY_FINISHED, APPLY_STARTED, BATTERY_LOW, COMPOSE_FAILED, COMPOSE_FINISHED, COMPOSE_STARTED, DUPLICATE_PLATFORM_DB, INTERNAL_ERROR, INVALID_SERVER_NOTIFICATION, MEMORY_LOW, NET_AUTODIAL_FAILED, NET_MANAGER_ERROR, NETWORK_CHANGED, NETWORK_EVAL, NO_NETWORK, PLAT_RULE_IN_NON_PLAT_DB, POWER_MANAGER_ERROR, RULE_EVAL_DB_LOCKED, RULE_EVAL_FAILED, RULE_LOAD_FAILED, SERVER_NOTIFICATION, SERVER_NOTIFICATION_FAILED, SYNC_FAILED, SYNC_FINISHED, SYNC_STARTED, TRACE, UNKNOWN

Constructor Summary

Constructors

Constructor and Description
BGSession() Create new session to interact with sync agent.

Method Summary

Methods

Modifier and Type	Method and Description
void	addMessageHandler(BGMessageHandler h) Add a custom message handler to sync agent
boolean	agentEnabled() Query whether sync agent is enabled.
void	close() Close the session and release all the resources used by the session.
void	enableAgent(boolean on) Enable or disable sync agent.
BGAgentStatus	getAgentStatus() Get current sync agent status information.
int	getAgentStatusCode() Get current sync agent status code constant.
BGException	getFatalError() If sync agent is in state DEFUNCT, retrieve the error information that caused the bad internal state.
BGSyncStatus	getSyncStatus() Get current status of sync within sync agent
void	pause() Pause sync agent.
void	removeMessageHandler(BGMessageHandler h) Remove a custom message handler to sync agent
void	resume() Resume sync agent.
void	showUI() Bring up sync agent UI.
void	start() Start sync agent.
void	stop() Stop sync agent.
void	waitForStatus(int statusCode) Wait for sync agent to reached specified status.
boolean	waitForStatus(int statusCode, long timeOut) Wait for sync agent to reach specified status.

Methods inherited from class java.lang.Object

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

Field Detail

DISABLE_PROP

public static final java.lang.String DISABLE_PROP

See Also:

Constant Field Values

Constructor Detail

BGSession

public BGSession()
          throws BGException

Create new session to interact with sync agent. Does not automatically start sync agent.

Throws:

BGException - - if the session could not be established

Method Detail

addMessageHandler

public void addMessageHandler(BGMessageHandler h)
                       throws BGException

Add a custom message handler to sync agent

Parameters:

h - - a message handler object of a class that implements BGMessageHandler interface

Throws:

BGException - - if sync agent is not running

agentEnabled

public boolean agentEnabled()
                     throws BGException

Query whether sync agent is enabled. The enabled/disabled setting is stored in ose.ini configuration file. When sync agent is disabled, it is not allowed to start. This setting can be used when only foreground sync is desired. Use enableAgent(boolean) to change this setting.

Returns:

true if enabled, false if disabled

Throws:

BGException - - if ose.ini file could not be read

close

public void close()

Close the session and release all the resources used by the session.

enableAgent

public void enableAgent(boolean on)
                 throws BGException

Enable or disable sync agent. This setting is stored in ose.ini configuration file. When sync agent is disabled it is not be allowed to start. This setting can be used when only foreground sync is desired. Use agentEnabled() to query the current setting

Parameters:

on - - true to enable, false to disable

Throws:

BGException - - if ose.ini file could not be modified

getAgentStatus

public BGAgentStatus getAgentStatus()
                             throws BGException

Get current sync agent status information.

Returns:

sync agent status object

Throws:

BGException - - if the status could not be obtained

See Also:

BGAgentStatus

getAgentStatusCode

public int getAgentStatusCode()
                       throws BGException

Get current sync agent status code constant.

Returns:

status code

Throws:

BGException - - if the status code could not be obtained

See Also:

BGAgentStatus

getFatalError

public BGException getFatalError()
                          throws BGException

If sync agent is in state DEFUNCT, retrieve the error information that caused the bad internal state.

Returns:

BGException with the fatal error or null if sync agent is not in state DEFUNCT

Throws:

BGException - - if error occurred while retrieving information

See Also:

BGAgentStatus

getSyncStatus

public BGSyncStatus getSyncStatus()
                           throws BGException

Get current status of sync within sync agent

Returns:

sync status object

Throws:

BGException - - if the sync status could not be obtained

See Also:

BGSyncStatus

pause

public void pause()
           throws BGException

Pause sync agent. If the agent is already paused or being paused this call has no effect. This call is asynchronous, it does not wait for sync agent to be paused before returning. Use waitForStatus(int, long) to wait for sync agent.

Throws:

BGException - - if sync agent is not in the state RUNNING, PAUSED, or PAUSE_PENDING.

See Also:

BGAgentStatus

removeMessageHandler

public void removeMessageHandler(BGMessageHandler h)
                          throws BGException

Remove a custom message handler to sync agent

Parameters:

h - - a message handler object of a class that implements BGMessageHandler interface. If the handler h was not previously added to sync agent via addMessageHandler(oracle.opensync.syncagent.BGMessageHandler), this call has no effect.

Throws:

BGException - - if sync agent is not running

resume

public void resume()
            throws BGException

Resume sync agent. If the agent is aready running, starting, or resuming this call has no effect. This call is asynchronous, it does not wait for sync agent to be resumed before returning. Use waitForStatus(int, long) to wait for sync agent.

Throws:

BGException - - if sync agent is not in the state PAUSED, RESUME_PENDING, START_PENDING or RUNNING.

See Also:

BGAgentStatus

showUI

public void showUI()
            throws BGException

Bring up sync agent UI. Normally sync agent is running as background application. This call will bring it in the foreground and show UI which allows to see various statistics and to control sync agent. The UI is a part of sync agent application so it can only be present after sync agent is started. User can manually hide the UI.

Throws:

BGException - - if sync agent is stopped or internal error has occurred

start

public void start()
           throws BGException

Start sync agent. If the agent is aready running, starting, or resuming this call has no effect. If the agent is paused, this call with resume the agent. This call is asynchronous, it does not wait for sync agent to be started before returning. Use waitForStatus(int, long) to wait for sync agent.

Throws:

BGException - - if sync agent is not in the state STOPPED, START_PENDING, RUNNING, PAUSED or RESUME_PENDING (that is the agent is in the state PAUSE_PENDING or STOP_PENDING), or if sync agent is disabled

See Also:

BGAgentStatus, agentEnabled()

stop

public void stop()
          throws BGException

Stop sync agent. If the agent is aready stopped or stopping this call has no effect. This call is asynchronous, it does not wait for sync agent to be stopped before returning. Use waitForStatus(int, long) to wait for sync agent.

Throws:

BGException - - if sync agent is not in the state RUNNING, PAUSED, STOPPED or STOP_PENDING.

See Also:

BGAgentStatus

waitForStatus

public void waitForStatus(int statusCode)
                   throws BGException,
                          java.lang.InterruptedException

Wait for sync agent to reached specified status. Same as {link #waitForStatus(int, long)} but with unlimited timeout.

Parameters:

statusCode - - status to wait for

Throws:

BGException

java.lang.InterruptedException

waitForStatus

public boolean waitForStatus(int statusCode,
                    long timeOut)
                      throws BGException,
                             java.lang.InterruptedException

Wait for sync agent to reach specified status.

Parameters:

statusCode - - the status to wait for. Only RUNNING, PAUSED or STOPPED are accepted.

timeOut - - maximum time to wait for in milliseconds

Returns:

true if the agent has reached specified status, false if the timeout has occured.

Throws:

BGException - - if the statusCode parameter is not one of the values above

java.lang.InterruptedException - - if the current thread was interrupted

See Also:

BGAgentStatus