Server IDL Interface Definition

Table Of Contents

Server IDL Interface Definition

Server IDL Interface Definition

---

This appendix contains the WANDEST IDL interface definition.

/*

 * The following are versions for each interface that this module

 * contains. Client must have the same major version code with the server.

 */

#pragma version WanDest::Admin 2.4

#pragma version WanDest::Server 2.4

#pragma version WanDest::Maint 2.4

/**

 * A module defining WanDest (WAN Data Extraction & Synchronization Tool)

 * service interface.

 */

module WanDest {

	/**

	 * Represents exception that can be thrown by Server

	 */

	exception Exception {

		enum Type {

			UnknownTable,

			UnknownColumn,

			UnknownKeys,

			InvalidType,

			InvalidLength,

			UnknownProcedure,

			DiskSpaceLow,

			UnloadFailed,

			NewUnloadFailed,

			DelUnloadFailed,

			CompressFailed,

			FtpLoginFailed,

			FtpFailed,

			TarFailed,

			FullUploadRequired,

			SynchExpired,

			SystemError,

			DatabaseError,

			CwmColdStarting,

			NoSuchServer,

			NoMoreThreads,

			UnsupportedType,

			EmptyTableList,

			EmptyKeyValues,

			EmptyParameterList,

			UnknownParameterType,

			UnknownException,

			InvalidFileDescriptor,

			SubsystemException,

			InternalError,

			ConnectionLost,

			TableLocked

		} errType;

		string errMsg;

	};

	/**

	 * Database column types

	 */

	enum ColumnType

	{

		Integer,

		SmallInt,

		CharString,

		Float,

		SmallFloat,

		Date,

		DateTime,

		VarCharString

	};

	/**

	 * Column Values

	 * The date format must be "%m/%d/%Y"

	 * The date time format must be "%Y-%m-%d %H:%M:%S"

	 * %Y = four digit year

	 * %m = two digit month

	 * %d = two digit day

	 * %H = two digit hour

	 * %M = two digit minute

	 * %S = two digit second

	 */

	typedef union ColumnDataUnion switch (ColumnType)

	{

		case Integer:	 long	intValue;

		case SmallInt:	 short	smallIntValue;

		case CharString: string		stringValue;

		case Float:	 double	floatValue;

		case SmallFloat: float		smallFloatValue;

		case Date:	 string 	dateValue;

		case DateTime:	 string 	dateTimeValue;

	} ColumnData;

	/**

	 * Database column definition

	 */

	struct Column {

		string			columnName;

		ColumnType		columnType;

		short			columnLength;

	};

	/**

	 * List of Column

 	 */

	typedef sequence<Column>	ColumnList;

	/**

	 * Unique key definition

	 */

	typedef sequence<Column>	Keys;

	/**

	 * List of keys

	 */

	typedef sequence<Keys>		KeysList;

	/**

	 * Database table definition

	 */

	struct Table {

		string			tableName;

		KeysList		keyList;

		ColumnList		columnList;

	};

	/**

	 * Database schema information

	 */

	typedef sequence<Table> 	Schema;

	/**

	 * Database table name list

	 */

	typedef sequence<string>	TableNameList;

	/**

	 * Column Value 

	 */

	struct ColumnValue {

		string			columnName;

		ColumnType		columnType;

		ColumnData		columnValue;

	};

	/**

	 * List of column values used for Real-time updates.

	 */

	typedef sequence<ColumnValue>	ColumnValueList;

	/**

	 * Value - no name

	 */

	struct Value {

		ColumnType		valueType;

		ColumnData		value;

	};

	/**

	 * List of column values used for Real-time updates.

	 */

	typedef sequence<Value>		ValueList;

	/**

	 * A table that client has requested for 

	 * a full upload, incremental updates and real time updates.

	 */

	struct TableSpec

	{

		string			tableName;

		Keys			rowKeys;

		ColumnList		columnList;

		string			whereClause;

	};

	/**

	 * A list of table that client has requested for 

	 * a full upload, incremental updates and real time updates.

	 */

	typedef sequence<TableSpec>	TableSpecList;

	/**

	 * Request specification.

	 * The frpUserName and ftpPassword is necessary for

	 * the server to ftp the full upload and incremental updates.

	 * The delimiter is the character that the ascii data file

	 * must used.  If it is empty, by default "|" will be used.

	 */

	struct Request

	{

		string 			ftpUserName;

		string 			ftpPassword;

		string			delimiter;

		TableSpecList		tableSpecList;

		boolean			returnOneTarFile;

	};

	/**

	 * List of the names of the files ftp-ed to the client side 

	 */

	typedef sequence<string>	FileNameList;

	/**

	 * Registration information.

	 * Used when client creates a new server.

	 */

	struct RegistrationInfo

	{ 

		string 			hostName;

		string 			applicationName;

	};

	/**

	 * Version Information

	 * The IDLVersion is a string containing a concatenations of

	 * the interfaces versions separated by ":"

	 */

	struct Versions {

		string CWMVersion;

		string WANDESTVersion;

		string IDLVersion;

	};

	/**

	 * Server object that provides Full Upload, Incremental Updates and

	 * Real-Time Updates services to a particular client.

	 * An instance of this object is created, when client invokes

	 * WanDest::Admin.register() method.

	 */

	interface Server

	{

		/**

		 * Get a full upload for table(s) specified by a_request.

		 * The data will be returned in an ascii format

		 * with column data for each row separated by delimiter character

		 * specified in the request.  Each row will contain key values

		 * followed by the column values in the order specified

		 * in the request.

		 *

		 * Full upload data will be put using ftp from server

		 * to client within this call.  The file names of

		 * the files sent are returned in a_outfile_list.

		 * Request for two different set of tables can be

		 * called concurrently.

		 *

		 * The starting time of this process is marked as the

		 * last sync time.  This time will be used by 

		 * incremental updates interface.

		 */

		void	getFullUpload (	in Request a_request,

					in string a_path,

					out FileNameList a_outfile_list

		) raises (Exception);

		/**

		 * Get incremental updates for table(s) specified by a_request

		 * since the last sync time which signifies one of the 

		 * following events:

		 * 1. last successful full upload,

		 * 2. last successful incremental updates,

		 *

		 * The data will be returned in an ascii format

		 * with column data for each row separated by delimiter character

		 * specified in the request. Each row will contain key values

		 * followed by the column values in the order specified

		 * in the request.

		 *

		 * Data will be put using ftp from server

		 * to client within this call.  The file names of

		 * the files sent are returned in a_outfile_list.

		 * Request for two different set of tables can be

		 * called concurrently. 

		 * If the elapsed time since the last sync time 

		 * exceeds the maximum allowable sync time period,

		 * (this is a configurable server parameter)

		 * an FullUploadRequired exception will be thrown.

		 */

		void	getUpdates (	in Request a_request,

					in string a_path,

					out FileNameList a_outfile_list

		) raises (Exception);

		/**

		 * Reverts sync time of tables in a_table_list to previous last sync time.

		 * If called more than once the subsequent calls following the first call 

		 * is a no-op.

		 * This can be used for error recovery and redundant system.

		 */

		void revertSyncTime ( 	in TableNameList a_tabname_list

		) raises (Exception);

		/**

		 * Wait for the insertion of a row of data (specified by

		 * a_key_values) in the specified table.

		 * Returns true and the requested columns if the row is found

		 * within a_timeout_val.

		 * Returns false otherwise.

		 */

		boolean	waitForRowInsertion (

					in string a_table,

					in ColumnList a_column_list,

					in ColumnValueList a_key_values,

					in short a_timeout_val,

					out ColumnValueList a_row_values

		) raises (Exception);

		/**

		 * Gets a row of data using stored procedure that takes

		 * parameters and returns exactly one row of data.

		 * Returns true a row is returned by the store procedure

		 * Returns false otherwise.

		 */

		boolean invokeStoredProc (

					in string a_proc_name,

					in ValueList a_input_param,

					out ValueList a_row_values

		) raises (Exception);

		/**

		 * Marks the last sync time of a_table_list to 

		 * current-time - STANDBY_LAGTIME 

		 * Where STANDY_LAGTIME is a server parameter that

		 * defines the window of time in which WANDEST servers

		 * used in redundant set may be out of sync.

		 */

		void markSyncTime ( 	in TableNameList a_tabname_list

		) raises (Exception);

	};

	/**

	 * Admin object that provides methods for 

	 * registering and deregistering.

	 * One instance of this object will be created per WANCV.

	 */

	interface Admin

	{

		/**

		 * Returns the version informations

		 */

		Versions getVersion() raises (Exception);

		/**

		 * Registers to WANDEST.  This will create a new persistent

		 * WanDest server for the client or return an existing one.

		 *

		 * The marker_name of the server is:

		 * "<client_host_name>.<client_application_name>"

		 */

		Server 	register ( 

					in RegistrationInfo a_reg_info

		) raises (Exception);

		/**

		 * Deregisters from WANDEST.  This will delete a WanDest server.

		 * Use this only if client no longer need WANDEST services.

		 */

		void 	deregister ( 

					in Server a_wd_server

		) raises (Exception);

		/**

		 * Returns database schema

		 */

		Schema getSchema () raises (Exception);

		/**

		 * Returns schema for a select tables

		 */

		Schema getTableSchema (

					in TableNameList a_tabname_list

		) raises (Exception);

		/**

		 * Validates the schema specified by the request 

		 */

		void validateSchema ( 

					in TableSpecList a_tabspec_list

		) raises (Exception);

	};

	/**

	 * A list of strings describing the status of the request.

	 */

	typedef sequence<string>	RequestLog;

	/**

	 * A list of strings describing all WANDEST thread activities

	 */

	typedef sequence<string>	ThreadActivities;

	/**

	 * Maintenance object that provides methods for maintenance

	 * and run-time diagnosis.

	 * One instance of this object will be created per WANCV.

	 */

	interface Maint

	{

		/**

		 * Returns the last <n> requests made to WanDest::Admin and

		 * WanDest::Server objects.

		 */

		RequestLog	getRequestLog() raises (Exception);

		/**

		 * Returns the activities of all WanDest threads

		 */

		ThreadActivities 	getThreadActivities() raises (Exception);

		/**

		 * Cancel the thread that is processing a full upload or incremental 

		 * update request.

		 * (NOTE: Due to what seems to be a Solaris/compiler bug, this 

		 * function is disabled. If the thread hangs because of the unload, 

		 * compress or ftp process, just kill the process.)

		 */

		void cancelThread ( 

					in long a_thread_id 

		) raises (Exception);

		/**

	 	 * Sets the logging level to n

		 */

		void setLogLevel (

					in short level

		) raises (Exception);

	};

};