DataPortal Application Client
The DataPortal Application client resides permanently on a host computer, so, unlike the DataPortal Applet client, it must be explicitly installed. Once installed, it can be started by explicitly running the startup script or via the desktop or desktop menu, as appropriate. When the Application starts, a graphical interface is displayed (see Figure 1).

The Application graphical interface consists of three main tabbed areas: "Transfers", "Console", and "Listeners", each can be selected by mouse cliking on the approprate tab. The Transfers area is used for defining and managing DataPortal transfer definitions. The Console area shows static information and dynamic status of transfers in progress. The Listeners area is used to control HTTP/SSL listeners for programatic control of data transfers.

Transfer Definitions
The DataPortal Application client can perform manual transfers, similar to the Applet client, however it has additional features and capabilities. To perform a transfer (manual or otherwise) as in the Applet case, a transfer is defined by specifying the DataPortal source and a target Database. However, the Application is also capbable of naming, saving, retrieving and deleting transfer definitions for future use. The Transfers area is used for both definition and management of transfer definitions.

The Source and Destination areas are similar to their Applet counterparts. A transfer requires the specification of both source and destination. A full description of the source includes the DataPortal source host (and a port, if required), the published DataSource on the selected host,  user/password (if required) and information about the protocol to be used - standard HTTP or encrypted HTTPS/SSL with certificate information. Destination information defines a standard target database as well as the name of the database that will hold the newly transferred business data.

Source Section
The topmost section is used to specify the Data  Source. The host and port (if any) is filled in with the originating DataPortal host information. The host and port values are separaed by a ":" (e.g. localhost:8080). A drop down list is populated with available Data Sources published to the selected DataPortal server and any of the Data Sources can be selected for transfer. If the selected Data Source requires a User and Password for access, they may be entered in the appropriate fields below the Data Source menu. If the selected Data Source does not require a User and Password, the corresponding fields will not be editable.

The specified Data transfer can be performed over a standard Web (HTTP) channel (the default), or a secure, encrypted, HTTPS/SSL channel. The secure SSL transfer not only encrypts data so it can not be understood if it is intercepted, it also requires that the server be correctly identified before a transfer can occur. This is done
by acquiring the server's Certificate (in a separate process) and installing it in a Keystore file on the client host. If a secure transfer is selected, the Keystore file that contains the necessary Certificate(s) must be specified in the HTTP/HTTPS area above the "Source Host" field. Multiple Certificates may be stored in a single Kestore file.

It is recommended that a single Keystore file containing Certificates for all hosts
involved in secure (HTTPS/SSL) transfers, for a given DataPortal session, be used.

Destination Section
The destination section specifies a database that will be the target of the data transfer. To configure your target database, you must have sufficient privileges to update data. If the Web browser you are using is not on the same computer as the target database, you will need to have remote (network) access through whatever firewalls are between the two computers. For information on using specific Database systems, see: Database System Info.
 
A database vendor type can be selected from a drop-down menu containing a list of the supported vendor databases. In some cases, it may be necessary to specify a major version level (e.g. IBM DB2 requires selection of either 7* or 8*, where the "*" includes all minor versions). Notes for the selected vendor database will appear in the "Info" area. These notes may include whether the selected vendor database requires an initial database to make a connection, default port number, and requirements for users etc

The host where the target RDBMS system is installed is entered into the "Destination Host" field. The user/password information, if required by the target database, is entered in the next two fields. Some database systems require that an existing database be specified in order to make a connection. This database, if required, is specified in the "Initial DB" field. Finally, the name of the database that will be the target of the transfer is entered in the "Destination DB" field. If the Destination DB is different from the Initial DB, the Initial DB will not be changed. If the Destination DB does not exist, it will be created, then popluated. If it does exist, all existing data will be removed and replaced with the new transfer data.


Figure 1) Application grapical interface for defining, managing, initiating and monitoring data transfers.


The fields used to define a DataPortal transfer are summarized in the tables below:

DataPortal Transfer Source Fields
HTTP/SSL:
Type of protocol used for data transfer. HTTP is the standard Web protocol and is the default. The HTTP protocol is not encrypted, so intercepted data may be understood. SSL is an encrypted Web protocol that protects data if it is intercepted. It also requires verifying the identity of the DataPortal server, so a Keystore file containing Certificates of any DataPortal servers that will be accessed through SSL must be provided. (Not necessary if HTTP protocol is to be used).
Source Host:
The DataPortal host with the published DataSources of interest. If the default Web port (usually 80) is used, no port needs to be specified. If a port needs to be specified, it is entered after the host name with a ":" delimiter (e.g. localhost:8080). The host/port info of the server where the client Applet originated will be initially set.
DataPortal DataSource:
A list of DataSources published to the selected DataPortal server. One (and only one) should be selected.
User Name, Password:
User name / password pair needed to gain access to the selected DataPortal DataSource, if required. If not required, fields should not be editable.


DataPortal Transfer Destination Fields
DB Vendor Type:
Select the DB vendor type from a drop down menu populated with the available choices. In some cases, a version number may need to be selected.
Destination Host:
The computer that your destinaton Database system is installed on (e.g. localhost is the standard name for the computer you are running your browser on).
User Name, Password:
User name / password pair needed to access the destination Database system. The user should have sufficient permission to create tables and write to them.
Initial DB:
Some Database systems require that a specific Database be specified to gain access to the Database system. If so, then the Database name should be entered. If it is not the Database specified as the Destination DB, no changes will be made to the Intial DB and it need not contain any data. If no Initial DB is required for a connection, this field may be left blank. See the DB specific notes in the "Info" area.
Destination DB:
This is the target Database where the data to be transferred will be inserted. In some cases (depending on the type of Database System used), a new Database may be created. Some Database systems will require that an already existing Database be updated. In those cases, a new, empty Database System must be created before a transfer can occur. This can be used (and reused) as the Destination DB. If an already existing Database is to be updated, no Initial DB need be specified.

Info/Status Section (Console Tabbed Area)
Static information (Info) and dynamic status (Status) areas are contained in the main Console tabbed area, which can be selected by mouse clicking on the "Console" tab. In some cases, the Console area is also selected automatically by depending on current activity (e.g. - the start of a transfer will display progress within the Console are).
 
Static background information (such as notes on different vendor Database systems) is displayed in the "Info" text area. When a Database vendor is selected from the "DB Vendor Type" menu, corresponding notes are displayed in the Info text area. Dynamic information, such as progress of a data transfer, is displayed in the "Status" area. The displayed view can be selected with the tabs in the upper left of the Info/Status area. Sometimes, one or the other view will be selected based on context, such as the start of a data transfer. The "Clear Status" button will clear the Status text area but will not affect the Info area.

Starting the Transfer
Once all the information required to define the DataPortal transfer has been entered, the "TRANSFER NOW" button may be activated. This will initiate the data transfer process. Data will be retrieved from the DataPortal server and will be put into the specified destination Database. A new database will be created, as needed. The structure will be built (including tables, table columns, primary keys, and foreign keys) and the retrieved data will be used to populate the Database. A current "snapshot" of the selected DataPortal DataSource will be created in the target Database. All existing tables in the destination database will be deleted before the database is populated with new tables and data.

Transfer progress may be monitored in the Info/Status area. As the data transfer process proceeds, progress messages  should appear indicating the Database is created, tables are created and populated and the number of rows added. Finally a "FINISHED"message with success or failure status is displayed, indicating that the transfer has completed.

Managing Transfer Definitions
Once a DataPortal transfer has been sufficiently defined, a transfer can be performed as described above. However, the defined transfer can also be named and stored for future use. This is done by entering a name in the "Transfer  Definition Name" field and  activating the "Store" button. For maximum portability, names should only use simple alpha-numeric characters and not contain spaces. Once the transfer definition has been saved, it's name will appear in the text area below the name entry field. A list of all stored definitions will be displayed. Stored definitions will persist beyond the current client session so that they will be available when the Application is restarted. Stored definitions may be removed by selecting them from the current list and activating the "Delete" button. More than one definition may be selected by using the keyboard "Control" button and a range can be selected with the keyboard "Shift" button.

By "double-clicking" on a stored transfer definition, the selected name will be entered into the "Transfer Definition Name" field and the fields in the Source and Destination areas will be populated wih their corresponding values. When the "Transfer Now" button is activated, the current field values will be used. Values can be modified and saved again by activating the "Store" button. If the definition name has not been changed, the modified values will replace the previous values in the corresponding definition. If the name has beend changed, the previous definition will be unaffected and the new values will be stored in a new definition, as specified by the new name.

Stored transfer definitions may also be referenced by transfer requests issued remotely or programatically as URLs sent to active Application Listeners (see the "Listener" section below). Remote or programatic transfer requests can be controlled by requiring user/password authentication as determined by the state of the "Password Required" / "Password NOT Required" radio buttons. Users and passwords for all transfer definitions that require password authentication can be managed by activating the "Manage Passwords for Stored Transfer Definitions" button, which creates a new window (see Figure 1a).

Managing Transfer Definition Passwords
Clicking on the button titled "Manage Passwords for Stored Transfer Definitions" brings up a new window, containing two sections. The top section is titled "All User Password Pairs" and is used to define the complete set of user/password pairs that can be applied to stored transfer definitions. Values may be entered for each user/password pair. Clicking on the "SUBMIT" button stores the current set of user/password pairs, replacing any sets that may have been previously saved.

The second section, titled "Associate User Password Pairs and Transfer Definitions" is multi-modal, as controlled by the three "Submit Mode" radio buttons. The action performed when clicking the "SUBMIT" button for this section is determined by which radio button is selected. If the top button, titled "Show User(s)/Password(s) for Selected Transfer Definition (Select 1)", is selected, previously stored user/password pairs associated with a single, selected stored transfer definition are indicated by highlighting when the "SUBMIT" button is activated. Conversely, if the second button, titled "Show Transfer Definition(s) for Selected User/Password (Select 1)" is selected, previously stored transfer definitions associated with a single, selected user/password pair are indicated by highlighting when the "SUBMIT" button is activated. If the third (bottom) radio button, titled "Apply Selected User(s)/Password(s) to Selected Transfer Definition(s)" is selected, any selected user/password pairs (1 or more) are applied to any selected (1 or more) stored transfer defnitions upon activation of the "SUBMIT" button.

Connect to Server
The DataPortal Applect client is downloaded from a DataPortal server, so it has a default DataPortal server, which it is initially connected to. Since the Application client is permanently installed on a host machine, it is not associated with any DataPortal server, so a server and port must be specified. Once specified, the "Connect" button may be clicked. An attempt will be made to connect to the specified server (and port). If the attempt is successful, a list of datasources available on the server will be applied to the "DataPortal Source" pulldown menu.

Listeners and Remote, Programatic Data Transfers
DataPortal transfers can be defined, initiated and monitored manually by using the Applet or Application graphical interfaces, as described in the previous sections. However, much of DataPortal's power comes from the ability to perform data transfers programatically. This is done by starting an HTTP and/or SSL listener, which is controlled from the "Listener" tab area of the DataPortal Application Client (see Figure 2).

  
Figure 2) Listeners tab area in the DataPortal Application Client.

DataPortal Application Client  listeners are dedicated Web servers which listen for DataPortal data transfer requests on the specified ports. Any application with network access to the DataPortal Application Client may request a data transfer by submitting a Web request to the appropriate listener. A transfer may be requested by inserting all necessary parameters into the URL request. A transfer may be specified by explicitly defining each of the paramaters required in a data transfer or by specifying the name of an already stored transfer definition. The parameter names for explicit specification of all required values are:

Data Transfer Individual Parameter Names
Source
DSHost                
 DataSource Host/Port (host:port)
DSName
 DataSource Name
DSUser
 DataSource User Name
DSPassword DataSource Password
Destination
DestHost Destination Host
DestDBVendorType Destination DB Vendor Type
(Allowed Values are:
MS Access 2000
MS SQL Server Version 7.*
MS SQL Server Version 2000.*
MySQL V4.0.*
MySQL V4.1.*
DB2 Version 7.*
DB2 Version 8.*
Oracle Version 9i.*
Oracle Version 10g.*
Firebird_V15.* )
DestInitialDB Destination Initial DB
DestDB Destination DB Name
DestUser Destination User
DestPassword Destination Password

Parameters can be inserted into URLs submitted to the Listeners. The URL pattern is:

 http(s)://host:port/DataPortal/Transfer?paramName1=value1&paramName2=value2...

Where http or https is used depending on whether the HTTP or SSL Listener is being used,  host  is the Application Client Listener host, and port is the port the Listener is running on. The "DataPortal/Transfer" string is fixed and the "?" indicates the begining of the paramater list. Each parameter name/value paramter pair has the form paramName=value, and the set of parameters is seperated by the "&" character. For example, to perform the transfer defined by the user interface in Figure 1, the following URL would be used.

http://clientHost:8281/DataPortal/Transfer?DSHost=localhost:8280&
 DSName=DailyOrders&
 DSUser=ordersUser&
 DSPassword=ordersPass&
 DestHost=ordersserver&
 DestDBVendorType=Oracle Version 9i.*&
 DestInitialDB=&
 DestDB=todaysOrders&
 DestUser=orders&
 DestPassword=destPass

The single line has been broken for ease of viewing. The parameter order does not matter and any superfulous parameter pairs (e.g. DataSource Name/Password) may be omitted.

Alternatively, transfers may be requested using the Transfer Definition name. The single required parameter is "TransferDef". The same transfer as above can be requested with the URL:

http://clientHost:8281/DataPortal/Transfer?TransferDef=OrdersTransfer
Transfer requests may be submitted programatically from an application or a Web browser, however, the requesting agent must have network access to the Listener. Either "get" or "post" submit types may be used. Any valid URL request to the listener will result in a transfer being initiated, regardless of how it was generated. Custom applications implemented in any programing language of choice may be used. In addition, a Java API
(Application Programing Interface), in both Java source and compiled code, is provided along with an example of how it can be used.

The primary class in the Java API provided for facilitating programatic transfers is the "DPremoteTransfer" class. The typical way it is used involves creating an instance of the class using a constructor that specifies the DataPortal server or server and port. Then, setters are used to set the specific parameters, either the full set of required individual parameters or a TransferDefinition. The TransferDefinition may be specified by name, or by creating a TransferDefinition object that wraps the individual parameters that fully specify a transfer. If a TransferDefinition is specified by name, it must refer to a TransferDefinition already defined and registered on the listening DataPortal Application Client. Once the required transfer definition parameters have been set, an appropriate "requestTransfer" method may be called. The request will be made to the specified server at the specified port and the results of the transfer will be returned in a "TransferResults" object, which wraps the boolean success/fail flag and a String message, summarizing the transfer.

The Listeners are configured with the "Listeners" tab area (see Figure 2). Either an HTTP or SSL Listener (or both) may be configured. The ports used by each Listener are entered in the appropriate fields. The SSL Listener also requires a Certificate saved in a Keystore file, which must be entered by typing into the appropriate field or by selecting the "Keystore File" button which will bring up a file navigation control. Associated Keystore and Key passwords must be entered, as needed, depending on the specifics of the Certificate Keystore.

To activate either or both Listeners, the appropriate "ON" button should be selected. When on, an "ON" button will have a dark grey background. If any values (including the "ON" states) are to be saved, the appropriate "SAVE" buttons should be selected. The saved values will be used until changed for the remainder of the current session and future sessions. As long as the Listeners have been configured and activated, the Application Client will be available to respond to requests issued programmatically, or via Web browsers.

If a URL of the correct form with no specified parameters (http(s)://host:port/DataPortal/Transfer)is submitted to an active Listener, it will respond with a Web page containing interactive forms (see Figure 3), which provide both information to submit URL transfer requests and an alternative way to request transfers.


Figure 3) Web page form returned for a parameterless URL transfer request submitted to a Listener.


The available parameter names are listed in parentheses to the right of the parameter description. "*" indicates a required parameter. This information may be used as a guide to form a programmatic URL transfer request. All parameters may be entered in the first form, then the top "Transfer" button may be pressed and the requested transfer will proceed. The page will return with a list of the submitted parameters before the transfer has been completed.

If the second (lower) form is used, one of the existing, stored transfer definitions may be selected using the drop down menu. The lower "Transfer" button may then be selected and the requested transfer will proceed.


Connection Concepts
Phone: (301) 625-9319
EMail: dataPortal@con2inc.com