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 CAAENOVWSDotNet1_1Client use case. It describes how to use the C# client binding that can be generated using the wsdl.exe utility 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 helps you to:

[Top]

The CAAENOVWSDotNet1_1Client Use Case

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

[Top]

What Does CAAENOVWSDotNet1_1Client Do

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

[Top]

Where To Find the CAAENOVWSDotNet1_1Client Code

The CAAENOVWSDotNet1_1Client use case is made of several classes located in both CAAENOVWSDotNet1_1Client.m and CAAENOVWSDotNet1_1ClientBase.m modules of the CAAENOVWS.edu framework:

<Install>\CAAENOVWS.edu\CAAENOVWSDotNet1_1Client.m\src
<Install>\CAAENOVWS.edu\CAAENOVWSDotNet1_1ClientBase.m\src

The CAAENOVWSDotNet1_1ClientBase.m module (library) contains the following resources:

<Source>\CAAENOVWSQueryCppProxy.cs
<Source>\CAAENOVWSQueryCppWrapper.cs
<Source>\CAAENOVWSUtils.cs

The CAAENOVWSQueryCppProxy.cs file contains the C# client binding generated using the wsdl.exe utility. A C# client binding consists of a proxy and several types definitions. The CAAENOVWSQueryCppWrapper.cs file contains a class that describes how to configure the generated proxy and how to invoke its methods.

The CAAENOVWSDotNet1_1Client.m module (executable) contains the following resources:

<Source>\CAAENOVWSDotNet1_1Client.cs
<Source>\CAAENOVWSQueryCppUseCase.cs

The CAAENOVWSDotNet1_1Client.cs file contains the main program. It parses the command line inputs and starts up the use case. The CAAENOVWSQueryCppUseCase.cs file contains the sample use case scenario.

[Top]

How to Launch CAAENOVWSDotNet1_1Client

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.

To run the CAAENOVWSDotNet1_1Client use case, you will need to build both CAAENOVWSDotNet1_1ClientBase.m and CAAENOVWSDotNet1_1Client.m modules. The use case code can be built using either the CAA V5 buildtime environment, or Visual Studio .NET 2003 as explained in [1].

You can then execute the command described below:

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

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

The same executable is used to launch all of the available ENOVIA CAA Web services use cases. The -t option is used to choose the target use case to run.

When building the modules with the CAA V5 buildtime environment, the CAAENOVWSDotNet1_1Client executable can be launched from the following location:

<Install>\CAAENOVWS.edu\intel_a\code\clr

[Top]

Step-by-step

The following section first explains how to generate the C# client binding for the ENOVWSQueryCpp CAA Web service demonstrated. The remaining sections describe how to configure the generated proxy and how to consume the Web service:

  1. Creating the C# 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 C# Client Binding

Please refer to [2] for details on how to generate the C# client binding using the wsdl.exe utility.

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

wsdl /namespace:com.dassault_systemes.caaenovws.caaenovwsdotnet1_1clientgen.enovwsquerycpp /username:wpsadmin /password:wpsadmin /out:CAAENOVWSQueryCppProxy.cs http://stophe1dsy.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 ENOVWSQueryCpp CAA Web service has been deployed. The /username and /username options are required to authenticate on the Web server hosting the Web service.

[Top]

Instantiating and Configuring the Generated Proxy

In order to consume an implementation of the ENOVWSQueryCpp CAA Web service deployed on a target Web server, you first need to instantiate the proxy generated using the wsdl.exe utility. This proxy must then 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.

The generated proxy class is used in order to marshall method calls and objects to SOAP requests, and to unmarshall SOAP responses to objects. The following code describes how to instantiate and configure it:

public class CAAENOVWSQueryCppWrapper {
  private const string SERVICE_ID = "urn!com!dassault_systemes!ENOVWSQueryImpl!ENOVWSQueryImpl!ENOVWSQueryCpp";
  private CAAENOVWSQueryCppProxy proxy = null;

  public CAAENOVWSQueryCppWrapper(
    CookieContainer container,
    string uri,
    string credUser,
    string credPwd,
    int timeOut) {
    proxy = new CAAENOVWSQueryCppProxy();

    // Compute the SOAP endpoint URI value that bounds to the deployed
    // implementation of the ENOVWSQueryCpp CAA Web service
    proxy.Url = uri + "servicerouter?service=" + SERVICE_ID;

    // Required for HTTP session state management
    proxy.CookieContainer = container; (1) 

    // Required for the Basic Authentication mechanism
    ICredentials credentials = new NetworkCredential(credUser, credPwd);
    proxy.Credentials = credentials; (2) 

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

(1): in order to maintain the HTTP session state between successive calls performed using either the same or multiple proxy instances, the CookieContainer property must be set on the proxy. This is mandatory in the context of ENOVIA LCA V5 CAA Web services,
(2): when security is enabled on the remote Web server, it is mandatory to set the Credentials property on the proxy. The values specified must match a valid set of credentials for the Basic Authentication mechanism,
(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 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, ref int oCount)

This method accepts the following parameters:

[in] iSelect   The SelectExpression for query. See [3] 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) {
    if (selectExpression == null) {
      throw new ApplicationException("Illegal argument: select expression is null");
    }

    SelectExpression selectExp = new SelectExpression();
    selectExp.Value = selectExpression; 
    int count = -1;

    try {
      Status status = proxy.QueryCount(selectExp, ref count);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
       throw new ApplicationException("Failed to count objects", e);
    }

    if (count == -1) {
      throw new ApplicationException("Failed to count objects");
    } 
    return count;
  }
}

[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, ref ENOVIA oResult)

The method accepts the following parameters:

[in] iSelect   The SelectExpression for query. See [3] 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) {
    if (selectExpression == null) {
      throw new ApplicationException("Illegal argument: select expression is null");
    }

    SelectExpression selectExp = new SelectExpression();
    selectExp.Value = selectExpression;
    ENOVIA resultSet = null;

    try {
      Status status = proxy.QueryObjects(selectExp, ref resultSet);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
      throw new ApplicationException("Failed to query objects", e);
    }

    if (resultSet == null) {
      throw new ApplicationException("Failed to query objects");
    }
    return resultSet;
  }
}

[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(Identifier[] iIds, ref ENOVIA oResult)

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 {
  ...
  private Identifier ToIdentifier(string id) {
    if (id == null) {
      throw new ApplicationException("Illegal argument: identifier value is null");
    }

    Identifier identifier = new Identifier();
    identifier.Identifier1 = CAAENOVWSUtils.ConvertFromHexToBinary(id);
    return identifier;
    }

    private Identifier[] ToIdentifierArray(string[] ids) {
      if (ids == null) {
        throw new ApplicationException("Illegal argument: identifiers array is null");
      }

      Identifier[] identifiers = new Identifier[ids.Length];
      for (int i = 0; i < ids.Length; i++) {
        identifiers[i] = ToIdentifier(ids[i]);
      }
      return identifiers;
    }

    public ENOVIA GetObjects(
      string[] objectUUIDs,
      string selectExpression) {
      if (objectUUIDs == null) {
        throw new ApplicationException("Illegal argument: object UUID array is null");
      }

      Identifier[] objectIds = ToIdentifierArray(objectUUIDs);
      SelectExpression selectExp = new SelectExpression();
      selectExp.Value = selectExpression;
      ENOVIA resultSet = null;

      try {
        Status status =
          proxy.GetObjects(objectIds, selectExp, ref resultSet);
        Console.Out.WriteLine("Status: {0}", status.Status1); 
      } catch (Exception e) {
        throw new ApplicationException("Failed to get objects", e);
      }

      if (resultSet == null) {
        throw new ApplicationException("Failed to get objects");
      }
      return resultSet;
   }
}

The CAAENOVWSUtils.ConvertFromHexToBinary method can be found at:

<Source>\CAAENOVWSUtils.cs

[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) {
    enoposapplicationbinderimpl.CAAENOPosApplicationBinderImplWrapper binderWrapper = null;
    enoposapplicationbinderimpl.SessionToken sessionToken = null;

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

      // Create a CookieContainer object to maintain the HTTP session
      // state accross proxies 
      CookieContainer container = new CookieContainer();

      // Instantiate wrapper client classes
      int timeOut = 360000;
      binderWrapper =
        new enoposapplicationbinderimpl.CAAENOPosApplicationBinderImplWrapper(
          container, uri, credUser, credPwd, timeOut);
      enovwsquerycpp.CAAENOVWSQueryCppWrapper queryWrapper =
        new enovwsquerycpp.CAAENOVWSQueryCppWrapper(
          container, uri, credUser, credPwd, timeOut);

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

      // Get user contexts
      string[] userContexts = binderWrapper.GetUserContexts(enoviaUser); 
     
      // Log in using the first available context
      if (userContexts.Length == 0) {
        throw new ApplicationException("No context found for the user specified");
      }
      sessionToken = binderWrapper.Login(userContexts[0]);

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

      // Create input XML select expression
      StringBuilder xmlFilter = new StringBuilder();
      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("<ORDERBY>");
      xmlFilter.Append("<ENOVIA_VPMPartMaster.V_ID>");
      xmlFilter.Append("</ORDERBY>");
      xmlFilter.Append("</FILTER>");

      int count = queryWrapper.QueryCount(xmlFilter.ToString());
      Console.Out.WriteLine("Query returned {0} result(s)", count);

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

      enovwsquerycpp.ENOVIA resultSet =
        queryWrapper.QueryObjects(xmlFilter.ToString());

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

      // The session must be closed even if a call to a method on the ENOVWSQueryCpp
      // CAA Web service fails
      binderWrapper.Logout(sessionToken); 
    } 
  }
}

The CAAENOVWSUtils.DisplayResults method can be found at:

<Source>\CAAENOVWSUtils.cs

[Top]

In Short

This use case explains how to use the C# client binding generated using the wsdl.exe utility in order to consume the ENOVWSQueryCppCAA CAA Web service. It also gives an overview of the available methods:

[Top]

References

[1] Building and Launching a CAA Web Service Use Case
[2] Generating a C# Client Binding
[3] Using SelectExpression
[4] Consuming the ENOPosApplicationBinderImpl CAA Web Service

History

Version: 1 [Jan 2006] Document created
[Top]

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