oracle.opensync.ose

Class OSESession

java.lang.Object

oracle.opensync.ose.OSESession

All Implemented Interfaces:

OSEExceptionConstants

public class OSESession
extends java.lang.Object
implements OSEExceptionConstants

OSESession is the main class in Java Sync API for both pure java and native clients. OSESession allows setting sync parameters and options, invoking sync, canceling sync and tracking sync progress. Note that in multithreaded environment a single OSESession is not supposed to be used concurrently from multiple threads. Each thread should open its own session. The only exception is calling OSESession.cancelSync from another thread.

Example:

      String user = "JOHN";
      String pwd  = "john";
      OSESession sess = null;
      try {
        sess = new OSESession(user, pwd.toCharArray())
          sess.setURL("localhost:88");
          sess.sync();
      }
      finally {
        if (sess != null)
                sess.close();
      }
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	DIR_RECEIVE Sync direction RECEIVE Data is only received, but not sent
static int	DIR_SEND Sync direction SEND Data is only sent, but not received
static int	DIR_SENDRECEIVE Sync direction SENDRECEIVE Bidirectional sync, this is the default
static int	ENC_AES Encryption type AES, this is the default
static int	ENC_NONE No encryption
static int	ENC_SSL Encryption type SSL Uses HTTPS protocol, so the data will go through secure sockets
static int	PRIO_DEFAULT Normal data priority
static int	PRIO_HIGH High data priority
static int	PRIO_LOWEST
static int	TR_HTTP Transport type HTTP, this is the default
static int	TR_USER Transport type USER Data is transfered by custom transport provided by application

Fields inherited from interface oracle.opensync.ose.OSEExceptionConstants

CONFIG_LOAD_ERROR, CONFIG_SAVE_ERROR, CONNECTION_TO_SRV_FAILED, DATABASE_NOT_FOUND, EMPTY_PASSWORD, EMPTY_USER, ENCRYPTION_ID_MISMATCH, ERR_CREDENTIALS, ERROR_RESUME_RECEIVE, ERROR_RESUME_SEND, HTTP_RESPONSE, HTTP_TRANSPORT_ERROR, INTERNAL_ERROR, INVALID_BUFFER, INVALID_DML_TYPE, INVALID_ENCR_VER, INVALID_ENCRYPTION_TYPE, INVALID_HANDLE, INVALID_HTTP_URL, INVALID_INT_OPT, INVALID_OPCODE, INVALID_PLUGIN_FLAGS, INVALID_PRIORITY, INVALID_SESS, INVALID_STR_OPT, INVALID_STRING_LENGTH, INVALID_SYNC_DIRECTION, INVALID_TRANSPORT_TYPE, MISSING_DEFAULT_DATABASE, MISSING_PLUGIN_API, NOT_SUPPORTED, OPCODE_LENGTH_OVERRUN, OPCODE_LENGTH_UNDERRUN, OPCODE_OUT_OF_SEQUENCE, PASSWORD_NOT_SPECIFIED, PLUGIN_CLASS_INIT_FAILED, PLUGIN_CLASS_NOT_FOUND, PLUGIN_EXCEPTION, PLUGIN_ID_NOT_FOUND, PUBLICATION_ID_MISMATCH, PUBLICATION_ID_NOT_FOUND, PUBLICATION_NOT_FOUND, SERVER_ERROR, SNAP_NAME_NOT_FOUND, SNAPSHOT_ID_EXISTS, SNAPSHOT_ID_NOT_FOUND, SYNC_CANCELED, SYNC_UNAVAILABLE, TRANS_NOT_FOUND, UNCOMPRESSED_DATA, UNEXP_TERM_OPCODE, UNEXPECTED_BLOB_DATA, UNEXPECTED_OPCODE, UNINIT_USER_TRANSPORT, UNRECOGNIZED_DATA, USER_NOT_SPECIFIED, USER_TRANSPORT_ERROR

Constructor Summary

Constructors

Constructor and Description
OSESession() Empty constructor.
OSESession(java.lang.String user) Sync session constructor for a user.
OSESession(java.lang.String user, char[] pwd) Sync session constructor for a user.

Method Summary

Methods

Modifier and Type	Method and Description
void	addProgressListener(OSEProgressListener pl) Add progress listener
void	cancelSync() Attempts to cancel the sync from another thread.
void	close() Closes the session and releases its resources It's expected that before application exists, it calls this function.
java.lang.String	getAppRoot() Gets current root location
boolean	getBackground() Gets a flag which indicates whether sync should be background The default is false, indicating foreground sync.
boolean	getEncryptDatabases() Gets the current value of encrypt databases flag
int	getEncryptionType() Gets current encryption type.
boolean	getForceRefresh() Gets current value set by setForceRefresh(boolean)
java.lang.String	getProxy() Returns current http proxy.
boolean	getSavePassword() Gets the boolean flag set by setSavePassword(boolean) The default is false.
boolean	getSyncApps() Gets a flag that indicates whether sync should download a list of application/client updates so they can later be installed.
int	getSyncDirection() Gets the current sync direction set by setSyncDirection(int) The default is DIR_SENDRECEIVE.
boolean	getSyncNewPub() Gets current value set by setSyncNewPub(boolean)
int	getSyncPriority() Gets sync priority The default is PRIO_DEFAULT.
int	getTransportType() Gets current sync transport type
java.lang.String	getURL() Returns current mobile server URL.
boolean	getUseFiles() Gets the current UseFiles value setUseFiles(boolean)
java.lang.String	getUser() Gets current sync user name
boolean	getUseResume() Gets the current UseResume value setUseResume(boolean)
static void	logError(java.lang.Exception e)
void	removeProgressListener(OSEProgressListener pl) Remove progress listener
void	saveUser() Saves user information in OSE meta files.
void	selectPub(java.lang.String name) Adds publication to the list of publications to be synchronized selectively
void	setAppRoot(java.lang.String appRoot) Allows specification of the root directory for various internal sync files as well as database files
void	setBackground(boolean on) Sets a flag which indicates whether sync should be background
static void	setDBFactory(oracle.opensync.db.DBFactory f)
void	setEncryptDatabases(boolean on) Enables database encryption for new databases created during sync.
void	setEncryptionType(int type) Sets sync encryption type to one of: ENC_AES, ENC_SSL or ENC_NONE
void	setForceRefresh(boolean on) To wipe out all of client's data and replace it with server's data, set this to true.
void	setNewPassword(char[] pwd) Allows clients to modify their password.
void	setPassword(char[] pwd) Sets sync user password
void	setProgress(OSEProgressListener p) Set sync progress listener
void	setProxy(java.lang.String proxy) Sets current http proxy.
void	setSavePassword(boolean on) Sets the flag for persistently saving user password.
void	setStartSyncAgent(boolean on) Sets a flag which indicates whether to start the Sync Agent upon sync completion
void	setSyncApps(boolean on) Sets a flag that indicates whether application/client updates should be downloaded during sync
void	setSyncDirection(int dir) Sets the sync direction.
void	setSyncNewPub(boolean on) Sets flag for enabling synchronization of new publications.
void	setSyncPriority(int prio) Sets sync priority.
void	setTransportType(int type) Sets current transport type.
void	setURL(java.lang.String url) Sets HTTP URL of the mobile server
void	setUseFiles(boolean on) Enables switching between streaming and using files to transport synchronization data.
void	setUseResume(boolean on) Enables using resume functionality, which will attempt to resume sending or receiving data during sync in light of network failure.
void	setUserTransport(OSETransport t) Sets custom user-defined transport for sync
void	shareConnection(java.lang.String dbName, java.lang.Object connObj) Provides database connection handle from the application to use in OSE engine, instead of engine opening its own database connection, which is default.
void	sync() Performs sync.

Methods inherited from class java.lang.Object

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

Field Detail

DIR_RECEIVE

public static final int DIR_RECEIVE

Sync direction RECEIVE Data is only received, but not sent

See Also:

Constant Field Values

DIR_SEND

public static final int DIR_SEND

Sync direction SEND Data is only sent, but not received

See Also:

Constant Field Values

DIR_SENDRECEIVE

public static final int DIR_SENDRECEIVE

Sync direction SENDRECEIVE Bidirectional sync, this is the default

See Also:

Constant Field Values

ENC_AES

public static final int ENC_AES

Encryption type AES, this is the default

See Also:

Constant Field Values

ENC_NONE

public static final int ENC_NONE

No encryption

See Also:

Constant Field Values

ENC_SSL

public static final int ENC_SSL

Encryption type SSL Uses HTTPS protocol, so the data will go through secure sockets

See Also:

Constant Field Values

PRIO_DEFAULT

public static final int PRIO_DEFAULT

Normal data priority

See Also:

Constant Field Values

PRIO_HIGH

public static final int PRIO_HIGH

High data priority

See Also:

Constant Field Values

PRIO_LOWEST

public static final int PRIO_LOWEST

See Also:

Constant Field Values

TR_HTTP

public static final int TR_HTTP

Transport type HTTP, this is the default

See Also:

Constant Field Values

TR_USER

public static final int TR_USER

Transport type USER Data is transfered by custom transport provided by application

See Also:

Constant Field Values

Constructor Detail

OSESession

public OSESession()
           throws OSEException

Empty constructor. If the last sync client info was saved, the session will be initialized with the saved info.

Throws:

OSEException - if last user was not saved or error occurred loading user info

OSESession

public OSESession(java.lang.String user)
           throws OSEException

Sync session constructor for a user. If the user's info was saved, the session will be initialized with the saved info. If the password was not saved, it can be set later by setPassword(char [])

Parameters:

user - sync user name

Throws:

OSEException - if error occurred loading user info

OSESession

public OSESession(java.lang.String user,
          char[] pwd)
           throws OSEException

Sync session constructor for a user. If the user's info was saved, the session will be initialized with the saved info.

Parameters:

user - sync user name

pwd - sync user password

Throws:

OSEException - if error occured loading user info

Method Detail

addProgressListener

public void addProgressListener(OSEProgressListener pl)

Add progress listener

Parameters:

pl - progress listener

See Also:

OSEProgressListener

cancelSync

public void cancelSync()
                throws OSEException

Attempts to cancel the sync from another thread. It's a non-blocking call that works on best-effort basis. If cancel is successful, the sync thread throws OSEException with error code OSEExceptionConstants.SYNC_CANCELED

Throws:

OSEException - if IO error has occurred

close

public void close()
           throws OSEException

Closes the session and releases its resources It's expected that before application exists, it calls this function.

Throws:

OSEException - if error occurred closing database connections

getAppRoot

public java.lang.String getAppRoot()

Gets current root location

Returns:

String current root location

See Also:

setAppRoot(String)

getBackground

public boolean getBackground()

Gets a flag which indicates whether sync should be background The default is false, indicating foreground sync.

Returns:

true if background, false if foreground

getEncryptDatabases

public boolean getEncryptDatabases()

Gets the current value of encrypt databases flag

Returns:

boolean

See Also:

setEncryptDatabases(boolean)

getEncryptionType

public int getEncryptionType()

Gets current encryption type. setEncryptionType(int) The default is ENC_AES.

Returns:

{ENC_AES | ENC_SSL | ENC_NONE}

getForceRefresh

public boolean getForceRefresh()

Gets current value set by setForceRefresh(boolean)

Returns:

boolean

getProxy

public java.lang.String getProxy()

Returns current http proxy.

Returns:

http proxy or null if no proxy is used

See Also:

setProxy(String)

getSavePassword

public boolean getSavePassword()

Gets the boolean flag set by setSavePassword(boolean) The default is false.

Returns:

boolean flag set by setSavePassword(boolean)

See Also:

setSavePassword(boolean)

getSyncApps

public boolean getSyncApps()

Gets a flag that indicates whether sync should download a list of application/client updates so they can later be installed. The default is false.

Returns:

true or false

getSyncDirection

public int getSyncDirection()

Gets the current sync direction set by setSyncDirection(int) The default is DIR_SENDRECEIVE.

Returns:

{DIR_SENDRECEIVE | DIR_SEND | DIR_RECEIVE}

See Also:

setSyncDirection(int)

getSyncNewPub

public boolean getSyncNewPub()

Gets current value set by setSyncNewPub(boolean)

Returns:

boolean

getSyncPriority

public int getSyncPriority()

Gets sync priority The default is PRIO_DEFAULT.

Returns:

sync priority

getTransportType

public int getTransportType()

Gets current sync transport type

Returns:

TR_HTTP, TR_USER The default is TR_HTTP.

See Also:

setTransportType(int)

getURL

public java.lang.String getURL()

Returns current mobile server URL.

Returns:

mobile server url

See Also:

setURL(String)

getUseFiles

public boolean getUseFiles()

Gets the current UseFiles value setUseFiles(boolean)

Returns:

boolean

getUser

public java.lang.String getUser()

Gets current sync user name

Returns:

String

getUseResume

public boolean getUseResume()

Gets the current UseResume value setUseResume(boolean)

Returns:

boolean

logError

public static void logError(java.lang.Exception e)

removeProgressListener

public void removeProgressListener(OSEProgressListener pl)

Remove progress listener

Parameters:

pl - progress listener

See Also:

OSEProgressListener

saveUser

public void saveUser()
              throws OSEException

Saves user information in OSE meta files.

Throws:

OSEException - if failed to save user info

selectPub

public void selectPub(java.lang.String name)
               throws OSEException

Adds publication to the list of publications to be synchronized selectively

Parameters:

name - publication name, pass null to unselect all publications and revert to normal (non-selective) sync

Throws:

OSEException - if publication with provided name was not found

setAppRoot

public void setAppRoot(java.lang.String appRoot)

Allows specification of the root directory for various internal sync files as well as database files

Parameters:

appRoot - directory string

setBackground

public void setBackground(boolean on)

Sets a flag which indicates whether sync should be background

Parameters:

on - true if background, false if foreground

See Also:

getBackground()

setDBFactory

public static void setDBFactory(oracle.opensync.db.DBFactory f)

setEncryptDatabases

public void setEncryptDatabases(boolean on)

Enables database encryption for new databases created during sync. The encryption mechanism is plugin-dependent. If plugin does not support encryption, this option has no effect. Once a database is encrypted, the engine will store this setting so that the database can be accessed later. Currently sync password serves as encryption key for all databases.

Parameters:

on - boolean true to enable encryption, false to disable

setEncryptionType

public void setEncryptionType(int type)
                       throws OSEException

Sets sync encryption type to one of: ENC_AES, ENC_SSL or ENC_NONE

Parameters:

type - encryption type

Throws:

OSEException - if invalid encryption type was provided

See Also:

getEncryptionType()

setForceRefresh

public void setForceRefresh(boolean on)

To wipe out all of client's data and replace it with server's data, set this to true. The default is false.

Parameters:

on - if true, upon sync completion, the client's data will be wiped out and replaced with server's data

setNewPassword

public void setNewPassword(char[] pwd)
                    throws OSEException

Allows clients to modify their password. Upon successful sync, client's password on the server will be changed to the new password

Parameters:

pwd - new password

Throws:

OSEException - if provided new password is blank

setPassword

public void setPassword(char[] pwd)
                 throws OSEException

Sets sync user password

Parameters:

pwd - sync password

Throws:

OSEException - if provided password is blank

setProgress

public void setProgress(OSEProgressListener p)

Set sync progress listener

Parameters:

p - OSEProgressListener

See Also:

OSEProgressListener

setProxy

public void setProxy(java.lang.String proxy)

Sets current http proxy.

Parameters:

proxy - http proxy or null if proxy is not used

setSavePassword

public void setSavePassword(boolean on)

Sets the flag for persistently saving user password. If true, the password will be saved.

Parameters:

on - boolean set to true, if the password needs to be saved.

See Also:

getSavePassword()

setStartSyncAgent

public void setStartSyncAgent(boolean on)

Sets a flag which indicates whether to start the Sync Agent upon sync completion

Parameters:

on - true if Sync Agent should be started, false if not

setSyncApps

public void setSyncApps(boolean on)

Sets a flag that indicates whether application/client updates should be downloaded during sync

Parameters:

on - true or false

See Also:

getSyncApps()

setSyncDirection

public void setSyncDirection(int dir)
                      throws OSEException

Sets the sync direction.

Parameters:

dir - sync direction

Throws:

OSEException - if invalid sync direction provided

See Also:

getSyncDirection()

setSyncNewPub

public void setSyncNewPub(boolean on)

Sets flag for enabling synchronization of new publications. If set to true, any subscribed new publications on the server will be downloaded to the client. Default = true.

Parameters:

on - boolean if true, any subscribed new publications on the server will be downloaded to the client. The default is true.

setSyncPriority

public void setSyncPriority(int prio)
                     throws OSEException

Sets sync priority.

Parameters:

prio - PRIO_DEFAULT or PRIO_HIGH

Throws:

OSEException - if invalid priority provided

See Also:

getSyncPriority()

setTransportType

public void setTransportType(int type)
                      throws OSEException

Sets current transport type.

Parameters:

type - int

TR_HTTP	default transport
TR_USER	custom transport

Throws:

OSEException - if invalid transport type provided

See Also:

getTransportType()

setURL

public void setURL(java.lang.String url)

Sets HTTP URL of the mobile server

Parameters:

url - mobile server URL for example: http://localhost:99 or https://localhost or localhost:99 or localhost (the protocol will default to http).

setUseFiles

public void setUseFiles(boolean on)

Enables switching between streaming and using files to transport synchronization data. If set to true, sync will store uploaded and downloaded data in a file, otherwise, data will be streamed. The default is false.

Note: streaming requires that the underlying client transport stack implements HTTP 1.1

Parameters:

on - boolean if true, sync will use files to store uploaded and downloaded data, otherwise, data will be streamed.

setUseResume

public void setUseResume(boolean on)

Enables using resume functionality, which will attempt to resume sending or receiving data during sync in light of network failure. This option will set UseFiles to be on (setUseFiles(boolean)), UseResume provides much more reliable transport for synchronizing data at the expense of very light performance overhead. The default is false.

Parameters:

on - boolean if true, resume functionality is enabled.

setUserTransport

public void setUserTransport(OSETransport t)

Sets custom user-defined transport for sync

Parameters:

t - user-defined transport instance, must implement OSETransport interface

See Also:

OSETransport

shareConnection

public void shareConnection(java.lang.String dbName,
                   java.lang.Object connObj)

Provides database connection handle from the application to use in OSE engine, instead of engine opening its own database connection, which is default. The connection handle is set for the duration of the session unless explicitly unset by calling shareConnection(null).

Parameters:

dbName - database name

connObj - connection object , has to be a valid connection object for particular type of database as used in OSE plugin. For native sync client, it must be an instance of java.lang.Integer or java.lang.Long encapsulating corresponding native connection handle (for example, for sqlite and BDB plugins it would be of type "sqlite3 *") For pure java sync client, it must be an instance of corresponding platform-specific database connection class: net.rim.device.api.database.Database for Blackberry client android.database.sqlite.SQLiteDatabase for Android client java.sql.Connection for SE client

Throws:

OSEException - if plugin error has occured

sync

public void sync()
          throws OSEException

Performs sync.

Throws:

OSEException - if sync has failed