A Altering Existing WSX Code to Interact with JAX-WS-Based Framework

This appendix provides background and procedural information to modify existing WSX code to interact with the JAX-WS-based framework of PLM Release 9.3.4 and future PLM releases.

A.1 Introduction

Agile WebService Extensions (WSX) was implemented to enable PLM installations extend the functionality of their PLM systems and expose site-specific solutions as a web service. This framework was based on the Apache eXtensible Interaction System (AXIS) and was available in PLM 9.3.3 and earlier releases.

Starting with PLM Release 9.3.4 and future PLM releases, Agile Web services were updated to use JAX-WS, a technology in Java for building web services to communicate using XML This document provides detailed procedures to migrate existing pre-release 9.3.4 web services to PLM Release 9.3.4.

A.1.1 Objectives

This document seeks to enable users to:

Modify existing web services code to interact with JAV-WS technology Understand basic concepts of web services using the JAV-WS technology and workflow in this technologyEnd to end testing of modified JAX-WS code

A.1.2 References

You can find useful information about JAX-WS technology at the following sites:

Apache Axis - http://ws.apache.org/axis/ JAX-WS Reference Implementation - https://jax-ws.java.net/

A.1.3 Pre-requisites

Make sure you have downloaded and installed the following products/components to modify existing WSX code to operate in an Agile PLM Release 9.3.4 environment:

Agile PLM 934JDK 7 or higher Apache ANT

A.2 Preparing Project Libraries

To enable web services interact with JAX-WS technology, the JAX-WS-based client and Apache Commons CLI libraries must run the MyFirstWebService example. Also, you must copy the new jar file to support javaws web service client.

To do this, open the WSX lib folder, and with the exception of the commons-cli.jar file, delete all other .jar files in the folder. The new.JAR file that you must copy to the lib folder, is com.oracle.webservices.wls.jaxws-wlswss-client.jar. You can access this file from ORACLE_HOME/wlserver/modules/clients/.

Note:

Alternatively, if you delete the commons-cli.jar file, you can download the commons-cli-1.2-bin.zip file from Apache's Download Commons CLI sight.

A.3 Updating the build.XML File

Use the following procedure to update the build.xml file.

To update the build.xml file:

Open the build.xml file located in the root project folder, and with the exception of ${built.classes.dir}, ${api.jar}, commons-cli.jar, remove all .jar files.

Add com.oracle.webservices.wls.jaxws-wlswss-client.jar located in the lib folder to build.classpath. The ant build path reference is as follows:

<path id="build.classpath">
   <pathelement location="${built.classes.dir}"/>   <pathelement path="${api.jar}"/>   <pathelement path="${lib.dir}/commons-cli.jar"/>
   <pathelement path=      "${lib.dir}/com.oracle.webservices.wls.jaxws-wlswss-client.jar"/></path>

Remove the following Axis taskdef entries because it is obsolete:

<taskdef resource="axis-tasks.properties"><classpath><path refid="build.classpath"/><pathelement location="${built.classes.dir}"/></classpath></taskdef>

Add the following ant taskdef statements to the build xml, as shown below.

<taskdef name="clientgen" classname="weblogic.wsee.tools.anttasks.ClientGenTask" classpathref="build.classpath" />

Note:

From an existing WSDL file, the clientgen Ant task generates the client component files that client applications use to invoke both WebLogic and non-WebLogic Web Services. http://docs.oracle.com/cd/E13222_01/wls/docs92/webserv/ anttasks.html#wp1075710

Delete ant target generate-stubs, generate-stubs-file, generate-stubs-url from the build xml file.

Add ant target generate-stubs and generate-stubs-file as shown below.

<target name="generate-stubs-file" depends="init>
   <clientgen wsdl="${wsx.url}/${serviceName}?wsdl" 
              destDir="${built.dir}/src" 
              type="JAXWS">   </clientgen>  <jar jarfile="${built.dir}/MyFirstWebServiceStub.jar">     <fileset dir="${built.dir}/src" includes="**/*.class"/>  </jar></target><target name="generate-stubs" depends="init,generate-stubs-file"/>

From ${basedir}/custom.properties, add the property file in build.xml to load other necessary data such as the wsx.url, servicename, username and so on.
```
<property file="${basedir}/custom.properties" />
```

A.4 Importing the Project to Eclipse Development Environment

This will enable you to use the Eclipse development environment to develop your MyFirstWebService example.

To import the project to Eclipse development environment:

In Eclipse, click File > New > Java Project.
In the New Java Project dialog, type MyFirstWebService and in the Location box, type the path to wsx in SDK_Samples folder (See the Note in"Client-Side Components.") If necessary, unzip SDK_samples.zip.
In Eclipse, select the MyFirstWebService project, and right click the pointer to open the Properties for MyFirstService dialog.
In MyFirstWebService dialog, select the Libraries tab, followed by the Add External JARs button to add the AgileAPI.jar and add com.oracle.webservices.wls.jaxws-wlswss-client.jar, commons-cli.jar in the lib folder, located in the SDK_Samples folder.

A.5 Migrating the WS Server Code from AXIS to JAX-WS

JAX-WS (a part of the Java Web Services Development Pack) uses annotations that were introduced in Java SE 5 to simplify the development and deployment of web service clients and endpoints. It uses annotations with Web services to configure bindings and handler chains to set names of portType, service, and other WSDL parameters.

Note:

Annotations are used at build time to map Java to WSDL files and XML schema, and at run time to control how the JAX-WS runtime environment processes and responds to Web service invocations.

For MyFirstWebService example, you can use the following statement to declare the Jaxws web service.

@WebService(portName = "MyFirstWebService", serviceName = "MyFirstWebService", targetNamespace = "http://xmlns.oracle.com/MyFirstWebService")

A.6 Deploying the Web Service in Agile Extensions

Run the ANT target deploy-service to compile and deploy MyFirstWebService to Agile $AGILE_HOME/integration/sdk/extensions folder.Subject to your environment, you can access WSDL from the following sites:

http://hostname:port/virtualPath/externsion/MyFirstWebService?wsdl

A.7 Generating Web Service Client Artifacts

To generate the client-side stubs from existing WSDL, do as follows:

To generate client-side stubs from existing WSDL:

Create custom.properties in project's WSX folder with the following content:

wsx.url=http://slc01bem.us.oracle.com:7001/web/extension serviceName=MyFirstWebService
Run the ant target generate-stubs to generate the client stubs jar, MyFirstWebServiceStub.jar in the lib folder.

A.8 Migrating the Client Code

To use the new generated client-side stubs, import the MyFirstWebServiceStub.jar file to Eclipse and open MyFirstClient.java. The getstub() method shown below initializes the client-side stubs to the desired web service engine.

static MyFirstWebService getStub(CommandLine cl) throws Exception {URL u = generateURL(cl);MyFirstWebService_Service locator = new MyFirstWebService_Service();MyFirstWebService stub = (MyFirstWebService) locator.getMyFirstWebServicePort();

// Configure the stub with the necessary authentication informationMap<String, Object> reqContext = ((BindingProvider)stub).getRequestContext();reqContext.put(BindingProvider.USERNAME_PROPERTY, cl.getOptionValue(USER_SHRT));reqContext.put(BindingProvider.PASSWORD_PROPERTY,cl.getOptionValue(PASSWORD_SHRT));reqContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, u);return stub;}

A.9 Modifying the Runner CLI Scripts

The Apache Commons CLI library, provides an API for parsing the command line options parsed to programs. Thus, running this API enables you to modify the two tmpl files shown below.

To modify the tml file for Windows:

Open runner.bat.tmpl for windows.

Modify the classpath as shown below:

set "CLASSPATH=@BUILT.CLASSES.DIR@"set "CLASSPATH=%CLASSPATH%;@LIB.DIR@/commons-cli.jar"set "CLASSPATH=%CLASSPATH%;@BUILTLIB.DIR@/MyFirstWebServiceStub.jar"set "CLASSPATH=%CLASSPATH%;     @LIB.DIR@/com.oracle.webservices.wls.jaxws-wlswss-client.jar"

To modify the .tml file for Linux/Unix:

Open the runner.sh.tmpl for Liunx.

Modify the classpath as follows:

cp=@BUILT.CLASSES.DIR@cp=$cp:@LIB.DIR@/commons-cli.jarcp=$cp:@LIB.DIR@/com.oracle.webservices.wls.jaxws-wlswss-client.jar

A.10 Running MyFirstWebService Sample on the WebService Client

To run the MyFirstWebService sample, invoke the CLASSPATH initializations information in the runner.sh (UNIX) or runner.bat (Windows.

To print out a usage statement for MyFirstClient, type the following command:

>runner client.MyFirstClient

To return the TitleBlock.Description field for part 1000-02, type the following:

>runner client.MyFirstClient -T 15000 -a "attribute_name"
-e virtual_path -h host -l port_no. -n item_number -p password -u username 

>runner client.MyFirstClient -T 15000 -a "TitleBlock.Description"                -e Agile -h  -l 80 -n 1000-02 -p agile -u jeffp