Skip Headers

Agile Product Lifecycle Management SDK Developer Guide - Using Extensions Release 9.3.3 E39308-01 |
| Contents

Previous | Next |

# 2 Developing Web Service Extensions

This chapter provides descriptions and procedures addressing Web Service Extensions and Web Services, Developing, Deploying, and using a Web Service, Authenticating Users, Preparing the Environment to Implement a WebService Sample, Web Service Clients, Creating a Web Service Client, Microsoft .NET Interoperability andWeb Service Extensions FAQs.

## 2.1 About Web Service Extensions

Web service extensions (WSX) is a Web service engine enabling communication between Agile PLM and disparate systems both internal and external including Enterprise Resource Planning (ERP) systems, Customer Resource Management (CRM) systems, Business-to-Business Integration systems (B2Bi), other Agile PLM systems, and supply chain partners. WSX can streamline the process for new product introduction (NPI), product changes, and rapid ramp-up of manufacturing resources. It can also simplify the process for aggregating raw product content and making critical product content available in real time to other core systems. WSX contains the tools and framework to develop new Agile PLM Web services.

You can use WSX to:

- Make product content available to Enterprise Application Integration (EAI) systems, which can then feed the data to a broad array of internal applications.

- Share product content with product design, manufacturing planning, shop floor, Enterprise Resource Planning (ERP), and Customer Relationship Management (CRM) applications.

- Make product content available to Business-to-Business (B2B) systems, which can transfer Agile Application server data across corporate boundaries to a wide range of external applications.

- Provide content to exchanges, reports, and custom applications and import Product content data from ERP and other supply chain applications.

Note: Agile Integration Services (AIS) is a set of Web services that is built with WSX technology to provide programmatic import and export capabilities for the Agile PLM system. AIS is a separately licensed product. For more information about AIS, refer to the Agile Integration Services Developer Guide.

### 2.1.1 Key Features

WSX includes the following key features:

- Programmatic access to data - WSX provides programmatic access to data stored in Agile PLM systems and other data resources, allowing you to create custom applications to automate content transfer.

- Accessibility - WSX provides accessibility of Agile PLM product content outside the corporate firewall using standard HTTP(S) technology.

- Multiple programming language support - WSX supports any language that can create and understand Simple Object Access Protocol (SOAP) and/or Web Services Description Language (WSDL).

- Multiple output format support - WSX supports aXML and PDX 1.0. You can also use XSL to transform XML data into any format, or develop Web services that return data in any format.

- Security - WSX communicates with XML-compliant applications using Internet-standard communication and security protocols (HTTP and SSL), so the interface is both firewall-friendly and secure.

### 2.1.2 WSX Architecture

To connect to Agile PLM and the WSX framework, you use standard Web service invocation methodologies.

## 2.2 About Web Services

Web services is a technology for building distributed applications. These services, which can be made available over the Internet, use a standardized XML messaging system and are not tied to any one operating system or programming language. Through Web services, companies can encapsulate existing business processes, publish them as services, search for and subscribe to other services, and exchange information throughout and beyond the enterprise. Web services are based on universally agreed upon specifications for structured data exchange, messaging, discovery of services, interface description, and business process design.

A Web service makes remote procedure calls across the Internet. It uses HTTP(S) or other protocols to transport requests and responses and the Simple Object Access Protocol (SOAP) to communicate request and response information.

The key benefits provided by Web services are:

- Service-oriented Architecture - Unlike packaged products, Web services can be delivered as streams of services that allow access from any platform. Components can be isolated; only the business-level services need be exposed.

- Interoperability - Web services ensure complete interoperability between systems.

- Integration - Web services facilitate flexible integration solutions, particularly if you are connecting applications on different platforms or written in different languages.

- Modularity - Web services offer a modular approach to programming. Each business function in an application can be exposed as a separate Web service. Smaller modules reduce errors and result in more reusable components.

- Accessibility - Business services can be completely decentralized. They can be distributed over the Internet and accessed by a wide variety of communications devices.

- Efficiency - Web services constructed from applications meant for internal use can be used externally without changing code. Incremental development using Web services is relatively simple because Web services are declared and implemented in a human readable format.

Like any technology, Web services have some limitations. When developing Web services, you should consider the following:

- SOAP is a simple mechanism for handling data and requests over a transport medium. It is not designed to handle advanced operations such as distributed garbage collection, object activation, or call by reference.

- Because Web services are network-based, they are affected by network traffic. The latency for any Web service invocation can often be measured in hundreds of milliseconds. Thus, the amount of functionality provided by the service should be significant enough to warrant making a high-latency call.

- Web services are not good at conversational programming. Thus, when designing services to be exposed, you should try to make the service as independent as possible.

### 2.2.1 Web Services Architecture

You can view Web services architecture in terms of roles and the protocol stack:

- Web service roles:

  - Service provider - This provides the service by implementing it and making it available on the Internet.

  - Service requestor - This is the user of the service who accesses the service by opening a network connection and sending an XML request.

  - Service registry -This is a centralized directory of services where developers can publish new services or find existing ones.

- Web services protocol stack:

  - Service transport layer - uses HTTP to transport messages between applications. Other transports will be supported in future AIS releases.

  - XML messaging layer - encodes messages in XML format by using SOAP, a platform-independent XML protocol used for exchanging information between computers. It defines an envelope specification for encapsulated data being transferred, the data encoding rules, and Remote Procedure Call (RPC) conventions.

  - Service description layer -describes the public interface to a specific Web service by using the Web Service Description Language (WSDL) protocol. WSDL defines an XML grammar for describing network services as collections of communication endpoints capable of exchanging messages, which contain either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a network protocol and message format. WSDL allows description of endpoints and their messages regardless of what message formats or network protocols are used to communicate. A WSDL document defines services as collections of network endpoints (called ports). A port is defined by associating a network address with a reusable binding, and a collection of ports define a service.

  - Service discovery layer - centralizes services into a common registry by using the Universal Description, Discovery, and Integration (UDDI) protocol.

Note: WSX does not currently support UDDI or other service discovery layers.

### 2.2.2 Security

WSX communicates with XML-compliant applications using Internet-standard communication and security protocols (HTTP and SSL). Communication between WSX and its clients (via the Web server) may be encrypted via Secure Sockets Layer (SSL) and a server-side certificate, thus providing authentication, privacy, and message integrity. Using standard Java cryptography libraries, you can encrypt and decrypt files, create security keys, digitally sign a file, and verify a digital signature.

The Web service extensions framework forces any invocation request received from outside the firewall to be secure. In other words, all external requests to WSX must be secured using HTTPS or an equivalent protocol. Internal requests to WSX can be conducted insecurely, that is, using HTTP.

There are several ways to enforce username and password security when invoking a Web service. If you are using the Agile API to develop your Web service, you can specify the username and password in the createSession() parameters just as you would with any API program.

For more information about Java security and cryptography support, see `http://docs.oracle.com/javase/1.3/docs/guide/security/index.html`.

### 2.2.3 Tools

There is no single set of tools needed to access Web services. The tools you choose depend very much on the environment you use to develop clients. Basically, you'll need tools that enable you to generate and process XML, and process HTTP request/responses messages.

The WSX framework is based on the Apache eXtensible Interaction System (AXIS), which is a SOAP processor. However, you can use other implementations of SOAP tools, regardless of source language, to build Web service clients.

Note: The WSX Java samples included with the Agile SDK show how to use AXIS. For detailed information about AXIS, its features, and how to use it, refer to the AXIS Web site: `http://xml.apache.org/axis`

### 2.2.4 Finding Additional Information About Web Services

This is a list of some Web sites to explore:

- WebServices.Org - `http://www.webservices.org/`

- Web Services Architect - `http://www.webservicesarchitect.com/`

- Web Services Journal - `http://www.informatik.uni-trier.de/~ley/db/journals/jwsr/jwsr8.html`

- webservices.xml.com - `http://www.xml.com/pub/a/ws/2001/04/04/webservices/index.html`

- Apache Axis - `http://ws.apache.org/axis/`

- Java Web Services Developer Pack - `http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-jwsdp-419428.html`

- Sun ONE Web Services Platform Developer Edition - `http://dsc.sun.com/appserver/reference/techart/webservice.html`

- Microsoft .Net Framework - `http://msdn.microsoft.com/netframework/`

- SOAP::Lite for Perl - `http://www.soaplite.com/`

- Soap Tutorial - `http://www.w3schools.com/soap/default.asp`

## 2.3 Developing and Deploying a Web Service

Writing your own Web service is a simple task, consisting of a few steps:

1. Define your Web service's entry point(s). A Web service entry point (or operation) corresponds to a public method in a Java class.

2. Code your Web service operation's logic. You need not follow any special rules when coding the logic for your Web service operation. You may take advantage of third party code libraries as well as Agile-provided libraries, including the Agile API.

3. Compile your Java code as you normally would.

4. Copy the compiled JAR file(s) to AGILE_HOME\integration\sdk\extensions on the Agile Application Server computer. The deployment descriptor for the Web service should also be in the JAR file(s) in a file named META-INF/services/com.agile.wsx.Deployment.wsdd.

Note: If you have several application servers in a clustered environment, you must deploy Web service files on each server in the cluster.

The Agile Application Server automatically deploys all Web services listed in the deployment descriptor, ensuring that your latest changes have been applied.

### 2.3.1 About Deployment Descriptors

The Web service deployment descriptor file (Deployment.wsdd) is an XML file that is formatted according to Axis's Web Service Deployment Descriptor (WSDD) format. It declares and describes the set of Web services and Web service operations that are to be exposed via WSX. The WSDD file also defines any additional behavior that should be used when processing incoming SOAP requests (such as authentication, and so on) or responses (such as reformatting outgoing data).

The Axis documentation provides a good introduction to the WSDD format and its use. However, before consulting the Axis documentation, please be aware of the following constraints within WSX:

- The Web service deployment descriptor should not contain global WSX configuration information. The configuration information declared within Deployment.wsdd should be restricted to service-specific declarations.

- WSX does not support the Axis .jws-based Web services. While these sound good on paper, we have found our mechanism of redeploying Web services to be more robust and easier to work with in a development environment.

- For security reasons, WSX does not include the Axis AdminServlet.

For more information about Axis deployment descriptors, refer to the following Axis documentations:

- Axis User's Guide - `http://ws.apache.org/axis/java/user-guide.html`

See the sections entitled "Custom Deployment - Introducing WSDD" and "Service Styles - RPC, Document, Wrapped, and Message."

- Axis Reference Guide - `http://ws.apache.org/axis/java/reference.html`

See the sections entitled "Deployment (WSDD) Reference."

Note: These sites are subject to periodic change. In that event, use your favorite search engine to locate these documents.

### 2.3.2 Reserved Web Service Names

The following Web service names are reserved because they are used by Agile Integration Services (AIS). Do not use them to name a Web service that you've created.

- Export

- Importer

- Reserved Service names:

  - FSHelper, DmsService (File manager and Viewer)

  - Export, Importer (AIS)

  - ResponseService, PackageService, AcsStatusService (ACS)

## 2.4 Using a Web Service

Once you have developed and deployed your custom Web service, you will want to use it. You can access your Web service using a URL of the form `http://hostname:port#/virtualPath/integration/ws/WebServiceName`

Note: You must use the Agile-modified axis.jar file that is included with the Agile API.This file gets installed in the following location when you install Agile's API component: agile_Home\integration\sdk\lib\axis.jar

### 2.4.1 Defining a Web Service Entry Point

A Web service entry point (or operation) corresponds to a public method in a Java class. Not all public methods in a class need be exposed as an operation, but all operations correspond to public methods. Thus, if you have a Java class (such as MyClass), that exposes two public methods (such as methodOne and methodTwo), it is possible for you to expose either or both methods as Web service operations.

As a general rule, the simpler the datatypes used for your parameter and return types, the more interoperable your Web service operation will be. More complex datatypes will require either custom serializers/deserializers or additional support from the Web service framework. More information on the additional serializers/deserializers provided by Axis can be found at `http://ws.apache.org/axis/java/apiDocs/org/apache/axis/encoding/Serializer.html` and .`http://ws.apache.org/axis/java/apiDocs/org/apache/axis/encoding/Deserializer.html` These sites are periodically changed. In this case, invoke your favorite search engine to locate the latest information on these interfaces.

Note: As a rule, do not try to return an Agile API object, such as IAgileSession or IItem, from a Web service. Web services should only return data structures.

## 2.5 Authenticating Users

All default out-of-box Web services and user customized versions are protected by the application server. To access a protected Web service, add the following lines in your Web service client stub code:

// Configure the stub with the necessary authentication information

stub.setUsername(cl.getOptionValue(USER_SHRT));

stub.setPassword(cl.getOptionValue(PASSWORD_SHRT));

stub.setMaintainSession(true);

To remove the Web container protection for a specific Web service, add the following lines in the following applications:

application.ear#application.war/WEB-INF/web.xml

and

    application.ear#integration.war/WEB-INF/web.xml files:
    <security-constraint>

<web-resource-collection>

<web-resource-name>Unprotect web services</web-resource-name>

<url-pattern>/ws/<web service name></url-pattern>

<url-pattern>/services/<web service name></url-pattern>

</web-resource-collection>

    </security-constraint>
    HashMap params = new HashMap();

### 2.5.1 Using Single Sign-On Cookies for Client-Server Access

After a user on the WSX client is authenticated by the Agile 9.X server which is protected by third party single sign-on products, the browser is granted a Single sign-on cookie. This cookie is sent to the custom j2ee Web application, provided this application is in the same DNS domain as the Agile 9.X server. Now, to invoke the Web service deployed on Agile 9.X server, you can pass the single sign-on cookie instead of username and password as a valid credential.

Note: If you are using both username/password and single sign-on cookies, the single sign-on cookie has precedence over username/password.

#### 2.5.1.1 Deployment Architecture

Interactions and the request flow between the Agile server and WSX client is summarized in the following illustration.

#### 2.5.1.2 Invoking the Web Service Client with a Single Sign-on Cookie

This is accomplished by first, retrieving the single sign-on cookie from the HTTP request followed by modifying the SOAP binding stub code.

#### 2.5.1.3 Retrieving the Single Sign-On Cookie

Before invoking the Web service client stub, you must retrieve the single sign-on cookie in the HTTP request. By default, the single sign-on cookie provided by SiteMinder is called "SMSESSION." Modify the cookie to the format specified in RFC2965 available at `http://www.ietf.org/rfc/rfc2965.txt`. The simplest format is "name=value" where name and value are accessed by calling the javax.servlet.http.Cookie object method.

#### 2.5.1.4 Modifying the SOAP Binding Stub Code

Find the Web service SOAP binding stub class which is generated by wsdl2java utility of axis. It is usually called service-name.SoapBindingStub.java. Add a variable named cookies and a method to set the value as shown below.

To modify the SOAP binding stub code:

1. Add the following lines in the SOAP stub class:

   private String cookies = "";

   public void setCookies(String cookies) {

   this.cookies = cookies;

   }

2. Add the line in bold font in createCall() method.

   if (super.cachedPortName != null) {

   _call.setPortname(super.cachedPortName);

   }

   _call.setProperty(org.apache.axis.transport.http.HTTPConstants.HEADER_COOKIE, this.cookies);

   java.util.Enumeration keys = super.cachedProperties.keys();

3. Recompile this class and follow the sample below to invoke the Web service stub.

   ((soaping binding stub class name)stub).setCookies(sso cookies you got in step 2);

   stub.setMaintainSession(true);

4. Compare with the documented sample that requires username and password as valid credentials.

   stub.setUsername(username);

   stub.setPassword(password);

   stub.setMaintainSession(true);

5. Test the Web service client as part of the j2ee Web application.

## 2.6 Preparing the Environment for MyFirstWebService

To explain developing a Web service, a sample that highlights the development process is provided. The sample, called MyFirstWebService, is a simple example that demonstrates how to create a Web service that can use the Agile SDK to retrieve information about a particular Item and return the Item as the result of the Web service operation.

To support the desired operation, the following entry point is defined:

    public String getItemField(String[] args) throws RemoteException

MyFirstWebService sample uses a third party library called Jakarta Commons CLI and parses args as a set of command line arguments. Based on these arguments, the results are returned as a String. You can find more information on implementation details in the SDK_samples.zip folder described in "Client-Side Components." The path to MyFirstWebService is in samples\wsx\src\first. The remaining paragraphs in this section describe the deployment process and do not address implementation details.

### 2.6.1 Downloading Tools to Build the Sample

To build and deploy the MyFirstWebService sample, you must download the following tools:

Tool | Download Site
--- | ---
Java 2 SDK SE Version 1.5 | `http://www.oracle.com/technetwork/java/archive-139210.html`
Apache Project's Ant build tool, version 1.6.5 | `http://archive.apache.org/dist/ant/binaries/`

### 2.6.2 Installing the Java SDK

This section provides the instructions to install the Java SDK on Windows and on Solaris platforms. You can skip this section if you already have the proper version of Java installed.

To install the Java SDK on Windows:

1. Double-click the distribution and follow the installation procedures.

2. Set the system variable JAVA_HOME to point to the home directory of your Java SDK installation (for example, D:\j2sdk150).

To install the Java SDK on Solaris:

1. Execute the distribution (for example, $ ./ j2sdk-1_5_0-solaris-sparc.sh) and follow the installation procedures.

2. Set the environment variable JAVA_HOME to point to the home directory of your Java SDK installation (for example, /home/user/j2sdk150).

3. Execute your .profile or .cshrc (depending on your shell) file to reinitialize your environment settings.

### 2.6.3 Installing Ant

This section provides the necessary instructions to install Ant on Windows and Solaris environments. Use the information in "Downloading Tools to Build the Sample." to download the Ant tool.

To install the Ant on Windows:

1. Extract the contents of the Zip archive to a local directory and follow the installation procedures.

   The Ant distribution for Windows is a zip file (for example, apache-ant-1.6.5-bin.zip).

2. Open a command prompt window and verify that Ant can be invoked by entering the following command:

%ANT_HOME%\bin\ant -version

The following output is displayed:

Apache Ant version 1.6.5 compiled on <date>

To install Ant on Solaris:

1. Extract the contents of the tar archive to a local directory (for example, /home/user/ant).

   The ANT distribution for UNIX is a tar file (for example, apache-ant-1.6.2-bin.tar.gz).

2. Execute your .profile or .cshrc (depending on your shell) file to set up your environment.

3. From a command prompt, verify that Ant can be invoked by entering the following command:

$ANT_HOME/bin/ant -version

The following output is displayed:

Apache Ant version 1.6.5 compiled on compilation_date

## 2.7 Building MyFirstWebService Sample

Agile provides several sample programs for the SDK, including a sample Web service program called MyFirstWebService. To download the sample program, refer to the Note in "Client-Side Components." The MyFirstWebService sample is in the wsx folder in SDK Samples.

The Ant tool reads the build.xml script and builds all targets in the following sequence on the server that is running the WSX samples:

- Compiles the Java code for the Web service into MyFirstWebService.jar.

- Copies the resulting MyFirstWebService.jar file, which includes the Deployment.wsdd file, and the commons-cli.jar file into the .../sdk/extensions folder.

- Generates a script (either runner.bat or runner.sh) that can be used to run the client. (It conveniently sets the CLASSPATH needed to run the client.)

- Generates client-side stub files and places them in the following folder:

  sdk\samples\wsx\built\src\client located in Oracle Agile PLM 9.3 Event and Web Services Samples. To access this folder, see the Note in"Client-Side Components."

- Compiles the client classes and places them in your local server.

To build the WSX sample on the server platform:

1. Copy the SDK_samlpes (ZIP) file. For information to access this file, see the Note in "Client-Side Components."

2. Go to samples/WSX folder.

If there's no AgileAPI.jar in this folder, you are not able to compile the WSX sample. In that case, do as follows:

1. Go to $AGILE_HOME/sdk/samples/wsx on the server.

2. Download wsdl4j-1.5.1.jar from `http://archive.apache.org/dist/ws/axis/1_2/` (axis-bin-1_2.zip#/lib), and copy it to lib folder and rename the file to wsdl4j.jar.

3. Build the MyFirstWebService sample using the sample's build.xml file:

   - On Windows - %ANT_HOME%/bin/ant

   - On Solaris/Linux - $ANT_HOME/bin/ant

   Important: If you are not building the Web service sample under $AGILE_HOME/sdk/samples/wsx, then upload the wsx/built/MyFirstWebService.jar into $AGILE_HOME/integration/sdk/extensions. This directory is configurable in agile.properties on the server. Because the SDK will not generate WSDL files or WSXs when you invoke `http://hostname:port/virtualPath/services/MyFirstWebService?wsdl`, it will not return the required WSDL file. To generate these files do as shown in the next step.

4. Copy the package wsdl4j.jar file described above into Agile application.ear#APP-INF/lib folder and redeploy the ear file.

   Note: This step is necessary if you want to access the WSDL file.

5. In the WSX folder, invoke the applicable command below to generate the WSX stub.

Note: This step is necessary if you want to access the WSDL file.

- On Windows - %ANT_HOME%/bin/ant

  - Dwsx.url=http://webserver/virtualPath/services -Dusername=username -Dpassword=password

  - On Solaris/Linux - $ANT_HOME/bin/antDwsx.url=http://webserver/virtualPath/services Dusername=username -Dpassword=password

## 2.8 About Web Service Clients

This section describes the tools that you can use to develop client applications and languages that can generate and process XML files and HTTP request/response messages.

### 2.8.1 Client Programming Languages

Although Agile tests and certifies Java for use in developing AIS clients, SOAP messages are platform- and language-independent, which means you can use virtually any client programming language that can generate and process XML and process HTTP request/response messages. For example, you can develop clients in Java, Visual Basic.Net, C++, C, or Perl.

There are helpful libraries for Java, .Net, Perl, Python, C++, and C, and for other environments as well. Here are some Web sites where you can find more information:

- Apache Axis - Open source SOAP implementation for Java: `http://ws.apache.org/axis/`

- Java Web Services Developer Pack (JWSDP) - Sun's Java implementation of the SOAP protocol:`http://www.oracle.com/technetwork/java/index-jsp-136025.html`

- Microsoft .Net - An XML Web services platform for Microsoft Windows that can be used to create Web service clients:`http://msdn.microsoft.com/net`

- SOAP::Lite for Perl - A Perl implementation of the SOAP protocol: `http://www.soaplite.com/`

Note: For a comprehensive list of other SOAP implementations, see the following Web site:`http://www.soapware.org/`

### 2.8.2 Accessing a Web Service

In general, to access a Web service, you need to do the following:

1. Generate a SOAP request - In many cases, a Web-service-aware code library will be able to generate client-side stubs that generate an appropriately formatted SOAP request.

2. Submit that request to WSX via HTTP or HTTPS - Once an appropriate set of client-side stubs has been generated, a client application can use these stubs to submit a request.

3. Process the SOAP response - The client-side stubs usually are responsible for processing the SOAP response and converting the response into an appropriate set of return objects.

The WSX samples provide examples of how SOAP and Web service-related libraries can make this process simple. The following sections illustrate, using the MyFirstWebService sample, the above steps in greater detail.

## 2.9 Creating a Web Service Client

When you build and deploy MyFirstWebService, you also automatically generate the client-side stubs and the client classes. This section uses MyFirstClient as an example to describe some general aspects of how to create a Web service client.

### 2.9.1 Generating the SOAP Request

In most cases, generating an appropriate SOAP request is as simple as making use of client-side stubs. Many Web-service-aware code libraries are able to generate client-side stubs for you. This entails using a code generation utility along with the WSDL for the desired Web service.

Axis provides a WSDL2Java utility that can be used to generate client-side stubs. Other Web-service-aware libraries have their own client-side stub generation facility. Microsoft .Net includes a wsdl.exe utility. In the case of the WSX samples, the client-side stub generation occurs during the samples' build process.

Within the build.xml file, you will find the following Ant target:

    <target name="generate-stubs" depends="init" unless="stubs.present">

<fail unless="wsx.url">wsx.url must be defined</fail>

<axis-wsdl2java output="${built.dir}/src"

url="${wsx.url}/MyFirstWebService?wsdl">

<mapping namespace=""`http://www.agile.com/ws/SampleWsx`

package="client"/>

</axis-wsdl2java>

    </target>

This Ant target is responsible for generating the client-side stubs for MyFirstWebService. This invocation retrieves the MyFirstWebService WSDL from ${ws.url}/MyFirstWebService?wsdl, generates Java code in the client Java package, and places the source code within the ${built.dir}/src directory. For more information on the WSDL2Java utility, please consult the Axis documentation, which can be found on the Axis Web site at`http://xml.apache.org/axis`.

Once the client-side stubs have been generated, the user can use the generated object definitions in order to more easily generate the appropriate SOAP request. Rather than requiring the user to understand how to construct a valid SOAP request, these stubs allow the user to focus on the capabilities of the target Web service operation. Looking at the MyFirstClient.java sample found within ..\samples\wsx\src\client, note that the main method contains all the code used to generate the SOAP request.

### 2.9.2 Submitting the SOAP Request

The next step in a Web service operation is to properly submit the generated SOAP request to the Web service engine. When dealing with generated client-side stubs, this step is usually as simple as pointing the stubs to the desired server and invoking a method on the stubs. You do not need to worry about opening a connection. Instead, the generated stubs handle these details for you.

The MyFirstClient.java sample found within ..\samples\wsx\src\client illustrates how to submit the SOAP request in two places:

- The getStub() method is responsible for pointing the client-side stubs to the desired Web service engine.

- The stub.getItemField() method invocation found within the main method is responsible for submitting the request to the Web service engine. The submitting of the request is managed by the stubs themselves; you do not need to worry about the connecting, submitting, or marshaling particulars.

The details on how you point the stubs to the desired Web service engine and submit the request vary from code library to code library. Please consult the documentation for your Web-service-aware code library for more information.

### 2.9.3 Processing the SOAP Response

The processing of the SOAP response is usually handled via the generated client-side stubs. Without these generated stubs, you would be responsible for parsing the XML-based SOAP response and dealing with the many formatting and unmarshaling issues that arise. However, when dealing with generated stubs, all of these details are taken care of for you, allowing you to receive properly typed Java objects. Rather than require you to parse an XML document and discern what the returned data is, the stubs automatically do this for you.

The details on how SOAP responses are processed will vary from code library to code library. Some SOAP servers expect the client to know the datatype through some other means (perhaps WSDL). Please consult the documentation for your Web-service-aware code library for more information.

### 2.9.4 Running the Sample on the Web Service Client

To build and deploy the MyFirstWebService sample, use the CLASSPATH initializations information in the runner.sh (UNIX) or runner.bat (Windows) to run sample on the Web service client. You can find these files in the SDK_samples.zip. To access SDK_samples.zip, see the Note in "Client-Side Components."

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

    > runner client.MyFirstClient

The following usage statement returns the "Title Block.Description" field for part 1000-02:

> 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 "Title Block.Description"

-e Agile -h localhost -l 80 -n 1000-02 -p agile -u jeffp

### 2.9.5 Creating an Agile Session inside WSX

By default, the Web container protects the WSX. Therefore, you must specify user credentials when creating an Agile Session inside the WSX. The following example creates an Agile session within a protected WSX.

Example 2-1 Setting up a session inside a WSX

AgileSessionFactory factory = AgileSessionFactory.getInstance(null);

IAgileSession session = factory.createSession(null);

Note: Do not override the implicit session.

To have a different user, you need to make an explicit SDK session as if connecting from a remote client. That is, provide an argument to the AgileSessionFactory.getInstance() method.

Example 2-2 Creating an explicit session independent of the implicit session

    AgileSessionFactory factory = AgileSessionFactory.getInstance ("http://...");

params.put(AgileSessionFactory.USERNAME, ...);

params.put(AgileSessionFactory.PASSWORD, ...);

IAgileSession session = factory.createSession(params);

## 2.10 Microsoft .NET Interoperability

Microsoft's .NET framework technology is a development framework that provides an application programming interface (API) to the services and APIs of classic Windows operating systems, while bringing together a number of disparate technologies that emerged from Microsoft in the late 1990s: ASP, COM+, XML, SOAP, to name a few.

.NET also brings together all the languages provided by the Visual Studio environments provided by Microsoft such as Visual Basic, J++, and C++. Also, new languages have been developed - such as C# (read C Sharp) and the relatively new language to the .NET family, J# (read J Sharp). J# is actually Java in Microsoft disguise providing integration of Java into the .NET framework. Yet, J# will not work with the Java VM. J#, in essence, acts as a wrapper to contain Java-enabled code to be executed by the .NET Common Language Runtime (CLR), Microsoft's own 'virtual machine'.

The CLR is probably the most important component to the .NET framework. The CLR provides for the activation of objects, security checks, memory management, object execution, and memory cleanup (garbage-collection) when objects are no longer being used.

Another factor behind .NET is that it not only provides for the writing of Windows-based applications or Web-based applications (via ASP.NET) by using any of the languages mentioned, it also can integrate these languages into one common API. This means that developers can write language independent code, inherit from classes, catch exceptions, and take full advantage of polymorphism across differing languages across the .NET framework.

Important: Although the WSX framework (the AXIS SOAP processor) works fine with AXIS Web service clients, it is not completely compatible with .Net. Neither Microsoft nor the Apache group have conducted interoperability tests for AXIS and .Net. For simple data types, AXIS-based Web services should work fine with .Net-based Web service clients. For some complex data types (such as binary attachments), you may experience interoperability problems. For interoperability information about non-AXIS Web service implementations deployed outside of the Agile Application Server, contact the specific Web service vendor.

## 2.11 Web Service Extensions FAQs

This section answers common questions about Web service extensions.

What is Web service extensions (WSX)?

WSX is a framework for Agile customers to extend the functionality of the Agile PLM server using Web services.

What are Web services?

Web services use the SOAP messaging protocol to provide software services over the Internet, allowing software components to interact with each other around the world. Web services are not tied to any one operating system or programming language. They use WSDL to describe a service's public interface, essentially making Web services self-describing and therefore relatively easy to use.

What can I do with WSX that I can not do solely with Agile's Java API?

WSX provides firewall-friendly, XML-based integration with Agile PLM data using the standard HTTP(S) protocol. It supports any SOAP-compliant programming language. For example, you can create Perl or .Net clients for a Web service. WSX enables systems in different companies to interact with each other easily and securely. Services deployed within WSX take advantage of all the scalability, failover, and clustering features provided by the application server. There are also compelling performance benefits to services that run on the application server.

Does WSX support both secured and unsecured connections?

Yes. Requests that come to a Web service from outside the firewall are subject to different security requirements from requests that originate within the firewall. Two separate entry points are provided for each WSX, external (outside the firewall) or internal. External requests are made against a proxy server and then forwarded to the application server. The proxy server resides in the DMZ. Internal requests can be made against the same secure proxy server, another proxy server that doesn't reside in the DMZ, or directly against the application server, as shown in the following figure.

What user authentication services are provided by WSX?

By default, WSX is protected by the application server. Username and password security is enforced whenever a WSX client invokes a service that is protected. For more information, see "Authenticating Users."

What SOAP engine does WSX use?

WSX is based on Apache Axis, an open-source implementation of SOAP. For more information about Axis, refer to the Axis Web site at `http://ws.apache.org/axis/`.

Does WSX handle SOAP attachments?

Yes. In fact, Agile Integration Services provides exportData and importData services that let you export and import binary attachment files.

Does WSX support stateful sessions?

Yes. The Axis Web services engine at the heart of WSX maintains session state between connections. Sessions can be based on HTTP cookies or on SOAP headers. This is useful for generating server-side code that supports more persistent applications instead of simple, one-shot processes. For more information about Web services sessions, refer to Axis documentation. You can start with the Axis FAQ located at `http://ws.apache.org/axis/faq.html`.

Does WSX support protocols other than HTTP?

No. WSX supports only HTTP-related protocols. For additional security, you can connect to a Web service using HTTPS and SSL. Over time, WSX may support additional protocols as needed.

Does WSX support Perl, Python, PHP, or other Web scripting languages?

WSX supports any client programming language that can send a SOAP message. Although the Agile SDK does not provide WSX client examples in Perl, Python, or PHP, those scripting languages are certainly capable of sending SOAP messages.

Does WSX support UDDI?

No. UDDI is a specification for a universal business registry of Web services that's designed to enable software to automatically discover and integrate with other services. It's currently unnecessary to register Agile PLM Web services on the Internet using UDDI. Agile PLM Web services are typically created for integration with internal software systems or to exchange data with partners or suppliers. However, Agile may consider supporting UDDI as the technology matures.

How do I deploy a Web service?

Place the service's JAR files in the agile_home/integration/sdk/extensions folder on the application server computer. Included with the Web service's JAR file(s) should be a deployment descriptor file named META-INF/services/com.agile.wsx.Deployment.wsdd.

The deployment descriptor file is an XML file formatted according to Axis' Web Service Deployment Descriptor (WSDD) format. It declares and describes the set of Web services and Web service operations that are exposed via WSX. The WSDD file also defines any additional behavior that should be used when processing incoming SOAP requests (such as user authentication) or responses (such as reformatting outgoing data). For more information about WSDD format, refer to the Axis Reference Guide at `http://ws.apache.org/axis/`.

When I deploy a Web service and its JAR file(s), do I need to update the application server classpath?

No. The classpath is updated automatically by a special-purpose classloader. The classloader extends the application server classpath with any classes located in agile_home/integration/sdk/extensions (or the location specified for the sdk.extensions property in the agile.properties file).

If I make changes to a Web service and redeploy it, do I need to restart the application server?

No. A special-purpose handler ensures that the Web services stack is updated with the latest files that have been deployed. Whenever a Web service request is made, the handler checks whether any JAR files located in agile_home/integration/sdk/services is updated, added, or removed. If so, the entire Web services stack is reset. This feature allows you to recompile your code and redeploy a Web service without having to restart the application server, saving you precious development time.

Are there any Agile products that use the WSX framework?

Yes. Agile Content Service (ACS) and Agile Integration Services (AIS) both rely on WSX framework to exchange data with the Agile PLM server.

What are Agile Integration Services?

Agile Integration Services (AIS) are Web services that provide import, export, and partlist functionality. Included with these Web services are sample Java Clients, but you can create other SOAP-compliant AIS clients in other programming languages.

What is basic authentication?

Basic authentication is a simple method of authentication. It allows a client program to provide credentials in the form of an unencrypted user name and password when making a request. There is a new Web module that uses basic authentication for deploying Web service listeners. You can find information to access Web services with basic authentication at: `http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=%2Fcom.ibm.websphere.express.doc%2Finfo%2Fexp%2Fae%2Ftwbs_auwschta.html`

For example, use this URL for the MyFirstWebService sample:

`http://hostname/Agile/integration/ws/MyFirstWebService?wsdl`