Web Service Call Builder

 

 

In this topic ...

Quick Tips

Using the Service Call Builder

Set the WSDL Fetch Timeout

Specifying Inputs for a WSDL-Based SOAP Service

Specifying Inputs for a Direct SOAP Service Call

Specifying Inputs for an HTTP Service

Specifying Inputs for a Model-Based Service

Using WSRR with WebSphere Portlet Factory

 

Related Topics ...

Overview: Creating Forms

Web Services Overview

WebSphere Service Registry and Repository information center

WebSphere Service Registry and Repository Web site

How to Use the Web Service Enable Builder

Example: Catching a Timeout Exception

Use the Web service call builder to call any WSDL, SOAP, or HTTP service. This builder adds to the model a linked Java object used to to invoke the service call and store the results in a variable. For Web services that take XML inputs, or return XML, the Web service call builder adds any schema from the WSDL document to the Web application, allowing you to then define a variable to be of a type defined by the schema.

The inputs that the Web service call builder call editor displays depending on the type of service you select in the builder call editor.

For more information about creating, consuming, and publishing Web services, see Web services overview.

For more information about accessing data from a database, see
Overview: Working with data.

 

Quick tips

  • Execute the service call by calling the serviceCallName.invoke() method -- In a model method or in an linked Java object method, call the invoke() method on the linked Java object that the Web service call builder call adds to the model. This linked Java object has the same name as the Web service call builder call. The code below, shows how to invoke a service call defined by a Web service call builder call named "getISBN":

    webAppAccess.callMethod("getISBN.invoke");

  • The serviceCallName_reply variable stores the outputs of the service call -- We can "walk" the results of the service call in the Choose Reference dialog when trying to use a value returned by the service call as an input to a builder call or as the value for an argument to an action.

  • The serviceCallName_replyHeaders variable contains any SOAP headers stored in the SOAP response -- SOAP headers are optional and not yet frequently used, and SOAP headers in SOAP response envelopes are used even less often, so it is expected that this variable value will not be set under most common use cases.

  • Consuming a Doc-Literal Type Service -- A doc-literal type service always has only one argument that is an XML document. To consume such a service follow these steps:

    1. Fetch WSDL in for the service in the Web service call builder. Give Web service call builder a name and click Apply. Note the schema type specified on the label for the argument.
    2. Leave the Web service call builder interface incomplete and add a variable builder to the model. Declare the variable to be of required schema type (When you clicked Apply that schema was loaded into the model.)
    3. Select the variable as the argument to the Web service call. At runtime, you will need to populate that variable with the desired data for the request.

  • Sending Raw Data - We can use the "HTTP" type of Web service call to send raw data. To do so, set a POST parameter called "BODY_CONTENT". When you do this, the supplied value is sent as the complete HTTP POST content of the request.

 

Using the Web service call builder

The Web service call builder allows you to execute several different types of services, and displays different inputs according to the type of service call you choose. The following steps describe the general process of configuring a Web service call:

  1. Choose the type of service you want to call: WSDL, SOAP, HTTP, or Local.

  2. Enter the URL for the service.

    For WSDL service calls, enter the URL for the WSDL document that describes the service you want to call. The URL may be HTTP-based, for example http://myhost/mywsdl.wsdl or a file within the project, such as WEB-INF/mywsdl.wsdl.

    If your organization is using WebSphere Service Registry and Repository (WSRR), then we can use WSRR to search for and download WSDL to your project. See Using WebSphere Service Registry and Repository (WSRR) with WebSphere Portlet Factory for more information.

  3. Specify the values for the arguments to pass to the service.

    For WSDL service calls, the Builder Call Editor lists the arguments the service requires and you just need to specify their values. For SOAP and HTTP service calls, you will need to know the required arguments and build up the arguments list with the Add Argument button in the Builder Call Editor.

  4. Enter any authentication information.

The other inputs to the Web service call builder are service type-specific, and in the case of WSDL service calls, may be read-only or have default values specified by the WSDL document. Each of the following sections describe how to specify the inputs for a particular service call type.

 

Set the WSDL fetch timeout

A property is available to set the default timeout on the fetch WSDL operation invoked when the Fetch WSDL button is clicked. This property is set to 30 (seconds) by default. We can change this value as required by your application or environment. The following property determines the timeout interval:

bowstreet.soap.wsdl.fetchTimeout=

To set this property enter the property and desired value into the override.properties file located in the project's WEB-INF/config directory. This property change will apply to only this project.

 

Specifying inputs for a WSDL-based SOAP service

The Web service call builder takes the following inputs for a WSDL service:

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the builder call list.
Service Call Type Enable the WSDL radio button.
WSDL URL Enter the URL for the WSDL document describing the service.

The URL may be http based, for example http://myhost/mywsdl.wsdl or a file within the project, such as WEB-INF/mywsdl.wsdl.

Click the Fetch/refresh WSDL button to display the operations exposed for the web service.

Request Parameters
Operation Select the operation you want to execute. Each operation listed will indicate if the operation type is RPC or Document.
AutoCreate Input Vars Enable this checkbox to force the Web Service Call Builder regen to create input variables for each of the service call inputs. We can see these variables in the Variable section of the WebApp Tree view after clicking Apply on the builder call, the names being in the form of, <buildername>_argN_<inputname>.

These variables do not appear in the Builder Call List, but we can get and set their values in methods and they are listed in the Choose Reference dialog.

Note that To preserve pre-existing values in the builder input fields, request parameter inputs with existing content do not get automatically populated with the auto created variable names. To get the automatically created input variable names into the request parameter inputs clear out the current value, and then either choose the new variable with the selector for that input field, or just un-check and re-check the AutoCreate Input Vars check box. This technique allows hard coded and automatically created variables to be used in the inputs without loss of pre-existing typed in values.

Argument(s) named according to WSDL document The Builder Call Editor displays the argument names for the selected operation as inputs to the Web service call.

We can use the Choose Reference to specify an appropriate value from a model element or we can enter a text string directly.

If the operation is RPC style, there will be an input for each argument. If the operation is docstyle, the service takes only one argument (am XML document) of the type indicated in the argument label. See Quick tips for information about consuming a doc-literal type of service.

Request SOAP Headers
Header name and Type Displayed when returned WSDL document indicates SOAP headers are required for the request. Displays the name and type of header.

Use the Choose Reference dialog to select a variable (of the proper type) to provide input for this request header.

Note that SOAP headers are XML and will probably be provided by you with schema-type variables.

Service Information (display only fields)
Reply The name and type of reply returned by the requested SOAP operation.
Service Description Service description from the WSDL document.
URL The service URL used to invoke the service.
Method Description Method description from the WSDL document.
Method Namespace Method namespace URI (namespace of target method).
SOAP Action SOAP action specified in the WSDL document for this operation
Advanced
Service URL (override) We can override the service URL specified in the WSDL document by entering another service URL here.

If the WSDL is an interface WSDL with no service URL specified, it can also be supplied here.

For example, if you reference a WSDL in a development environment and expose the service in a deployed environment, the host name, application context, etc. will most likely be different. In this case, we can enter the URL that takes into account the host name, port, and application context of the deployed environment, or supply these values via a Variable that will have the correct values at runtime.

Service Host name (override) We can override the host name for the service by entering the new host name here. This can be set to localhost if using TCP tunnel for debugging. See Testing services for more information on using TCP tunnel.
Service Port (override) We can override the port number for the service by entering the port number here. This can be set to your tunnel port if using TCP tunnel for debugging. See Testing services for more information on using TCP tunnel.
Timeout (in seconds) Default is 30. Enter the number of seconds to wait for a response from the service. See Example: Catching a timeout exception for an example of how to handle a timeout exception for a service call.
Additional SOAP Headers Use this input if you want to include additional SOAP headers in the service call that were not specified in the WSDL. Reference an XML variable that contains the value for the header.
HTTP Headers Use this input to send additional HTTP headers in the request. In the HTTP header list, enter any HTTP header names and set the header values using the Choose Reference dialog, or enter a text string directly.
(optional) Logging Select the type of logging, if any, that you want the builder to perform. Information will be written to the application server's console as well as the factory runtime's log file and can help in debugging problems with the service.

We can choose:

  • None - To disable logging

  • Inputs and outputs only - To dump the inputs and the response
  • Envelope only - To dump the SOAP request and response envelope for a WSDL/SOAP service call

  • All -To dump all the above information

Dummy/Stub Result Supply a value to be returned instead of actually calling the service. For example, you might enable this functionality for testing purposes so that we can run the model without requiring the service to be in place.
(optional) Username (Basic Auth) If the service requires basic user authentication, enter the user name to use for the request here.
(optional) Password (Basic Auth) If the service requires basic user authentication, enter the password for the specified user here.
(optional) HTTP Proxy Host Enter the host name of the proxy server.

Note that This proxy setting and those below allow the setting of a proxy for this specific Web Service Call. As a result, a system wide JVM -Dhttp.proxyXXX setting does not need to be used. If a system-wide proxy setting is in effect, proxy settings made here in the Web Service Call Builder will override the system value.

(optional) HTTP Proxy Port Enter the port number of the proxy server.
(optional) HTTP Proxy User Enter a user name for the proxy server.
(optional) HTTP Proxy Password Enter a password associated with the user name above.

The Builder Call Editor also displays information about the model-based Web service in the Service Information group. If you expand the Service Information heading in the Builder Call Editor, the following information is displayed:

  • Reply Name and Type

  • Service Documentation

  • Method Documentation

 

Specifying inputs for a model-based local service

The Web service call builder takes the following inputs for a model-based (local) service. Note that there are fewer inputs that a WSDL service because at runtime the local service is invoked by a Java call within the JVM, instead of by issuing a SOAP request over the wire.

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Service Call Type Set the radio button to Local to configure a service call to a Local Model/WebApp method based service.
Model Use the Model Chooser to select the model that contains the method exposed as a Web service with a Web Service Enable Builder call. All models containing a Web Service Enable Builder should be listed.

Click the Fetch/refresh WSDL button to display the operations exposed as Web services in the model.

Operation Select the operation you want to execute.
Argument(s) named according to WSDL document The Builder Call Editor displays the argument names for the selected operation as inputs to the Web Service Call.

We can use the Choose Reference dialog to specify an appropriate value from a model element or we can enter a text string directly.

Service Information (display only fields)
Reply The name and type of reply returned by the requested SOAP operation.
Service Description Service description from the WSDL document.
URL The service URL used to invoke the service.
Method Description Method description from the WSDL document.
Method Namespace Method namespace URI (namespace of target method).
SOAP Action SOAP action specified in the WSDL document for this operation
Advanced
(optional) Logging Select the type of logging, if any, that you want the builder to perform. Information will be written to the application server's console as well as the factory runtime's log file and can help in debugging problems with the service.

We can choose:

  • None - To disable logging

  • Inputs and outputs only - To dump the inputs and the response

  • Envelope only - To dump the SOAP request and response envelope for a WSDL/SOAP service call

  • All -To dump all the above information

Dummy/Stub Result Supply a value to be returned instead of actually calling the service. For example, you might enable this functionality for testing purposes during application development so that we can run the model without requiring the other target model to be in place.

 

Specifying Inputs for a SOAP Service

We can call a SOAP service that is not defined with a WSDL document by entering the information needed to configure the SOAP request. We can use a known SOAP request envelope for that service to get the information we need to configure your own call to that service.

For example, if you had the following SOAP request envelope, you could configure a Service Call to the target method by extracting the values of the following elements in the SOAP request:

<SOAP-ENV:Envelope    xmlns:SOAP- ENV="http://schemas.xmlsoap.org/soap/envelope/"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xmlns:xsd="http://www.w3.org/2001/XMLSchema">    <SOAP- ENV:Body>       <ns1:getServiceResponsePublic xmlns:ns1="urn:MyBubble- SoapServices"          SOAP- ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">          <service Name xsi:type="xsd:string">Meaning</serviceName>          <inputText xsi:type="xsd:string">permeate</inputText>       </ns1:getServiceResponsePublic>    </SOAP-ENV:Body> </SOAP-ENV:Envelope>

 

SOAP header return behavior

As of WeSphere Portlet Factory V5.9, the new AXIS SOAP header construct returns multiple SOAP headers as XML data. Prior to this version, only the first header in the list of headers was returned. We can control header return behavior with an argument we can invoke at Factory startup. If you prefer to revert the Factory to the old behavior of returning only the first SOAP header, start the Factory with the following argument:

-Dbowstreet.responseHeader.getFirstChild=true

When started in the way only a single response header will be returned as a result of a SOAP request.

The Web Service Call Builder takes the following inputs for a SOAP service:

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Service Call Type Enable the SOAP radio button.
Request Parameters
SOAP URL Enter the URL for the service. The URL is not included in the SOAP envelope and must be known prior to creating the service call.
Target Method Using the above SOAP envelope as an example, the value of the Target Method is: getServiceResponsePublic.
Method Namespace urn:MyBubble- SoapServices
Schema Namespace http://www.w3.org/2001/XMLSchema
SOAP Action Default is an empty String "". If the service you are calling specifies a SOAP action, enter that URL here. The SOAP action will be sent as an HTTP header.

For example, http://www.serviceobjects.com/GetTrackingInfo.

(optional) Literal Data If the target SOAP service is document style, enable this checkbox. If the SOAP service is RPC style, we can leave this checkbox disabled.
Arguments Enter the argument name, Java class and value for each argument you want to pass to the service.
Reply class Enter the name of the Java class for the service's response such as String, int, etc.
Advanced
(optional) Timeout Default is 30 seconds.
(optional) SOAP Headers Use this input if you want to include additional SOAP headers in the service call that were not specified in the WSDL. Reference an XML variable that contains the value for the header.
(optional) HTTP Headers Use this input to send additional HTTP headers in the request. In the HTTP Header list, enter any HTTP Header names and set the header values using the Choose Reference dialog, or enter a text string directly.
(optional) Logging Select the type of logging, if any, that you want the Builder to perform. Information will be written to the application server's console as well as the Factory's log file and can help in debugging problems with the service.

We can choose:

  • None - To disable logging

  • Inputs and outputs only - To dump the inputs and the response

  • Envelope only - To dump the SOAP request and response envelope for a WSDL/SOAP service call

  • All -To dump all the above information

(optional) Dummy/Stub Result Supply a value to be returned instead of actually calling the service.

For example, you might enable this functionality for testing purposes during application development so that we can run the model without requiring the other target model to be in place.

(optional) Username (Basic Auth) If the service requires basic user authentication, enter the user name to use for the request here.
(optional) Password (Basic Auth) If the service requires basic user authentication, enter the password for the specified user here.
(optional) Encoding Style Used when accessing some developer tool kits to specify alternate argument encodings. Can be generally left blank.
(optional) HTTP Proxy Host Enter the host name of the proxy server.

Note that This proxy setting and those below allow the setting of a proxy for this specific service call. As a result, a system wide JVM -Dhttp.proxyXXX setting does not need to be used. If a system-wide proxy setting is in effect, proxy settings made here in the Web service call builder will override the system value.

(optional) HTTP Proxy Port Enter the port number of the proxy server.
(optional) HTTP Proxy user Enter a user name for the proxy server.
(optional) HTTP Proxy Password Enter a password associated with the user name above.

 

Specifying inputs for an HTTP service

The Web service call builder takes the following inputs for an HTTP service:

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the Builder Call List.
Service Call Type Enable the HTTP radio button to configure a service call to an HTTP service.
Service Information
URL Enter the URL for the service.
HTTP Request Type GET or POST. By default, HTTP service calls have a request type of GET unless you specifically enter POST.
Arguments In the Arguments list, enter each argument name and use the Reference Chooser to set the value of the argument, or enter a text string directly.
HTTP Reply Schema Type If the reply is expected to be XML, use this input to schema-type the reply variable according to some schema defined in the model. This allows the reply variable to be integrated with the data page builder.
Advanced
(optional) Timeout (in seconds) Default value is 15 seconds. We can set this value higher to allow more time for a response from the service call.
Follow Redirect Enabled by default. If you do not want the service request to follow any redirections, disable this checkbox.
(optional) Force Content type to If the response from the HTTP service is something other than HTML, set the content type to the appropriate value, such as text/xml.
(optional) Parse all Reply Tags Enabled by default. If the structure returned is very complex, you disable this checkbox to keep the Factory from examining all the tags in the structure returned by the service call.
Wrap reply in <html/Document> tag Enable this check box (default) to wrap returned HTTP response data in a <htmlDocument> tag. This will yield <htmlDocument><HTML>...</HTML>.. and any other content prior to the </htmlDocument> end tag.

Disable this check box to return the first child element of the response IXml. This is useful in situations where you are expecting "text/xml" to be returned and can thus get back only the XML content not wrapped.

(optional) HTTP Headers In the HTTP header list, enter any HTTP header names and set the header values using the Choose Reference dialog, or enter a text string directly.
(optional) HTTP Cookies Enter the name for the cookie to include with the request and select the variable or method that contains or returns the cookie object.

Note that The list widget can accept a String of the form "name=value" or an IXml object with a <Value> child in it.

(optional) Logging Select the type of logging, if any, that you want the Builder to perform. Information will be written to the application server's console as well as the Factory's log file and can help in debugging problems with the service.

We can choose:

  • None - To disable logging

  • Inputs and outputs only - To dump the inputs and the response

  • Envelope only - To dump the SOAP request and response envelope for a WSDL/SOAP service call

  • All -To dump all the above information

(optional) Dummy/Stub Result Supply a value to be returned instead of actually calling the service.

For example, you might enable this functionality for testing purposes during application development so that we can run the model without requiring the other target model to be in place.

(optional) Basic Auth User Name If the service requires basic user authentication, enter the user name to use for the request here.
(optional) Basic Auth Password If the service requires basic user authentication, enter the password for the specified user here.

 

Using WSRR with WebSphere Portlet Factory

WebSphere Service Registry and Repository (WSRR) provides a master metadata registry and repository for Web services, ranging from traditional Web services that use SOAP/HTTP bindings to services that use a broad range of protocols and programming models. We can use WSRR to register, search for, and download SOA related artifacts, such as WSDL documents, XSD schemas and XML files, all of which may be useful in a WebSphere Portlet Factory application. A typical use case for portlet development entails a developer searching WSRR for such resources (for example, by service name, XML namespace or by properties), and then downloading the appropriate resources from WSRR to the Eclipse project for use in development of the application.

Once you download WSDL, XSD, or XML files from WSRR into the project, they may be used from the project just as any other such file-based resources you might have obtained from other sources, with builders such as Web service call, schema or the import to XML builder.

For instance, a localWeather.wsdl downloaded from WSRR to your project's WEB-INF folder could be referenced by the Web wervice call builder's WSDL input as WEB-INF/localWeather.wsdl.

WSRR provides two graphical user interfaces for searching and exporting WSDL, XSD and XML files: a Web-based user interface and an Eclipse plugin. See the topics Web UI Help and Managing services using the Eclipse user interface from the WebSphere Service Registry and Repository information center (http://publib.boulder.ibm.com/infocenter/sr/v6r0/index.jsp) for more information on installing and configuring the WSRR Eclipse plugin and for usage information for these interfaces.

  • The Service Registry Web interface may be used from a browser to search and query WSRR artifacts and export them to the local disk. Since the interface is outside of the Eclipse development environment, provide the specific location of your Eclipse project when downloading the WSRR artifacts (for example, C:\Documents and Settings\username\workspace\myproject\WEB-INF\ ).

  • The WSRR Service Registry Eclipse plugin is a better choice when working in an Eclipse based tool such as WebSphere Portlet Factory because itpresents you with a list of projects to choose from when you select WSRR artifacts to download.

By default, the WebSphere Portlet Factory perspective in Eclipse attempts to verify whether the WSRR Eclipse plugin is installed. If it is installed, the plugin is launch in the bottom layout area of Eclipse along with the Tasks and Applied Profiles views. If you have already customized your perspective, or have a previous perspective layout that Eclipse has cached, you might need to explicitly configure Eclipse to show the WSRR Plugin view with the Eclipse menu action: Window

then click Show View

then click Other

then click Service Registry.