SDK Web Services Developers Guide. SDL WorldServer 10.2

(1)

SDK Web Services Developers Guide

SDL WorldServer 10.2

(2)

Documentation Notice

This documentation and the data contained herein are the property of SDL Language Technologies, located at 69 Hickory Drive, Waltham, MA 02451 USA, and its licensors. Any use, disclosure, reproduction, modification, display or transfer of the data and/or documentation is prohibited, except by the express written authorization of SDL. This document contains proprietary SDL Language Technologies information and is licensed for use pursuant to the SDL standard software license agreement.

If you are an entity of the U.S. government, you agree that the program(s) and data referred to in this document are Commercial Computer Software, as defined in the F.A.R., and the DoD F.A.R. Suppl., and are delivered with only those rights set forth in the SDL standard software license agreement.

The program(s) referred to in this document are not specifically developed, or licensed, for use in any nuclear, aviation, mass transit, or medical application or in any other inherently dangerous applications, and any such use shall be construed as a misuse of the program(s). SDL shall not be liable for any claims or damages arising from such use of the program(s) for any such applications.

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT NOTICE. SDL MAKES NO

WARRANTY OF ANY KIND REGARDING THIS MATERIAL, AND ASSUMES NO RESPONSIBILITY FOR ANY ERRORS THAT MAY APPEAR IN THIS DOCUMENT.

Copyright © 1998-2012 by SDL plc. All rights reserved. IDIOM is a registered trademark, and WORLDSERVER is a trademark, of SDL plc. Trados and MultiTerm are registered trademarks of SDL plc. All other company product or service names referenced herein are properties of their respective owners.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/). This product also includes software developed by:

■ _{the W3C consortium (http://www.w3c.org)} ■ _{the SAX project (http://www.saxproject.org)}

Jaspersoft JasperReports is distributed under license from Jaspersoft, Inc. SDL Language Technologies 69 Hickory Drive Waltham, MA 02451 USA Publication date: June 2012

(3)

Chapter 1 About the SDL WorldServer SDK

Web Services Developer Guide

Welcome to SDL Language Technologies and WorldServer™. SDL WorldServer is a translation management system that provides advanced linguistic technology, process automation, content repository integration and management services. Completely aligned with SDL Studio™, WorldServer provides consistent analysis and reporting of translation projects for localization managers, project managers, translators and reviewers.

Scope

The SDL WorldServer SDK Web Services Developer Guide describes the web service support in the WorldServer Software Developer's Kit. In web client environments, web services support exposes essential WorldServer SDK services as programmable, language-independent web service interfaces.

SDL WorldServer Documentation and

Resources

The SDL WorldServer documentation set includes 14 separate deliverables. Some of these documents are installed with WorldServer.

The following publications are available from the SDL Knowledgebase, in the Product Documentation/SDL_WorldServer folder.

Administrator Guide

Information on setting up and administering WorldServer in your environment. Administrator Tutorial - Configuring SDL WorldServer

The process of performing an initial configuration of WorldServer. Basic Operations Guide

Basic system administration and troubleshooting information for installed WorldServer systems.

Browser Workbench User Guide

(6)

Installation and Upgrade Guide

Instructions for installing or upgrading WorldServer and its components in your environment.

Planning and Prerequisites Guide

Conceptual information for planning a WorldServer installation or upgrade, including environment requirements and options for the WorldServer platform, infrastructure, and supported components.

SDK Web Services Developer Guide

Reference guide for programmers who need to add Web Services to WorldServer. Software Development Kit (SDK) User Guide

Reference guide for programmers to understand the APIs that extend WorldServer functionality and integrate WorldServer with other custom or third-party applications. Translation Memory Mode Concepts Guide

Information for project managers that need to understand the Studio-aligned translation memory mode.

User Guide

Information for general WorldServer users: project managers, translators, and reviewers.

WorldServer and Studio Integration Guide

Information for translators, reviewers, and project managers that use SDL Studio with WorldServer.

The following WorldServer documentation resources are also available: WorldServer Release Notes

Where: The Knowledgebase SDL WorldServer/Release Notes folder. Also available from the WorldServer FTP site:Walthamftp.sdl.com/dist/product/

worldserver/<releasenumber>/

Information on enhancements and changes in the most recent release. Also contains late-breaking information about known issues and issues fixed in this release. SDL Glossary

Where: http://producthelp.sdl.com/glossary/en/glossary.htm

An alphabetical list of terms related to WorldServer and other SDL products. Transport Online Help

Context-sensitive help is available for most pages in TransPort from the More Info... link. A full web help system is available from the Help link at the top of each page. All Language Technologies online help documentation is also available from the following web page:http://www.sdl.com/en/language-technology/ support/online-product-help/

(7)

WorldServer Online Help

Context-sensitive help is available for most pages in WorldServer from the More Info... link. A full web help system is available from the Help link at the top of each page.

(8)

(9)

Chapter 2 Introduction

This chapter describes the pieces of the WorldServer SDK Developers kit that make up the Web Services resources.

WSDL-based Web Services

WorldServer system and custom Web services use Apache Axis Web services

implementations, and are fully compliant with the the Web Services Description Language (WSDL). The WorldServer WSDL is installed with WorldServer:

/Webapps/ws/wsdl/WorldServerServices.wsdl

For more information on Apache Axis, see http://ws.apache.org/axis/.

The formal specification of WSDL can be found here: http://www.w3.org/TR/wsdl20/. Two additional mechanisms of Web services invocation are also supported:

■ _{Any WSDL-compliant platform can dynamically discover and invoke}

WorldServer services using the WorldServer WSDL.

■ _{Web clients can be statically generated and built on WSDL-compliant platforms}

from the WorldServer WSDL, and then used to invoke the Web services at runtime.

Web Services Privileges

A special WorldServer Web Services user privilege is required to run all SDK Web services. As shown in Figure 1, the WorldServer administrator grants or revokes this privilege on the User Type page:

(10)

Management > User Setup > User Types > User Type: Administrator > General Options > Web Services

Initially, only the Administrator user type is granted this privilege. An Administrator needs to assign this privilege to any user type deemed safe to exercise this privilege. Anyone with this Web Services privilege can use most of the APIs exposed in the system SDK Web Services library over the Web, so this privilege must be granted carefully. Another privilege, Can remove objects using Web Services, protects all Remove, Delete, and Cancel Web services APIs. By default, only administrators can use any Web service APIs that fall into this category. A user who is granted the Web Services privilege but not the Can remove objects using Web Services privilege can use only those Web service APIs that do not remove objects or cancel ongoing activities.

System SDK Web Services

Currently, SDK APIs for AIS, Linkage, Asset, Translation Memory, Term Database, and Workflow are also exposed in the System Web Services layer, extending this server-side functionality across the Web.

The SDK client Javadocs contained in the SDK distribution describe in detail all System Web services currently exposed. This list will continue to grow in the future as more SDK Web services APIs are added. For the current comprehensive list, see the following file in the SDK distribution Zip file.

docs/api/client/index.html

Before you develop any custom Web services components, be sure to check the System Web Services suite, as the desired functionality may already be available to you out of the box with your WorldServer installation.

The SDK system Web services are packaged to run out of the box using the deployed WorldServer WAR file (ws.war) on various application servers.

No extra deployment steps are necessary at the customer site, because system Web services are automatically deployed into the running application server.

(11)

The Axis deployment file%WS_HOME%/WEB-INF/server-config.wsddincluded in the WAR file is a portable, application-server-neutral WSDD file of deployed System SDK Web services that enables these Web services to run out of the box at the customer site.

System SDK Web Services Components

■ _{WorldServer Web services WSDL}

webapps/ws/wsdl/WorldServerServices.wsdl

This WSDL document enables true language-neutral invocation of WorldServer Web services. The Java and .NET Web client libraries are now generated from this WSDL document.

■ _{Java Web server packages}

com.idiominc.wssdk.component.webservice

Delegates incoming SDK Web-service calls and data-transfer-objects to SDK implementations on the Web server.

■ _{Java Web client proxy packages}

com.idiominc.webservices.client.*

These are the SDK APIs that Java Web-client programs invoke. They are delivered in the Java Web client library.

lib/client/wssdk-client.jar

■ _{.NET Web client proxy}

Com.Idiominc.Webservices.Client.*

All SDK client proxy packages are delivered in the .NET DLL:

dotnet/lib/WSWebServices.dll

These are the SDK APIs that .NET (C#, VB) Web-client programs invoke.

■ _{Javadocs for the Web client proxy}

These are the Web service interfaces that the developer uses to create client applications that access WorldServer services. They are contained in the SDK distribution.

docs/api/client/com/idiominc/webservices/client/

■ _{Web server beans – Generic Web server WorldServer object}

This object is extended by all custom and system SDK Web server beans; provides data-transfer-object support and transaction-local support.

com.idiominc.wssdk.component.webservice.WSObject

(12)

■ _{Java Web client proxies – Generic Web client WorldServer object}

This object is extended by all Java custom and system SDK Web client proxies; provides client-side data-transfer-object support

com.idiominc.webservices.client.WSObject

■ _{.NET Web client proxies - Generic Web client WorldServer object}

This object is extendedby all .NET custom and system SDK Web client proxies; provides data-transfer-object support for .NET Web clients.

Com.Idiominc.Webservices.Client.WSObject

Web Services Configuration

You can find the global configuration of Web services, along with deployment descriptors for all of the SDK Web services, in this file:

WEB-INF/server-config.wsdd

You can get a full listing of all currently deployed Web services via this sample URL:

http://localhost:8080/ws/services

In place oflocalhost:8080, substitute the location of your WorldServer system.

(13)

Chapter 3 System Tools and Custom

Components

The sample tools and components described in this chapter provide models for web services customization. The various components can be used in your environment, as appropriate.

System Sample Tools

The WorldServer SDK includes several Java, .NET, and PERL Web services sample tool applications that have been written using System Web services.

Java Web services sample tools are in this folder:

samples\src\com\idiominc\wssdk\samples\tools\webservices

.NET Web services tools (equivalent to the Java tools) are in thedotnetsub-folder of the folder specified above. There is a .NET version equivalent to most of the Java Web services sample tools.

Similarly, PERL (SOAP::Lite) Web services tools (equivalent to the Java tools) are in the

perlsub-folder of the folder specified above. There is a .pl version equivalent to most of the Java Web services sample tools (plus some additional PERL tools).

In addition, there is a sample of dynamic invocation of WorldServer system Web services using the Apache Web Services Invocation Framework (WSIF) in the wsif sub-folder of the folder specified above. For more information on WSIF, seehttp://ws.apache.org/wsif/. Thecom.idiominc.wssdk.samples.tools.webservicespackage contains these Java and .NET sample Web service utility tools:

Sample Description

CheckinAsset Checks in versioned assets in WorldServer through WorldServer AIS connectors that support versioning

CheckoutAsset Checks out versioned assets in WorldServer through WorldServer AIS connectors that support versioning

(14)

CreateProject Creates and executes project groups

CreateTD Creates TDs using the specified names, if TDs do not already exist with the specified names

CreateTDGroup Creates a TD Group using the specified name and specified write and member TDs, if a TD Group does not already exist with the specified name

CreateTM Creates TMs using the specified names, if TMs do not already exist with the specified names

CreateTMGroup Creates a TM Group using the specified name and specified write and member TMs, if a TM Group does not already exist with the specified name

DeployComponent Deploys components to WorldServer DownloadAsset Downloads files from WorldServer ExportKit Exports translation kits

ExportTD Exports term databases ExportTDEntries Exports term database entries ExportTM Exports translation memories ExportTMEntries Exports translation memory entries ImportKit Imports translation kits

ImportTM Imports term databases ImportTD Imports translation memories

ScopeAsset Scopes assets using specified target locale and TM, and displays the scoping report

SearchTD Performs a (leverage) search on specified TD SearchTDWildcard Performs a wildcard search on specified TD

SearchTMFreeform Performs a freeform search on specified TM and produces CSV output of search results

SearchTMFuzzy Performs a fuzzy search on specified TM and produces CSV output of search results

SetFileAttribute Attaches files to WorldServer projects UploadFile Uploads files to WorldServer

(15)

Web Services Generation

The required components of the SDK Custom Web services are automatically generated using Apache Axis org.apache.axis.wsdl.Java2WSDL and

org.apache.axis.wsdl.WSDL2Javageneration tools. For more information about these Apache Axis tools, see:

■ _{http://ws.apache.org/axis/java/user-guide.html}

■ _{http://ws.apache.org/axis/java/reference.html#Java2WSDLReference} ■ _{http://ws.apache.org/axis/java/reference.html#WSDL2JavaReference}

Custom Component Samples

WorldServer includes five custom SDK Web services component samples.

These samples have a two-fold purpose: to demonstrate server-side SDK functionality, and to generate Web services and client-side proxies for the original SDK applications which provide identical SDK functionality in the Web client environment.

The ANT scriptsamples/build.xmlincluded with the samples has targets that

generate, build, deploy, and run the Web services. (See the Toolkit Samples topic.) This is representative of what’s required for building and deploying each Web services sample. For running the Web services samples, you must create a WorldServer test environment with which the sample applications will communicate. For detailed instructions about what this WorldServer test environment should include, read theconfig.properties

file for each sample. You must configure the samples using theconfig.propertiesfile in each sample’s folder to match the WorldServer test environment that you have set up, and rebuild the samples to include the custom configuration.

Distribution File Package

The Web services samples are also available in deployable packages in the SDK distribution files:

samples/dist/*WebServiceServer.zip

You may choose to use these and skip the generate and build steps for the samples. But if you are interested in developing your own custom Web services components you will need to generate and build your Web services, and a good place to start is by generating and building the samples.

(16)

Toolkit Sample

The toolkit sample makes valuable SDK tools available as custom Web services.

samples/component/webservices/toolkit

These SDK tools are imported and adapted from the SDK tools samples. They implement batch import of translation memories and term databases, export and import of

translation kits, and leveraging and scoping of WorldServer asset hierarchies.

Note: This sample is for tutorial purposes only; the Web service APIs illustrated in this sample are already available in the WorldServer system Web services suite.

Original SDK Tools

The original SDK sample tools package on which the toolkit Web services are based is a collection of utilities implemented using WorldServer SDK. To learn how to run each utility, refer to the sample Javadocs. The package includes these tools.

ExportKit Exports a Translation Kit from World Server in order to work offline (for example, utilizing WorldServer Desktop Workbench) ImportKit Uploads back into WorldServer assets that were translated offline LeverageAssets Leverages WorldServer asset(s) by filtering, applying translation

memory matches, generating scoping information, and (optionally) generating partial translations

TDImporter Performs a batch import of Term Databases from SDL MultiTerm files

TMImporter Performs a batch import of Translation Memories from TMX files

Building and Running the Toolkit Sample

For detailed information about the prerequisite WorldServer test environment for running a sample, read itsconfig.propertiesfile.

(17)

In the ANT scriptsamples/build.xml, the ANT targets that generate, build, deploy, and run the Web service are described below. See also ANT SDK Custom Web Services Build Targets, below.

■ build.webservice.toolkit

Builds the original SDK application and generates the toolkit Web service; generates WSDL fromToolkit.java; generates Java service and client stubs from the WSDL; builds the toolkit Java service, client stubs, and test application. The resulting package,samples/dist/ToolkitWebServiceServer.zip, contains all of the server classes for subsequent deployment of the Web services on the application server.

■ run.app.toolkit

Runs the original SDK application, and verifies its intended server-side standalone functionality without yet involving any Web services.

■ deploy.webservice.toolkit

Required parameters: Specifyws.hostandws.contextparameter values to customize the WorldServer URL.

Deploys the toolkit Web service on the running application server; the application server may need to be restarted and must be running before you run this target. Prerequisite: Requires the WorldServer environment variableWS_HOMEto be configured.

Note: Make sure the Application Server context is capable of reloading the newly built Web services server JARs during deployment; otherwise, you must restart your application server after this step!

■ run.webservice.toolkit

Runs the Java toolkit Web client application and verifies that its client-side functionality is identical to server-side SDK functionality.

Required parameters: Specifyws.hostandws.contextparameters to customize the WorldServer URL.

Prerequisite: Requires the WorldServer environment variableWS_HOMEto be configured.

To run the Java Web client application, you must specify the WorldServer Axis servlet URL. This is the Web-service equivalent of a user typing the WorldServer URL in a Web browser to launch a WorldServer session on the application server.

Example: Java Web client

Using therun.webservice.toolkittarget, specifyws.hostandws.context

parameter values to customize the WorldServer Axis URL:

samples> ant -Dws.host=localhost:8080 -Dws.context=ws run.webservice.toolkit

If you are not using therun.webservice.toolkittarget, you must specify the WorldServer Axis servlet URL, as shown in this example:

toolkit>java -Dws.url=http://localhost:8080/ws/services com.idiominc.wssdk.samples.component.webservices.toolkit. test.ToolkitTest

(18)

■ build.dotnet.webservice.toolkit, run.dotnet.webservice. toolkit(.NET Web services build and run targets)

Builds and runs the .NET toolkit Web client application and verifies that its client-side functionality is identical to server-side SDK functionality.

Prerequisite: To build and run the Windows .NET Web client samples, you must first download the .NET Version 1.1 SDK (it's easy and free). Two downloads are required (in this order):

■ _{Microsoft .NET Framework Version 1.1 Redistributable Package} ■ _{Microsoft .NET Framework SDK Version 1.1}

Then you simply configure your shell by running, for example,c:\Program Files\Microsoft.NET\SDK\v1.1\Bin\sdkvars

ANT targetsbuild.dotnet.webservice.toolkitand

run.dotnet.webservice.toolkitare also available to build and run the .NET Web client proxy and tests.

To build the .NET Web client:

samples> ant build.dotnet.webservices.samples

As with the Java Web client, to run the .NET Web client application you must specify the WorldServer Axis servlet URL.

Example: .NET Web client

Using therun.dotnet.webservice.toolkittarget, specifyws.hostandws. contextparameters to customize the WorldServer Axis servlet URL:

samples> ant -Dws.host=localhost:8080 -Dws.context=ws run.dotnet.webservice.toolkit

If you are not using therun.dotnet.webservice.toolkittarget, you must specify the WorldServer Axis servlet URL, as shown in this example:

cd src/com/idiominc/wssdk/samples/component/webservices/ toolkit

toolkit>set WS_URL=http://localhost:8080/ws/services toolkit> dist\Toolkit.exe

Requirements for Running Toolkit Web Services

Samples

The WorldServer Axis servlet URL (for example,http://localhost:8080/ws/ services) is the only configuration required to run WorldServer Web client applications. The only other requirements are language-specific XML and SOAP libraries that are available in most languages.

For a Java Web client, you need only these JARs:

■ lib/client/wssdk-client.jar(Java system Web client proxy)

■ ToolkitWebServiceClient.jar(Java toolkit Web client proxy)

■ axis.jar,xml.jar(standard Apache Xerces Axis and XML libraries)

(19)

For a .NET Web client, you need only these libraries:

■ WSWebServices.dll(.NET system Web client proxy)

■ ToolkitWebServiceClient.dll(.NET toolkit Web client proxy)

■ _{System XML and SOAP DLLs}

You can simply run the .NET Web client applications in the SDK samples distribution folder (samples/dist); any required DLLs are copied into the same folder by build scripts, and the required XML and SOAP DLLs will load from your .NET installation.

Toolkit Sample Web Services Components

Here are the components of the Toolkit Web Services Sample.

■ _{Custom SDK Application (}Toolkit.java).

This is the starting point. It is a custom running toolkit SDK application that implements all of the methods in the toolkit by adapting the original tools classes. This SDK application runs through a complete test scenario that exercises all of the tools (TM/TD kit import, leverage, TM/TD kit export).

The Java2WSDL generator uses this running SDK application to generate a WSDL description for the Web services. The WSDL2Java generator, in turn, uses the generated WSDL to generate Java Web server and client stubs. Likewise, for the .NET platform the .NET WSDL tool is used to generate .NET Web client stubs. The generated toolkit Web clients are completely decoupled from the toolkit Web server, and can be run across the Web on different computers.

All TM/TD (kit) import/export operations are done by serializing and deserializing streams between the toolkit’s Web client and Web server.

The Web services are served by the originalToolkit.javafile, which contains all of the Web service implementations. Axis directs all Web client requests to this service. The-coption is passed to WSDL2Java to tell it to use the same starting class for the actual Web services implementation.

■ toolkit\sdk-service.wsdl

Generated WSDL used to generate Web client proxies to bind to Web services. All of the Java and .NET Web client stubs are generated from this WSDL file.

■ _{Generated Java Web client proxy (}ToolkitSampleStub.java) These are the toolkit APIs that Java Web-client programs invoke.

■ test/ToolkitTest.java

Web client Java toolkit test application that runs over the Web with functionality identical to the original SDK toolkit application.

All TM/TD (kit) import/export operations are done by serializing/deserializing streams between the toolkit’s Web client and Web server. This class uses the generated Web client stubToolkitSampleStubto access all Web service functionality.

■ _{.NET Web client support (}csharp)

All corresponding .NET C# Web client tests are in thecsharpsub-folder.

■ _{Generated .NET Web client proxy (}ToolkitSampleService.cs)

This is generated by running the .NETWSDL.exetool on the previously-generated WSDL.

(20)

toolkit> wsdl.exe /language:cs

/n:Com.Idiominc.Wssdk.Samples.Component.Webservices. Toolkit sdk-service.wsdl

Thebuild.dotnet.webservice.toolkitANT target compiles the toolkit client proxy class into a .NET DLL:

samples/dist/ToolkitWebServiceClient.dll

These are the toolkit APIs that .NET (C#, VB) Web-client programs invoke. Thebuild.dotnet.webservice.toolkitANT target performs this .NET Web client generation.

■ csharp/Test/ToolkitTest.cs

Web client .NET toolkit test application that runs over the Web with functionality identical to the original SDK toolkit application.

Thebuild.dotnet.webservice.toolkitANT target compiles the toolkit test class into a .NET .exe:

samples/dist/Toolkit.exe

You can then immediately run the compiled .exe because the build script copies the required .NET Web client proxy DLLs into the same folder.

All TM/TD (kit) import/export operations are done by serializing and deserializing streams between the toolkit’s Web client and Web server.

■ samples/docs/api/com/idiominc/wssdk/samples/ webservices/ component/toolkit/client

Generated Javadocs for the toolkit Web client proxy. These are the Web service interfaces against which the client application developer will program.

The Web client knows nothing about how these are implemented; the developer merely codes against these exposed interfaces.

■ toolkit\deploy.wsdd

Generated service descriptors for the toolkit Web service; these are used for deploying the toolkit Web service on the application server.

toolkit\deploy.wsdd

Generated service descriptors for the toolkit Web service; these are used for deploying the toolkit Web service on the application server.

So what happens if I have more information I want to add?

Samples Provided Outside the Toolkit

There are four other component samples provided outside the SDK toolkit itself.

UserList Sample (samples/component/webservices/userlist)

This is a simple sample that implements the SDK servlet UserList sample as a Web service. This sample simply enumerates all current WorldServer users.

(21)

Noconfig.propertiesis required for this sample, and no special WorldServer test environment setup is required.

Translation Memory Sample

(samples/component/webservices/tm)

This is a sample Web service object-manager for accessing WorldServer factory services that manage translation memory and translation group objects.

This demonstrates a Web-services manager using system SDK data transfer objects in a custom SDK Web service application.

For detailed instructions about the WorldServer test environment that is a prerequisite for running this sample, read itsconfig.propertiesfile.

Note: This sample is for tutorial purposes only; the Web service APIs illustrated in this sample are already available in the WorldServer system Web Services Suite.

Workflow Sample (samples/component/webservices/workflow)

This is a sample Web services project manager for managing project-groups, projects, and tasks. It demonstrates a Web-services subsystem using custom data transfer objects that wrap data obtained from system SDK data objects. WorldServer projects are created remotely, and their status is monitored until all tasks enter the translation step according to the test workflow.

This sample provides a setup Web method that creates and executes a project-group containing a specified number of projects and tasks. It includes a teardown Web method that cancels a running project-group, projects, and tasks. It relies on a simple translation test workflow.

For detailed instructions about the WorldServer test environment that is a prerequisite for running this sample, read itsconfig.propertiesfile.

Note: The Web services workflowsample run.app.workflowANT target additionally requires WorldServer to be running because it exercises workflows and projects execution. These are performed by WorldServer daemons.

WSDL Sample (samples/component/webservices/wsdl)

This is an SDK implementation of a pure custom Web service component using only WSDL dynamic invocation. It exposes WorldServer functionality via Web services in a standard way that can be accessed from anywhere using only the accompanying

sdk-service.wsdl.

For instructions on how to build, deploy, and run this sample, see itsreadme.txtfile. For dynamic WSDL invocation, the Axissamples.client.DynamicInvokertool is used. For example, to create projects using a WorldServer session:

(22)

> java samples.client.DynamicInvoker sdk-service.wsdl createProject 213840201 "WebServiceTest"

"Project for testing Web Service" default French-France

/FileSystem/English-US/HTML/10/Overview.htm "Simple Translation" 0 UnitTestCostModel0

createProjectReturn=

Loading assets... Project created for locale French-France...

1 project was created. Project Group of ID 1065 was created.

SDK Web Service Component Class

The server side genericcom.idiominc.wssdk.component.Webservice.WSObject

.class serves a number of purposes. It provides the following generic services:

■ _{Session authentication for all Web service requests}

■ _{Local transaction management for all Web service requests} ■ _{Data Transfer Object data for all participating objects}

Session authentication and local transaction management are provided by this method on WSObject.

protected Object run(WSRunnable runnable) throws Exception

All Web service methods execute a code in a Web service secure context provided by this method.

System Web Service Java Server Pages

Web Service Java Server Pages are also generated by the System Web service generator from the Web service interfaces, for initial smoke testing of system Web service

component methods. These Java Server Pages are available only for system Web services. Only WorldServer Administrators are permitted to access these Java Server Pages. These pages enable user-friendly, non-programmatic invocation of all exposed Web service methods using a Web browser. Web service pages display Web method listings, parameter inputs for selected methods, and results of invoking selected methods. This

(23)

provides arbitrary servletbased method invocation functionality, and provides a convenient way to test Web service implementations.

The frames of a generated Web services page are as follows:

■ Methods_{frame – displays all exposed Web-service methods for the current Web}

service.

■ Parameters_{frame – requests input for all named method parameters; for}

WorldServer parameters, enter appropriate identifier values and check the appropriate identifier checkbox(es) where multiple identifiers are available for that object. Parameter values entered must match identifier types indicated by all checked identifier boxes.

■ Result_{frame – displays the Data Transfer Object results of invoking the Web}

service method with specified parameters. You can recursively follow links to additional Web service pages or Data Transfer Objects. Each Web service page is displayed in the context of a WorldServer Data Transfer Object currently associated with the Web service at runtime.

The typical root URL for this servlet component is:

http://localhost:8080/ws/webservices/WSContext/Main.jsp.

(24)

Sample Java Server Demo

The following sample demonstrates some of the system Web services Java Server Pages. Note: You must replace entry values shown below with your own search text, locale names, etc.

Preparation:

1. In WorldServer, navigate to Tools > Translation Memories . 2. Select an available translation memory.

3. Using the Standard search type, identify a Source Language, two Target Languages, and some “Search For” terms and Minimum Score % that will return some TM entries. Note these values for use in your Web services tests, below.

4. Navigate to Tools > Term Databases . 5. Select an available term database.

6. Identify a “Search In” language and a “Search For” term that will return some TD entries. Note these values for use in your Web services tests.

Sample Demo Steps

Procedure

1. Navigate tohttp://localhost:8080/ws/webservices/WSContext/Main. jsp(Forlocalhost:8080, substitute the location of your WorldServer system.) 2. Click the Method link:loginUser(String, String)

3. Enter Parameter values:

4. To execute the method, click Invoke. (To see the Invoke button you may need to move the bottom border of the Parameters frame downward.)

5. In the Result frame, to get to the WorldServer Services page click the WSContext link in the Object column.

6. Click the link: TmManager Service.

7. Click the Method link:getAllTms(). Invoke this method. (There are no parameters, but to see the Invoke button you may need to move the bottom border of the Parameters frame downward.)

8. In the Result frame, locate the TM that you identified in the demo Preparation instructions. For this TM, click the link:tm.WSTm.

9. Click this Method link:lookupSubstring(String, linguistic. System Tools and Custom Components

(25)

10. Enter Parameter values:

11. Invoke this method. In the Result frame, WorldServer displays TM hits for standard lookup of the specified search text.

12. Enter different Parameter values from those that you entered in Step 10.

13. Invoke this method again. In the Result frame, WorldServer displays TM hits for standard lookup of the specified search text.

14. Click this Method link:searchFreeform(String, linguistic.WSLanguage, linguistic.WSLanguage, int)

15. Enter Parameters:

16. Invoke this method. In the Result frame, WorldServer displays TM hits for the freeform SQL wildcard query.

17. Return to the WorldServer Services page by clicking theServiceslink in the top right corner of the Parameters frame.

18. Click the link:TdManager Service.

19. Click the Method link:getTds(). Invoke this method. 20. In the Result frame, click the link:td.WSTdManager.

21. In the Result frame, locate the TD that you identified in the demo Preparation instructions. For this TD, click the link:td.WSTd.

22. Click this Method link:lookupWithWildcards2(String, linguistic. WSLanguage, linguistic.WSLanguage)

23. Enter Parameter values. (Note that the search term is preceded and followed by asterisks (*). For example, *mark*:

24. Invoke this method. In the Result frame, WorldServer displays all TD hits that contain your search term.

(26)

ANT SDK Custom Web Services Build

Targets

ANT targets for building and deploying all SDK Web service samples and running these samples to verify the generated services are provided in ANT scriptsamples/

build.xml. There are individual targets for building, deploying, and running samples as described above. There are also the targets described below for building, deploying, and running all of the Web services samples in a single operation.

Thedeploy.webservicesANT targets require the environment variable %WS_ HOME% to be configured. For example:

set WS_HOME=\webapps\ws

Thedeploy.webservicesand

run.webservices

ANT targets require a running WorldServer Web application.

■ build.webservices.samples

Generates and builds all SDK Web services samples.

samples> ant build.webservices.samples

■ deploy.webservices.samples

Deploys all Web services samples.

samples> ant -Dws.host=localhost:8080 -Dws.context=ws deploy.webservices.samples

Note: Make sure that the application server context is capable of reloading the newly-built Web services server JARs during deployment. If not, you must restart your application server after this step.

■ run.webservices.samples

Runs all Web services samples.

samples> ant -Dws.host=localhost:8080 -Dws.context=ws run.webservices.samples

■ build.dotnet.webservices.samples

Builds all .NET SDK Web services client samples.

samples> ant build.dotnet.webservices.samples

■ run.dotnet.webservices.samples

Runs all .NET SDK Web services client samples.

(27)

samples> ant -Dws.host=localhost:8080 -Dws.context=ws run.dotnet.webservices.samples

Note: NOTE: The Microsoft .NET SDK is required for all .NET ANT targets. For information on obtaining the .NET SDK, seebuild.dotnet.webservice. toolkit, above.

Deployment Known Limitations

Component Manager Not Available

Unlike all other SDK components, deploying Web services custom components does not use the SDKWSComponentManager. Web services custom components do not get uploaded to the WorldServer database through Management > Administration

> Customization , as do other components.

Instead, you must copy your Web services custom component JARs into the proper place on your application server computer,/WEB-INF/lib/in your installed WorldServer application folder.

Also, Axis toolorg.apache.axis.client.AdminClientmust be invoked manually, passing as parameters the target WorldServer Web services URL and the Web services deployment descriptor. For example:

toolkit> java org.apache.axis.client.AdminClient -l http://localhost:8080/ws/services deploy.wsdd

Special considerations apply to this deployment mechanism in a cluster environment and with re-installation or upgrade of WorldServer.

In a cluster environment, you must deploy your custom Web services server JARs on every node in the cluster, and you might need to restart each node (if hot deployment does not work properly).

When WorldServer is re-installed or upgraded, you must preserve and restore all custom Web services JARs. Otherwise they could easily get lost in the transition. In addition, you should deploy the new versions of any sample components that you had previously installed.

(28)

Axis Clients Not Compatible with Dynamic

Reloading

Axis clients do not work properly in WorldServer if the Web services client classes are dynamically reloaded as part of other WorldServer components such as Automatic Actions.

Multiple inconsistent versions of classes can result from uploading Web services client classes as part of the Zip file of another component (such as an Automatic Action). This may be due to Axis class caches not being refreshed when classes are dynamically reloaded. Axis XML serializers cache classes and bean getter and setter methods of those classes. When a class is reloaded by the WorldServer component class loader when the Automatic Action is executed after any upload operation, some parts of Axis serializers may still refer to obsolete versions of the class and its methods.

This results in multiple inconsistent versions of the classes cached in memory, which causes class-cast exceptions, or messages such as:

java.lang.IllegalArgumentException: object is not an instance of declaring class

To avoid this situation, package your Axis client classes in a separate JAR and deploy them manually on each application server by copying them to/WEB-INF/lib/. Avoid uploading them on the fly as part of automatic-action or other component Zip files. Split the componentdependent Axis Web client classes so that the system class-loader will load them only once, instead of them being re-uploaded every time by the WorldServer component class loader.

SDK Web Services Developers Guide. SDL WorldServer 10.2