| Oracle® Outside In Transformation Server Developer's Guide Release 8.4.1 Part Number E12868-05 |
|
|
View PDF |
| Oracle® Outside In Transformation Server Developer's Guide Release 8.4.1 Part Number E12868-05 |
|
|
View PDF |
This chapter details the fundamental steps you must take to run Transformation Server and begin generating output using the tsmanager and/or tsagent modules.
This chapter includes the following sections:
To install Transformation Server, download the archive from the Oracle site (http://edelivery.oracle.com/). Place the download into a directory that contains a previously downloaded Outside In installation on your local drive to complete installation.
Note:
At least one of the Outside In Export products needs to be installed before Transformation Server is downloaded.
Important:
Transformation Server, its configuration files, and the Outside In Export technologies are designed to reside in the same directory. Placing them elsewhere may result in errors.
You will need to set the TSROOT variable to the location of the Transformation Server installed SDK. For example, for a Linux version of Transformation Server, you would set TSROOT=/user/jsmith/ts/ts_linux-x86-32_sdk/sdk.
If you load more than one OIT SDK, you must copy files from the secondary installations into the top-level OIT SDK directory as follows:
docs – copy all subdirectories named “[product name]guide” into this directory.
redist – copy all binaries into this directory.
sdk – this directory has several subdirectories: common, demo, lib, resource, samplecode, samplefiles. In each case, copy all of the files from the secondary installation into the top-level OIT SDK subdirectory of the same name. If the top-level OIT SDK directory lacks any directories found in the directory being copied from, just copy those directories over.
On some Linux installations, particularly newer ones, the Motif libraries that are installed are not compatible with the libraries that are used to build the Outside In technology. This is known to be the case with most of the SuSE installations, for example. It is likely that you have a binary incompatibility if you try to build one of the Xwindows-based sample applications included with this product and see an error at compile time that looks like the following
warning: libXm.so.1, needed by ../../libsc_vw.so, may conflict with libXm.so.3
Problems can also be seen when trying to convert graphics files. For example, zero byte graphics files will be generated if our technology cannot find the proper Motif library. You can check to see if this is the case by running the following command:
ldd libos_xwin.so
This will print a list of the dependencies that this library has. If the line for the Motif library looks like the following:
libXm.so.1 => not found
then your system may not have a compatible Motif library installed.
The proper solution to both of these problems is to install a compatible Motif library and use it to build your application. Often, the installation discs for your particular Linux platform will have the proper libraries. If your installation discs do not have the libraries, instructions for downloading a binary rpm can be found at http://www.lesstif.org/download.html. Remember that if you are doing development, you will also need the proper header files, as well.
The Motif library versions used by Oracle when building and testing the Outside In binaries are:
x86 Linux: OpenMotif v. 2.2.3
This product requires the Visual C++ libraries included in the Visual C++ Redistributable Package available from Microsoft. Transformation Server requires the x86 Windows package. Users can dowload the required library from http://www.microsoft.com/downloads/details.aspx?FamilyId=90548130-4468-4BBC-9673-D6ACABD5D13B&displaylang=en.
To deploy Visual C++ libraries using the Visual C++ Redistributable Package, perform the following steps:
Copy the Visual C++ Redistributable Package (vcredist_x86.exe) to the target computer.
Run vcredist_x86.exe on the target computer. This installs all Visual C++ libraries as shared assemblies. On a target computer with support for manifest-based binding of applications to their dependencies (Windows XP Home Edition, Windows XP Professional, Windows Server 2003, Windows Vista), the libraries are installed in the WinSxS folder. On a computer without such support (Windows 2000), the libraries are installed to both the WinSxS and System32 folders.
Your application is ready to be run.
Here is an overview of the files contained in the main installation directory for this product:
| File | Description |
|---|---|
|
ACE-5.8.1 |
Third party ACE library that provides process control and thread synchronization |
|
sccts |
C API library for Transformation Server Clients |
|
ts_buffered_io |
Transformation Server buffered IO library |
|
ts_components |
Transformation Server support library |
|
ts_engine_options |
Transformation Server generic options handling library |
|
ts_file_io_module |
Transformation Server file IO library |
|
ts_hx_engine |
HTML Export engine for use by tsagent |
|
ts_ix_engine |
Image Export engine for use by tsagent |
|
ts_logging_facility |
Transformation Server logging support library |
|
ts_msg_logger_app |
Transformation Server logging process |
|
ts_pdf_engine |
PDF Export engine for use by tsagent |
|
ts_riot_iop_module |
Transformation Server Client side, redirected IO library |
|
ts_riotstub |
C API support library for Transformation Server Clients |
|
ts_soap_ext |
Transformation Server SOAP support library |
|
ts_soap_std |
Transformation Server SOAP support library |
|
ts_soap_ta_client |
Transformation Server SOAP support library |
|
ts_soap_ts_client |
Transformation Server SOAP support library |
|
ts_soap_ts_server |
Transformation Server SOAP support library |
|
ts_soap_tss |
Transformation Server SOAP support library |
|
ts_sx_engine |
SearchML Export engine for use by tsagent |
|
ts_url_iop_module |
Transformation Server HTTP IO library |
|
ts_utils |
Transformation Server support library |
|
ts_xx_engine |
XML Export engine for use by tsagent |
|
tsagent |
Transformation Server agent process |
|
tsmanager |
Transformation Server manager process |
|
tsapi.jar |
Java API library for Transformation Sever Clients |
|
tools.jar |
Java classes used by configserver and option_set_editor utilities |
|
configserver |
Java GUI application for editing the server_startup.xml file |
|
option_set_editor |
Java GUI application for editing the agent_option_sets.xml file |
Transformation Server's main application is tsmanager. When this program is started, it will in turn start up Transformation Agents (tsagent) and initiate communication with them. tsmanager will then listen for incoming transformation requests. Incoming requests for transformations are distributed among the running Transformation Agents, who return the results of the requests to tsmanager, which will then send those results back to the original requestor.
tsagent can be started in standalone mode apart from tsmanager as well, for applications where reduced resource usage is desirable.
This section deals with these applications and their command-line parameters.
Note:
If any of the following .xml files that tsmanager and its agents depend upon change while tsmanager is running, then it must be shut down and restarted.
server_startup.xml
agent_option_sets.xml
agent_engine_list.xml
agent_iospect_types.xml
The following is an overview of product details.
The user can alter tsmanager's parameters via the command line, the XML configuration file named server_startup.xml, or both. For parameters that can be set both ways, the command line overrides server_startup.xml. For both methods, parameter string values are case-sensitive. If server_startup.xml is malformed or missing an option, tsmanager will resort to defaults if it can avoid a bailout.
The following command line options have parameters. The command --help provides a list of these as well as their shorthands (e.g., --host = -s).
The hostname or IP address to use when listening to transformation requests. Value may be a name, such as "server.host.com" or an IP address such as "127.0.0.1;" the host address must be valid for the machine on which tsmanager is running. If no host name is specified on the command line or in the configuration file, tsmanager will listen to incoming requests on all available addresses. If no host is specified on either the command line or in server_startup.xml, tsmanager will listen for requests on all of the computer's available IP addresses. The server_startup.xml parameter is the <serverName> subelement of <ConnectionsInfo>.
The TCP port number on which tsmanager will listen for incoming requests. There is no default value; this parameter must be specified. The server_startup.xml parameter is the <port> subelement of <ConnectionsInfo>.
This parameter is only valid on UNIX systems.
This is the directory where pipes will be created. The location must be local to the machine. The default value is /tmp. The server_startup.xml parameter is the <pipDir> subelement of <logInfo>.
The following command line flags are used.
If set, this option prints supplemental diagnostic information to the log file.
The tsmanager command line syntax is simple:
tsmanager --parameter1 value1 --parameter2 value2 ...
Both the long option and short option can be used for syntax, for example, the port command long option is "--port" and the short option is "-p". Use the --help (-h) command to show the short options. Parameters and their values are separated by one or more spaces or tabs.
The following parameters are supported:
cfgfile: The parameter cfgfile causes tsmanager to update the parameter values in server_startup.xml with the other parameter values specified on the same command line, then exit immediately without initiating any transformation operations.
host: Described in Section 2.2.1.2, "Command Line Options with Parameters."
loghostname: Logs the client host name (slower than logip).
logip: Logs the client's IP address.
numagents: Described in Section 2.2.1.2, "Command Line Options with Parameters."
pipedir: Described in Section 2.2.1.2, "Command Line Options with Parameters."
port: Described in Section 2.2.1.2, "Command Line Options with Parameters."
trace_on: Described in Section 2.2.1.3, "Command Line Flags."
version: Described in Section 2.2.1.3, "Command Line Flags"
The following command line will cause tsmanager to listen for incoming transformation requests on TCP port 90 of IP address 127.0.0.1 (localhost).
tsmanager --host 127.0.0.1 --port 90
The following command line will cause tsmanager to listen for incoming transformation requests on TCP port 100 and use a pool of 3 transformation agents to handle transformation requests.
tsmanager --port 100 --numagents 3
When you launch tsmanager, it spawns a logging application called ts_msg_logger_app. This application logs server activity based on parameters specified in the server_startup.xml configuration file (the configuration file is discussed in the following section). The log can be rotated based on a maximum file size (the rotateSize parameter in the logInfo section of the server_startup.xml file) or by time of day (the rotateTime parameter in the logInfo section of the server_startup.xml file). When the log is rotated, the old log file is not deleted.
The file server_startup.xml resides in the same directory as tsmanager. If this file is not present, you must specify at least the port number on the tsmanager command line.
If the rotate_time value of the logInfo section of the configuration file is filled with a valid, non-empty time, rotate_size can be zero or empty. However, if the rotate_time value is empty and the rotate_size value is zero, ts_msg_logger_app will not start and will print out an error message to the console. Also, if both rotate_time and rotate_size have non-empty values, tsmanager will always use the rotate_time value and ignore the rotate_size value.
The path value must be set or ts_msg_logger_app will not start.
Configuration File Example
<TsServerStartup xsi:type="tss:TsServerStartup"
... other attributes deleted for clarity... >
<agentsInfo xsi:type="ts:agentsInfo">
<poolSize xsi:type="xsd:unsignedInt">4</poolSize>
</agentsInfo>
<connectionsInfo xsi:type="tss:connectionsInfo">
<serverName xsi:type="xsd:string"></serverName>
<port xsi:type="xsd:unsignedInt">60611</port>
</connectionsInfo>
<logInfo>
<host>128.26.53.89</host>
<port>90</port>
<path>c:\logs</path>
<rotate_time>23:00</rotate_time> <!-- HR:MN -->
<rotate_size>5</rotate_size> <!-- in MB -->
</logInfo>
</TsServerStartup>
In addition to its typical usage, running in tandem with tsmanager, tsagent can be started in standalone mode (using the standalone flag), allowing low-overhead, single-threaded communications with the server. Here is a guide to tsagent's parameters.
The following are command line flags with parameters.
The hostname or IP address to use when listening to transformation requests. Value may be a name, such as "server.host.com" or an IP address such as "127.0.0.1;" the host address must be valid for the machine on which TSagent is running. If no host name is specified on the command line or in the configuration file, TSagent will listen to incoming requests on all available addresses. There is no default value; this parameter must be specified.
The following are other command line flags.
This flag will allow tsagent to connect to one client and when that client ends the connection, tsagent will exit.
This flag is required if you wish to run tsagent in standalone mode separately from tsmanager.
This flag allows the standalone agent to get input from stdin and write output to stdout.
There are several XML configuration files used by Transformation Server to store its configuration information. These files are located in the same directory as the Outside In binaries. A developer may add IO Providers or Transformation Engines to the Transformation Server core by modifying these files.
agent_iospec_types.xml: Contains the list of input/output providers installed on the server. Each element in the list maps an IO "specification type" (for example, path or url) to a module that contains the code that implements the IO Provider interfaces for this type.
agent_engine_list.xml: Contains the list of Transformation Engines available on the server.
agent_option_sets.xml: Contains the predefined sets of transformation options.
server_startup.xml: Contains startup parameters that affect the tsmanager application. If this file is not present, tsmanager parameters must be specified on its command line.
The following are examples from provided files.
<?xml version="1.0" encoding="UTF-8"?>
<?file version="1.0"?>
<IoSpecTypeToModuleMap xsi:type="tss:IoSpecTypesList"
other attributes deleted for clarity...>
<SpecType xsi:type="tss:SpecType">
<!-- For local file system and shared file system paths-->
<Name xsi:type="xsd:string">path</Name>
<Module xsi:type="xsd:string">ts_file_io_module</Module>
</SpecType>
<SpecType>
<!-- used internally for client-side redirected IO
support -->
<Name xsi:type="xsd:string">riot</Name>
<Module xsi:type="xsd:string">ts_riot_iop_module</Module>
</SpecType>
<SpecType>
<!-- For files that can be read (GET) and written (PUT)
via HTTP-->
<Name xsi:type="xsd:string">url</Name>
<Module xsi:type="xsd:string">ts_url_iop_module</Module>
</SpecType>
</IoSpecTypeToModuleMap>
<?xml version="1.0" encoding="UTF-8"?>
<?file version="1.0"?>
<EngineList xsi:type="tss:EngineList"
other attributes deleted for clarity...>
<Engine xsi:type="tss:Engine">
<EngineName xsi:type="xsd:string">HTML Export Engine</EngineName>
<EngineModule xsi:type="xsd:string">ts_hx_engine</EngineModule>
<OutputFormatNames xsi:type="tss:StringList">
<Name xsi:type="xsd:string">html</Name>
<Name xsi:type="xsd:string">mhtml</Name>
</OutputFormatNames>
</Engine>
<Engine xsi:type="tss:Engine">
<EngineName xsi:type="xsd:string">Image Export Engine</EngineName>
<EngineModule xsi:type="xsd:string">ts_ix_engine</EngineModule>
<OutputFormatNames xsi:type="tss:StringList">
<Name xsi:type="xsd:string">bmp</Name>
<Name xsi:type="xsd:string">gif</Name>
<Name xsi:type="xsd:string">jpeg</Name>
<Name xsi:type="xsd:string">png</Name>
<Name xsi:type="xsd:string">tiff</Name>
</OutputFormatNames>
</Engine>
<Engine xsi:type="tss:Engine">
<EngineName xsi:type="xsd:string">Search Export Engine</EngineName>
<EngineModule xsi:type="xsd:string">ts_sx_engine</EngineModule>
<OutputFormatNames xsi:type="tss:StringList">
<Name xsi:type="xsd:string">page-ml</Name>
<Name xsi:type="xsd:string">search-ml</Name>
<Name xsi:type="xsd:string">search-ml-2</Name>
<Name xsi:type="xsd:string">search-ml-3</Name>
<Name xsi:type="xsd:string">search-ml-3-1</Name>
<Name xsi:type="xsd:string">search-ml-3-2</Name>
<Name xsi:type="xsd:string">search-html</Name>
<Name xsi:type="xsd:string">search-text</Name>
</OutputFormatNames>
</Engine>
<Engine xsi:type="tss:Engine">
<EngineName xsi:type="xsd:string">XML Export Engine</EngineName>
<EngineModule xsi:type="xsd:string">ts_xx_engine</EngineModule>
<OutputFormatNames xsi:type="tss:StringList">
<Name xsi:type="xsd:string">flexiondoc-4</Name>
<Name xsi:type="xsd:string">flexiondoc-5</Name>
<Name xsi:type="xsd:string">flexiondoc_5</Name>
<Name xsi:type="xsd:string">flexiondoc-5-1</Name>
<Name xsi:type="xsd:string">flexiondoc-5-2</Name>
</OutputFormatNames>
</Engine>
<Engine xsi:type="tss:Engine">
<EngineName xsi:type="xsd:string">PDF Export Engine</EngineName>
<EngineModule xsi:type="xsd:string">ts_pdf_engine</EngineModule>
<OutputFormatNames xsi:type="tss:StringList">
<Name xsi:type="xsd:string">pdf</Name>
</OutputFormatNames>
</Engine>
</EngineList>
<?xml version="1.0" encoding="UTF-8"?>
<?file version="1.0"?>
<OptionSets xsi:type="tss:OptionSetList"
other attributes deleted for clarity...>
<OptionSet xsi:type="tss:OptionSet">
<Name xsi:type="xsd:string">Netscape 6.2</Name>
<Options xsi:type="tss:OptionList">
<Option xsi:type="ts:Option">
<name xsi:type="xsd:string">flavor</name>
<value xsi:type="ts:FlavorEnum">netscape4.0</value>
</Option>
<Option xsi:type="ts:Option">
<name xsi:type="xsd:string">defaultFont</name>
<value xsi:type="tsDefaultFont">
<fontname xsi:type="xsd:string">Times New Roman
</fontname>
<height xsi:type="xsd:unsignedShort">9</height>
</value>
</Option>
</Options>
</OptionSet>
<OptionSet xsi:type="tss:OptionSet">
<-- ... more option sets... -->
</OptionSet>
</OptionSets>
<?xml version="1.0" encoding="UTF-8"?>
<?file version="1.0"?>
<TsServerStartup xsi:type="tss:TsServerStartup"
other attributes deleted for clarity...>
<agentsInfo xsi:type="ts:agentsInfo">
<poolSize xsi:type="xsd:unsignedInt">4</poolSize>
</agentsInfo>
<connectionsInfo xsi:type="tss:connectionsInfo">
<serverName xsi:type="xsd:string">127.0.0.1</serverName>
<port xsi:type="xsd:unsignedInt">9999</port>
</connectionsInfo>
</TsServerStartup>
To facilitate easy creation of option sets for transformations, an Option Set Editor application is included with Transformation Server. This application is launched using a batch file called option_set_editor, located in the installation's root directory.
Once launched, the editor displays its main screen, shown here:
Here are the steps to follow to create an option set using this application.
Click New Option Set to create a new set.
Type a name for the new set in the Name field.
Add an option by either clicking the Add button at the bottom of the main screen, or clicking Edit then Add Option.
By default, the new option will be xsd:boolean, but this value can be changed by double-clicking on xsd:boolean in the Type column, and then selecting a new option from the drop-down list that appears. Similarly, you can change the value for any option in the set by double-clicking on the current value in the Value column, and then either selecting a value from the drop-down menu (if applicable) or typing a value into the field.
If you wish to remove an option that you've added, click it to highlight it, and then click the Remove button, or click Edit then Remove Option. You can also remove all options from the current set by clicking Edit then Remove All Options.
To begin a new option set, you can click New Option Set or Edit then New Option Set.
When you are ready to save a set to an XML file, click Edit then Save or Edit then Save As.
You can open an existing option set for editing by clicking File then Open. If at any point you wish to revert to the file's initial state prior to editing, click the Cancel Changes button. Clicking this button when working with a set that has not yet been saved simply brings you back to the blank default start screen.
Note:
The Option Set Editor can make intelligent decisions about when to base64-encode text. For example, if a user creates a stringData entry in the Option Set Editor and the character set of the string is not UTF-8-encoded, the editor will automatically base64-encode the string and set the base64 flag to true. Such behavior explains the possible presence of <base64> tags in the output.
Transformation Server exposes several internal APIs to allow your application to extend the core functionality to better integrate with your application.
The Transformation Engine specification allows your application to integrate non-Outside In export software into the Transformation Server framework. See Chapter 6, "Transformation Engine Specification" for details.
The IO Provider specification allows your application to extend the input and output functionality beyond the file system. See Chapter 7, "IO Provider Specification" for details.
|
 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
