Go to primary content
Agile Product Lifecycle Management SDK Developer Guide - Developing PLM Extensions
Release 9.3.6
E71153-01 ,Oracle and/or its affiliates. All rights reserved.
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

2 Developing Web Service Extensions

This chapter includes the following:

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 both Simple Object Access Protocol (SOAP) and 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.

Figure 2-1 WSX architecture

Surrounding text describes Figure 2-1 .

2.2 Web Services Technology

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 enables describing the endpoints and their messages independent of the message formats or network protocols. 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 (through the Web server) may be encrypted through 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.

2.2.4 Finding Additional Information About Web Services

This is a list of some websites to explore:

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 can also use third party code libraries in addition to the 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 Reserved Web Service Names

The following Web service names are reserved for use by the 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.


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:

Example 2-1 Accessing a protected Web Service

// Configure the stub with the necessary authentication informationstub.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 lines in the following applications:

application.ear#integration.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>

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 and or password and single sign-on cookies, the single sign-on cookie has precedence over username or 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.

Surrounding text describes ch2_02.gif.

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 you can access both name and value by calling the javax.servlet.http.Cookie object method.

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 8 SDK SE Version 1.7 http://www.oracle.com/technetwork/java/archive-139210.html
Apache Project's Ant build tool, version 1.9.4 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 re-initialize 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 typing this command %ANT_HOME%\bin\ant -version.

    The following message is displayed:

    Apache Ant version 1.9.4 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.9.4-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 typing this command $ANT_HOME/bin/ant -version.

    The following message appears:

    Apache Ant version 1.9.4 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 commons-cli.jar file into the.../sdk/extensions folder.

  • Generates a script (either runner.bat or runner.sh) 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 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 $AGILE_HOME/sdk/samples/wsx on the server.

  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


  1. Important:

    If you are not building the Web service sample under $AGILE_HOME/sdk/samples/wsx, then upload 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.

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

    • 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 websites where you can find more information:


Note:

For a comprehensive list of other SOAP implementations, refer to the following website: 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 through 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 you can use 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 sample's build process.

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.Within the build.xml file, you will find the following Ant target:

  <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>

Once the client-side stubs have been generated, the user can use the generated object definitions to 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. That is, stubs themselves manage the submission of requests and

    The submitting of the request is managed by the stubs themselves; you do not need to worry about the .Stubs themselves manage the submission of the request, and you do need to perform the connection or marshaling particulars

The details on how you point the stubs to the desired Web service engine and submit the request varies for different code libraries. To this end, Oracle recommends that you consult the documentation for your Web-service-aware code library for the necessary information.

2.9.3 Processing the SOAP Response

The processing of the SOAP response is usually handled through 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 un-marshaling 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). 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 initialization 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 a usage statement for MyFirstClient, type 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-2 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 must make an explicit SDK session as if connecting from a remote client. That is, provide an argument to the AgileSessionFactory.getInstance() method as shown in the following example.

Example 2-3 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 several 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 (VM).

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 (throughASP.NET) by using any of the languages mentioned, it can also integrate these languages into one common API. Thus, developers can write language independent code that 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 cannot 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 does not reside in the DMZ, or directly against the application server, as shown in the following figure.

Figure 2-2 How Web service clients connect to the Agile PLM server

Surrounding text describes Figure 2-2 .

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 website at http://ws.apache.org/axis/.

Does WSX handle SOAP attachments?

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

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) is a deployment descriptor file called: 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 throughWSX. The WSDD file also defines any additional behavior that is necessary 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 enables you 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 un-encrypted 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 files:

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