Use XML Configuration

Use XML Configuration

Transcoding Technology provides an XML-based command utility for configuring the transcoding server and its resources. With XML configuration, you can:

Preserve some configuration changes when you install a new version of this product

Copy and modify resource definitions

Copy resource definitions from one server to another

Register new resources to be used during transcoding, including stylesheets, annotators, preference profiles, and transcoding plugins.

Enable and disable resources

Import an existing cocoon.properties file to enable you to migrate from the Cocoon application server.

XML configuration creates an XML-based definition of your transcoding resources that can be imported into any transcoding server. The resources whose information can be manipulated include stylesheets, annotators, preference profiles (device and user), and transcoding plugins. XML configuration also manipulates a Setup resource, which describes settings for the local transcoding server.

Note that XML configuration does not make copies of the resources themselves: transcoding plugins (.jar files), stylesheets (.xsl files), or annotators (.ann files). The one exception is preference profiles, which are copied in their entirety. For the other resources, XML configuration copies stylesheet selectors, annotator selectors, and transcoding plugin properties. This means that if you want to copy resources and their definitions from one machine to another, copy the resource files themselves, or make them available from a Web server, before you import their definitions onto a new machine.

XML configuration commands

XML configuration provides these commands. Click the command name to see the arguments for that command and other information about its use. You can enter any command with -help or -? to see a summary of the valid arguments.

Command Function

ExportResources Exports resource definitions to an XML file.

ImportResources Registers new resource definitions or imports changes to existing resource definitions from an XML file.

EnableResources Enables a resource that is currently included in the transcoding configuration.

DisableResources Disables a resource that is currently included in the transcoding configuration.

ImportCocoon Imports a Cocoon properties file to support stylesheet specifications within XML documents.

Log entries will be written to the Transcoding Technology log file, log/TranscoderMessages.log, when any import or export command is issued. Entries will be written to the XML configuration trace file, log/cmdmagictrace.log, whenever a problem is encountered. These logs are located under the Transcoding Technology installation directory (for example, C:\Program Files\IBMTrans).

Copying and modifying resources

Use XML configuration to export existing resource definitions and then import them after they have been modified. XML configuration can work with these types of resources:

Stylesheets

Annotators

Preference profiles (device and user)

Transcoding plugins

Setup (Includes basic transcoding settings but does not include settings for WebSphere Application Server)

For example, suppose you have already registered a set of annotators to be applied to a set of documents on a certain Web server, and the documents are moved to a different domain, or even to a new directory on the server. You need to make the same change to each URL used to select one of these annotators. To make this change with XML configuration:

Export your annotator resources to an XML file.

Use an XML or text editor to find and replace the necessary strings in the URLs.

Import your updated annotator resources.

Registering new resources

Before you can use a resource with Transcoding Technology, register the resource with the transcoding server. This section describes the registration process and notes important differences that exist for the registration of transcoding plugins.

Registering annotators, stylesheets, and preference profiles

The process of registering an annotator, stylesheet, or preference profile is similar to that of copying and modifying existing resources. While in some cases the creator of the resource might also provide an XML configuration file with the resource, you can create your own XML file by exporting an existing resource and using the file as a template.

For example, consider the situation where you have created a group of stylesheets that will be applied in a similar fashion to that of a stylesheet already registered. However, you want to make small changes to the way each stylesheet is applied, such as matching on a different URL or referencing a different DTD. To register the new stylesheets through XML configuration:

Place the stylesheets (.xsl files) on your transcoding server or on a Web server.

Export a stylesheet resource to an XML file for use as a template.

Use an XML or text editor to make several copies of the stylesheet definition and modify each one to represent one of your new stylesheets.

Register the new stylesheets by importing your updated stylesheet resources.

Registering transcoding plugins

As with other resources, you can register a transcoding plugin by using the ImportResources command to specify an XML file containing information about the plugin. This XML file is usually provided by the plugin author, along with the plugin's JAR file, and contains information such as whether the plugin is enabled by default and whether to overwrite the registration of an existing plugin. The <Location> element within the XML file provides the path used to locate the JAR file. This can be a full path or a path relative to the directory where the ImportResources command is issued. If no path information is specified, the JAR file is assumed to be in the same directory as the XML file at the time of registration.

The following sample codes registers a transcoder named myUsefulTranscoder.jar:

<Resources> <Plugin> <Location>c:/mydirectory/myUsefulTranscoder.jar</Location> <Force>true</Force> <Enable>true</Enable> <Plugin> </Resources>

Run ImportResources using the following command: ImportResources -File myFile.xml. The <Location> element in the XML file will tell the XML Configuration tool where to find the transcoder.

You can also export an existing transcoding plugin definition to use as a template for the new plugin. In this case add the <Location> element and set any other parameters for the transcoding plugin. Because the settings for existing transcoding plugins might not be appropriate for the plugin you are registering, it is recommended that you only take this approach if you are familiar with the new plugin and understand how Transcoding Technology uses the various plugin settings.

For example, to register a transcoding plugin specified by the NewPluginFile.xml file and then refresh the transcoding server to pick up the new plugin, do the following:

Copy the XML file to the Transcoding Technology installation directory.

Copy the JAR file to the directory specified by the XML file.

Enter the following at the command line:
ImportResources -file NewPluginFile.xml -RefreshServer

Copying resource definitions to another machine

After you have configured one transcoding server, you can use XML configuration to copy the resource definitions to another machine. Remember that XML configuration does not copy the resources themselves (transcoding plugins, annotators, or stylesheets). This means that make sure that the resources are available on your target machine in exactly the same location as on your original machine. One way to accomplish this is to place the resources on a Web server instead of on the transcoding server. Then the resources can be accessed using HTTP by any transcoding server. If you do not want to use a Web server, copy any resource files to the target machine before you import the resource definitions.

To copy resource definitions from one transcoding server to another, follow these steps:

Install the product on the first server.

Register any new transcoding resources and configure your resources using XML configuration.

Use the ExportResources command to export your resource definitions to an XML file.

Install WebSphere Everyplace Access on the second (target) server.

If you added any new resources to the first server (annotators, stylesheets, or transcoding plugins), copy any local files (.ann, .xsl, and JAR files) to the target server. Skip this step if the files are located on a Web server.

Copy the XML file created in step 3 to the target server.

Import the resource definitions from the XML file on the target server. Resolve any errors, such as files not found.

XML configuration command arguments

These tables show the arguments that can be used with each XML configuration command. These arguments can be specified in any order, and they are not case sensitive.

ExportResources arguments

Argument Default value Description

-File [filename] WTPResources.XML Name of the file to which to export the resources

-Append no Append the new resources to the specified file. Duplicate resources will be overwritten. If this argument is not specified and there is an existing file, it will be overwritten.

-ResourceType "[resource type, resource names]" all resource types Export the resources of the specified types (stylesheet, annotator, plugin, device, user, or setup). The default is to export all resources. If names are specified after the type, resources of that type with those names will be exported. Use an asterisk (*) as a wildcard character.

-ResourceFolder "[resource type, folder names]" all folders Export the resources in the specified folder. The default is to export resources from all folders. If folder names are specified after the resource type, the resources of that type within those folders will be exported. Use an asterisk (*) as a wildcard character.

-Comment [text] none Add the specified text to the file as a comment.

-Encoding [value] UTF-8 Encoding to be used for the exported XML. Other available values will depend on your JDK.

-Help
or
- ?
false Displays help for the command.

For example, the following two commands produce a file called MyResources.xml with all stylesheet selectors and device profiles:

ExportResources -ResourceType stylesheet -File MyResources.xml ExportResources -ResourceType device -append -File MyResources.xml

The following command produces a file called MyResources.xml with the specified two device profiles and two annotator selectors:

ExportResources -ResourceType "device, WML-Device, IMode2-Color" -ResourceType "annotator, Raleigh, Durham" -File MyResources.xml

You can combine the ResourceType argument and the ResourceFolder argument to restrict the selection of resources by folder name. For example, the following command produces a file called MyResources.xml with all stylesheet selectors that have names beginning with Flight and that are registered in the ibm/samples folder:

ExportResources -ResourceType "stylesheet, Flight*" -ResourceFolder "stylesheet, ibm/samples" -File MyResources.xml

Note: Resource names and folder names are case sensitive.

ImportResources arguments

Argument Default value Description

-File [filename] WTPResources.XML Name of the file from which to import the resources

-ResourceType "[type, names]" all types Import the resources of the specified types (stylesheet, annotator, plugin, device, or user). The default is to import all the resources found in the file. If names are specified after the type, resources of that type with those names will be imported.
Note: Importing a plugin definition is not the same as registering the plugin for the first time.

-ResourceFolder "[resource type, folder names]" all folders Import the resources to the specified folder. The default is to import resources to the root of the transcoding resources tree. If folder names are specified after the resource type, the resources of that type will be imported to those folders. Use an asterisk (*) as a wildcard character.

-RefreshServer false Automatically refresh the transcoding server to update the status of the resource. If this is not specified, the resource status will not be updated until the next time the transcoding server is refreshed.

-Encoding [value] UTF-8 Encoding to be used for the imported XML. Other available values will depend on your JDK.

-Help
or
- ? false Displays help for the command.

Run ImportResources.bat or ImportResources.sh from the Transcoding Technology root directory to import any changes made after a previous export. If the resource already existed, the old values will be overwritten.

For example, if you created MyResources.xml with the first two export commands above, then ImportResources -File MyResources.xml would import all the resources in the file, while ImportResources -ResourceType device -File MyResources.xml would import only the device profiles contained in the file.

You can combine the ResourceType argument and the ResourceFolder argument to restrict the selection of resources by folder name. For example, the following command produces a file called MyResources.xml with all stylesheet selectors that are registered in all stylesheet folders whose names begin with "ib":

ImportResources -ResourceType "stylesheet" -ResourceFolder "stylesheet, ib*" -File MyResources.xml

Note: When you import resource definitions, Transcoding Technology attempts to verify the existence of all local files referred to by the definitions. For example, when you import stylesheet selectors, Transcoding Technology checks whether the stylesheet files identified in the selectors exist in the specified locations. If the files are not found, a warning message is issued. Files identified using http:// rather than file:// are not verified.

Executing instructions in the XML document

You can add processing instructions in an XML document before importing it, and the import process will execute the instructions as it imports the file. The supported instructions are:

Instruction Function

<?Delete?>
If specified within a resource definition, delete all resource definitions with the SelectorName value defined for that resource. If the resource definition supports folders (stylesheets, annotators, and transcoding plugins), a <Folder> value must also be present along with the <SelectorName>.

The following example deletes the InternalHtmlDomCreator plugin:

<?xml version="1.0" encoding="UTF-8"?> <Resources ServerModel="configSet1" Version="magic50"> <Plugin> <Folder>ibm/TextEngine</Folder> <SelectorName>InternalHtmlDomCreator</SelectorName> <?Delete?> </Plugin> </Resources>

<?Refresh Server?> Issue a command to the transcoding server to reload all resources of the type within which this command is included. You only need to include this instruction once per resource type, even if the XML file includes several resources of that type.

EnableResources arguments

Argument Default value Description

-ResourceType "resource type, resource names" required Enable the resource specified by the type and name.

-ResourceFolder "[resource type, folder names]" all folders Enable the resources in the specified folder. If folder names are specified after the resource type, the resources of that type in the specified folders will be enabled. Use an asterisk (*) as a wildcard character.

-RefreshServer false Automatically refresh the transcoding server to update the status of the resource. If this is not specified, the resource status will not be updated until the next time the transcoding server is refreshed.

-Help
or
- ? false Displays help for the command.

Run EnableResources.bat or EnableResources.sh from the Transcoding Technology installation directory to enable the specified resource.

For example, to enable the device profile for a standard WML device and then update the transcoding server, use the following:

EnableResources -ResourceType "device,WML-Device" -RefreshServer

DisableResources arguments

Argument Default value Description

-ResourceType "[type, names]" all types Disable the resource specified by the type and names. If names are specified after the type, resources of that type with those names will be imported. The importing process adds a new resource (for example: stylesheet, annotator, transcoder, preference profile) to the Transcoding configuration.

-ResourceFolder "[resource type, folder names]" all folders Disable the resources in the specified folder. If folder names are specified after the resource type, the resources of that type in the specified folders will be disabled. Use an asterisk (*) as a wildcard character.

-RefreshServer false Automatically refresh the transcoding server to update the status of the resource. If this is not specified, the resource status will not be updated until the next time the transcoding server is refreshed.

-Help
or
- ? false Displays help for the command.

Run DisableResources.bat or DisableResources.sh from the Transcoding Technology installation directory to disable the specified resource.

For example, to disable the device profile for a standard WML device, use the following:

DisableResources -ResourceType "device, WML-Device"

Importing Cocoon properties

If you have been using the Cocoon application server, you can import your cocoon.properties file into Portal:

ImportCocoon -File <path>/cocoon.properties

Update Setup resources

To update a local setting, such as specifying what Request Viewer clients have access to the the transcoding server, you can export the setup resource, modify it as needed, and re-import it.

The command used to export the Setup resources is ExportResources -ResourceType Setup. This will create a default file called WTPResources.xml. After modifications, it can be imported back to update a local settings.

Here is an example of the file created by exporting the setup resource.

<?xml version="1.0" encoding="UTF-8"?>  <Resources ServerModel="configSet1" Version="magic50"> <Setup> <RunWTPAs>servlet</RunWTPAs> <ServerModelToBeUsed>configSet1</ServerModelToBeUsed> <RemoteRequestViewer> <Enable>false</Enable> <AuthorizedHostName></AuthorizedHostName> </RemoteRequestViewer> <RMIRegistry> <Enable>false</Enable> <HostName></HostName> <Port>1099</Port> </RMIRegistry> </Setup> </Resources>

Here is an example that shows the RequestViewer client from myenabledhost1.com and myenabledhost2.com enabled to have access to the transcoding server on the current host.

<?xml version="1.0" encoding="UTF-8"?>  <Resources ServerModel="configSet1" Version="magic50"> <Setup> <RunWTPAs>servlet</RunWTPAs> <ServerModelToBeUsed>configSet1</ServerModelToBeUsed> <RemoteRequestViewer> <Enable>true</Enable> <AuthorizedHostName>myenabledhost1.com</AuthorizedHostName> <AuthorizedHostName>myenabledhost2.com</AuthorizedHostName> </RemoteRequestViewer> <RMIRegistry> <Enable>true</Enable> <HostName></HostName> <Port>1099</Port> </RMIRegistry> </Setup> </Resources>

See also

Resources

Solutions

Command	Function
ExportResources	Exports resource definitions to an XML file.
ImportResources	Registers new resource definitions or imports changes to existing resource definitions from an XML file.
EnableResources	Enables a resource that is currently included in the transcoding configuration.
DisableResources	Disables a resource that is currently included in the transcoding configuration.
ImportCocoon	Imports a Cocoon properties file to support stylesheet specifications within XML documents.

Argument	Default value	Description
-File [filename]	WTPResources.XML	Name of the file to which to export the resources
-Append	no	Append the new resources to the specified file. Duplicate resources will be overwritten. If this argument is not specified and there is an existing file, it will be overwritten.
-ResourceType "[resource type, resource names]"	all resource types	Export the resources of the specified types (stylesheet, annotator, plugin, device, user, or setup). The default is to export all resources. If names are specified after the type, resources of that type with those names will be exported. Use an asterisk (*) as a wildcard character.
-ResourceFolder "[resource type, folder names]"	all folders	Export the resources in the specified folder. The default is to export resources from all folders. If folder names are specified after the resource type, the resources of that type within those folders will be exported. Use an asterisk (*) as a wildcard character.
-Comment [text]	none	Add the specified text to the file as a comment.
-Encoding [value]	UTF-8	Encoding to be used for the exported XML. Other available values will depend on your JDK.
-Help or - ?	false	Displays help for the command.

Argument	Default value	Description
-File [filename]	WTPResources.XML	Name of the file from which to import the resources
-ResourceType "[type, names]"	all types	Import the resources of the specified types (stylesheet, annotator, plugin, device, or user). The default is to import all the resources found in the file. If names are specified after the type, resources of that type with those names will be imported. Note: Importing a plugin definition is not the same as registering the plugin for the first time.
-ResourceFolder "[resource type, folder names]"	all folders	Import the resources to the specified folder. The default is to import resources to the root of the transcoding resources tree. If folder names are specified after the resource type, the resources of that type will be imported to those folders. Use an asterisk (*) as a wildcard character.
-RefreshServer	false	Automatically refresh the transcoding server to update the status of the resource. If this is not specified, the resource status will not be updated until the next time the transcoding server is refreshed.
-Encoding [value]	UTF-8	Encoding to be used for the imported XML. Other available values will depend on your JDK.
-Help or - ?	false	Displays help for the command.

Argument	Default value	Description
-ResourceType "resource type, resource names"	required	Enable the resource specified by the type and name.
-ResourceFolder "[resource type, folder names]"	all folders	Enable the resources in the specified folder. If folder names are specified after the resource type, the resources of that type in the specified folders will be enabled. Use an asterisk (*) as a wildcard character.
-RefreshServer	false	Automatically refresh the transcoding server to update the status of the resource. If this is not specified, the resource status will not be updated until the next time the transcoding server is refreshed.
-Help or - ?	false	Displays help for the command.

Argument	Default value	Description
-ResourceType "[type, names]"	all types	Disable the resource specified by the type and names. If names are specified after the type, resources of that type with those names will be imported. The importing process adds a new resource (for example: stylesheet, annotator, transcoder, preference profile) to the Transcoding configuration.
-ResourceFolder "[resource type, folder names]"	all folders	Disable the resources in the specified folder. If folder names are specified after the resource type, the resources of that type in the specified folders will be disabled. Use an asterisk (*) as a wildcard character.
-RefreshServer	false	Automatically refresh the transcoding server to update the status of the resource. If this is not specified, the resource status will not be updated until the next time the transcoding server is refreshed.
-Help or - ?	false	Displays help for the command.