CAA Web Services Home

 

Consuming the ENOVWSQueryCpp CAA Web Service

Using the ENOVWSQueryCpp CAA Web Service for query
Use Case

Abstract

This article discusses the CAAENOVWSQueryCppAxis1_3Client use case. It describes how to use the Java client binding that can be generated using the Axis WSDL2Java emitter in order to consume the ENOVWSQueryCpp CAA Web service. It provides a sample usage scenario that demonstrates how to query objects from ENOVIA LCA V5.

What You Will Learn With This Use Case

This use case demonstrates how to write a client application that consumes the ENOVWSQueryCpp CAA Web service. It uses queryCount, queryObjects, getObjects methods within this service as an example. It helps you to:

This article also provides guidances on how to build and run the sample client application using IRAD (IBM Rational Application Developer) 6.0, although any other Java IDE (Integrated Development Environment) or stand-alone JDK/JRE (Java Development Kit/Java Runtime Environment) could be used for that purpose.

[Top]

The CAAENOVWSQueryCppAxis1_3Client Use Case

CAAENOVWSQueryCppAxis1_3Client is a use case of the CAAENOVWS.edu framework that illustrates the ENOVWSQueryCpp CAA Web service capabilities.

[Top]

What Does CAAENOVWSQueryCppAxis1_3Client Use Case Do

The sample usage scenario delivered with this use case contains the following steps:

[Top]

Where To Find the CAAENOVWSQueryCppAxis1_3Client Code

The CAAENOVWSQueryCppAxis1_3Client use case is made of several classes located in the CAAENOVWSAxis1_3Client.mj module of the CAAENOVWS.edu framework:

Windows: <Install>\CAAENOVWS.edu\CAAENOVWSAxis1_3Client.mj\src
Unix: <Install>/CAAENOVWS.edu/CAAENOVWSAxis1_3Client.mj/src

The sample Java resources generated using the Axis WSDL2Java emitter are delivered in the following directory (Windows):

<Source>\<Output-package>\CATServiceExceptionType.java
<Source>\<Output-package>\ENOVWSQueryCpp.java
<Source>\<Output-package>\ENOVWSQueryCppLocator.java
<Source>\<Output-package>\IQueryWS.java
<Source>\<Output-package>\IQueryWSBindingStub.java
<Source>\<Output-package>\Identifier.java
<Source>\<Output-package>\Status.java
<Source>\<Output-package>\ENOVIA.java (+ all related classes)
<Source>\<Output-package>\holders\ENOVIAHolder.java (+ all related classes)
<Source>\<Output-package>\holders\SessionTokenHolder.java
<Source>\<Output-package>\holders\StringArrayTypeHolder.java

The CAAENOVWSAxis1_3Client.mj module contains the other following resources:

<Source>\<Root-package>\CAAENOVWSClient.java
<Source>\<Root-package>\CAAENOVWSQueryCppUseCase.java
<Source>\<Root-package>\CAAENOVWSQueryCppWrapper.java

The CAAENOVWSQueryCppWrapper class describes how to configure the generated proxy and how to invoke its methods. The CAAENOVWSQueryCppUseCase class demonstrates a sample use case scenario of the ENOVWSQueryCpp CAA Web service. The CAAENOVWSClient class contains the main program. It parses the command line inputs and starts up the use case.

This use case has a dependency on the CustomSessionHandler class which is available in the CAAJAXRPCHTTPSessionHandler.mj module of the CAAWebServices.edu framework. Please refer to [1] for details on HTTP session management and where to find the related class.

This use case has also a dependency on the CAAENOPosAppBinderImplAxis1_3Client use case in order to manage a session with ENOVIA LCA V5. Please refer to [1] for details on where to find the related code.

[Top]

How to Launch CAAENOVWSQueryCppAxis1_3Client

To launch the CAAENOVWSQueryCppAxis1_3Client use case, you will need to set up a buildtime environment, build the code along with its prerequisites, set up a runtime configuration and then execute the use case. You can see [3] for details on how to perform these steps within the IRAD 6 environment.

There is no prerequisites to running this use case. If there are no ENOVIA_VPMPartVersion (Parts) in the LCA V5 database then this service returns 0. Otherwise, it returns the count of the number of ENOVIA_VPMPartVersion (Parts) in the LCA V5 database.

The sample usage scenario delivered within this use case is launched from the CAAENOVWSClient class. It defines a main method that takes several options as parameters, as described below:

-w <URI> -e <ENOVIA username> -u <Basic Authentication username> -p <Basic Authentication password> -t ENOVWSQueryCpp

Here follows a sample command, to be updated with your own environment configuration:

-w http://stophe1dsy.dsy.ds:9080/B17 -e cjk -u wpsadmin -p wpsadmin -t ENOVWSQueryCpp

[Top]

Step-by-step

The following section first explains how to generate the Java client binding for the ENOVWSQueryCpp CAA Web service demonstrated. The remaining sections then describe the code that must be written in order to consume this Web service:

  1. Creating the Java Client Binding
  2. Instantiating and Configuring the Generated Proxy
  3. Querying Count
  4. Querying Objects
  5. Getting Objects
  6. Sample Usage Scenario

[Top]

Creating the Java Client Binding

Please refer to [3] for details on how to generate the Java client binding using the Axis WSDL2Java emitter.

Here follows a sample command in order to generate the Java client binding for the ENOVWSQueryCpp CAA Web service:

%JDK_HOME%\bin\java org.apache.axis.wsdl.WSDL2Java -o C:\CAAENOVWS\src -p com.dassault_systemes.caaenovws/caaenovwsaxis1_3client.generated http://karindsy.dsy.ds:9080/B17/wsdl?service=urn:com:dassault_systemes:ENOVWSQueryImpl:ENOVWSQueryImpl:ENOVWSQueryCpp

The server name, port, and context root URI information must be updated to match the server where the CAA Web service has been deployed. The list of generated resources is available from the above section: "Where To Find the CAAENOVWSQueryCppAxis1_3Client Code".

[Top]

Instantiating and Configuring the Generated Proxy

In order to be able to consume the ENOVWSQueryCpp CAA Web service implementation that has been deployed on a target server, you first need to retrieve an instance of the IQueryWSBindingStub generated class (also referred to as the proxy). It is a common best practice to manipulate an instance through its related interface whenever available. The WSDL2Java emitter produces an interface that is implemented by the IQueryWSBindingStub class: IQueryWS. It describes the available methods for the remote CAA Web service.

Warning   Although the IQueryWSBindingStub class can be directly instantiated using its own set of constructors, the Axis User's Guide recommends to discard this approach. Instead, the recommended approach is to use another generated class for that purpose: ENOVWSQueryCppLocator. It implements the ENOVWSQueryCpp interface.

The following code describes how to instantiate the generated proxy. Such proxy is used in order to marshall method calls and objects to SOAP requests, and to unmarshall SOAP responses to objects. This proxy must be configured in order to manage authentication on the remote Web server, timeout, and session management. Maintaining the HTTP session state is mandatory when consuming ENOVIA LCA V5 CAA Web services.

public class CAAENOVWSQueryCppWrapper {
  private String SERVICE_ID = "urn!com!dassault_systemes!ENOVWSQueryImpl!ENOVWSQueryImpl!ENOVWSQueryCpp";
  private IQueryWS proxy = null;

  public CAAENOVWSQueryCppWrapper(String clientId, String uri, int timeOut) {
    // Compute the SOAP endpoint URI value that bounds to the deployed
    // implementation of the ENOVWSQueryCpp CAA Web service
    String endpoint = uri + "servicerouter?service=" + SERVICE_ID;

    // Retrieve proxy instance
    ENOVWSQueryCppLocator locator = new ENOVWSQueryCppLocator();
    try {
      proxy = locator.getENOVWSQueryCppPort(new URL(endpoint));
    } catch (MalformedURLException e) {
      ...
    } catch (ServiceException e) {
      ...
    }

    // Required for HTTP session state management on the current proxy (1)
    ((IQueryWSBindingStub) proxy).setMaintainSession(true);

    if (clientId != null) {
      // Used to maintain the HTTP session state accross distinct proxies (2)
      HandlerInfo info = new HandlerInfo();
      info.setHandlerClass(CustomSessionHandler.class);
      Map handlerConfig = new HashMap();
      handlerConfig.put(CustomSessionHandler.CLIENT_ID, clientId);
      info.setHandlerConfig(handlerConfig);

      HandlerRegistry registry = locator.getHandlerRegistry();
      String portName = ((ENOVWSQueryCppLocator) locator).getENOVWSQueryCppPortWSDDServiceName();
      QName name = new QName(portName);
      List chain = registry.getHandlerChain(name);
      chain.add(info);
    }

    // Increase the default client time-out (3)
    ((IQueryWSBindingStub) proxy).setTimeout(timeOut);
  }
}

(1): in order to maintain the HTTP session state between successive calls performed using the same proxy instance, the setMaintainSession method must be used. This is mandatory in the context of ENOVIA LCA V5 CAA Web services,
(2): in order to maintain the HTTP session state between successive calls performed using distinct proxy instances, a JAX-RPC custom handler must be configured on the proxy. This is mandatory in the context of ENOVIA LCA V5 CAA Web services. You can refer to [1] for details,
(3): the default timeout value can be increased in order to avoid potential issues at runtime, such as losing the HTTP connection before receiving the SOAP responses. The sample value specified in the code is in milliseconds.

[Top]

Querying Count

Object counts can be queried from ENOVIA LCA V5 based on search criteria. This can be achieved using the following method, which is available through the generated proxy:

public Status queryCount(SelectExpression iSelect, IntHolder oCount)
  throws RemoteException, CATServiceExceptionType

This method accepts the following parameters:

[in] iSelect   The SelectExpression for query. See [5] for details
[in/out] oCount   The count of objects matching the input SelectExpression criteria

The following code demonstrates the use of the queryCount method:

public class CAAENOVWSQueryCppWrapper {
  ...
  public int queryCount(String selectExpression) throws Exception {
    ...
    // Create input data
    SelectExpression selectExp = new SelectExpression();
    selectExp.setValue(selectExpression);
    IntHolder count = new IntHolder();
    count.value = -1;
    ...
    // Invoke method on remote CAA Web service
    try {
      Status status = proxy.queryCount(selectExp, count);
      System.out.println("Status: " + status.getStatus());
    } catch (CATServiceExceptionType e) {
      throw e;
    } catch (Throwable t) {
      throw new Exception("Failed to count objects", t);
    }
    ...
    // Process output data
    if (count == null || count.value == -1) {
      throw new Exception("Failed to count objects");
    }
    return count.value;
  }
}

[Top]

Querying Objects

Objects can be queried from ENOVIA LCA V5 based on search criteria. This can be achieved using the following method, which is available through the generated proxy:

public Status queryObjects(SelectExpression iSelect, ENOVIAHolder oResult)
  throws RemoteException, CATServiceExceptionType

The method accepts the following parameters:

[in] iSelect   The SelectExpression for query. See [5] for details
[in/out] oResult   The objects matching the input SelectExpression criteria

The following code demonstrates the use of the queryObjects method:

public class CAAENOVWSQueryCppWrapper {
  ...
  public ENOVIA queryObjects(String selectExpression) throws Exception {
    ...
    // Create input data
    SelectExpression selectExp = new SelectExpression();
    selectExp.setValue(selectExpression);
    ENOVIAHolder resultSet = new ENOVIAHolder();

    try {
      Status status = proxy.queryObjects(selectExp, resultSet);
      System.out.println("Status: " + status.getStatus());
    } catch (CATServiceExceptionType e) {
      throw e;
    } catch (Throwable t) {
      throw new Exception("Failed to query objects", t);
    }

    // Process output data
    if (resultSet == null || resultSet.value == null) {
      throw new Exception("Failed to query objects");
    }
    return resultSet.value;
  }
}

[Top]

Getting Objects

Objects can be retrieved from ENOVIA LCA V5 based on given identifiers. This can be achieved using the following method, which is available through the generated proxy:

public Status getObjects(IdentifierArrayType iIds, ENOVIAHolder oResult)
  throws RemoteException, CATServiceExceptionType

The method accepts the following parameters:

[in] iIds   The object identifiers
[in/out] oResult   The objects matching the input identifiers

The following code demonstrates the use of the getObjects method:

public class CAAENOVWSQueryCppWrapper {
  ...
  public ENOVIA getObjects(String[] objectUUIDs, String selectExpression)
    throws Exception {
    ...
    // Create input data
    Identifier[] objectIds = CAAENOVWSUtils.toIdentifierArray(objectUUIDs);
    SelectExpression selectExp = new SelectExpression();
    selectExp.setValue(selectExpression);
    ENOVIAHolder resultSet = new ENOVIAHolder();

    // Invoke method on remote CAA Web service
    try {
      Status status = proxy.getObjects(objectIds, selectExp, resultSet);
      System.out.println("Status: " + status.getStatus());
    } catch (CATServiceExceptionType e) {
      throw e;
    } catch (Throwable t) {
      throw new Exception("Failed to get objects", t);
    }

    // Process output data
    if (resultSet == null || resultSet.value == null) {
      throw new Exception("Failed to get objects");
    }
    return resultSet.value;
  }
}

The CAAENOVWSUtils.toIdentifierArray method can be found at:

<Install>\<Source>\<Package>\CAAENOVWSUtils.java

[Top]

Sample Usage Scenario

The following code depends on:

It demonstrates a sample usage scenario for the ENOVWSQueryCpp CAA Web service:

public class CAAENOVWSQueryCppUseCase {
  private String uri = null;
  private String credUser = null;
  private String credPwd = null;

  public CAAENOVWSQueryCppUseCase(String uri, String credUser, String credPwd) {
    this.uri = uri;
    this.credUser = credUser;
    this.credPwd = credPwd;
  }

  public void runSampleUsageScenario(String enoviaUser) {
    ...
    CAAENOPosApplicationBinderImplWrapper binderWrapper = null;
    SessionToken sessionToken = null;

    try {
      // ------------------------------------------------------------
      // Step 1 - Instantiate and configure the proxy
      // ------------------------------------------------------------

      String clientId = new Long(System.currentTimeMillis()).toString();
      int timeOut = 360000;

      // Instantiate the wrapper client class
      binderWrapper = new CAAENOPosApplicationBinderImplWrapper(clientId,
        uri, credUser, credPwd, timeOut);
      CAAENOVWSQueryCppWrapper queryWrapper = new CAAENOVWSQueryCppWrapper(
        clientId, uri, timeOut);

      // ------------------------------------------------------------
      // Step 2 - Open session with ENOVIA LCA V5
      // ------------------------------------------------------------

      String[] userContexts = binderWrapper.getUserContexts(enoviaUser);

      sessionToken = binderWrapper.login(userContexts[0]);

      // ------------------------------------------------------------
      // Step 3 - Count objects and display result
      // ------------------------------------------------------------

      // Create input XML select expression
      StringBuffer xmlFilter = new StringBuffer();
      xmlFilter.append("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
      xmlFilter.append("<FILTER CASESENSITIVE=\"TRUE\">");
      xmlFilter.append("<SELECT>");
      xmlFilter.append("<OBJECT DOMAIN=\"PRODUCT\" NAME=\"VPMBOPartInstance\"/>");
      xmlFilter.append("</SELECT>");
      xmlFilter.append("<WHERE>");
      xmlFilter.append("<FILTER_CONDITION OPERATOR=\"AND\">");
      xmlFilter.append("<ATTRIBUTE_FILTER>");
      xmlFilter.append("<EXPRESSION OP=\"LIKE\" VALUE=\"*\">");
      xmlFilter.append("<ATTRIBUTE NAME=\"ENOVIA_VPMPartMaster.V_ID\" />");
      xmlFilter.append("</EXPRESSION>");
      xmlFilter.append("</ATTRIBUTE_FILTER>");
      xmlFilter.append("</FILTER_CONDITION>");
      xmlFilter.append("</WHERE>");
      xmlFilter.append("</FILTER>");

      int count = queryWrapper.queryCount(xmlFilter.toString());

      System.out.println("Query returned " + count + " result(s)");

      // ------------------------------------------------------------
      // Step 4 - Query objects and display results
      // ------------------------------------------------------------

      ENOVIA resultSet = queryWrapper.queryObjects(xmlFilter.toString());

      CAAENOVWSUtils.displayResults(resultSet, 2);
    } catch (CATServiceExceptionType e) {
      ...
    } catch (Exception e) {
      ...
    } finally {
      // ------------------------------------------------------------
      // Step 5 - Terminate opened session
      // ------------------------------------------------------------

      // The session must be closed even if a call to a method on the
      // ENOVWSQueryCpp CAA Web service fails
      try {
        binderWrapper.logout(sessionToken);
      } catch (Exception e) {
        System.err.println("Failed to logout gracefully");
      }
    }
  }
}

The CAAENOVWSUtils.displayResults method can be found at:

<Install>\<Source>\<Package>\CAAENOVWSUtils.java

[Top]

In Short

This use case explains how to use the Java client binding generated using the Axis WSDL2Java emitter in order to consume the ENOVWSQueryCppCAA Web service. It also gives an overview of the methods available for that particular CAA Web service:

[Top]

References

[1] Maintaining the Session State
[2] Consuming the ENOPosApplicationBinderImpl CAA Web Service
[3] Building and Launching a CAA Web Service Use Case
[4] Generating a Java Client Binding
[5] Using SelectExpression

History

Version: 1 [Apr 2005] Document created
Version: 2 [Jan 2006] Document updated
[Top]

Copyright © 1994-2006, Dassault Systèmes. All rights reserved.