Release 10.1A: OpenEdge Development:
Web Services

> ## Binding to a server object handle

> As for an AppServer, you use the `CONNECT( )` method on the server object handle to bind that server object handle to a Web service. This is the basic syntax:

> Syntax
>     CONNECT (
>         connection-parameters
>         [ , userid ] [ , password ] [ , app-server-info ]
>       )

> A Web service binding requires and uses only the `connection-parameters` argument, which is a character string containing embedded parameter values to specify the binding. For a Web service, the last three parameters are AppServer-specific parameters and are ignored if specified.

> The `connection-parameters` parameter string can contain connection parameters for either an AppServer application service, a Web service, or both. If the string contains any Web service parameters, OpenEdge assumes that the method is binding to a Web service and ignores any AppServer-specific connection parameters in the string.

> ##### Connection parameters

> The primary function of the connection parameters is to specify the location and transport information for the Web service on the network. Web services provide two separate mechanisms for doing this. OpenEdge supports both mechanisms through the Web service connection parameters.

> This is the Web service syntax for the `connection-parameters` string:

> Syntax
>     -WSDL wsdl-document [ -WSDLUserid user-id [ -WSDLPassword password ] ]
>     {
>          {
>             [ -Service service-name [ -ServiceNamespace service-namespace ] ]
>             [ -Port port-name ]
>          }
>       |
>          {
>             [ [ -Binding binding-name [ -BindingNamespace binding-namespace ] ]
>                 -SOAPEndpoint URL-endpoint ]
>          }
>     }
>     [ -SOAPEndpointUserid user-id [ -SOAPEndpointPassword password ] ]
>     [ -TargetNamespace targetNamespace ]
>     [ -maxConnections num-connections ]
>     [ -connectionLifetime nSeconds ]
>     [ -nohostverify ]
>     [ -nosessionreuse ]
>     [ -pf filename ]

> The only fully required element is the `-WSDL` parameter to identify the WSDL document for the Web service. Note that the remaining “required” elements specify service, port, and binding information, but contain only optional elements. This is to indicate that if the WSDL document contains enough unambiguous information to specify both a valid transport and location for the Web service, you do not have to specify any of this information in the connection parameters, and the Web service will be bound according to the WSDL. This is only possible for a WSDL with a single service and port specification, because there is no provision for specifying a SOAP endpoint in WSDL without defining a service.

> Basically a complete binding can be specified by one of these mechanisms:

> 1. A valid service and port (transport and Web service URL location) specification (the most common mechanism).

> 2. A valid binding (transport) and SOAP endpoint (Web service URL location) specification (sometimes used to bind a SOAP viewer between the client and the Web service, or to provide a consortia of equivalent Web service locations).

> Also, if the WSDL unambiguously specifies only some of the required information, the connection parameters need only contain the required options to unambiguously complete the transport and location information in the WSDL document. So, for a service and port specification, you can specify either a `-Service` option (to unambiguously identify one or more services that define a single port in the WSDL) or a `-Port` option (to specify one of several ports defined for a single service in the WSDL). For a binding and SOAP endpoint specification, the minimum required element is the -`SOAPEndpoint` connection parameter, which can complete the location specification for a WSDL that defines a single `<binding>` element. If the WSDL contains multiple services, ports, or bindings, the connection parameters must specify the necessary `-Service`/`-Port` or `-Binding`/`-SOAPEndpoint` options to uniquely and correctly identify the transport and location.

> If the WSDL defines a single service, port, and binding, and you include no service, port, and binding options in the connection parameters, the WSDL-defined service and port take precedence. If your connection parameters include both valid `-Service`/`-Port` and valid `-Binding`/`-SOAPEndpoint` options, the `CONNECT( )` method fails.

> In all cases, any specified service, port, or binding options must match the corresponding WSDL entries exactly with respect to namespace, local name, and letter case; otherwise, the `CONNECT( )` method fails. If the WSDL defines multiple services, ports, or bindings, and the connection parameters do not specify the necessary service, port, or binding options, the `CONNECT( )` method also fails.

> Table 9–1 provides a short description for each parameter in the Web service connection parameter string, in the order they appear in the syntax. For more information on these parameters, see the `CONNECT( )` method entry in OpenEdge Development: Progress 4GL Reference .

> Table 9–1: Web service connection parameters
> Connection parameter | Description
> --- | ---
>     -WSDL wsdl-document
> | URL, UNC, or local file pathname (possibly relative) to the WSDL file that describes the Web service.
>     -WSDLUserid user-id
> | Username to authenticate access to the WSDL file (overridden by any username specified in the WSDL URL).
>     -WSDLPassword password
> | Password to authenticate access to the WSDL file (overridden by any password specified in the WSDL URL).
>     -Service service-name
> | Name of a `<service>` element in the WSDL.
>     -ServiceNamespace service-namespace
> | Namespace to disambiguate duplicate-named `<service>` elements.
>     -Port port-name
> | Name of a `<port>` element defined in the specified `<service>` element.
>     -Binding binding-name
> | Name of a `<binding>` element in the WSDL.
>     -BindingNamespace binding-namespace
> | Namespace to disambiguate duplicate-named `<binding>` elements.
>     -SOAPEndpoint URL-endpoint
> | URL location for the Web service.
>     -SOAPEndpointUserid user-id
> | Username to authenticate access (by either `-Service` or `-Binding`) to the Web service.
>     -SOAPEndpointPassword password
> | Password to authenticate access (by either `-Service` or `-Binding`) to the Web service.
>     -TargetNamespace targetNamespace
> | The target namespace specified in the WSDL for the Web service must match, as a verification check.
>     -maxConnections num-connections
> | Maximum number of simultaneous (parallel) connections maintained between the client and Web service for asynchronous requests.
>     -connectionLifetime nSeconds
> | The maximum number of seconds that a given connection can be reused for asynchronous requests before it is destroyed.
>     -nohostverify
> | If specified, turns off host verification for a Secure Socket Layer (SSL) connection using HTTPS. Without this parameter specified, the client compares the host name specified in the URL with the Common Name specified in the server certificate, and raises an error if they do not match. With this parameter specified, the client never raises the error. For more information, see the sections on managing the OpenEdge certificate store in OpenEdge Getting Started: Core Business Services .1
>     -nosessionreuse
> | If specified, the connection does not reuse the SSL session ID when reconnecting to the same Web server using HTTPS.1
>     -pf filename
> | File containing any parameters specified in the `CONNECT( )` method.

> 1These connection parameters affect all SSL connections made using the Web service server handle, including any WSDL file access or Web service access that uses HTTPS.

> ##### Using HTTPS

> When you use HTTPS to make a secure connection to a Web service, you might have to manage the OpenEdge certificate store to contain the necessary digital certificates for SSL verification. For information on managing the OpenEdge certificate store, see OpenEdge Getting Started: Core Business Services .

> ##### Invoking the binding

> These examples show use of the two mechanisms for binding an actual Web service:

> Binding a Web service in the 4GL using service and port
>     DEFINE VARIABLE hWebService AS HANDLE.
>     CREATE SERVER hWebService.
>     hWebService:CONNECT
>         ("-WSDL http://www.xmethods.net/sd/2001/TemperatureService.wsdl
>           -Service TemperatureService
>           -Port TemperaturePort").

> Binding a Web service in the 4GL using binding and SOAP endpoint
>     DEFINE VARIABLE hWebService AS HANDLE.
>     CREATE SERVER hWebService.
>     hWebService:CONNECT
>         ("-WSDL http://www.xmethods.net/sd/2001/TemperatureService.wsdl
>           -Binding TemperatureBinding
>           -SOAPEndpoint http://www.xmethods.net:80/soap/servlet/rpcrouter").

> Note: The public Web service used in these examples might not always be available and its URL can change at any time.

> ##### Binding results

> After a successful attempt to bind a Web service, the server object is initialized for the Web service. This means that on the server object handle the:

> - `CONNECT( )` method returns the value, `TRUE`, during invocation.

> - `SUBTYPE` attribute returns the value, `"WEBSERVICE"`.

> - `CONNECTED( )` method returns the value, `TRUE`.

> Note: A value of TRUE does not indicate the state of the HTTP/S connection between the client and Web service. Subsequent requests can fail if there is an HTTP failure at any point between the client and Web service.

> An attempt to bind a Web service can fail for any of the following reasons:

> - A corrupt WSDL file.

> - A parameter specification in the`connection-parameters` string is invalid.

> - The value specified for the `-TargetNamespace` parameter does not match the target namespace specified in the WSDL document. (This is a version check.)

> - The specified WSDL document is not found.

> - The value for the `-WSDLUserid` or the `-WSDLPassword` parameter is invalid.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095