SDK Web Services Developers Guide SDL WorldServer 10.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. IfyouareanentityoftheU.S.government,youagreethattheprogram(s)anddatareferredtointhisdocumentareCommercial ComputerSoftware,asdefinedintheF.A.R.,andtheDoDF.A.R.Suppl.,andaredeliveredwithonlythoserightssetforthinthe 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 oftheprogram(s).sdlshallnotbeliableforanyclaimsordamagesarisingfromsuchuseoftheprogram(s)foranysuch 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 II SDK Web Services Developers Guide
Contents 1 AbouttheSDLWorldServerSDKWebServicesDeveloperGuide... 1 SDLWorldServerDocumentationandResources... 1 2 Introduction... 5 WSDL-basedWebServices... 5 WebServicesPrivileges... 5 SystemSDKWebServices... 6 WebServicesConfiguration... 8 3 SystemToolsandCustomComponents... 9 SystemSampleTools... 9 WebServicesGeneration... 11 CustomComponentSamples... 11 ToolkitSample... 12 BuildingandRunningtheToolkitSample... 12 RequirementsforRunningToolkitWebServicesSamples... 14 ToolkitSampleWebServicesComponents... 15 SamplesProvidedOutsidetheToolkit... 16 SDKWebServiceComponentClass... 18 SystemWebServiceJavaServerPages... 18 SampleJavaServerDemo... 20 SampleDemoSteps... 20 ANTSDKCustomWebServicesBuildTargets... 22 DeploymentKnownLimitations... 23 Index... 0 SDK Web Services Developers Guide III
IV SDK Web Services Developers Guide
Chapter 1 About the SDL WorldServer SDK Web Services Developer Guide Scope 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. 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 Information on embedded translation tool for brief reviews or edits. SDK Web Services Developers Guide 1
About the SDL WorldServer SDK Web Services Developer Guide 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.afullwebhelpsystemisavailablefromthehelplinkatthetopofeachpage. 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/ 2 SDK Web Services Developers Guide
About the SDL WorldServer SDK Web Services Developer Guide WorldServer Online Help Context-sensitive help is available for most pages in WorldServer from the More Info...link.AfullwebhelpsystemisavailablefromtheHelplinkatthetopofeach page. SDK Web Services Developers Guide 3
About the SDL WorldServer SDK Web Services Developer Guide 4 SDK Web Services Developers Guide
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 fromtheworldserverwsdl,andthenusedtoinvokethewebservicesat 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: SDK Web Services Developers Guide 5
Introduction 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. AnyonewiththisWebServicesprivilegecanusemostoftheAPIsexposedinthesystem 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 butnotthecanremoveobjectsusingwebservicesprivilegecanuseonlythoseweb 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 Webservicescurrentlyexposed.ThislistwillcontinuetogrowinthefutureasmoreSDK 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. TheSDKsystemWebservicesarepackagedtorunoutoftheboxusingthedeployed 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. 6 SDK Web Services Developers Guide
Introduction The Axis deployment file%ws_home%/web-inf/server-config.wsdd included in the WAR file is a portable, application-server-neutral WSDD file of deployed System SDKWebservicesthatenablestheseWebservicestorunoutoftheboxatthecustomer 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.* AllSDKclientproxypackagesaredeliveredinthe.NETDLL: 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 SDK Web Services Developers Guide 7
Introduction Java Web client proxies Generic Web client WorldServer object ThisobjectisextendedbyallJavacustomandsystemSDKWebclientproxies; 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 forallofthesdkwebservices,inthisfile: WEB-INF/server-config.wsdd YoucangetafulllistingofallcurrentlydeployedWebservicesviathissampleURL: http://localhost:8080/ws/services In place of localhost:8080, substitute the location of your WorldServer system. 8 SDK Web Services Developers Guide
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 the dotnet sub-folder of thefolderspecifiedabove.thereisa.netversionequivalenttomostofthejavaweb services sample tools. Similarly, PERL(SOAP::Lite) Web services tools(equivalent to the Java tools) are in the perl sub-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, see http://ws.apache.org/wsif/. The com.idiominc.wssdk.samples.tools.webservices package contains these Java and.net sample Web service utility tools: Sample CheckinAsset CheckoutAsset Description Checks in versioned assets in WorldServer through WorldServer AIS connectors that support versioning Checks out versioned assets in WorldServer through WorldServer AIS connectors that support versioning SDK Web Services Developers Guide 9
Sample CreateProject CreateTD CreateTDGroup CreateTM CreateTMGroup Description Creates and executes project groups Creates TDs using the specified names, if TDs do not already exist with the specified names Creates a TD Group using the specified name and specified write andmembertds,ifatdgroupdoesnotalreadyexistwiththe specified name Creates TMs using the specified names, if TMs do not already exist with the specified names Creates a TM Group using the specified name and specified write andmembertms,ifatmgroupdoesnotalreadyexistwiththe specified name DeployComponent Deploys components to WorldServer DownloadAsset ExportKit ExportTD Downloads files from WorldServer Exports translation kits Exports term databases ExportTDEntries Exports term database entries ExportTM Exports translation memories ExportTMEntries Exports translation memory entries ImportKit ImportTM ImportTD ScopeAsset SearchTD Imports translation kits Imports term databases Imports translation memories Scopes assets using specified target locale and TM, and displays the scoping report 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 SetFileAttribute UploadFile Performs a fuzzy search on specified TM and produces CSV output of search results Attaches files to WorldServer projects Uploads files to WorldServer 10 SDK Web Services Developers Guide
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.wsdl2java generation 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 script samples/build.xml included 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 the config.properties file for each sample. You must configure the samples using the config.properties file 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 Youmaychoosetousetheseandskipthegenerateandbuildstepsforthesamples.Butif you are interested in developing your own custom Web services components you will needtogenerateandbuildyourwebservices,andagoodplacetostartisbygenerating and building the samples. SDK Web Services Developers Guide 11
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 TheoriginalSDKsampletoolspackageonwhichthetoolkitWebservicesarebasedisa collection of utilities implemented using WorldServer SDK. To learn how to run each utility, refer to the sample Javadocs. The package includes these tools. Sample ExportKit ImportKit LeverageAssets TDImporter TMImporter Description Exports a Translation Kit from World Server in order to work offline(for example, utilizing WorldServer Desktop Workbench) Uploads back into WorldServer assets that were translated offline Leverages WorldServer asset(s) by filtering, applying translation memory matches, generating scoping information, and (optionally) generating partial translations Performs a batch import of Term Databases from SDL MultiTerm files 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 its config.properties file. 12 SDK Web Services Developers Guide
In the ANT script samples/build.xml, the ANT targets that generate, build, deploy, andrunthewebservicearedescribedbelow.seealsoantsdkcustomwebservices Build Targets, below. build.webservice.toolkit Builds the original SDK application and generates the toolkit Web service; generates WSDL from Toolkit.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: Specify ws.host and ws.context parameter values to customize the WorldServer URL. Deploys the toolkit Web service on the running application server; the application servermayneedtoberestartedandmustberunningbeforeyourunthistarget. Prerequisite: Requires the WorldServer environment variable WS_HOME to 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: Specify ws.host and ws.context parameters to customize the WorldServer URL. Prerequisite: Requires the WorldServer environment variable WS_HOME to 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 URLinaWebbrowsertolaunchaWorldServersessionontheapplication server. Example: Java Web client Using the run.webservice.toolkit target, specify ws.host and ws.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 the run.webservice.toolkit target, 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 SDK Web Services Developers Guide 13
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 targets build.dotnet.webservice.toolkit and run.dotnet.webservice.toolkit are also available to build and run the.net Web client proxy and tests. Tobuildthe.NETWebclient: samples> ant build.dotnet.webservices.samples AswiththeJavaWebclient,torunthe.NETWebclientapplicationyoumust specify the WorldServer Axis servlet URL. Example:.NET Web client Using the run.dotnet.webservice.toolkit target, specify ws.host and ws. context parameters 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 the run.dotnet.webservice.toolkit target, 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. ForaJavaWebclient,youneedonlytheseJARs: 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) 14 SDK Web Services Developers Guide
Fora.NETWebclient,youneedonlytheselibraries: 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.netplatformthe.netwsdltoolisusedtogenerate.netwebclientstubs. The generated toolkit Web clients are completely decoupled from the toolkit Webserver,andcanberunacrosstheWebondifferentcomputers. 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 original Toolkit.java file, which contains all of the Web service implementations. Axis directs all Web client requests to this service. The-coptionispassedtoWSDL2Javatotellittousethesamestartingclassfortheactual Web services implementation. toolkit\sdk-service.wsdl Generated WSDL used to generate Web client proxies to bind to Web services. All ofthejavaand.netwebclientstubsaregeneratedfromthiswsdlfile. 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 stub ToolkitSampleStub to access all Web service functionality..net Web client support(csharp) All corresponding.net C# Web client tests are in the csharp sub-folder. Generated.NET Web client proxy(toolkitsampleservice.cs) This is generated by running the.net WSDL.exe tool on the previously-generated WSDL. SDK Web Services Developers Guide 15
toolkit> wsdl.exe /language:cs /n:com.idiominc.wssdk.samples.component.webservices. Toolkit sdk-service.wsdl The build.dotnet.webservice.toolkit ANT target compiles the toolkit client proxyclassintoa.netdll: samples/dist/toolkitwebserviceclient.dll These are the toolkit APIs that.net(c#, VB) Web-client programs invoke. The build.dotnet.webservice.toolkit ANT 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. The build.dotnet.webservice.toolkit ANT target compiles the toolkit test classintoa.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. SowhathappensifIhavemoreinformationIwanttoadd? Samples Provided Outside the Toolkit There are four other component samples provided outside the SDK toolkit itself. UserList Sample(samples/component/webservices/userlist) ThisisasimplesamplethatimplementstheSDKservletUserListsampleasaWeb service. This sample simply enumerates all current WorldServer users. 16 SDK Web Services Developers Guide
No config.properties is 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 its config.properties file. 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 its config.properties file. Note: The Web services workflow sample run.app.workflow ANT 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 its readme.txt file. For dynamic WSDL invocation, the Axis samples.client.dynamicinvoker tool is used. For example, to create projects using a WorldServer session: SDK Web Services Developers Guide 17
> 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= <b>loading assets...</b> Project created for locale <i>french-france...</i> <p><b>1 project was created.</b> Project Group of ID 1065 was created. SDK Web Service Component Class The server side generic com.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 AllWebservicemethodsexecuteacodeinaWebservicesecurecontextprovidedbythis 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 18 SDK Web Services Developers Guide
provides arbitrary servletbased method invocation functionality, and provides a convenient way to test Web service implementations. TheframesofageneratedWebservicespageareasfollows: 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. SDK Web Services Developers Guide 19
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, andsome SearchFor termsandminimumscore%thatwillreturnsometm 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. Identifya SearchIn languageanda SearchFor termthatwillreturnsometd entries. Note these values for use in your Web services tests. Sample Demo Steps Procedure 1. Navigate to http://localhost:8080/ws/webservices/wscontext/main. jsp(for localhost:8080, substitute the location of your WorldServer system.) 2. Click the Method link: loginuser(string, String) 3. Enter Parameter values: 4. Toexecutethemethod,clickInvoke.(ToseetheInvokebuttonyoumayneedto 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 toseetheinvokebuttonyoumayneedtomovethebottomborderoftheparameters 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. WSLanguage, linguistic.wslanguage, double) 20 SDK Web Services Developers Guide
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.ReturntotheWorldServerServicespagebyclickingtheServiceslinkinthetopright 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.IntheResultframe,locatetheTDthatyouidentifiedinthedemoPreparation 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. SDK Web Services Developers Guide 21
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 script samples/ 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. The deploy.webservices ANT targets require the environment variable%ws_ HOME% to be configured. For example: set WS_HOME=\webapps\ws The deploy.webservices and 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. 22 SDK Web Services Developers Guide
samples> ant -Dws.host=localhost:8080 -Dws.context=ws run.dotnet.webservices.samples Note:NOTE:TheMicrosoft.NETSDKisrequiredforall.NETANTtargets. For information on obtaining the.net SDK, see build.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 SDK WSComponentManager. 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 tool org.apache.axis.client.adminclient must 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 everynodeinthecluster,andyoumightneedtorestarteachnode(ifhotdeploymentdoes 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. SDK Web Services Developers Guide 23
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 classesaspartofthezipfileofanothercomponent(suchasanautomaticaction).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 maystillrefertoobsoleteversionsoftheclassanditsmethods. 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. 24 SDK Web Services Developers Guide