Signiant Support

13.1 CTE SDK Developer's Guide Print



CTE SDK Overview

The Content Transfer Engine (CTE) SDK is a component of the Signiant software suite that allows you to exchange files with users or organizations without requiring both parties to have a Signiant agent installed. Through the use of this API, any computer with Java installed on it can initiate transfers. In addition, with the helper applet, any user with Web-browser and Internet connectivity can perform a Content Transfer Engine SDK transfer. The Content Transfer Engine SDK can transfer files over a WAN-accelerated secure tunnel.


CTE SDK Architecture

The Content Transfer Engine SDK is a component of the Signiant software suite that users can run as an applet embedded in a Web page. Web developers can specify all of the transfer parameters (such as server host name, files to transfer, authentication credentials, and so on) in the Web page reference, or can allow end users to specify these parameters. The Content Transfer Engine SDK utilizes the Signiant Java Transfer Engine (SJTE), which is a Java bean that supports file transfers with any Signiant agent, using the Signiant Transfer Protocol from inside any Java application.

The SJTE supports a subset of the Signiant transfer functionality including the following:

  • Can initiate transfers to/from a Signiant agent

  • WAN acceleration
  • Security services

  • Bandwidth throttling

  • File checkpointing
  • Retries and restarts

  • Authenticated transfer (using server certificate and client user ID/password)
  • Encrypted transfer

  • File date and time check types

In addition, the SJTE can also perform all of the above (except WAN acceleration) through an HTTP tunnel. This allows for easy firewall navigation, as well as enabling users who access the Internet through a proxy to perform Content Transfer Engine SDK-enabled transfers.

Bandwidth levels below 128 KBytes/sec are not supported, as performance is not reliable.

Web Page Implementation

When a user invokes a Content Transfer Engine SDK transfer from a Web page, the Web page references both the Java and the Content Transfer Engine SDK plug-in objects, and provides transfer parameters to the Content Transfer Engine SDK. The browser loading the Web page first ensures that the plug-in objects are installed, and, if they are not, installs them. The browser then runs the Content Transfer Engine SDK with the supplied parameters, or prompts the user to supply missing parameters.

The Content Transfer Engine SDK connects to an Agent configured as a Content Transfer Engine-enabled server, and authenticates. Users can specify multiple agents for load balancing, fault tolerance and protocol fallback (for example, if WAN acceleration is not possible, HTTP can be used instead). The Content Transfer Engine-enabled server performs authentication and authorization through a third party that is either the local operating system or a system that provides an appropriate Web service (in other words, SOAP).

Once the transfer is authenticated and authorized, the Content Transfer Engine-enabled server can report the status of the transfer to a third party through a Web services interface.

Most developers will customize the Content Transfer Engine SDK with their own transfer parameters, and embed it in their own Web page through which users can access it to run transfers. As a starting point, the Content Transfer Engine SDK comes pre-configured with a reference applet to run transfers through the Signiant Manager Web interface and Manager Web server.

Prerequisites

The following are required before attempting to use the Content Transfer Engine SDK:

  • Signiant Manager and Agents installed with version 11.0 or later

    You must be running an 11.0 HTTP server in order to use the HTTP tunnel feature.

  • Administrative access to the Signiant Manager
  • Agents that will be involved in Content Transfer Engine SDK transfers must be configured as Content Transfer Engine-enabled servers.

The Content Transfer Engine SDK should be installed by default during the Manager installation. To verify that the Content Transfer Engine SDK is installed, follow these steps:

  1. Login to the Manager as an administrative user.
  2. Select Administration > Manager > Applications.

    The Content Transfer Engine SDK application appears in the list, with a status of Installed. If it does not appear in the list, contact Technical Support.

Content Transfer Engine SDK and Proxies

Content Transfer Engine SDK has been tested with a number of enterprise and desktop HTTP proxies. It should be compatible with most enterprise HTTP proxies. Signiant does not recommend using Content Transfer Engine SDK with desktop HTTP proxies.

Memory Issues

Users who experience frequent out of memory errors should increase the amount of memory available to their web browser's Java Virtual Machine. To address memory issues, do the following:

Windows

  1. Choose Settings >Control Panel >Java Control Panel.
  2. Select the Java tab.
  3. Under Java Applet Runtime Settings, choose View.

    This opens the Java Runtime Settings dialog box.

  4. Under Java Runtime Parameters, increase the amount of memory available by entering -Xmx128M (for 128 MB) or -Xmx256 (for 256 MB), and so on, until you no longer experience out of memory errors. You must restart the browser for the memory change to take effect.

Linux

  1. Depending on your desktop (Gnome, KDE, etc.) a menu entry is created under System > Preferences >Java Plugin Control Panel. If you cannot find this program, launch the Java Control Panel from the command line with the following syntax: 

    $JAVA_HOME/bin/java -Djavaplugin.user.profile= -Djavaplugin.version=1.7.0_51 -Djavaplugin.nodotversion=170_51 –classpath

    $JAVA_HOME/jre/lib/deploy.jar:$JAVA_HOME/jre/lib/plugin.jar:$JAVA_HOME/jre/lib/javaplugin_l10n.jar com.sun.deploy.panel.ControlPanel

  2. Select the Java tab.
  3. Under Java Applet Runtime Settings, choose View. This opens the Java Runtime Settings dialog box.
  4. Under Java Runtime Parameters, increase the amount of memory available by entering -Xmx128M (for 128 MB) or -Xmx256 (for 256 MB), and so on, until you no longer experience out of memory errors.

    You must restart the browser for the memory change to take effect.


CTE-enabled Servers

Before you can run a Content Transfer Engine SDK transfer, you must configure the Agents as Content Transfer Engine-enabled servers. This allows them to send/receive data to/from Content Transfer Engine SDK Java clients. You configure these agents through the Manager. If you are using relay agents, and there is no relay entry defined for "tgt," both the source and the relay agent must use the same port number. In addition, you must enable Content Transfer Engine SDK on the relay Agent.

Although regular Signiant Agents run on a broad range of platforms (including Windows, Linux, MacOS and commercial UNIXes), you can configure a Content Transfer Engine SDK agent to run only on Windows (32- and 64-bit), Linux and Mac (local authentication only on the Mac). It does not support the following agent types: Windows 2000 or Solaris.

Note: The Agent cannot be Media Exchange-enabled if the Agent is Content Transfer Engine-enabled (or vice versa). Content Transfer Engine-enabled servers can access any Direct Access (DAS), Storage Area Network Attached (SAN) or Network Attached (NAS) storage.

To configure a Signiant Agent as a Content Transfer Engine-enabled server, do the following:

  1. On the Content Transfer SDK tab, enable Enable Content Transfer SDK.
  2. In the Concurrent Transfers field, the value typed here indicates the number of concurrent uploads and downloads that can be performed on the Content Transfer Engine SDK. This value can be the number of remaining licenses up to a maximum of 10 per Content Transfer Engine SDK enabled Agent. If no licenses remain and more concurrent transfers are needed, either redistribute existing licenses from other Content Transfer Engine SDK enabled Agents or contact Signiant to obtain additional capacity. Note: this does not apply to Media Shuttle.
  3. The Authentication mechanism controls the way a Content Transfer Engine-enabled server authenticates with the Agent. Specify one authentication mechanism and associated parameters, including the following:
    • Local: uses the local server authentication mechanism to determine if the passed authentication credentials (user ID and password) are valid, and to provide file access according to the local user's local file access rights. All files uploaded will be owned by the local user.
    • Signiant: this is a sample Web service that implements authentication event processing. The sample Web service will authorize any transfer request that includes a user ID and password that is valid for logging into the Signiant Manager Web interface. The sample Web service will also use the Content Transfer Engine SDK disconnect messages to add Content Transfer Engine SDK transfer statistics to the database.

      Transfers will be performed as the Signiant agent default user and restricted in scope to the agent default directory under a specific directory for the user. (For example, \transfers\fsmith\<file>).

      You must choose this value in order to be able to view job information in the Signiant Web interface activity screen.

      When Signiant is enabled you must also configure the Namespace and specify a Process Event.

    • SOAP: allows you to replace the Signiant Web service with a custom service the user provides. SOAP messages for each event will be passed. Transfers are performed as the agent default user and are restricted in scope to the directory returned from the authentication request.

      When SOAP is enabled you must also configure the URL, Namespace and specify a Process Event.

  4. Set the events that are valid for processing on a Signiant agent. The Signiant agent has an authentication and event passing interface so that third- party applications or services can control and monitor Agent interaction with the Content Transfer Engine-enabled server. This interface supports the following events:
    • Begin File: Calls a Web service to determine if the file can be uploaded or downloaded.
    • Rename File: Calls a Web service to determine what the file should be called on the server.
    • End File: Calls a Web service to notify that the transfer of an individual file is complete.
    • Disconnect: Calls a Web service to notify that the entire transfer is complete.
  5. Click OK

CTE SDK Transfer Configuration

The Content Transfer Engine SDK reference implementation uses the Signiant Manager as the Web server for Content Transfer Engine SDK transfers. The Manager serves the Content Transfer Engine SDK transfer engine applet and processes events generated by the Content Transfer Engine-enabled server. Users must do the following to use the Content Transfer Engine SDK reference implementation:

  • Make sure the Agents that will act as Content Transfer Engine-enabled servers are properly configured.
  • Create a Content Transfer Engine SDK Configuration.

CTE SDK Configuration

Before a user can run a Content Transfer Engine SDK transfer, a Content Transfer Engine SDK configuration must exist. The two prompts that control the addresses from which files are transferred are: Remote Agent (the agent list) and Fallback URL List (the URL list). The Content Transfer Engine SDK processes the agent list first, and if it is not able to contact an Agent using a Signiant protocol (i.e., TCP or UDP), then the URL list is processed. If the URL list is line separated, the list is processed in the order in which the URLs appear. If it is pipe (|) separated, the Content Transfer Engine SDK tries all of the addresses at the same time and uses the quickest to respond.

To configure the Content Transfer Engine SDK reference implementation, do the following:

  1. From the Manager, select Developer > CTE Test Configurations.
  2. Click Add Configuration and complete the specifications for the transfer configuration. When the configuration provides all of the values for a transfer, the transfer begins immediately upon starting the Content Transfer Engine SDK transfer.

    The following table describes the configuration prompts.

     

    Prompt Description
    Configuration Name The name for the Content Transfer Engine SDK Transfer configuration.
    Transfer The type of transfer for this configuration. Choose from Send (files are transferred to the selected remote agent) or Receive (files are transferred from the selected remote agent).
    Visible Specifies that users running a Content Transfer Engine SDK job can view the specified parameter. Place a check beside each parameter you want users to be able to view, or place a check in the box directly below Visible to select all of the parameters. The combination of Visible and Editable parameters affects the behavior of the Content Transfer Engine SDK job.
    Editable Specifies that users running a Content Transfer Engine SDK job can change the specified parameter. Place a check beside each parameter you want users to be able to edit, or place a check in the box directly below Editable to select all of the parameters. The combination of Visible and Editable parameters affects the behavior of the Content Transfer Engine SDK job.
    Server The agent to which you are transferring the files on a Send transfer or from which you are transferring files on a Receive transfer. Type an agent name in the field, or choose an agent from the drop-down list. Separate multiple agents with a space. If the agent has a relay, use the following format:

    agent1[relay1 relay2(portForRelay2)] agent2[relay3(port) relay4]  agent3 agent4

    Port numbers are optional, but the square brackets are required. Both the source and the relay agent must use the same port number. In addition, you must enable the Content Transfer Engine SDK on the relay Agent. Note that Content Transfer Engine SDK does not support Windows 2000 Agents. Even if these Agent types are part of your file transfer system, they will not appear in the Agent drop-down list.
    Fallback URL List This is a list of URLs that the transfer attempts to use once the Agent list is exhausted, or if it has not been specified. The following protocols are supported: UDP (WAN Acceleration), TCP (parallel streams), or HTTP (parallel streams over HTTP). Use the following format for the fallback URL list, separating each URL with a new line "\n" or the pipe "|" character. With the pipe character as separator, the Content Transfer Engine SDK tries all of the addresses at the same time and uses the quickest to respond. URLs separated by new lines are processed in the order in which they appear:

    protocol://[username@ | username:password@]host[:port]/path [ | ] [ protocol://host/path]

    Protocol is one of: mxtcp (TCP authentication), mxwan (WAN acceleration), or HTTP. The host and path are implementation dependent, and the port is an optional value that may be specified in order to use a non-standard port. The user name and password are optional and if specified, can either be clear text, or the keywords %user% and %password%, which are substituted for the currently-supplied Content Transfer Engine SDK user name and password.

    Note that the native Content Transfer Engine SDK format is: protocol://target.host@relay.host:port

    Where protocol can be mxtcp for a parallel streams (TCP) transfer, or mxwan for a UDP transfer, target.host is the name passed to the relay (if present), relay.host is the agent to which a direct connection is made, and port is the port on which the Agent is listening.

    User The name of the user that the transfer is running on the Content Transfer Engine-enabled server. With Local authentication, the transfer uses the username and password of the user on the Content Transfer Engine-enabled server. With SOAP authentication, the username and password are passed to the SOAP server, effectively ignored by the Content Transfer Engine-enabled server, since the transfer runs as the default user. The SOAP server can use the username and password to perform authentication. Note that if you use the %user% and %password% keywords for the Fallback URL List (see above), the user and password you specify here and in the following field are substituted.
    Password The password for the user that the transfer is running on the Content Transfer Engine-enabled server. With Local authentication, the transfer uses the username and password of the user on the Content Transfer Engine-enabled server. With SOAP authentication, the username and password are passed to the SOAP server, effectively ignored by the Content Transfer Engine-enabled server, since the transfer runs as the default user. The SOAP server can use the username and password to perform authentication.  The field displays the password masked as asterisks.
    File(s) to Transfer The location of the files that you want to transfer. You must specify the location as an absolute path. With local authentication, when setting up receive jobs, you must include a path for each file specified. With local authentication, the target directory is created if it does not exist.
    Destination Directory The directory to which to transfer the file(s). With Signiant and SOAP authentication, the destination directory is ignored in a send, because transfers are placed in a sandbox in a specific location. With local authentication, the target directory is created if it does not exist.

    Click Browse to select a directory. With Signiant or SOAP authentication, the user is restricted to the default directory specified for the agent/ Content Transfer Engine SDK. The Content Transfer Engine SDK creates a sub-directory matching the user in the authentication, for example, transfers\fsmith\[file]. The sub-directory label matches the user name exactly as specified in the authentication. This means that it is case-sensitive in Linux, so you could end up with two directories with the "same" name (for example, Admin/admin). You can specify a sandbox as a response from the SOAP server. If you specify a sandbox as a response from the SOAP server, all transferred files will go into the sandbox.

    Directory Handling Mode Specifies the way the directory structure will be replicated on transfer. Choose from the following:     
    • Full (replicates the parent directory, as well as the specified directory. For example, if the specified directory is "\my files", on transfer, the directory structure would include the parent, similar to "c:\parent directory\my files").
    • Flat (all the files appear in a single root directory, regardless of sub-directory structure on the source).
    • Path (the directory structure is replicated from the specified directory downwards. For example, "\my files\new\file 1, file 2").             
    C.A. Certificate Displays the CA certificate the agent uses for server authentication. The certificate that appears by default is the one generated by the Manager. You may want to use a different CA certificate if you are using a different Certificate Authority. The certificate must be from the Manager from which the agent was installed. To extract a CA, follow these steps:
    • Login as root/Administrator to a host that is populated with the Manager trusted CA whose certificate you are trying to obtain. For example, if you are interested in obtaining a Manager trusted CA certificate for the site MySite.com, then logon to an agent that belongs to MySite.com (i.e., MyHost01.MySite.com).
    • Run the administrative command: dds_cert extract. This will extract certificates from the credentials store, and among them will exist the Manager trusted CA certificate named ddsCA_cert.pem.
    • Copy ddsCA_cert.pem to a location where agents wishing to import it into their local credentials store can access it.
    • Logout
    • Paste the contents of the ddsCA_cert.pem file in the CA Certificate field.

      OR

      Click Browse to select the location of the CA cert file.

    Number of Retries The number of times the source attempts to transfer a file after an initial failure, such as "file in use". Default value is 3. A value of 0 indicates no retries. Maximum value you can specify is 99.
    Number of Restarts Specifies the maximum number of times the SDK attempts to restart a transfer after a recoverable failure such as a network outage. If set to zero ("0"), no transfer agent restarts are attempted. Maximum value you can specify is 99. The default value is 3.
    Transport The method to use for transferring the files. Choose from the following:

     

    • WAN Accelerator then Parallel Streams - Use the WAN accelerator (UDP) initially, but if communication cannot be established, try parallel streams (TCP).
    • WAN Accelerator - Use the WAN Accelerator (UDP) only.
    • Parallel Streams - Use Parallel Streams (TCP) only.
    Note that if you specify a Fallback URL List (see above), then the transport will go to the fallback option if none of the transport option(s) specified here works. If a fallback URL is specified, but an agent is not, this field is ignored.

     

    Number of Streams Specifies the number of files to transfer at one time. The default (and maximum) value is 4. Specifying zero will cause an error. The default value becomes the lower of the number of files to be transferred or the number of streams specified. For example, if you specify two files, only two streams are used.
    Bandwidth Limit Prompts users to choose the percentage of bytes per second to a maximum of whatever the CPU can handle, or a percentage of a selected network connection (for example, 75% of 128 Kbps). Note that bandwidth limiting is done on each stream connection, so a value specified here is passed to the controlling agent for each template executed and divided among the streams as follows:
    • It is divided by the number of streams the agent will use for each remote agent (typically four).
    • It is further divided by the potential number of concurrent remote agents. This will be the lesser of the maximum allowed number of concurrent agents, and the number of remote agents specified in the template.

      Note that bandwidth throttles may also be employed by other network devices and policies (e.g., QoS), therefore, a bandwidth throttle (or target maximum) defined here may not be achievable. If you are having difficulty achieving a particular bandwidth target ensure that other policies are not impacting your ability to reach the desired throughput.

    Encrypt The encryption level selected will dictate how securely the information is transmitted over the network (note: the file/package is always stored in the original format).  Encryption is isolated to the 'on the wire' portion of the transfer only and does not affect what is stored on the file system whatsoever.

    Allows specification of the encryption level from the following values:

    • Strong encryption
    • No encryption, signed
    • No encryption, unsigned
    The default value is Strong encryption. Note that mutual authentication is always used, regardless of the encryption level specified. Encryption is done "in-stream" and not on disk prior to sending.

    The No encryption,signed option transfers unencrypted (plain text) data, but includes the SSL protocol's message digest calculation and signing to ensure data stream integrity.

    The No encryption, unsigned option allows the transfer of data, after the initial SSL authentication of the endpoints, to proceed with no encryption, no message digest computation and no signing of the message digests (normally included with the SSL protocol). This mode of operation is only for raw performance, since it makes no guarantee of the integrity of the data stream other than the default one has with a normal network channel. The underlying TCP protocol can guarantee the integrity of messages across each single network hop, but has no facilities for detecting a man-in-the-middle attack.

    Logging Specifies the level of detail that appears in the log files for a job run. Choose from "None," "Info," "Fine," "Finer," or "Finest". "Finest" provides the greatest amount of detail, while "Info" provides the least. The default is "Info". Note "finest" logging may have a significant impact on performance.
    Trace Whether to create a trace file for the connection on the agent. Use in consultation with a technical support person to define agent trace flags.
    WAN Acceleration Specific Parameters
    Target Transfer Rate The rate at which the agent should attempt to send data. Typically this is the maximum speed of the network (i.e., 100Mbps, 10Mbps, and so on). You no longer have to set a definitive target transfer rate, as the transfer will now attempt to discover the target throughput by analyzing packet loss and adjusting its transmission rate accordingly. Each transfer will continually adjust itself to maximize its throughput across all network access points between the source and the target. You may specify the target transfer rate for use under conditions where you know the actual link throughput in advance. If specified, the transfer uses the target transfer rate as a bandwidth ceiling. It is the rate of transfer including retransmission. Note that if you plan to set a Minimum Transfer Rate (see below) you must specify a Target Transfer Rate that is larger than the Minimum Transfer Rate you specify.
    Minimum Transfer Rate The minimum rate at which the transfer should send the data. Note that the Minimum Transfer Rate works only if you set a Target Transfer Rate (see above), and if that Target Transfer Rate value is larger than the specified minimum transfer rate. Limits the slowest transmission rate to which the transfer can back off, regardless of packet loss. Be careful when setting the Minimum Transfer Rate variable, as it can flood the network.
    Aggressiveness Prompts users to specify how sensitive the job will be to other network traffic when running the job. Choose from High, Medium or Low. The default value is High.
  3. Place a check in the Visible box beside any parameters to display the prompt in the Transfer Settings dialogue or leave it blank not to display it.
  4. Place a check in the Editable box beside any parameters to allow a user to edit a prompt in the Transfer Settings dialogue or leave it blank to disable editing.

Running a CTE SDK Job

When you run a Content Transfer Engine SDK transfer job, the Transfer Settings screen appears. If a user has configured fields for display or editing, they will appear in this screen. Where applicable, users should edit the fields before clicking Transfer to run the job.

To initiate a Content Transfer Engine SDK transfer through the reference implementation, follow these steps:

  1. From the Manager, select Developer>CTE Test Configuration.
  2. To edit transfer settings, click the Edit configuration icon.
  3. To launch a transfer, click the Launch transfer icon. This will open a status page and a Transfer Settings dialogue. The status page provides information about the Content Transfer Engine SDK job, after it starts running.

    Navigating away from the status page will stop the transfer. Note also that clicking More expands the display to show the files being transferred. However, the display shows only the first 30 files. After 30 files, it stops listing the files in the display, even if more files are being transferred.

    If the configuration provides all the values for a transfer, the transfer will begin immediately upon starting the Content Transfer Engine SDK.

    To initiate a transfer run, click the Transfer button in the Transfer Settings dialogue. This dialogue contains the transfer configuration parameters. Editable parameters for the transfer can be modified by an end users.

Event Log

Users can view logging information about Content Transfer Engine SDK transfer jobs in the Signiant Manager Web interface, including the following:

  • User as which the job ran

  • Content Transfer Engine Agent

  • Source/Target agent

  • Date and time on which the transfer started and finished

  • How long the transfer ran

  • How many files were transferred

Note that if you want to view job run information in the Signiant Manager Web interface Event Log screen, you must specify the following agent configuration:

  • Authentication: Signiant
  • Process Event: Begin File (enabled)
  • Process Event: End File (enabled)
  • Process Event: Disconnect (enabled)

To view Content Transfer Engine SDK transfer activity, follow these steps:

  1. From the Manager, select Developer>CTE Event Log.

    The following describes the fields in the Content Transfer Engine SDK Transfer Event Log/MXReports screen:

    • User: The name of the user as which the Content Transfer Engine SDK/Media Exchange job ran.
    • Client: The name of the computer on which the Content Transfer Engine SDK/Media Exchange ran. This name is not authoritative, as it is the name the user gave the machine when they installed the machine's operating system.
    • Server: The name of the Content Transfer Engine/Media Exchange-enabled server.
    • Started: The date and time at which the Content Transfer Engine SDK/Media Exchange job began.
    • Finished: The date and time at which the job completed.
    • Duration: How long the Content Transfer Engine SDK/Media Exchange transfer ran.
    • # Files: How many files were transferred during the job run.

    Click the magnifying glass beside a listed job run to view details about it.

Event Log Detail/Media Exchange Reports

Displays detailed information about each file transferred during a specific Content Transfer Engine SDK/Media Exchange transfer run, including the items listed in the table below.

Clicking the "More" button expands the display to show the files being transferred. However, the display shows only the first 30 files. After 30 files, it stops listing the files in the display, even if more files are being transferred.

If the transfer has failed, the screen indicates that the transfer failed, and an "x" icon appears between the two computers.

Navigating away from the page will stop a transfer.
  • File: The name of the transferred file.
  • Size: How big the file is (in bytes).
  • Direction: Whether the file was sent or received.
  • Status: Indicates whether the transfer is "running," "completed" or "stale". Stale indicates that the transfer timed out and did not complete.
  • Started: The date and time when the transfer began.
  • Finished: The date and time when the transfer completed.
  • Duration: How long the transfer took.
  • Transfer Rate (bytes/sec): The number of bytes transferred per second.
  • Transfer Rate (bits/sec): The number of bits transferred per second.

Content Transfer Engine SDK Javadocs

As part of the Content Transfer Engine SDK installation, the Developer>CTE Javadocs menu appears in the Signiant Web interface. Selecting this menu item gives you access to the SDK Javadocs.

As well, a package containing the Javadocs is copied to the following location on the Signiant Manager:

https://<Manager_address>/signiant_content_transfer_engine_sdk/secure/webclient/javadocs

To extract the Javadocs (for example, to print them), use the following command:

jar xvf /usr/signiant/dds/3rdparty/jboss/server/default/deploy/signiant_content_transfer_engine_sdk.war

This extracts a copy of the Javadocs into the local directory secure/webclient/javadocs.


CTE SDK Status

Connection Status

You can retrieve the Content Transfer Engine's connection status with the engine.getConnectionStatus() method.

The following table lists all the possible connection status values for the SDK:

Connection Status Description
CONNECTING Indicates that the TransferEngine is currently in the process of connecting to a remote system.
AWAITING_DATA_STREAMS Indicates that the TransferEngine is currently in the process of negotiating data streams with a remote system. This can take some time (>10s) if the Transport is UDP_THEN_TCP.
CONNECTED Indicates that the TransferEngine is currently connected to a remote system.
COMPONENT_QUEUED Indicates that the TransferEngine is currently connected to a remote system, but the transfer is queued.
DISCONNECTED Indicates that the TransferEngine is currently not connected.

Completion Status

There are situations where a 'cancelled' status indicates a pause in the transfer before an automatic reconnect will be attempted. As such, you cannot use the engine.isCompleted() and the engine.getCompletionStatus() calls, by themselves, to definitively determine the transfer state.

To determine the status of the SDK transfer, the best approach is to do the following:

  1. Use a Transfer Listener with the engine.addTransferListener() method.
  2. Decide upon the method used to detect engine termination:

    You can use the engine.waitForTransfer() method to block program execution until the transfer engine has completed its work. If a blocking operation is not appropriate for your application, create a polling loop that periodically calls the getCompletionStatus() method and exits when a termination status is detected.

  3. Retrieve the engine's final status with the engine.getCompletionStatus() method. The Transfer Listener will receive notifications on the exception (Exception e) method.
  4. Create a method that handles these notifications when the following exceptions are passed:
    • TransferWarning
    • RetryableSituationWarning
  5. When the engine.getCompletionStatus() call returns "CANCELLED" AND the Transfer Listener receives TransferWarning or RetryableSituationWarning events, the transfer is in a state where it is currently not running but is pending a restart.

    Any other event passed to the Transfer Listener on this method indicates a transfer that is not running and will not be restarted. The following table lists all the possible completion status values for the SDK:

     

    Completion Status Exception Description
    INCOMPLETE any The transfer is currently running.
    SUCCESSFUL any The transfer has finished and was successful with no warnings or errors.
    WARNING any The transfer has finished and was successful, but one or more non-fatal warnings were issued.
    FAILURE any The job has finished unsuccessfully, with one or more fatal errors.
    CANCELLED

    TransferWarning

    RetryableSituationWarning

    The transfer is not currently running, but will be restarted automatically.
    any other The transfer is not currently running and will not be restarted automatically.

 


CTE SDK Deployment

Signiant Content Transfer Engine SDK can run as an applet embedded in a Web page. It allows users to transfer files to and from the Signiant Manager, using systems that are not running the Signiant agent software. This section explains how to configure Content Transfer Engine SDK and embed it in an HTML Web page and assumes that you have experience working with HTML markup and deploying Java applications and applets.

Prerequisites

Although the Content Transfer Engine SDK should work with a broad range of browsers, the following browsers are the only ones specifically tested and supported:

Windows 7, Windows 8, Windows 8.1, Windows 10

  • Internet Explorer 10, 11
  • Microsoft Edge (HTML 12, 13, 14)
  • Mozilla Firefox 40 - 53
Signiant App
  • Internet Explorer 11
  • Google Chrome (Latest version)
  • Microsoft Edge (Latest version)
  • Mozilla Firefox (Latest version)
  • Apple Safari 9.0.3, 9.1, 10 - 10.0.3, 10.1, 10.1.1

Macintosh OS X 10.9, 10.10, 10.11

  • Apple Safari 9.0.3, 9.1.3, 10 - 10.0.3, 10.1, 10.1.1
  • Mozilla Firefox 40 - 53
  • Google Chrome 40 - 58

Media Exchange Desktop Client

  • Window 7, 8, 8.1, 10
  • Macintosh OS X 10.10, 10.11

Planning a Content Transfer Engine SDK Configuration

Before configuring Content Transfer Engine SDK, you need to consider the following:

  • Which agents will be involved in Content Transfer Engine SDK transfers?
  • What authentication do you want to use?
  • What events do you want to process in your application?
  • What destination directory/sandbox do you want to use?
  • What protocols you want to use?

Content Transfer Engine SDK Agents

Before you can run a Content Transfer Engine SDK transfer, you must configure the agents involved in the transfers as Content Transfer Engine-enabled servers. This configuration includes the following:

  • Whether or not the agent can take part in a Content Transfer Engine SDK transfer.

  • The type of authentication mechanism a Content Transfer Engine SDK transfer will use to connect with the agent.

  • Which events will be processed.

  • What protocols to use.

Authentication

You can specify the method that the Content Transfer Engine SDK transfer will use to validate users as which the transfer runs and processes events. Choose from one of the following:

  • Local - Use the local server authentication mechanism to determine if the passed authentication credentials (user ID and password) are valid, and to provide file access according to the local user's local file access rights. All files uploaded will be owned by the local user. No other event processing is done. In this mode, the Content Transfer Engine SDK transfer server authentication and authorization behavior is much like an FTP server. With local authentication, the target directory is created if it does not exist.

  • Signiant - A sample Web service that implements authentication event processing. The sample Web service will authorize any transfer request that includes a user ID and password that is valid for logging into the Signiant Manager Web interface. All transfers are performed as the agent's default user, and file transfers are restricted to a directory determined by appending the user name to the agent's default transfer directory (for example,

    transfers\fsmith\<file>

    All uploads are placed in the directory and all downloads are performed from this directory. The sample Web service will also use other events to record Content Transfer Engine SDK transfer statistics in the database.
  • SOAP - Authenticates using a user-supplied Web service. The field can contain multiple URLs, separated by a space, to which SOAP messages corresponding to the events will be sent. If the first URL does not respond, then the Content Transfer Engine SDK transfer will look to the next URL in the list until it finds one that responds. You can list multiple URLs in priority order. SOAP messages corresponding to all events will be sent to the specified URL.

Process Event

You can specify how the initial Content Transfer Engine SDK transfer connection/authentication event is handled, with all other subsequent events being handled the same way. Note that the "local" authentication option does not allow you to specify any "process events". Agents have an authentication and event passing interface so that third-party applications or services can control and monitor Agent interaction with Content Transfer Engine SDK. If you specify "Signiant" or "SOAP" authentication (which both use as a Web service for authentication), all other events will be sent to the same address.

The interface supports the following events:

  • Begin File - Calls a Web service to determine if the file can be uploaded or downloaded.
  • Rename File - Calls a Web service to determine what the file should be called on the server.
  • Filter File - Calls a Web service to determine if the file contents should be filtered. 

    This event cannot be enabled through the Agent Configuration screen.  It can only be enabled as a response from a SOAP Server authentication call.  (See the example SOAP Authentication call for a sample of how this can be done.)  Note also that this event prevents check points for pause, resume, or restart from working.

  • End File - Calls a Web service to notify that the transfer of an individual file is complete.
  • Disconnect - Calls a Web service to notify that the entire transfer is complete.

You specify this agent configuration and authentication information through the Signiant Manager Web interface, in the agent configuration screen. You can specify any of the event URLs or name spaces (URIs) as a response from the SOAP server. If you specify one or more of the responses, its value overrides the one supplied in the Signiant Manager Web interface.

com.signiant.interactivetransfer.soap.begin_file_urls

com.signiant.interactivetransfer.soap.begin_file_uri

com.signiant.interactivetransfer.soap.rename_file_urls

com.signiant.interactivetransfer.soap.rename_file_uri

com.signiant.interactivetransfer .soap.filter_file_urls

com.signiant.interactivetransfer.soap.filter_file_uri

com.signiant.interactivetransfer.soap.end_file_urls

com.signiant.interactivetransfer.soap.end_file_uri

com.signiant.interactivetransfer.soap.disconnect_urls

com.signiant.interactivetransfer. soap.disconnect_uri

Destination Directory and Sandbox

The destination directory is the directory to which files are transferred on a send transfer, and from which they are transferred on a receive transfer. With SOAP authentication, the destination directory is ignored in a send, because transfers are placed in a sandbox in a specific location. With local authentication, the target directory is created if it does not exist.

With Signiant or SOAP authentication, the user is restricted to the default directory specified for the agent/ Content Transfer Engine SDK. The Content Transfer Engine SDK creates a sub-directory matching the user in the authentication, for example, transfers\fsmith\<file>. The sub-directory label matches the user name exactly as specified in the authentication. This means that it is case-sensitive in Linux, so you could end up with two directories with the "same" name (for example, Admin/admin).

You can specify a sandbox as a response from the SOAP server. If you specify a sandbox as a response from the SOAP server, all transferred files will go into the sandbox. 

The "sandbox" transfer engine property (available only with SOAP authentication) allows you to specify a different directory than the default "transfers" directory. Whatever directory is returned here is the destination directory, with no user name appended. If you specify sandbox as a response from the SOAP server, all transferred files will go through the sandbox.

Protocols

The Content Transfer Engine SDK supports the following protocols:

  • UDP (WAN Acceleration)
  • TCP (parallel streams)
  • HTTP (parallel streams over HTTP)

Using the Fallback URL List feature, users can specify the order in which the Content Transfer Engine SDK transfer will try the listed protocols.

Configuration Properties

In addition to agent configuration information, you should consider the following:

  • What Content Transfer Engine SDK fields do you want to pre-set?
  • What Content Transfer Engine SDK fields do you want users to be prompted for?
  • What Content Transfer Engine SDK fields do you want to allow a user to see, but not edit?

You specify this information as a Java property list. When a user runs a Content Transfer Engine SDK configuration, the applet reads its configuration from this list. The Content Transfer Engine SDK transfer runs, transferring the files/directories and sending statistics events with information about the transfer (number of files transferred, how long the transfer ran, and so on).

Developers who do not want the user to know what server they are uploading to, or how they are authenticating the transfer, may want to run the Java property list through an obfuscation class to produce a compiled configuration string which they deploy with the Content Transfer Engine SDK. When a user runs a Content Transfer Engine SDK configuration, the applet reads its configuration from the obfuscated string. Obfuscation is an optional step in the Content Transfer Engine SDK deployment process.

Transfer Engine Properties

The following table describes the parameters for Content Transfer Engine SDK. Note that all property names require the following prefix:

com.signiant.interactivetransfer.engine

 

Property Name Required SOAP Description

agent_list

Yes

No

A space-separated list of the agent(s) with which the client can communicate, as well as any relay agents those agents may need. When more than one agent is listed, the transfer engine attempts to launch a transfer on all of the agents at the same time. The first agent with which it connects continues with the transfer. All other connections immediately end. If the agent has a relay, use the following format:

agent1[relay1 relay2(portForRelay2)]

agent2[relay3(port) relay4]  agent3 agent4

Note that port numbers are optional, but the square brackets are required. Both the source and the relay agent must use the same port number. In addition, you must enable the Content Transfer Engine SDK on the relay agent.

Syntax:

com.signiant.interactivetransfer.engine.agent_list=hostdomain2.somewhere.com

 

For agents with relays:

com.signiant.interactivetransfer.engine.agent_list=hostdomain2.somewhere.com [hostdomain3.somewhere.com (480)]

bandwidth_throttle

No

Yes

Limit the transfer rate of the job to the specified number of bytes per second. If set to "0", no bandwidth throttle is used. Note that bandwidth levels below 128 KBytes/sec are not supported, as performance is not reliable.

Syntax:

com.signiant.interactivetransfer.engine.bandwidth_throttle=0

 

ca_certificate 

Yes

No

The certificate for the CA used by the remote Content Transfer Engine SDK transfer server agent. The CA is expressed in PEM format (i.e., begin and end certificate lines enclosing the base64 encoded version of the certificate), and is used to authenticate the Content Transfer Engine SDK transfer server. This value can be obtained on the Signiant Manager by running the command 'dds_cert extract' and using the text from the ddsCA_cert.pem file. If you are using a third-party CA certificate, you will need to enter it in this field.

Syntax:

com.signiant.interactivetransfer.engine.ca_certificate=<certificate_file>

 

destination_dir 

No

Yes

The directory to which to transfer the file(s). With Signiant and SOAP authentication, the destination directory is ignored in a send, because transfers are placed in a sandbox in a specific location. With Signiant or SOAP authentication, the user is restricted to the default directory specified for the agent/ Content Transfer Engine SDK. The Content Transfer Engine SDK creates a sub-directory matching the user in the authentication, for example, transfers\fsmith\<file>.

The sub-directory label matches the user name exactly as specified in the authentication. This means that it is case-sensitive in Linux, so you could end up with two directories with the "same" name (for example, Admin/admin). You can specify a sandbox as a response from the SOAP server. If you specify a sandbox as a response from the SOAP server, all transferred files will go into the sandbox.  See also the password, sandbox and user properties described elsewhere in this table. With local authentication, the target directory is created if it does not exist.

Syntax:

com.signiant.interactivetransfer.engine.destination_dir=/tmp/qa/targ

 

dir_handling_mode

No

Yes

Allows you to specify how the directory structure of the files you are transferring is preserved on the target. Choose from the following:Path: Preserve the path hierarchy under the requested path. Flat: Place all files directly into the target directory. Full: Preserve full source path hierarchy, including parents.

Syntax:

com.signiant.interactivetransfer.engine. dir_handling_mode

 

encrypt

No

Yes

Whether or not the transfer should use SSL encryption or attempt to negotiate an SSL connection without encrypting the data. No encryption would result in increased performance for the transfer at the cost of security. The possible values are the following:

STRONG - The strongest encryption allowed by your CA certificate. If this is Signiant certified, the encryption is 128-bit DES.

NONE - Digitally signed, but not encrypted. Transfers unencrypted (plain text) data, but includes the SSL protocol's message digest calculation and signing to ensure data stream integrity.

UNSIGNED - Allows the transfer of data, after the initial SSL authentication of the endpoints, to proceed with no encryption, no message digest computation and no signing of the message digests (normally included with the SSL protocol). This mode of operation is only for raw performance, since it makes no guarantee of the integrity of the data stream other than the default one has with a normal network channel.

Syntax:

com.signiant.interactivetransfer.engine.encrypt=strong

 

files

Yes

Yes

The location of the files that you want to transfer. You must specify the location as an absolute path. With local authentication, when setting up receive jobs, you must include a path for each file specified.

Syntax:

com.signiant.interactivetransfer.engine.files= c:\\tmp\\qa\\files\\file.100m

 

logging

No

Yes

This configuration text is used to initialize the Java logging manager. It is specified in Java property file format. Values can be a simple logging level (such as none, info, fine, finer or finest), or a Java logging specification. With the simple log level, the log file is located in the JVM's java.io.tmpdir, using the file pattern "sigitc-yyyy-mm-dd-hh-mm-ss-ccc.log", and the level is set for all Content Transfer Engine SDK classes to the level stated (e.g., info, fine, and so on).

Syntax:

com.signiant.interactivetransfer.engine.logging=none  

 

mode

No

No

Whether the transfer is going to be sending files or receiving them. Possible values are SEND or RECEIVE. The default value is "SEND".

Syntax:

com.signiant.interactivetransfer.engine.mode=RECEIVE

 

password

Yes

Yes

The password for the user as which the transfer is running on the Content Transfer Engine-enabled server. With Local authentication, the transfer uses the username and password of the user on the Content Transfer Engine-enabled server. With SOAP authentication, the username and password are passed to the SOAP server, effectively ignored by the Content Transfer Engine-enabled server, since the transfer runs as the default user. The SOAP server can use the username and password to perform authentication.

Syntax:

com.signiant.interactivetransfer.engine.password=testing

 

restarts

No

Yes

Specifies the maximum number of times the SDK attempts to restart a transfer after a recoverable failure such as a network outage. The ITC_Authenticate method is called on a restart, with a new session_id. The default restart value is "3". A value of "0" indicates no restarts (the first failure aborts the job). A value of "1" means the job will run once, and if it fails, it will restart, and attempt to run a second time.

Syntax:

com.signiant.interactivetransfer.engine.restarts=0

 

retries

No

Yes

The number of times the source attempts to transfer a file after an initial failure, such as "file in use". The ITC_Begin_File method is called upon retry, and may be called multiple times. The ITC_End_File method is called only once, when the retry file count is exhausted. The default value is "3". A value of "0" indicates no retries (the first failure aborts the job). A value of "1" means the job will run once, and if it fails, one retry will occur.

Syntax:

com.signiant.interactivetransfer.engine.retries=0

 

sandbox

No

Yes

Note that this parameter is available only with SOAP authenticating. You cannot put it in your config file or the Manager Web interface. Allows you to specify a different directory than the IT Server agent default directory. Whatever directory is returned here is the destination directory.

Syntax:

com.signiant.interactivetransfer.engine.sandbox=</tmp/qa/targ>

 

service_data

No

Yes

This field is provided for passing arbitrary information needed by the remote Content Transfer Engine SDK transfer server to distinguish instances of this transfer. The Content Transfer Engine SDK transfer engine makes no use of this parameter - it is simply passed through to the Web services.

Syntax:

com.signiant.interactivetransfer.engine.service_data=service

 

session_id 

No

Yes

This property is not contained within the client configuration, and is in fact, removed if present. Content Transfer Engine SDK generates a unique session_id that is passed to the SOAP server. The SOAP server can modify the session_id, and this session_id is used in all subsequent SOAP transfers (ITC_Begin_File, ITC_End_File, and so on). Note that a new session_id is generated if a restart occurs.

Syntax:

com.signiant.interactivetransfer.engine.session_id=abc123

 

streams 

No

Yes

Specifies the number of files to transfer at one time. The default (and maximum) value is 4. Specifying zero will cause an error. The default value becomes the lower of the number of files to be transferred or the number of streams specified. For example, if you specify two files, only two streams are used.

Syntax:

com.signiant.interactivetransfer.engine.streams=4

 

trace

No

Yes

Whether to create a trace file for the connection on the agent. Use in consultation with a technical support person to define agent trace flags. Note that setting the trace option creates very large log files on the Content Transfer Engine SDK transfer server and has an impact on performance.

Syntax:

com.signiant.interactivetransfer.engine.trace=

 

transport

Yes

Yes

The transport method to use. Possible values are the following:

  • UDP (use the WAN accelerator only)
  • TCP (use parallel TCP streams only)
  • UDP_THEN_TCP (use the WAN accelerator initially; but if communication cannot be established, fall back to parallel TCP streams).

The default value is UDP. Note that if you specify a Fallback URL List (see url_list, below), then the transport will go to the fallback option if none of the transport option(s) specified here works. If a fallback URL is specified, but an agent is not, this field is ignored.

Syntax:

com.signiant.interactivetransfer.engine.transport=TCP

 

udp.aggressiveness

No

Yes

Indicates how sensitive the job will be to other network traffic when running. "High" aggressiveness yields the least to other network traffic. Choose from 1 (low), 2 (medium) or 3 (high).

High: The agent will always attempt to send data at the Target Transfer rate (specified or dynamically calculated) and not share with other network traffic. It is recommended that you specify a Target Transfer rate with the High aggressiveness setting. If you do not, it is possible for the transfer to drive other traffic off the network, possibly resulting in a denial of service. By setting a reasonable target transfer rate, this setting can be most effective at overcoming packet loss on less reliable networks.

Medium: The agent will always attempt to send data at the Target transfer rate (specified or dynamically calculated), however, if other traffic is detected, the agent will share the network resources but never fall below the Minimum Transfer Rate (if specified). Use the Medium aggressiveness setting as the default setting, along with specifying a Target Transfer rate value where possible. Setting the target achieves a balance between network sharing and overcoming packet loss.

Low: The agent will always attempt to send data at the Target Transfer Rate (specified or dynamically calculated), however, if other traffic is detected, the agent will drop its transfer rate more quickly and attempt to creep back up to the Target Transfer rate more slowly. Use the Low aggressiveness setting for clean networks (little or no packet loss between endpoints) where sharing the network is the primary goal of the transfer.

The default value is "2".

Syntax:

com.signiant.interactivetransfer.engine.udp.aggressiveness=2

 

udp.local_port

No

No

Specifies the local port used for UDP. The default value is 49221.

Syntax:

com.signiant.interactivetransfer.engine.udp.local_port=integer integer > 0

 

udp.minimum_rate

No

Yes

The minimum rate at which the transfer should send the data, in bytes per second. Note that the Minimum Transfer Rate works only if you set a Target Transfer Rate (see above), and if that Target Transfer Rate value is larger than the specified minimum transfer rate. Limits the slowest transmission rate to which the transfer can back off, regardless of packet loss. Be careful when setting the Minimum Transfer Rate variable, as it can flood the network. The default value is "0" (no minimum).

Syntax:

com.signiant.interactivetransfer.engine.udp.minimum_rate=0

 

udp.payloadsize

No

Yes

Specifies the UDP message size in the agent. This can assist if you are running across networks where the Maximum Transmission Unit (MTU) is set to a value that would not allow a full 1500 byte packet through without fragmentation. Note that the smaller the value, the lower the performance will be. You cannot set the value lower than 300 or higher than 1430. If an invalid value (e.g., the word "three hundred" instead of "300" or a too low/too high value) is specified, the default value of 1024 is used.

The SOAP service can modify the parameter, but the modification is applicable to the data stream only. By the time the SOAP authentication takes place, the control stream is already set up and can no longer be modified. If not specified, the default is 1032 (1024 + 8 bytes of header). So, the following is possible with the SOAP service:No payload size is specified in the client's configuration.  The initial control stream connection is then established with a payload size of 1032. SOAP authentication takes place. The SOAP server detects that this particular client is on a large MTU network pipe, so it decides to send back a configuration change, raising the payload size to 1438. The Content Transfer Engine receives the parameter, along with the successful login token, and proceeds to establish the data stream with a payload size of 1438.

Syntax:

com.signiant.interactivetransfer.engine.udp.payloadsize=<number with a max of 1438 bytes>

 

udp.port_range

No

No

Specifies the UDP port range. Specify values between 0 and 65535.

Syntax:

com.signiant.interactivetransfer.engine.udp.port_range=> 0 and < 65535

 

udp.target_rate

No

Yes

The rate at which the agent should attempt to send data, in bytes per second. Typically this is the maximum speed of the network (i.e., 100Mbps, 10Mbps, and so on). You no longer have to set a definitive target transfer rate, as the transfer will now attempt to discover the target throughput by analyzing packet loss and adjusting its transmission rate accordingly.

Each transfer will continually adjust itself to maximize its throughput across all network access points between the source and the target. You may specify the target transfer rate for use under conditions where you know the actual link throughput in advance. If specified, the transfer uses the target transfer rate as a bandwidth ceiling. It is the rate of transfer including retransmission. Note that if you plan to set a Minimum Transfer Rate (see below) you must specify a Target Transfer Rate that is larger than the Minimum Transfer Rate you specify. The default value is "0".

Syntax:

com.signiant.interactivetransfer.engine.udp.target_rate=0

 

url_list

No

No

This is a list of URLs that the transfer will attempt to use once the agent list is exhausted, or if it has not been specified. The following protocols are supported: UDP (WAN Acceleration), TCP (parallel streams), or HTTP (parallel streams over HTTP). Use the following format for the fallback URL list, separating each URL with a new line "\n" or the pipe "|" character. With the pipe character as separator, the Content Transfer Engine SDK tries all of the addresses at the same time and uses the quickest to respond. URLs separated by new lines are processed in the order in which they appear:

protocol://[username@ | username:password@]host[:port]/path [ | ] [ protocol://host/path]

Protocol is one of: mxtcp (TCP authentication), mxwan (WAN acceleration), or HTTP. The host and path are implementation dependent, and the port is an optional value that may be specified in order to use a non-standard port. The user name and password are optional and if specified, can either be clear text, or the keywords %user% and %password%, which are substituted for the currently-supplied Content Transfer Engine SDK user name and password. Note that the native Content Transfer Engine SDK format is as follows:

protocol://target.host@relay.host:port

Where "protocol" can be "mxtcp" for a parallel streams (tcp) transfer, or "mxwan" for a udp transfer, "target.host" is the name passed to the relay (if present), "relay.host" is the agent to which a direct connection is made, and "port" is the port on which the agent is listening. This value renders "transport" ineffective. The agent_list and transport values work together, being converted to a URL list that is prepended to any values that might appear in the url_list parameter.

Syntax:

com.signiant.interactivetransfer.engine.url_list= protocol://[username@ | username:password@]host[:port]/path [ | ] [protocol://host/path]

 

user

Yes

Yes

The name of the user as which the transfer is running on the Content Transfer Engine-enabled server. With Local authentication, the transfer uses the username and password of the user on the Content Transfer Engine-enabled server. With SOAP authentication, the username and password are passed to the SOAP server, effectively ignored by the Content Transfer Engine-enabled server, since the transfer runs as the default user. The SOAP server can use the username and password to perform authentication. Note that if you use the %user% and %password% keywords for the Fallback URL List (see above), the user and password you specify here and in the following field are substituted.

Syntax:

com.signiant.interactivetransfer.engine.user=qatest

 

use_tcp_control_channel

No

No

Enable usage of the TCP control channel for UDP transfer.

Syntax:

com.signiant.interactivetransfer.engine.use_tcp_control_channel=Tru

 

Transfer Engine Header Properties

The following table describes the parameters for Content Transfer Engine SDK header properties. Note that all property names require the following prefix:

com.signiant.interactivetransfer.engine.header

.
Property Name Required SOAP Description
jobgroup No Yes The name of the group in the Manager Web interface Jobs>Groups screen. The group is automatically created the first time a CTE is run and will have a description of "Default Job Group for Content Transfer Engine jobs." The Job Group may also be created prior to the first run, by adding a new job group and assigning a description.

Syntax:

com.signiant.interactivetransfer.engine.header.jobgroup=my_group1

 

jobnameprefix No Yes The prefix that shows up as the first part of the job when it is added to the job group.

Syntax:

com.signiant.interactivetransfer.engine.header.jobnameprefix=CTE

 

packageid No Yes The database index for the package object that may be associated with the operation the CTE SDK is performing. If present, the package_id specified is stored in the job run record for the particular SDK transfer. The Media Exchange application uses this value.

Syntax:

com.signiant.interactivetransfer.engine.header.packageid=599

 

Java Logging Classes

For the Java logging, the property is specified according to the LogManager class http://java.sun.com/reference/api/index.html. The Content Transfer Engine SDK installation creates a link to the SDK Javadocs:

https://<Transfer_Manager_address>/signiant_content_transfer_engine_sdk /secure/webclient/javadocs

If you need to extract the Javadocs (for example, you would like an offline copy), use the  following command to extract a copy of the Javadocs into the local directory

secure/webclient/javadocs

jar xvf /usr/signiant/dds/3rdparty/jboss/server/default/deploy/signiant_content_transfer_engine_sdk.war secure/webclient/javadocs

The following is an explanation of the loggable classes and what information each provides. The use of FINER or FINEST levels can have a performance impact on WAN acceleration, by making it slower.

com.signiant.interactivetransfer.engine.TransferEngine.level=

  • CONFIG - changes to values used to set up transfer
  • FINE - session initialization, shutdown, finding fastest agent to respond
  • FINEST - file progress, transfer rates, and so on

com.signiant.interactivetransfer.engine.ControlStream.level=

  • INFO - debug informational messages from the remote Content Transfer Engine SDK transfer server agent scripts
  • FINE - control stream initialization, shutdown, package summary
  • FINEST - heartbeat control, command processing, data stream interaction, and contents of package scripts

com.signiant.interactivetransfer.engine.DataStream.level=

  • FINE - data stream initialization, shutdown, package summary
  • FINEST - individual file processing
com.signiant.interactivetransfer.engine.Stream.level=
  • FINE - expected/actual application protocol responses
  • FINER - application layer protocol data read/written (commands, not data packets)

com.signiant.interactivetransfer.engine.Port.level=

  • FINE - SSL negotiation, control
  • FINEST - counts data written to/from the port itself (pre/post-ssl)

com.signiant.interactivetransfer.engine.UdpConnection.level=

  • FINER - UDP (WAN accelerator) connection control
  • FINEST - UDP datagram packet handling

com.signiant.interactivetransfer.engine.UdpSession.level=

  • FINER - UDP datagram packet allocation, window negotiation, packet retransmission control
  • FINEST - Internal locks, low level UDP datagram management 

The following is an example of Java logging that reports informational messages to standard output, and a moderate amount of logging detail to a log file. To set the level, simply place it all into a Java String and call engine.setLogging() with that string.

 

com.signiant.interactivetransfer.engine.ControlStream.level=FINE

com.signiant.interactivetransfer.engine.DataStream.level=FINE

com.signiant.interactivetransfer.engine.Stream.level=FINE

com.signiant.interactivetransfer.engine.TransferEngine.level=FINE

handlers=java.util.logging.FileHandler,java.util.logging.ConsoleHandler

java.util.logging.ConsoleHandler.level=ALL

java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter

handlers=java.util.logging.FileHandler

java.util.logging.FileHandler.pattern=/tmp/my_log_file.log

java.util.logging.FileHandler.count=1

java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

java.util.logging.FileHandler.level=ALL

Transfer Applet Properties

In addition, you can specify whether or not the user can see and/or edit the configuration information inside Content Transfer Engine SDK. To do so, you need to create another Java string, using the following prefix:

com.signiant.interactivetransfer.applet

The following table describes the view and edit properties:

Property Description

edit_fields

The properties that are editable by the user scheduling the transfer. Each locked property name is listed on a single line.

Syntax:

com.signiant.interactivetransfer.applet.edit_fields= com.signiant.interactivetransfer.engine.user\ncom .signiant. interactivetransfer.engine.password\ncom .signiant.interactivetransfer.engine.files\ncom.signiant .interactivetransfer.engine. destination_dir\ncom .signiant.interactivetransfer.engine.ca_certificate \ncom.signiant.interactivetransfer.engine.retries \ncom.signiant.interactivetransfer.engine.restarts \ncom.signiant.interactivetransfer.engine.udp .aggressiveness\ncom.signiant. interactivetransfer .engine.streams

show_fields

The properties that are visible to the user scheduling the transfer.

Syntax:

com.signiant.interactivetransfer.applet.show_fields= com.signiant.interactivetransfer.engine.mode\ncom .signiant. interactivetransfer.engine.agent_list \ncom.signiant.interactivetransfer.engine.user\ncom .signiant.interactivetransfer. engine.password\ncom .signiant.interactivetransfer.engine.files\ncom .signiant.interactivetransfer.engine .destination_dir\ ncom.signiant.interactivetransfer .engine.ca_certificate\ncom.signiant .interactivetransfer.engine.retries\ncom.signiant .interactivetransfer.engine.restarts\ncom.signiant .interactivetransfer.engine.udp.target_rate\ncom .signiant.interactivetransfer. engine.udp.minimum_rate \ncom.signiant.interactivetransfer.engine.udp .aggressiveness\ncom.signiant.interactivetransfer .engine.streams\ncom. signiant.interactivetransfer .engine.bandwidth_throttle\ncom.signiant .interactivetransfer.engine.encrypt\ncom.signiant .interactivetransfer.engine.logging\ncom.signiant .interactivetransfer.engine.trace

Applet Show and Edit Properties

Depending on how you combine the view and edit properties, the following behavior will occur:

Show Edit Description

yes

yes

The property is displayed as normal, and the user is able to change the contents of the property.

yes

no

The property is displayed as normal, however the controls pertaining to this property are disabled (grayed out). The user is not able to change the contents of the property, however, the property is displayed as normal.

no

yes

The property's value is displayed as dots. The user is able to change the contents of the property, and, once changed, the value replaces the dots and is user-readable.

no

no

The property's value is displayed as dots and the controls pertaining to this property are disabled (grayed out).

Connection-Specific Transfer Parameters

Property  Value

Agent

The agent the client is connecting to (through the relay, if any).

Syntax:

com.signiant.interactivetransfer.connection.agent=agent1.someplace.com

Control_stream

Whether or not this connection is the control stream of the transfer (true), or if it is one of the data streams (false).

Syntax:

com.signiant.interactivetransfer.connection.control_stream=true

fallback

Whether or not this transfer is occurring due to a fallback condition (i.e., the UDP transfer failed to make any connections). This value is either true or false.

Syntax:

com.signiant.interactivetransfer.connection.fallback=true

itc_host

The DNS host name of the machine running the client.

Syntax:

com.signiant.interactivetransfer.connection.itc_host=host2.someplace.com

itc_ip

The IP address of the machine running the client.

Syntax:

com.signiant.interactivetransfer.connection.itc_ip=123.123.123.123

relay_address

The host name of the relay being used for this connection.

Syntax:

com.signiant.interactivetransfer.connection.relay_address=relay1.someplace.com

relay_port

The port number on the relay host being used for this connection.

Syntax:

com.signiant.interactivetransfer.connection.relay_port=40091

restarted

The number of times this transfer has been attempted and failed to complete successfully.

Syntax:

com.signiant.interactivetransfer.connection.restarted=3

session_id

The session id parameter (if any) the Signiant agent returned.

Syntax:

com.signiant.interactivetransfer.connection.session_id=abc123

transport

Whether this transfer is being attempted over TCP or UDP.

Syntax:

com.signiant.interactivetransfer.connection.transport=UDP

User

The user account that is running the client.

Syntax:

com.signiant.interactivetransfer.connection.user=qatest

Interface-Specific Transfer Parameters

The following table describes interface-specific parameters to the Web service(s) for connections. They are specific to each instance of a connection to an agent, and are specific to the network interface that is used in order to make the connection. Note that all property names require the following prefix:

com.signiant.interactivetransfer.connection.interface

Property  Value

display_name

The human-readable name assigned to the network adapter. On Microsoft Windows this is a long name such as "Ethernet adapter Wireless Network Connection".  This value is not present if the Java version is less than 1.6.

Syntax:

com.signiant.interactivetransfer.connection.interface.display_name=eth0

inet_address

The IPv4 or IPv6 address assigned to the network adapter that is being used to connect to the agent.

Syntax:

com.signiant.interactivetransfer.connection.interface.inet_address=192.168.0.1

inet_host_name

The host name associated with the host address of the network adapter. If the host name lookup fails, the address is passed in this field.

Syntax:

com.signiant.interactivetransfer.connection.interface.inet_host_name=client.signiant.com

mac_address

The MAC address of this network adapter. This defaults to "unknown" if the Java version is less than 1.6, or the MAC address cannot be inspected due to system security restrictions, or is not available due to the adapter being virtual.

Syntax:

com.signiant.interactivetransfer.connection.interface.mac_address=00:50:56:c0:00:01

name

The OS specific name for this adapter. On Linux this is typically in the form "eth0". This value is not present if the Java version is less than 1.6.

Syntax:

com.signiant.interactivetransfer.connection.interface.name=eth0

Java-Specific Transfer Parameters

The following table describes Java-specific parameters to the Web service(s) for connections.  They are specific to the client Java Virtual Machine that is executing the SDK.

Property Value

java.version

The version of Java that is running the SDK.

Syntax:

java.version=1.5.0_19

os.arch

The CPU architecture for the system that is running the SDK.

Syntax:

os.arch=x86

os.name

The name of the operating system that is running the SDK.

Syntax:

os.name=Linux

os.version

The version of the operating system that is running the SDK.

Syntax:

os.version=2.6.28-13-generic

Running the Obfuscator

Once you have created your property list, you may choose to compile it into a single obfuscated string. In addition to the default (Obfuscator.java). The following obfuscation types are now supported, when the first five characters of the properties are the following:

  • HTTP: download the config file from the specified URL (e.g., HTTP:https://127.0.0.1/config.txt)
  • OBFS: the original default obfuscator
  • RURL: relative URL - download the config file from the same website as the applet, but using the specified relative path (e.g., RURL:/configs/config.txt). The relative URL must be base-64 encoded.
  • TEXT: the text that follows is the configuration properties themselves. For this method, follow these guidelines:
    • there can be no "\r" characters anywhere in the text file
    • All fields with "\n" in their values must be escaped to be "\\n"
    • All fields should appear on one line, each line separated by a normal "\n"

Values returned when using HTTP, RURL or TEXT must be in clear (plain) text. They cannot be obfuscated.

To run the obfuscator, do the following: Extract the Obfuscator class from the Signiant Content Transfer Engine SDK ".war" file:

jar xvf <path/to>signiant_content_transfer_engine_sdk.war WEB-INF/classes/com/signiant/interactivetransfer/Obfuscator.class jar xvf <path/to>signiant_content_transfer_engine_sdk.war WEB-INF/classes/com/signiant/interactivetransfer/Obfuscator$Field Handler.class

Run the Obfuscator as follows:

java -cp WEB-INF/classes com/signiant/interactivetransfer/Obfuscator <path/to>Config.file

The following methods in the Obfuscator class allow you to compile the string:

  • void load (String path) throws IOException

    Load the properties from the Java property list file specified by the path parameter.

  • String getObfuscatedProperties ()

    Get the compiled, obfuscated configuration string to pass to the application or applet.

The following is an example of an obfuscator string:

// compile an obfuscation string from a property list file Obfuscator obfuscator = new Obfuscator(); try { obfuscator.load("ITC-config.prop"); } catch (IOException ex) { // handle error } String config = obfuscator.getObfuscatedProperties();

Running the Obfuscator From the Command Line

  1. Locate the file signiant_content_transfer_engine_sdk.war. This is located in the folder <JAVA_HOME>/server/default/deploy/ where <JAVA_HOME> defaults to /usr/signiant/dds/3rdparty/jboss on Linux
  2. Unzip this file into a temporary folder (<TEMP_FOLDER>).
  3. Issue the command:

    java -classpath <TEMP_FOLDER>/WEB-INF/classes com.signiant.interactivetransfer.Obfuscator <input file> <output file>

For example:

java -classpath /NetApp/users/ayates/war/WEB-INF/classes/ com.signiant.interactivetransfer.Obfuscator emapsigniant.cfg output.cfg

Setting the HTTP Server Debug Level

This procedure explains how to set the server debug level via the command line and in the dds.conf file. Changes to the dds.conf (via dds_admin or by editing the file) take effect immediately. No server restart is required. All logs go to the log/prtcl_servers directory in the following format: dds_http_server-YYYY-MM-DD.log.

Even without component tracing turned on, there is a minimal set of information logged to the file, including a "Health Check" which reports every 15 minutes. To set the HTTP server debug level via the command line, follow these steps:

  1. Start dds_admin:

    $> dds_admin > set trace_comp dds_http_server > quit

You can also edit the dds.conf (dds.cfg) file (located in /etc/dds.conf) in a text editor, and add the following line:

Components to trace: dds_http_server

Detecting Java

For the best possible user experience, the web application encompassing the CTE should check the Java has been installed. The example below used the Oracle Java Detection toolkit, from http://www.java.com/js/deployJava.txt.

// Try to detect the installed versions of Java using the Java Deployment Toolkit Script (deployJava.js) var minimumJavaVersionInstalled = deployJava.versionCheck('1.5.0_12+'); // If the detection call detects that Java is installed, still try to establish connectivity with our applet. // Under Mac OS X 10.7, the browser will report that Java is available even though it isn't. if (minimumJavaVersionInstalled) { Signiant.util.applet.onAppletReady('transferEngine', function() { // Established connectivity, hide applet window appletWrapEl.dom.style.left = ''; appletWrapEl.dom.style.top = ''; appletWrapEl.addClass('mx-applet-hidden'); }, this, null, function() { // Could not establish connectivity, display error this.updateJavaAppletPanel();    var javaPanel = this.getJavaCompatibilityPanel(); var headerPanel = Ext.getCmp('mx-header-panel-ct');  headerPanel.add(javaPanel); headerPanel.ownerCt.doLayout(); }); } else {   this.updateJavaAppletPanel();  var javaPanel = this.getJavaCompatibilityPanel(); this.extraHeaderPanels = [javaPanel]; }

Launching Content Transfer Engine SDK Transfer Engine from Command Line

Before you can launch the Content Transfer Engine SDK transfer engine from the command line, you need to save a config file. To do so, follow these steps:

  1. From the Manager, select Developer>CTE Test Configurations.
  2. Click the disk icon next to the configuration file you want to save.
  3. Note the location to which you saved the config file.

On your Linux Manager, presuming you are installed in /usr/signiant/dds, type the following:

/usr/signiant/dds/3rdparty/jdk/jdk-<version>/jre/bin/java /usr/signiant/dds/3rdparty/tomcat/webapps/signiant_ content_transfer_engine_sdk /secure/webclient/webclient.jar com.signiant.interactivetransfer.engine.TransferEngine

<path_to_your_config_file.here>

On Windows, type the following:

C:\Program Files\Signiant\Mobilize\3rdparty\jdk\bin\java -cp C:\Program Files\Signiant\Mobilize\3rdparty\tomcat\webapps\ signiant_content_transfer_engine_sdk \secure\webclient\webclient.jar com.signiant.interactivetransfer.engine.TransferEngine

<path_to_your_config_file.here>

As long as you have a current version of Java on the filesystem of the computer on which you want to run, all you need to do is copy the webclient.jar from the Manager, and you can run it on another machine.


CTE SDK Sample Parameters

Sample Configuration File

                #Signiant Transfer Agent Settings 
#Fri Jul 14 11:02:23 EDT 2006 
com.signiant.interactivetransfer.engine.ca_certificate=-----BEGIN CERTIFICATE----- 
\r\nMIIFVDCCBDygAwIBAgIBADANBgkqhkiG9w0BAQQFADCBtTELMAkGA1UEBhMCV 
VMx\r\nFjAUBgNVBAgTDU1hc3NhY2h1c2V0dHMxEzARBgNVBAcTCkJ1cmxpbmd0b24 
xFjAU\r\nBgNVBAoTDVNpZ25pYW50IEluYy4xHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1 
dGhv\r\ncml0eTFBMD8GA1UEAxM4b3R0cWExMGEub3R0LnNpZ25pYW50LmNvbSBE 
VE0gQ2Vy\r\ndGlmaWNhdGUgQXV0aG9yaXR5c2FtbXkwHhcNMDYwNjIwMDQwMDAx 
WhcNMTYwNjE5\r\nMDQwMDAxWjCBtTELMAkGA1UEBhMCVVMxFjAUBgNVBAgTDU1 
hc3NhY2h1c2V0dHMx\r\nEzARBgNVBAcTCkJ1cmxpbmd0b24xFjAUBgNVBAoTDVNpZ 
25pYW50IEluYy4xHjAc\r\nBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhvcml0eTFBMD8GA1 
UEAxM4b3R0cWExMGEu\r\nb3R0LnNpZ25pYW50LmNvbSBEVE0gQ2VydGlmaWNhdG 
UgQXV0aG9yaXR5c2FtbXkw\r\nggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB 
AQC9yh0J20lWVshaxNeRO3JY\r\nbJa7J6DjOrjC7t87BHISPsu6q6ugkTbDL2rdOOWov 
W52ARyqs3y+rvmdsiE2UdMG\r\niinRKouszgneQhp2EHewG807gMkUMLVtqvFyixvatP 
bBszoCVknf5R12zInbxvPg\r\n+IulxsOJ3uH5AChADpVtTCpWFSDwVIVHNuDMZUBt3tyc 
zEVB2OMm95H08fveAqdC\r\nlBrB72uHt2IYX9eZG1ap67wWlB2RYg0KpOQfhmqjYbFb 
wVhq+TGIWuTaxPMg9ft3\r\nOoR2TMuinuuJihNX3o0uAkaCJc7a31grjO7yK6htqA/CNyv 
o8SCuJ/6nmjGnFLZz\r\nAgMBAAGjggFrMIIBZzAPBgNVHRMBAf8EBTADAQH/MBEGC 
WCGSAGG+EIBAQQEAwIC\r\nBDALBgNVHQ8EBAMCAQYwMAYJYIZIAYb4QgENBCM 
WIVRydXN0ZWQgRERTIENlcnRp\r\nZmljYXRlIEF1dGhvcml0eTAdBgNVHQ4EFgQU2jm 
j7l5rSw0yVb/vlWAYkK/YBwkw\r\ngeIGA1UdIwSB2jCB14AU2jmj7l5rSw0yVb/vlWAYkK/ 
YBwmhgbukgbgwgbUxCzAJ\r\nBgNVBAYTAlVTMRYwFAYDVQQIEw1NYXNzYWNodX 
NldHRzMRMwEQYDVQQHEwpCdXJs\r\naW5ndG9uMRYwFAYDVQQKEw1TaWduaWFu 
dCBJbmMuMR4wHAYDVQQLExVDZXJ0aWZp\r\nY2F0ZSBBdXRob3JpdHkxQTA/BgNV 
BAMTOG90dHFhMTBhLm90dC5zaWduaWFudC5j\r\nb20gRFRNIENlcnRpZmljYXRlIEF1 
dGhvcml0eXNhbW15ggEAMA0GCSqGSIb3DQEB\r\nBAUAA4IBAQAPaCs+cO6B1IOB7 
witfRyPXoG9CbIQ9Th0FikIN7lS1BGbMjYVzSdd\r\nHseQ2ZLstfETlPASst0JT2ARrHsitK 
bECzLJ3+D8n5s91LahtuAetc3P1tVZrnRd\r\n7/yLboK57pXlVfEcz1ps3vfa8xyDMYiQ/WD 
unhoxPTPhRIM2c9lym6zMZ7/Eqj84\r\naCl3FCn1nKbkZ4JJ5q2V7CjFklnQ8goTE8B2L7 
Cu1LTa1Bjl4UBd4Dqz8WW0IgrQ\r\nBidQFigc6NLRMVuZs/Z7aYov8cYEEbX/xLzqgmpw 
g4fLMLD6SvzqA4Ob0g2tJ7ST\r\nMHWFXX5ZF3JN5zXP6mW/JDNCPpgX0wUp\r\n----- 
END CERTIFICATE----- 

com.signiant.interactivetransfer.engine.user=qatest 

com.signiant.interactivetransfer.engine.agent_list=host-domain2.somewhere.com 

com.signiant.interactivetransfer.engine.files=c\:\\tmp\\qa\\files\\file.100m

com.signiant.interactivetransfer.engine.destination_dir=/tmp/qa/targ 

com.signiant.interactivetransfer.engine.udp.aggressiveness=2 

com.signiant.interactivetransfer.engine.logging=fine 

com.signiant.interactivetransfer.applet.show_fields=com.signiant.interactivetransfer.e 
ngine.mode\ncom.signiant.interactivetransfer.engine.agent_list\ncom.signiant.interact 
ivetransfer.engine.user\ncom.signiant.interactivetransfer.engine.password\ncom.signi 
ant.interactivetransfer.engine.files\ncom.signiant.interactivetransfer.engine.destinatio 
n_dir\ncom.signiant.interactivetransfer.engine.ca_certificate\ncom.signiant.interactive 
transfer.engine.retries\ncom.signiant.interactivetransfer.engine.restarts\ncom.signiant 
.interactivetransfer.engine.udp.target_rate\ncom.signiant.interactivetransfer.engine.ud 
p.minimum_rate\ncom.signiant.interactivetransfer.engine.udp.aggressiveness\ncom.si 
gniant.interactivetransfer.engine.streams\ncom.signiant.interactivetransfer.engine.ban 
dwidth_throttle\ncom.signiant.interactivetransfer.engine.encrypt\ncom.signiant.intera 
ctivetransfer.engine.logging\ncom.signiant.interactivetransfer.engine.trace 

com.signiant.interactivetransfer.engine.password=testing 

com.signiant.interactivetransfer.engine.bandwidth_throttle=0 

com.signiant.interactivetransfer.engine.restarts=0 

com.signiant.interactivetransfer.engine.streams=8 

com.signiant.interactivetransfer.engine.retries=0 

com.signiant.interactivetransfer.engine.encrypt=false 

com.signiant.interactivetransfer.engine.mode=RECEIVE 

com.signiant.interactivetransfer.engine.trace=true 

com.signiant.interactivetransfer.applet.edit_fields=com.signiant.interactivetransfer.en 
gine.user\ncom.signiant.interactivetransfer.engine.password\ncom.signiant.interactiv 
etransfer.engine.files\ncom.signiant.interactivetransfer.engine.destination_dir\ncom.si 
gniant.interactivetransfer.engine.ca_certificate\ncom.signiant.interactivetransfer.engin 
e.retries\ncom.signiant.interactivetransfer.engine.restarts\ncom.signiant.interactivetra 
nsfer.engine.udp.aggressiveness\ncom.signiant.interactivetransfer.engine.streams 

com.signiant.interactivetransfer.engine.url_list=http://web-server/downloads

com.signiant.interactivetransfer.engine.udp.target_rate=100000000 

com.signiant.interactivetransfer.engine.transport=TCP 

com.signiant.interactivetransfer.engine.udp.minimum_rate=5000000   
                   
                          

Sample HTML Markup for Content Transfer Engine SDK Applet

The following example shows the HTML markup required to embed the Content Transfer Engine SDK applet in a Web page, ensuring that it will operate properly on different browser platforms, and that compatible browsers will download the required Java Runtime Environment (JRE) automatically. Substitute the obfuscated configuration string you created for "<<CONFIG>>" (note that the value appears twice):

<html> 

<head> 

<meta http-equiv='content-type' content='text/html; charset=UTF-8'>

<title>Interactive Transfer / 6.1 DTM</title> 

</head> 

<body resizeTo(490,200)"> 

<object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93" 
name="interactivetransfer" width="100%" height="100%" 
codebase="https://java.sun.com/update/1.5.0/jinstall-1_5_0_03-windows- 
i586.cab#Version=1,5,0,0"> 

<param name="code" value="com.signiant.interactivetransfer.TransferApplet.class" >

<param name="java_code" 
value="com.signiant.interactivetransfer.TransferApplet.class"> 

<param name="java_archive" value="/signiant/secure/webclient/webclient.jar"> 

<param name="type" value="application/x-java-applet;version=1.5"> 

<param name="autoexec" value="true"> 

<param name="autostart" value="-1"> 

<param name=".config" value="<<CONFIG>>"> 

<param name="mayscript" value="true"> 

<param name="scriptable" value="true"> 

<param name="bgColor" value="[000000]"> 

<param name="fgColor" value="[ffffff]"> 

<param name="onCancel" value="[client-side Java script]"> 

<param name="onClose" value="[client-side Java script]"> 

<param name="onComplete" value="[client-side Java script %status%]"> 

<param name="onConnection" value="[client-side Java script %status% 
%sessionId%]"> 

<param name="onFile" value="[client-side Java script %name% %size% %state%]"> 

<param name="onInfo" value="[client-side Java script %msg%]"> 

<param name="onLess" value="[client-side Java script]"> 

<param name="onMore" value="[client-side Java script]"> 

<param name="onPause" value="[client-side Java script]"> 

<param name="onResume" value="[client-side Java script]"> 

<comment>

<embed type="application/x-java-applet;version=1.5" 

 id="interactivetransfer" 

 width="100%" 

 height="100%" 

 pluginspage="https://java.sun.com/j2se/1.5.0/download.html" 

 java_code="com.signiant.interactivetransfer.TransferApplet.class" 

 java_archive="/signiant/secure/webclient/webclient.jar" 

 autostart="-1"

 name="code" value="com.signiant.interactivetransfer.TransferApplet.class"  

 autoexec="true" 

 .config="<<CONFIG>>" 

 mayscript = "true" 

 scriptable = "true" />

<noembed> 

This application requires a Java Runtime Plug-in. 

</noembed> 

</comment> 

</object> 

</body> 
</html> 
 

The following table describes the parameters in the above script:

Parameter Description
Java_code The name of the Java class to use as the "main" entry point for the applet.
Java_archive The URL of the Java archive (jar) that contains the binary code for the applet.
Type The mime type of the object (Java applet; minimum version).
autoexec Hint to the browser to allow the applet to start immediately after loading.
.config The obfuscated Signiant parameters for the Content Transfer Engine SDK applet to use.
mayscript Browser hint allowing applet to call JavaScript.
scriptable JRE hint allowing applet to call JavaScript.
bgColor The background color for the applet, specified as RGB in octal or hexadecimal. If not specified, the applet will use the current system user interface theme for the background.
fgColor The foreground color for the applet, specified as RGB in octal or hexadecimal. If not specified, the applet will use the current system user interface theme for the foreground.
cancelLabel The text for the "Cancel" button, specified as a literal string of text.  For example

 

<param name="cancelLabel" value="My Button">

 

will cause the cancel button to have the label "My Button" written on it instead of "Cancel".
onCancel The action that should occur upon the job being cancelled. User defines the action through a Java script.
onClose The action that should occur upon the applet being closed. User defines the action through a Java script.
OnComplete%status% The action that should occur upon the job being completed. The Java Engine will return the status of the job. User defines the action through a Java script. The following are allowed values for the %status% variable:

"cancelled" - indicates the file transfer was cancelled by the user

"failure" - indicates the file transfer was not successful

"incomplete" - indicates the file transfer is not yet completed

"successful" - indicates the file transfer was successful

"warning" - indicates the file transfer was successful, but there was a warning during the file transfer

onConnection %status% %sessionId% The action that should occur upon connection with the agent involved in the job. The Java Engine will return the status of the job and a session ID for the job. User defines the action through a Java script. The following are allowed values for the %status% variable:

"awaiting data streams"- indicates the TransferEngine is currently in the process of negotiating data streams with a remote connection

"connected" - indicates the TransferEngine is currently connected to a remote system

"connecting" - indicates the TransferEngine is currently in the process of connecting to a remote system

"disconnected" - indicates the TransferEngine is currently not connected

onFile %name% %size% %state% The action that should occur upon the file starting or completing. The Java Engine will return the name of the file, its size and state. User defines the action through a Java script. The following are allowed values for the %state% variable: "error" - indicates the file transfer did not complete successfully "pending" - indicates the file transfer has not yet started "skipped denied" - indicates the file transfer was denied by a SOAP server request "skipped exists"- indicates the file was not transferred because it already exists on the target with the same size "transferred" - indicates the file transfer completed successfully
onInfo %msg% The action that should occur upon a log being generated. The Java Engine will return the log message. User defines the action through a Java script.
onLess The action that should occur upon a user selecting the Less button on the applet. User defines the action through a Java script.
onMore The action that should occur upon a user selecting the More button on the applet. User defines the action through a Java script. Note that the "more" display shows only the first 30 files. After 30 files, it stops listing the files in the display, even if more files are being transferred.
onPause The action that should occur upon a job being paused. User defines the action through a Java script.
onResume The action that should occur upon a job being resumed. User defines the action through a Java script.

The java_archive value is dependant on your Web server configuration. For example, you might not run this off the Signiant Manager, but instead choose to copy the webclient.jar to your own Web server and have it download from there. In such a case, you will need to specify the path to the jar file as it exists on your Web server.

Parameters in the bottom half of the table, for which users provide a Java script, allow you to specify actions such as redirecting to another page, displaying a text message and so on. Any occurrences of variables will be replaced. Users can now customize the applet, giving them more control over it.

Sample Transfer

The following is a sample TransferDemo.java file:

import java.io.*; 
import java.util.*; 

import com.signiant.interactivetransfer.engine.FileTransfer; 
//import com.signiant.interactivetransfer.engine.FileTransfer.State; 
import com.signiant.interactivetransfer.engine.StatusEvent; 
import com.signiant.interactivetransfer.engine.TransferEngine; 
import com.signiant.interactivetransfer.engine.TransferListener; 
import com.signiant.interactivetransfer.engine.TransferMode; 
import com.signiant.interactivetransfer.engine.Transport; 
public class TransferDemo implements TransferListener 
{ 
static String certificate = "-----BEGIN CERTIFICATE----- 
\r\nMIIFBjCCA+6gAwIBAgIBADANBgkqhkiG9w0BAQQFADCBmzELMAkGA1UEBhMCVVMx\r\ 
nDjAMBgNVBAgTBVN0YXRlMQ0wCwYDVQQHEwRDaXR5MQ8wDQYDVQQKEwZOYXNoQ28 
x\r\nHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhvcml0eTE8MDoGA1UEAxMzb3R0d3Mx\r\nM 
mIub3R0LnNpZ25pYW50LmNvbSBEVE0gQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4X\r\nDT 
A2MTEyMTA1MDAwMVoXDTE2MTEyMDA1MDAwMVowgZsxCzAJBgNVBAYTAlVTMQ4w\r\n 
DAYDVQQIEwVTdGF0ZTENMAsGA1UEBxMEQ2l0eTEPMA0GA1UEChMGTmFzaENvMR4w\r\ 
nHAYDVQQLExVDZXJ0aWZpY2F0ZSBBdXRob3JpdHkxPDA6BgNVBAMTM290dHdzMTJi\r\nL 
m90dC5zaWduaWFudC5jb20gRFRNIENlcnRpZmljYXRlIEF1dGhvcml0eTCCASIw\r\nDQYJKoZ 
IhvcNAQEBBQADggEPADCCAQoCggEBAMfGiYr5z6FKn21YuRnokiZ6+bx+\r\nOtPwEiTeXlrH 
LSN38auxIYX9nMcKzny/IcOtFA7YVec+Hyc0sBYtA+PhIa0gDvvA\r\nnsj9T8F/QpCC4AzuD/jzp+ 
x2S6sjWFLy8rektKCUBOSdVxvOuv+7SVNqS3C6s9PK\r\nFrL4MYLKv3QgkadBRRMeeWI6uU
wO81D5tfoMGuwklGzvIqjA+CWFL48wNdJsPqzF\r\nQHTcbd8zfcnHV7b9/Joarly+aVxr2mQE5 
mVUhbyjf7e4b5oJ945X67mJhJT6yyBk\r\nkmsrkEj/00c58vE/5YSj406Ir/QT1WhwfkNrlFu+jTa/90 
d5x/3ic6WRlQcCAwEA\r\nAaOCAVEwggFNMA8GA1UdEwEB/wQFMAMBAf8wEQYJYIZIAYb4 
QgEBBAQDAgIEMAsG\r\nA1UdDwQEAwIBBjAwBglghkgBhvhCAQ0EIxYhVHJ1c3RlZCBERF 
MgQ2VydGlmaWNh\r\ndGUgQXV0aG9yaXR5MB0GA1UdDgQWBBTaOaPuXmtLDTJVv++VYBi 
Qr9gHCTCByAYD\r\nVR0jBIHAMIG9gBTaOaPuXmtLDTJVv++VYBiQr9gHCaGBoaSBnjCBmzE 
LMAkGA1UE\r\nBhMCVVMxDjAMBgNVBAgTBVN0YXRlMQ0wCwYDVQQHEwRDaXR5MQ8wD 
QYDVQQKEwZO\r\nYXNoQ28xHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhvcml0eTE8MDoG 
A1UEAxMz\r\nb3R0d3MxMmIub3R0LnNpZ25pYW50LmNvbSBEVE0gQ2VydGlmaWNhdGUgQ 
XV0aG9y\r\naXR5ggEAMA0GCSqGSIb3DQEBBAUAA4IBAQCzHPq97jXkxlv/8OcODWvkcPPtR 
jfH\r\nWaJOCZkuuxwNS3aTsttx38+yfRSNY7X9ArjrgK+6WWKM3afELLWWET5VkhoPksB9\r\n 
FEJVo2g4Dmfx0TmRflT0zTh7J8xHz7dvQf4RV3qKbQyjD7/tme7bKASIYdhajFaZ\r\ntDyyqwe+X 
PLpvNkSEhiGhgs1R41CqCuk1wZ1EyIm3oYMQ3oux0XuGj/yyKZ7KgCC\r\nP/s+kkQUXzR0Y7f 
45uO5aiORwE7CB+8rHBwitXTBlh/UyW3GbK8cwnaWFbWCwMYW\r\ntQQ81WWiNjTVGlqx07 
ppTwlotQ0VcFe1LxfrYdFjs7Ji5Fgpu2jpxAZD\r\n 
-----END CERTIFICATE-----"; 

static public String logging = 
"com.signiant.interactivetransfer.engine.ControlStream.level=FINE\ncom.signiant.interactive 
transfer.engine.DataStream.level=FINE\ncom.signiant.interactivetransfer.engine.Stream.level 
=FINE\ncom.signiant.interactivetransfer.engine.TransferEngine.level=FINE\nhandlers=java.ut 
il.logging.FileHandler,java.util.logging.ConsoleHandler\njava.util.logging.ConsoleHandler.lev 
el=ALL\njava.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter\nhand 
lers=java.util.logging.FileHandler\njava.util.logging.FileHandler.pattern=/tmp/my_log_file.log\ 
njava.util.logging.FileHandler.count=1\njava.util.logging.FileHandler.formatter=java.util.loggi 
ng.SimpleFormatter\njava.util.logging.FileHandler.level = ALL"; 

public Vector<FileTransfer> files; 
public Vector<String> errors; 

public TransferDemo () 
{ 
files = new Vector<FileTransfer>(); 
errors = new Vector<String>(); 
} 

public static void main(String[] args) { 

TransferEngine engine = new TransferEngine (); 
TransferDemo listener = new TransferDemo(); 
engine.setCertificate(certificate); 
engine.setMode(TransferMode.SEND);
engine.setTransport(Transport.TCP); 
engine.setAggressiveness(2); // 2 = Medium 
engine.addTransferListener(listener); 
engine.setLogging(logging); 

try 
{ 

LineNumberReader lr = new LineNumberReader(new 
InputStreamReader(System.in)); 

System.out.print("Please enter the target system: "); 
engine.setAgentList(lr.readLine()); 
System.out.print("Please enter the username: "); 
engine.setUser(lr.readLine()); 
System.out.print("Please enter the password: "); 
engine.setPassword(lr.readLine().toCharArray()); 
System.out.print("Please enter the target directory: "); 
engine.setDestination(lr.readLine()); 
System.out.println("Please enter the list of files to transfer.  Enter an 
empty line when done."); 

String input; 
List <String> filelist = new LinkedList <String> (); 
while(!"".equals(input = lr.readLine())) 
filelist.add(input); 

engine.setFiles(filelist.toArray(new String[0])); 
} catch (IOException inputError) 
{ 
System.out.println("Error reading input: "+inputError); 
} 

try 
{ 
engine.startTransfer ();
} 
catch (Exception e) 
{ 
System.err.println ("Exception caught initiating transfer: " + 
e.getMessage ()); 
System.exit (-1); 
} 

while ( ! engine.isCompleted() ) 
{ 
try { Thread.sleep(200); } catch (Exception discard) {} 
// Wait for the engine to load files prior to emitting any statistics 
if(engine.getTotalBytesToTransfer() == 0) 
continue; 

long percentComplete = 
(engine.getBytesSkipped()+engine.getBytesTransferred()) * 100 
/ engine.getTotalBytesToTransfer(); 
long transferRateKb = engine.getTransferRate() / 1024; 
System.out.print("Progress: " + percentComplete + "% - " + 
transferRateKb + " KBytes/s \r" ); 
} 

System.out.println("\n\nFile transfer summary report:"); 
for (int i = 0; i < listener.files.size(); i++) 
{ 
FileTransfer f = listener.files.elementAt(i); 
System.out.print("File: "+f.getFileString()); 
switch (f.getState()) 
{ 
case PENDING: 
System.out.println(" did not complete"); 
break; 
case SKIPPED_DENIED: 
System.out.println(" transfer denied"); 
break; 
case SKIPPED_EXISTS: 
System.out.println(" was already present on the remote system"); 
break; 
case TRANSFERRED:
System.out.println(" was successfully transferred"); 
break; 
case ERROR: 
System.out.println(" encountered an error during transfer"); 
break; 
} 
} 

CompletionStatus status = engine.getCompletionStatus(); 
switch (status) 
{ 
case SUCCESSFUL: 
break; 
case WARNING: 
case FAILURE: 
System.out.println("The following errors occurred during the 
transfer: "); 
for (int i = 0; i < listener.errors.size(); i++) 
System.out.println("  "+listener.errors.elementAt(i++)); 
break; 
} 

System.exit(0); 
} 

public void connectionStatusChange(ConnectionStatus status) 
{ 
System.out.println("Engine is now: "+status); 
} 

public void exception(Exception e) 
{ 
errors.add(e.getMessage()); 
} 
public void preTransfer() 
{ 
}
public void fileHeader(FileTransfer file) 
{ 
files.add(file); 
} 

public void preFile(FileTransfer file) 
{ 
} 

public void filePosition(FileTransfer file, long position) 
{ 
} 

public void fileProgress(FileTransfer file, long bytesSent) 
{ 
} 

public void skipFile(FileTransfer file) 
{ 
} 

public void postFile(FileTransfer file) 
{ 
} 

public void postTransfer(CompletionStatus status) 
{ 
} 

public void statusUpdate(StatusEvent status) 
{ 
System.out.println(status.getStatus()); 
} 
}

Multiple Transfers

import java.io.*;
import java.net.*;
import java.util.*;
import java.text.*;

import com.signiant.interactivetransfer.engine.*;

public class MxUpload implements TransferListener{

 public static void main(String args []){
  int maxFiles = 5;

  String configFile = args[0];
  String uploadDir = args[1];

  System.out.println("Config = " + configFile);
  System.out.println("Dir    = " + uploadDir);

  File dirObj = new File(uploadDir);
  File[] dirContents = dirObj.listFiles();

  TransferEngine[] engines = new TransferEngine[dirContents.length];
  MxUpload[] listeners = new MxUpload[dirContents.length];

  try{
   for(int i = 0; i < dirContents.length && i < maxFiles; i++){
	String theFile = dirContents[i].getAbsolutePath();

	System.out.println("file # " + i + " = " + theFile);

	engines[i] = new TransferEngine();
	listeners[i] = new MxUpload();

	engines[i].loadSettings(new File(configFile));
	engines[i].setFiles(new String[]{theFile});
	engines[i].addTransferListener(listeners[i]);
	engines[i].startTransfer();
   }//for  
			
   long maxTransferRateKbits = 0l;

   int stillRunning = engines.length;
   while(stillRunning > 0){
	try { Thread.sleep(1000); } catch (Exception discard) {}

	stillRunning = 0;

	long totalTransferRateKbits = 0l;
	String subRates = "";

	for(int i = 0; i < engines.length; i++){
	 if(! engines[i].isCompleted()){
	  stillRunning++;
	  if(engines[i].getTotalBytesToTransfer() != 0){

		long percentComplete = (engines[i].getBytesSkipped() + engines[i].getBytesTransferred()) * 100
		/ engines[i].getTotalBytesToTransfer();

		long transferRateKbits = engines[i].getTransferRate() / 1024 * 8;

		totalTransferRateKbits += transferRateKbits;

		if(! subRates.equals("")) subRates += " + ";
		subRates += commaFormat(transferRateKbits);

//	  System.out.println("Progress [" + i + "] : " + percentComplete + "% @ " + transferRateKbits + " Kbits/s");
	  }//if
     }//if
	 try { Thread.sleep(200); } catch (Exception discard) {}
	}//for

	if(totalTransferRateKbits > maxTransferRateKbits) maxTransferRateKbits = totalTransferRateKbits;

	System.out.println("Overall Rate for " + stillRunning + " tranfers : " + commaFormat(totalTransferRateKbits)
	+ " Kbits (" + subRates + ")");
	 }//while
			
	   System.out.println("Max Rate : " + commaFormat(maxTransferRateKbits));

	   }catch (Exception e){
		 System.err.println("Exception caught while performing transfer:  " + e.getMessage());
		 e.printStackTrace();
		 System.exit(1);
	  }// t/c

		for(int i = 0; i < engines.length; i++) engines[i].release();

		System.exit(0);
	}

	public MxUpload(){}

	public void exception(Exception e){
		System.out.println("ERROR : " + e.getMessage());
	}

	public void fileHeader(FileTransfer file){}
	public void connectionStatusChange(ConnectionStatus status){}
	public void statusUpdate(StatusEvent status){}
	public void preTransfer(){}
	public void preFile(FileTransfer file){}
	public void filePosition(FileTransfer file, long position){}
	public void fileProgress(FileTransfer file, long bytesSent){}
	public void skipFile(FileTransfer file){}
	public void postFile(FileTransfer file){}
	public void postTransfer(CompletionStatus status){}

	private static String commaFormat(long theNumber){
		String returnString = "";
		String outFormatString = "#,###";
		try{
			DecimalFormat theFormat = new DecimalFormat(outFormatString);
			return theFormat.format(theNumber);
		}catch(Exception ex2){}//try
		return "";
	}
}
  

Sample Fallback URL Implementations

The following outlines three different fallback URL scenarios with examples of how to implement them.

Try All Simultaneously

This example shows how to configure Signiant Content Transfer Engine SDK to try all the protocols at the same time, and select the first one to respond. These should appear on the same line, separated by the "|" symbol.

mxwan://srv6.somewhere.com|mxtcp://srv6.somewhere.com|http://srv6.somewhere.com:8080

UDP then HTTP

This example shows how to configure Signiant Content Transfer Engine SDK to try the UDP protocol, and then fallback to HTTP if UDP is not available.

mxwam://srv6.somewhere.com http://srv6.somewhere.com:8080

UDP then TCP then HTTP

This example shows how to configure Signiant Content Transfer Engine SDK to try the UDP protocol first, then fallback to TCP if UDP is not available, then fallback to HTTP if neither UDP nor TCP are available.

mxwan://srv6.somewhere.com mxtcp://srv6.somewhere.com http://srv6.somewhere.com:8080


SOAP Authentication

The following describes the SOAP APIs between the remote Content Transfer Engine SDK transfer server agent and the SOAP server associated with it. The Simple Object Access Protocol (SOAP) allows a client to communicate programmatically with a Signiant Agent over the HTTP protocol and execute APIs. The events that are processed using SOAP are:

  • Content Transfer Engine SDK connection to the agent
  • begin uploading a file
  • begin downloading a file
  • file transfer completed successfully
  • file transfer completed in error
  • Content Transfer Engine SDK disconnect from the agent

Note that there is only one response from the SOAP server for each call.

If your SOAP server requires a namespace to be supplied with SOAP calls to the server, you must fill in the correct namespace/urn using these parameters, and add them to the signiant.ini file.

signiant.ini File

The signiant.ini file is the configuration file used for the Content Transfer Engine SDK transfer server. This is a typical configuration file, with ITEM = value pairs specified one per line. Blank lines and lines beginning with the "#" character are ignored. When a user selects SOAP as the authentication method for a Content Transfer Engine SDK transfer, the GUI auto-inserts the following parameters into the signiant.ini file. These parameters are the relevant URLs called for each SOAP method:

ITC_AUTHENTICATE_URLS=https://agent1/signiant/services/InteractiveTransferService ITC_BEGIN_FILE_URLS=https:// agent1/signiant/services/InteractiveTransferService ITC_RENAME_FILE_URLS=https:// agent1/signiant/services/InteractiveTransferService ITC_END_FILE_URLS=https:// agent1/signiant/services/InteractiveTransferService ITC_DISCONNECT_URLS=https:// agent1/signiant/services/InteractiveTransferService

The following values are NOT auto-inserted, and are not configurable via the Signiant Manager Web interface. If your SOAP server requires a namespace to be supplied with SOAP calls to the server, you must fill in the correct namespace/urn using these parameters, and add them to the signiant.ini file. For example, if your SOAP server is based on JBOSS (jboss.org), you MUST add these parameters to the signiant.ini file so that they are sent to the URI of the namespace. The signiant.ini file exists in the following directory of the Content Transfer Engine SDK server

(i.e., c:\program files\signiant\mobilize\3rdparty\tomcat\webapps\signiant\secure\hosts)

ITC_AUTHENTICATE_URI=https:// agent1/signiant/services/InteractiveTransferService ITC_DISCONNECT_URI=https:// agent1/signiant/services/InteractiveTransferService ITC_RENAME_FILE_URI=https:// agent1/signiant/services/InteractiveTransferService ITC_END_FILE_URI=https:// agent1/signiant/services/InteractiveTransferService ITC_BEGIN_FILE_URI=https:// agent1/signiant/services/InteractiveTransferService

SOAP Methods

The following describe the methods called by Content Transfer Engine SDK on the SOAP server at different points during the transfer.

ITC_Authenticate

The ITC_Authenticate method is called at the beginning of a transfer, and again on a network retry.

METHOD NAME: ITC_Authenticate

This method verifies authentication for the Content Transfer Engine SDK transfer job.

Input Parameter

string properties: A "name=value" list of agent properties, separated by a new line.

The following is an example of a SOAP envelope for the ITC_Authenticate call:

 <?xml version="1.0" encoding="UTF-8" ?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
  <ITC_Authenticate xmlns="http://myserver/myurn">
  <properties xmlns="" xsi:type="xsd:string">com.signiant.interactivetransfer.connection.agent=agent1.acme.com 
  com.signiant.interactivetransfer.connection.control_stream=true com.signiant.interactivetransfer.connection.fallback=
  false com.signiant.interactivetransfer.connection.itc_host=agent1.acme.com 
  com.signiant.interactivetransfer.connection.itc_ip=127.0.0.1 com.signiant.interactivetransfer.connection.port=49221 
  com.signiant.interactivetransfer.connection.relay_address=relayhost.acme.com 
  com.signiant.interactivetransfer.connection.relay_port=49221 com.signiant.interactivetransfer.connection.restarted=0
  com.signiant.interactivetransfer.connection.session_id= com.signiant.interactivetransfer.connection.transport=TCP 
  com.signiant.interactivetransfer.engine.agent_list=agent1acme.com 
  com.signiant.interactivetransfer.engine.ca_certificate=
  -----BEGIN CERTIFICATE----\nMIIENzCCAx+gAwIBAgIBDDANBgkqhkiG9w0BAQQFADCBjjELMAkGA1UEBhMCQ0E 
  xEDAOBgNVBAgTB09udGFyaW8xDzANBgNVBAcTBk90dGF3YTENMAsGA1UEChMERE 
  VNTzEUMBIGA1UECxMLU2lnbmlhbnQgSVQxNzA1BgNVBAMTLlNpZ25pYW50IE1vYmls
  aXplIERFTU8gQ0Egb24gZGVtby5zaWduaWFudC5jb20wHhcNMDcwMjIxMDUwMDAxWhc
  NMDgwMjIxMDUwMDAxWjBxMQswCQYDVQQGEwJDQTEQMA4GA1UECBMHT250YX 
  JpbzEPMA0GA1UEBxMGT3R0YXdhMQ0wCwYDVQQKEwRERU1PMQ0wCwYDVQQLEw 
  RERU1PMSEwHwYDVQQDExhvdHR3czU4Lm90dC5zaWduaWFudC5jb20wgZ8wDQYJKoZ 
  IhvcNAQEBBQADgY0AMIGJAoGBANzJVNVj3dzo03E84W9qPFK+KL3DkMBMDFpqfjaw3
  o7gYpjjL2dGVT5+EGX1C2Lg8hXRD1tF2Nsn7XoeixlfIRMFq1r4vF7sphNpYmDhLDSosEMu 
  wrfptu4et7jxf/poiuNquh7YfxmfcDVJ/70lXa+p9CVK5aFShTL1bCpmIPxRAgMBAAGjggE+MI 
  IBOjAJBgNVHRMEAjAAMBEGCWCGSAGG+EIBAQQEAwIGwDALBgNVHQ8EBAMCBe 
  AwMAYJYIZIAYb4QgENBCMWIVRydXN0ZWQgRERTIENlcnRpZmljYXRlIEF1dGhvcml0 
  eTAdBgNVHQ4EFgQUjWYbGuxaS9HJ7RrIT38ESRKqpB0wgbsGA1UdIwSBszCBsIAU2jmj7
  l5rSw0yVb/vlWAYkK/YBwmhgZSkgZEwgY4xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEw 
  dPbnRhcmlvMQ8wDQYDVQQHEwZPdHRhd2ExDTALBgNVBAoTBERFTU8xFDASBgNVB 
  AsTC1NpZ25pYW50IElUMTcwNQYDVQQDEy5TaWduaWFudCBNb2JpbGl6ZSBERU1PIE 
  NBIG9uIGRlbW8uc2lnbmlhbnQuY29tggEAMA0GCSqGSIb3DQEBBAUAA4IBAQDC0PTP25 
  F3fDSxhHisz0schZ9iHkLwrXMVEodJTk16eFY/W0rUPj0p4wBJ/zBX+kwtl0h3PNrmbI678qIsb 
  Bfw+UDh0dSSTmdVjjf2IYGqYEsY+wcS4/24LSyxqt5z4ZLSH3qOuEtj0AZLiTOmRth3UPUzz 
  1rev2bHD0/eeeLDHwlhRb48X4ZIzo6xtxOdQJISgsZmxZCg2hDIUVqfF7IFLdiZFBV4cZUzFH 
  A67FcFEqDwgsym5ZfzemYj+TkoVZeyZg26ikX0bVRlZuod8TpZgGygZjpjE8kf3UJzcsvg3lOB
  B+sqyeXkSiNumzprYEzTQtIciRI51i1Bdav1xYp\n
  -----END CERTIFICATE----
  \n com.signiant.interactivetransfer.engine.destination_dir=/tmp com.signiant.interactivetransfer.engine.encrypt=STRONG 
  com.signiant.interactivetransfer.engine.files=/home/testing/source/chunks/10m.dat 
  com.signiant.interactivetransfer.engine.logging=finest com.signiant.interactivetransfer.engine.mode=SEND 
  com.signiant.interactivetransfer.engine.password=emca com.signiant.interactivetransfer.engine.session_id=
  NDAxOTM0NjEzNTExNzc3MDI0MjQ= com.signiant.interactivetransfer.engine.streams=1  
  com.signiant.interactivetransfer.engine.trace=-trace com.signiant.interactivetransfer.engine.transport=TCP
  com.signiant.interactivetransfer.engine.udp.aggressiveness=3 com.signiant.interactivetransfer.engine.user=
  admin</properties> 
  </ITC_Authenticate>
  </soap:Body>
  </soap:Envelope>  

Output Parameter

The output parameter for ITC_Authenticate is a complex type with the following key value pairs:

string properties: A copy of the properties string sent to the SOAP server, with values changed as required. For example, the application has generated a unique session_ID (1234), but you want to change it to ABC, you would set the session_ID to ABC in the properties string.

string allow: The literal string "Y" if authentication was successful, or "N" if authentication is denied.

The following is an example SOAP envelope of the server response to an ITC_Authenticate call:

  <?xml version="1.0" encoding="UTF-8" ?> 
    <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
     http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
     http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
     <soap:Body>
     <ITC_AuthenticateResponse xmlns="http://myserver/myurn">
     <s-gensym72>
     <allow xsi:type="xsd:string">Y</allow> 
     <properties xsi:type="xsd:string">com.signiant.interactivetransfer.connection.agent=agent1.acme.com 
     com.signiant.interactivetransfer.connection.control_stream=true 
     com.signiant.interactivetransfer.connection.fallback=false com.signiant.interactivetransfer.connection.itc_host=
     agent1.acme.com com.signiant.interactivetransfer.connection.itc_ip=127.0.0.1 
     com.signiant.interactivetransfer.connection.port=49221 com.signiant.interactivetransfer.connection.relay_address=
     relayhost.acme.com com.signiant.interactivetransfer.connection.relay_port=49221 
     com.signiant.interactivetransfer.connection.restarted=0 com.signiant.interactivetransfer.connection.session_id= 
     com.signiant.interactivetransfer.connection.transport=TCP com.signiant.interactivetransfer.engine.agent_list=
     agent1acme.com com.signiant.interactivetransfer.engine.ca_certificate=
     -----BEGIN CERTIFICATE----
     \nMIIENzCCAx+gAwIBAgIBDDANBgkqhkiG9w0BAQQFADCBjjELMAkGA1UEBhMCQ0E 
     xEDAOBgNVBAgTB09udGFyaW8xDzANBgNVBAcTBk90dGF3YTENMAsGA1UEChMERE 
     VNTzEUMBIGA1UECxMLU2lnbmlhbnQgSVQxNzA1BgNVBAMTLlNpZ25pYW50IE1vYmls 
     aXplIERFTU8gQ0Egb24gZGVtby5zaWduaWFudC5jb20wHhcNMDcwMjIxMDUwMDAxWhc 
     NMDgwMjIxMDUwMDAxWjBxMQswCQYDVQQGEwJDQTEQMA4GA1UECBMHT250YX 
     JpbzEPMA0GA1UEBxMGT3R0YXdhMQ0wCwYDVQQKEwRERU1PMQ0wCwYDVQQLEw 
     RERU1PMSEwHwYDVQQDExhvdHR3czU4Lm90dC5zaWduaWFudC5jb20wgZ8wDQYJKoZ 
     IhvcNAQEBBQADgY0AMIGJAoGBANzJVNVj3dzo03E84W9qPFK+KL3DkMBMDFpqfjaw3 
     o7gYpjjL2dGVT5+EGX1C2Lg8hXRD1tF2Nsn7XoeixlfIRMFq1r4vF7sphNpYmDhLDSosEMu 
     wrfptu4et7jxf/poiuNquh7YfxmfcDVJ/70lXa+p9CVK5aFShTL1bCpmIPxRAgMBAAGjggE+MI 
     IBOjAJBgNVHRMEAjAAMBEGCWCGSAGG+EIBAQQEAwIGwDALBgNVHQ8EBAMCBe 
     AwMAYJYIZIAYb4QgENBCMWIVRydXN0ZWQgRERTIENlcnRpZmljYXRlIEF1dGhvcml0 
     eTAdBgNVHQ4EFgQUjWYbGuxaS9HJ7RrIT38ESRKqpB0wgbsGA1UdIwSBszCBsIAU2jmj7 
     l5rSw0yVb/vlWAYkK/YBwmhgZSkgZEwgY4xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEw 
     dPbnRhcmlvMQ8wDQYDVQQHEwZPdHRhd2ExDTALBgNVBAoTBERFTU8xFDASBgNVB
     AsTC1NpZ25pYW50IElUMTcwNQYDVQQDEy5TaWduaWFudCBNb2JpbGl6ZSBERU1PIE 
     NBIG9uIGRlbW8uc2lnbmlhbnQuY29tggEAMA0GCSqGSIb3DQEBBAUAA4IBAQDC0PTP25
     F3fDSxhHisz0schZ9iHkLwrXMVEodJTk16eFY/W0rUPj0p4wBJ/zBX+kwtl0h3PNrmbI678qIsb 
     Bfw+UDh0dSSTmdVjjf2IYGqYEsY+wcS4/24LSyxqt5z4ZLSH3qOuEtj0AZLiTOmRth3UPUzz 
     1rev2bHD0/eeeLDHwlhRb48X4ZIzo6xtxOdQJISgsZmxZCg2hDIUVqfF7IFLdiZFBV4cZUzFH 
     A67FcFEqDwgsym5ZfzemYj+TkoVZeyZg26ikX0bVRlZuod8TpZgGygZjpjE8kf3UJzcsvg3lOB 
     B+sqyeXkSiNumzprYEzTQtIciRI51i1Bdav1xYp\n
     -----END CERTIFICATE----
     \n com.signiant.interactivetransfer.engine.destination_dir=/tmp com.signiant.interactivetransfer.engine.encrypt=STRONG
     com.signiant.interactivetransfer.engine.files=/home/testing/source/chunks/10m.dat 
     com.signiant.interactivetransfer.engine.logging=finest com.signiant.interactivetransfer.engine.mode=SEND 
     com.signiant.interactivetransfer.engine.password=emca com.signiant.interactivetransfer.engine.session_id=
     NDAxOTM0NjEzNTExNzc3MDI0MjQ= com.signiant.interactivetransfer.engine.streams=1 
     com.signiant.interactivetransfer.engine.trace=-trace com.signiant.interactivetransfer.engine.transport=TCP 
     com.signiant.interactivetransfer.engine.udp.aggressiveness=3 com.signiant.interactivetransfer.engine.user=
     admin</properties> 
     </s-gensym72>
     </ITC_AuthenticateResponse>
     </soap:Body>
   </soap:Envelope>  
    

ITC_Begin_File

The ITC_Begin method is called at the start of a transfer, for each file.

METHOD NAME: ITC_Begin_File

This method provides information about starting the file transfer.

Input Parameter

  • string session_id: The session id associated with the respective authentication call.
  • string direction: The literal string "SEND" if the file transfer direction is from the Content Transfer Engine SDK agent to the transfer server, or "RECEIVE" if the direction is from the transfer server to the Content Transfer Engine SDK agent.
  • string source_path: The name of the file as it exists on the source side of the transfer.
  • number file_size: The size of the file in bytes (e.g., the number 1024 represents 1 kb).

The following is an example of a SOAP envelope for the ITC_Begin_File call:

 <?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ITC_Begin_File xmlns="http://myserver/myurn">
    <session_id xmlns="" xsi:type="xsd:string">NDAxOTM0NjEzNTExNzc3MDI0MjQ</session_id> 
    <direction xmlns="" xsi:type="xsd:string">SEND</direction> 
    <source_path xmlns="" xsi:type="xsd:string">./admin/10m.dat</source_path> 
    <file_size xmlns="" xsi:type="xsd:long">10485760</file_size> 
    </ITC_Begin_File>
    </soap:Body>
  </soap:Envelope>  

Output Parameter

string allow

The literal string "Y" if this file should be transferred, or "N" if the file transfer is denied.

The following is an example SOAP envelope of the server response to an ITC_Begin_File call:

 <?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ITC_Begin_FileResponse xmlns="http://myserver/myurn">
    <s-gensym78 xsi:type="xsd:string">Y</s-gensym78> 
    </ITC_Begin_FileResponse>
    </soap:Body>
  </soap:Envelope> 
 

ITC_Filter_File

The ITC_Filter_File method is called at the beginning of a transfer, and again on a network retry.  It is enabled by the ITC_Authenticate method. Enabling the filter file event prevents files from being restartable. Due to the nature of the content being transformed during transmission, it is not possible to pause, resume, or restart a transfer from any position other than the start of the file.

METHOD NAME: ITC_Filter_File

This method verifies authentication for the Content Transfer Engine SDK transfer job.

Input Parameter

  • string session_id: The session id associated with the respective authentication call.
  • string direction: The literal string "SEND" if the file transfer direction is from the Content Transfer Engine SDK agent to the transfer server, or "RECEIVE" if the direction is from the transfer server to the Content Transfer Engine SDK agent.

    Causing encryption to occur for "SEND" transfers means that the file becomes encrypted with the pass phrase prior to being written to the agent's file system.  This is probably not what was intended; the typical use case has the file in clear text on the agent's file system, and encrypted as the user receives the file.

  • string source_path: The name of the file as it exists on the source side of the transfer.

  • number file_size: The size of the file in bytes (e.g., the number 1024 represents 1 KByte).

The following is an example of a SOAP envelope for the ITC_Filter_File call:

 <?xml version="1.0" encoding="UTF-8" ?>
         <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-
         instance" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
         xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
            <soap:Body>
               <ITC_Filter_File xmlns="http://myserver/myurn">
               <session_id xmlns=""
		           xsi:type="xsd:string">NDAxOTM0NjEzNTExNzc3MDI0MjQ</session_id>
               <direction xmlns="" xsi:type="xsd:string">SEND</direction>
               <source_path xmlns="" 
		           xsi:type="xsd:string">./admin/10m.dat</source_path>
               <file_size xmlns="" xsi:type="xsd:long">10485760</file_size>
               </ITC_Filter_File>
            </soap:Body>
         </soap:Envelope>
    
 

Output Parameter

The output parameter for ITC_Filter_File is a complex type with the following keys: string encryption.passphrase

The actual pass phrase to use in order to encrypt the file contents using AES 256-bit encryption prior to transfer.  If a zero length pass phrase is returned, the file contents are not encrypted.

The following is an example SOAP envelope of the server response to an ITC_Filter_File call:

<?xml version="1.0" encoding="UTF-8" ?>
  <soap:Envelope
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
   <ITC_Filter_FileResponse xmlns="http://myserver/myurn">
     <s-gensym78 xsi:type="xsd:string">encryption.passphrase=My Secret
     </s-gensym78>
   </ITC_Filter_FileResponse>
   </soap:Body>
 </soap:Envelope>         
  

ITC_Rename_File

The ITC_Rename_File method is called at the start of the transfer, for each file.

METHOD NAME: ITC_Rename_File

This method provides information about renaming the transferred file.

Input Parameter

  • string session_id: The session id associated with the respective authentication call.
  • string direction: The literal string "SEND" if the file transfer direction is from the Content Transfer Engine SDK agent to the Content Transfer Engine SDK server, or "RECEIVE" if the direction is from the Content Transfer Engine SDK server to the Content Transfer Engine SDK agent.
  • string source_path: The name of the file as it exists on the source side of the transfer.
  • number file_size: The size of the file in bytes (e.g., the number 1024 represents 1 kb).

The following is an example of a SOAP envelope for the ITC_Rename_File call:

<?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
  <ITC_Rename_File xmlns="http://myserver/myurn">
  <session_id xmlns="" xsi:type="xsd:string">NDAxOTM0NjEzNTExNzc3MDI0MjQ</session_id> 
  <direction xmlns="" xsi:type="xsd:string">SEND</direction> 
  <source_path xmlns="" xsi:type="xsd:string">10m.dat</source_path> 
  <file_size xmlns="" xsi:type="xsd:long">10485760</file_size> 
  </ITC_Rename_File>
  </soap:Body>
  </soap:Envelope>
   

The following is an example SOAP envelope of the server response to an ITC_Rename_File call:

<?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
  <ITC_Rename_FileResponse xmlns="http://myserver/myurn">
  <s-gensym75 xsi:type="xsd:string">10m.dat</s-gensym75> 
  </ITC_Rename_FileResponse>
  </soap:Body>
  </soap:Envelope> 
     

ITC_End_File

The ITC_End_File method is called once at the end of a transfer. In a retry scenario, the ITC_End_File method is still called only once, when the retry file count is exhausted. (For example, if the retry value is 3, the ITC_End_File method is called after all three retry attempts have completed.)

METHOD NAME: ITC_End_File

This SOAP call provides information about ending the file transfer.

Input Parameter

  • string session_id: The session id associated with the respective authentication call.

  • string source_path: The name of the file as it exists on the source side of the transfer.

  • string completion: The action taken on the file by Content Transfer Engine SDK. This will be one of the following: "OK", "skipped" or "error".

The following is an example of a SOAP envelope for the ITC_End_File call:

<?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
  <ITC_End_File xmlns="http://myserver/myurn">
  <session_id xmlns="" xsi:type="xsd:string">NDAxOTM0NjEzNTExNzc3MDI0MjQ</session_id> 
  <source_path xmlns="" xsi:type="xsd:string">./admin/10m.dat</source_path> 
  <completion xmlns="" xsi:type="xsd:string">skipped</completion> 
  </ITC_End_File>
  </soap:Body>
  </soap:Envelope>    
    

The following is an example SOAP envelope of the server response to an ITC_End_File call:

<?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
  <ITC_End_FileResponse xmlns="http://myserver/myurn" xsi:nil="true" /> 
  </soap:Body>
  </soap:Envelope>
    

ITC_Disconnect

The ITC_Disconnect method is called after all files are sent.

METHOD NAME: ITC_Disconnect

This method provides information about the completion of the file transfer.

Input Parameter

  • string session_id: The session id associated with the respective authentication call.
  • string remote_host: The Content Transfer Engine SDK server host name as reported in the transfer. This may or may not be resolvable through DNS.
  • number transfer_number: The number of files transferred.
  • number transfer_size: The size of the files transferred in bytes (e.g., the number 1024 represents 1 kb).
  • number transfer_time: The number of seconds taken for the transfer to complete.
  • number transfer_skip: The number of files not transferred due to ITC_Begin_File call actively denying the file transfer, or because the file already exists on the Content Transfer Engine SDK server.

The following is an example of a SOAP envelope for the ITC_Disconnect call:

<?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
  <ITC_Disconnect xmlns="http://myserver/myurn">
  <session_id xmlns="" xsi:type="xsd:string">NDAxOTM0NjEzNTExNzc3MDI0MjQ</session_id> 
  <remote_host xmlns="" xsi:type="xsd:string">host1.acme.com</remote_host> 
  <transfer_number xmlns="" xsi:type="xsd:long">1</transfer_number> 
  <transfer_size xmlns="" xsi:type="xsd:long">10485760</transfer_size> 
  <transfer_time xmlns="" xsi:type="xsd:long">4</transfer_time> 
  <transfer_skip xmlns="" xsi:type="xsd:long">0</transfer_skip> 
  </ITC_Disconnect>
  </soap:Body>
  </soap:Envelope>
    

The following is an example SOAP envelope of the server response to an ITC_Disconnect call:

<?xml version="1.0" encoding="UTF-8" ?> 
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" soap:encodingStyle="
  http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
  <ITC_DisconnectResponse xmlns="http://myserver/myurn" xsi:nil="true" /> 
  </soap:Body>
  </soap:Envelope>    
    

Sample SOAP Service

The sections that follow provide Perl examples that use the SOAP::Lite module to provide implementations of the SOAP services described in this manual. The following header is required for the name space to be defined, and transport modules to be imported:

package InteractiveTransferService; use Socket qw(:DEFAULT :all); use SOAP::Transport::HTTP; use Encode; my $da emon = SOAP::Transport::HTTP::Daemon -> new (LocalPort => 2055) -> dispatch_to('InteractiveTransferService') -> handle;

ITC_Authenticate

This example shows an authentication routine that, for example, authenticates only passwords that contain an even number of characters.  Additionally it shows how to cause the file filter SOAP call back to occur if the name of the file being downloaded is also an even number of characters, and how to set bandwidth throttles based on the user name.  Lastly, it demonstrates how to build up the return parameters with custom values.

sub ITC_Authenticate
{
    my ($class, $auth_params) = @_;

    my %session_info;
    my @info = split("\n",$auth_params);
    foreach my $key (@info)
    {
        my @kv = split("=",$key,2);
        $session_info{$kv[0]}=$kv[1];
    }

    my $allow = "N";

    if ( (length
          ($session_info{"com.signiant.interactivetransfer.engine.password"}) % 2)
         == 0 )
    {
        $allow = "Y";
    }
    else
    {
        $allow = "N";
    }

    if ( (length
          ($session_info{"com.signiant.interactivetransfer.engine.files"}) % 2)
         == 0 and
         (uc
          ($session_info{"com.signiant.interactivetransfer.engine.mode"})
          eq "RECEIVE") )
    {
        $session_info{"com.signiant.interactivetransfer.soap.filter_file_urls"}
          = "http://10.208.0.1:2055/";
    }


    if ( $session_info{"com.signiant.interactivetransfer.engine.user"}
         eq "speedster" )
    {
        $session_info{"com.signiant.interactivetransfer.engine.bandwidth_throttle"}
          = 0; # unlimited speed
    }
    else
    {
        $session_info{"com.signiant.interactivetransfer.engine.bandwidth_throttle"}
          = 10485760; # 10 MBytes/second
    }

    my $return_params = "";

    foreach my $key (sort (keys %session_info))
    {
        $return_params .= "$key=".$session_info{$key}."\n";
    }

    print "Returning: $return_params";
    return { 'allow' => $allow,
             'properties' => $return_params
           };
}    
    

ITC_Begin_File

This example shows how to allow files to be downloaded only if the size is an even number of bytes.

sub ITC_Begin_File
{
    my ($class, $session_id, $direction, $source_path, $size) = @_;

    if ( ($size % 2) == 0 )
    {
        return "Y";
    }
    else
    {
        return "N";
    }}    
    

ITC_Rename_File

This example shows how to cause files to be renamed to have an extension of ".large" if the file size is considered large.

sub ITC_Rename_File
{
    my ($class, $session_id, $direction, $source_path, $size) = @_;

    if ($size > 1048576 )
    {
        return $source_path.".large";
    }
    else
    {
        return $source_path;
    }
}    
    

ITC_Filter_File

This example shows how to cause files to be encrypted with a specific pass phrase if the size is considered large.

sub ITC_Filter_File
{
    my ($class, $session_id, $direction, $source_path, $size) = @_;

    if ($size > 1048576 )
    {
        return "encryption.passphrase=Secret pass phrase";
    }
    else
    {
        return ""; # No pass phrase means no encryption
    }
}    
    

ITC_End_File

This example shows how to print out the completion status of a file transfer.

sub ITC_End_File
{
    my ($class, $session_id, $source_path, $completion) = @_;

    print "File $source_path completed with status: $completion\n";

    return;
}    
    

ITC_Disconnect

This example shows how to print out the statistics for the entire transfer session.

sub ITC_Disconnect
{
    my ($class, $session_id, $remote_host, $files_transferred, $bytes_transferred, $elapsed_seconds, $files_skipped) = @_;

    print "Session: $session_id to $remote_host completed in $elapsed_seconds seconds\n";
    print "  Number of files transferred: $files_transferred\n";
    print "  Number of bytes transferred: $bytes_transferred\n";
    print "  Number of files skipped:     $files_skipped\n";

    return;
}