Adding parameters to Web services

You can add to Web services parameters that set optional properties within a supported database that a Web service performs operations against and optional properties of the connections between the Web service and the database. You can add these parameters by default to the Web services that you create within a data development project, or you can add them when deploying individual Web services.

About this task

You can pass additional control or audit information to Web services by specifying additional Web service parameters and then passing values for those parameters. You specify the parameters in the Parameters table on the Web Services page of the Properties window for your project or in the Deploy Web Service wizard.

You can pass values to the additional parameters by three different methods:
  • Specifying the values directly in the Parameters table
  • Specifying the values in SOAP message headers, if client applications will send SOAP/HTTP messages to the Web services
  • Specifying the values in HTTP control parameters, if client applications will send REST-like messages to the Web services

Passed values apply only to the operation that the message requests. They do not span more than one message or operation.

Procedure

To add parameters to Web services:

  1. Decide which control parameters you want to add and the values that you want to set for them.
    Parameters for passing DB2® database client audit information
    • connection.jcc.clientAccountingInformation
    • connection.jcc.clientUser
    • connection.jcc.clientProgramName
    • connection.jcc.clientWorkstation

    For descriptions of these parameters, see the links in the Related information section at the end of this topic. When you follow a link, locate the parameter by finding the third part of its name. For example, if the parameter is connection.jcc.clientUser, locate the parameter by finding clientUser.

    Parameters for passing connection information
    connection.stmt.maxRows
    Specifies the maximum number of rows to return for a result set.
    connection.stmt.queryTimeout
    Specifies the number of seconds that the JDBC driver waits for the statement to run on the database. If the statement does not run within this amount of time, the connection closes.
    Parameter for specifying message output format
    outputFormat
    For a description of this control parameter, see Message output formats.
  2. If you are using an Apache Tomcat Web server, your Resource definition set the parameter accessToUnderlyingConnectionAllowed to true. For example, if you were using the sample database that comes with DB2 for Linux, UNIX, and Windows, your resource definition would look similar to this. The accessToUnderlyingConnectionAllowed parameter is highlighted in bold.
    <Resource driverClassName="com.ibm.db2.jcc.DB2Driver" 
    maxActive="4" 
    maxIdle="2" 
    maxWait="5000" 
    name="jdbc/sample" 
    password="password" 
    type="javax.sql.DataSource" 
    url="jdbc:db2://localhost:50000/sample" 
    username="userID" 
    validationQuery="select * from employee" 
    accessToUnderlyingConnectionAllowed="true"/>
  3. Open either the Properties window for a data development project or the Deploy Web Service wizard.
    Option Description
    To add the parameters to every Web service in a data development project
    1. Right-click the project node and then select Properties.
    2. In the Properties window, select Web Services.
    To add the parameters only to a Web service that you want to deploy
    • In a data development project, right-click the Web service, and then select Build and Deploy.
  4. For each parameter, follow these steps:
    1. To the right of the Parameters table, click New. An editable row appears in the table.
    2. Type the name of the parameter in the Name column of the editable row.
    3. To have the value of the parameter used every time that a Web service performs an operation on the database, type the value of the parameter in the Value column. If the parameter name begins with the prefix service, you must specify the value.
    4. To provide the value in the header of SOAP messages or in an HTTP control parameter of REST messages, leave the Value column blank.

Example

Suppose that you want to set the database connection property clientUser for all the Web services in your data development project. You right-click the project node, and then select Properties. In the Properties window, you select Web Services. On the Web Services page next to the Parameters table, you click New to add a row to the table. In the Name column of the new row, you type connection.jcc.clientUser.

The Parameters table on the Web Services properties page for the project and in the Deploy Web Service wizard.
There are three ways that you can provide the value for this parameter:
  • Specify the value in the Value column of the new row. The Web services apply the parameter and its value to all database connections, without exception. Any value that is specified for this parameter in a client application is ignored.
    Specifying the value of the parameter in the Value column of the Parameters table.
  • Specify the value in the header of SOAP/HTTP messages that client applications send to the Web services.

    Sample for Apache Axis2 generated code using the SOAP header

    package myClientTest;
    
    import example.WebService2Stub;
     
    public class getEmployee {
    
       public static void main(String args[]) {
          try {
             // create the stub
             WebService2Stub stub = new WebService2Stub("http://localhost:8000/WebService2/services/WebService2");
             // create the request elment for SOAP body
             WebService2Stub.GetEmployee empRequest = new  WebService2Stub.GetEmployee();
             // fill request with employee number
             empRequest.setEmpno("000130");
    
             // create the Header for the request element
             WebService2Stub.ConnectionProperties properties = new WebService2Stub.ConnectionProperties();
             WebService2Stub.ConnectionPropertiesType propertiesType = new WebService2Stub.ConnectionPropertiesType();
             properties.setConnectionProperties(propertiesType);
    
             // fill the header with properties
             WebService2Stub.Property_type0 property1 = new WebService2Stub.Property_type0();
             property1.setName("connection.jcc.clientUser");
             property1.setValue("heathr");
             propertiesType.addProperty(property1);
    
    
             WebService2Stub.GetEmployeeResponse response =  stub.getEmployee(empRequest, properties);
    
             //...
    
          } catch (Exception e) {
             System.err.println(e.toString());
          }
       }
    }

    This is the SOAP request that is generated by the code:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
       <soapenv:Header>
          <ns1:connectionProperties xmlns:ns1="urn:example">
             <property name="connection.jcc.clientUser" value="heathr"/>
          </ns1:connectionProperties>
       </soapenv:Header>
       <soapenv:Body>
          <ns1:getEmployee xmlns:ns1="urn:example">
             <empno>000130</empno>
          </ns1:getEmployee>
       </soapenv:Body>
    </soapenv:Envelope>
  • Specify the value in an HTTP control parameter of REST-like messages that client applications send to the Web services. In the URL of a REST message, an HTTP control parameter is denoted by an underscore prefix.

    The following input message uses REST-like HTTP GET (url-encoded):

    GET /Project1WebService2/rest/WebService2/getEmployee?empno=000130&_connection.jcc.clientUser=heathr HTTP/1.1
    User-Agent: Java/1.5.0
    Host: localhost:8070 
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 
    Connection: keep-alive
    Content-type: application/x-www-form-urlencoded

    The resulting URL for the request is as follows. This URL can be used in all HTTP bindings.

    http://localhost:8080/Project1WebService2/rest/WebService2/getEmployee?empno=000130&_connection.jcc.clientUser=heathr


Feedback