Configure the Web services client cache

Configuring the Web services client cache can improve the performance of your application server by caching the responses from remote Web services for a specified amount of time.

 

Before you begin

You should have the dynamic cache service enabled. To enable the dynamic cache service, see Task overview: Using the dynamic cache service to improve performance. Before attempting to configure the Web services client cache, you should understand how to create basic cache policies. See Configuring cacheable objects with the cachespec.xml file for more information.

 

Overview

Enabling the Web services client cache is an option to improve the performance of your system by using the dynamic cache service to save responses from remote Web services for a specified amount of time. For more information about the Web Services client cache, see Web services client cache.

 

Procedure

  1. Locate the Web Services Description Language (WSDL) file for the remote service. Portions of the WSDL file contain information that you will use in writing your cache policy. For more information about WSDL files, see WSDL. Following is an example of portions of a WSDL file that contains values that are used for the purpose of demonstration

    <definitions targetNamespace="http://TradeSample.com/"
        xmlns:tns="http://TradeSample.com/"
        xmlns="http://schemas.xmlsoap.org/wsdl/"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <message name="getQuoteRequest">
        <part name="symbol" type="xsd:string"/>
      </message>
    .....
    .....
    <binding name="SoapBinding" type="tns:GetQuote">
      <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="getQuote">
          <soap:operation soapAction=""/>
          <input name="getQuoteRequest">
            <soap:body namespace="http://TradeSample.com/" 
            use="encoded"
          encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
          </input>
          ......
          </operation>
    </binding>
    <service name="GetQuoteService">
      <port binding="tns:SoapBinding" name="SoapPort">
        <soap:address location="http://TradeSample.com:9080/service/getquote"/>
      </port>
    </service>
    </definitions>
    
    The highlighted text indicates values that are used in writing your cache policy.

  2. Choose how you plan to generate the cache id for your Web services client caching. We can build your cache id rules by using one of four options:

    • By calculating a hash of the SOAPEnvelope

    • By using SOAPHeader entries

    • By using operation and part parameters

    • By using custom Java code to build the cache id from input SOAP message content

    Using SOAPHeader entries is the best option if one can include information for building cache keys as part of the SOAP header. This method creates easy to read cache keys and can be built without parsing the SOAP body. Use custom Java code to generate a specific cache id based on the SOAP message. If you cannot include the header information, one can calculate the hash of the SOAPEnvelope for performance or parse the SOAP Body for user-friendly cache keys.

  3. Develop your cache policy.

    All Web services client cache policies must have the class JAXRPCClient. The name element in each cache entry is the target endpoint location that is defined in the WSDL file. We can find this address in the WSDL file by finding the <soap:address location=".."/> tag located in the port element. In the WSDL file for this sample, the address is http://TradeSample.com:9080/service/getquote. Develop the rest of your cache policy by using one of the following options:

    • Calculate a hash of the SOAPEnvelope to identify the request
      <cache>
        <cache-entry>
          <class>JAXRPCClient</class>
          <name>http://TradeSample.com:9080/service/getquote</name>
          <cache-id>
            <component id="hash" type="SOAPEnvelope"/>
            <timeout>60</timeout>
          </cache-id>
        </cache-entry>
      </cache>
      

Note the component attributes to create a cache id based on a hash calculation of the SOAPEnvelope. The cache id for this sample is generated as http://TradeSample.com:9080/service/getquote:Hash=xxxHashSoapEnvelope.

  • Use the SoapHeader to identify the request
    <cache>
      <cache-entry>
        <class>JAXRPCClient</class>
        <name>http://TradeSample.com:9080/service/getquote</name>
        <cache-id>
          <component id="urn:stock:getQuote" type="SOAPHeaderEntry"/>
        </cache-id>
      </cache-entry>
    </cache>
    

    This cache id is built by using special information in the SOAP header to identify requests for entries in the cache. Specify the type as SOAPHeaderEntry and the id as the operation name located in the binding element in the WSDL file. The cache id for this sample is generated as http://TradeSample.com:9080/service/getquote:urn:stock:getQuote=IBM.

    An example of a SOAP request generated by the client using SOAP Header:

    Note that the soapenv:actor attribute must contain com.ibm.websphere.cache

    POST /wsgwsoap1/soaprpcrouther HTTP/1.1
    SOAPAction: ""
    Context-Type: text/xml; charset=utf-8
    User-Agent: Java/1.4.1
    Host: localhost
    Accept: text.html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Connection: keep-alive
    Content-Length: 645
    
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope 
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Header>
      <getQuote soapenv:actor="com.ibm.websphere.cache" xmlns="urn:stock">IBM</getQuote>
    </soapenv:Header>
    <soapenv:Body
    soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding">
      <getQuote xmlns="urn:ibmwsgw#GetQuoteSample">
        <symbol xsi:type="xsd:string">IBM</symbol>
      </getQuote>
    </soapenv:Body>
    </soapenv:Envelope>
    

  • Use operation and part to identify the request
    <cache>
      <cache-entry>
        <class>JAXRPCClient</class>
        <name>http://TradeSample.com:9080/service/getquote</name>
        <cache-id>
          <component id="" type="operation">
            <value>http://TradeSample.com/:getQuote</value>
          </component>
          <component  type="part"/>
        </cache-id>
      </cache-entry>
    </cache>
    

    This example uses operation and request parameters. The operation can be a method name in the WSDL file located in the binding element or a method name in the Document/Literal Invocation (DII). If the namespace of the operation is defined, the value should be formatted as namespaceOfOperation:nameOfOperation. The part type can be defined in the message element of the WSDL file, as a request parameter, or as a request parameter of the DII invocation. Its id attribute is the part or parameter name, and the value is the part or parameter value. The cache id generated from using operation and request parameters is http://TradeSample.com:9080/service/getquote:operation=http://TradeSample.com/:getQuote/symbol=IBM.

    An example of the SOAP request generated by the client using operation and part:

    POST /wsgwsoap1/soaprpcrouter HTTP/1.1
    SOAPAction:""
    Content-Type: text/xml/charset=utf-8
    User-Agent: Java/1.4.1
    Host: localhost
    Accept: text.html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Connection: keep-alive
    Current-Length: 645
    
    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope
    xmlns: soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body
      soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <getQuote xmlns="urn:ibmwsgw#GetQuoteSample">
        <symbol xsi:type="xsd:string">IBM</symbol>
      </getQuote>
    </soapenv:Body>
    </soapenv:Envelope>
    

    • Use custom Java code to build the cache id from input SOAP message content

      If you use custom Java code to build the cache id, create an ID generator Java class that implements the IdGenerator interface defined in the com.ibm.websphere.cache.webservices.IdGenerator package and add a reference to the class you create in the cachespec.xml file by using the idgenerator tag.

      You can also implement the com.ibm.websphere.cache.webservices.MetaDataGenerator package to assign cache metadata such as timeout, priority, and dependency ids to cache entries using the metadatagenerator tag.

      Implement the com.ibm.websphere.cache.webservices.InvalidationGenerator interface and use the invalidationgenerator tag in the cachespec.xml file to generate cache ids and to invalidate entries in the cache. The id generated by the invalidation generator can be a cache id or a dependency id.

      For example, if you develop an ID generator class named SampleIdGeneratorImpl, a metadata generator class named SampleMetaDataGeneratorImpl, and an invalidation generator class named SampleInvalidationGeneratorImpl, your cachespec.xml file might contain the following:

      <cache-entry>
        <class>JAXRPCClient</class>
        <name>http://TradeSample.com:9080/service/getquote</name>
        <cache-id>
          <idgenerator>com.mycompany.SampleIdGeneratorImpl</idgenerator>
          <metadatagenerator>com.mycompany.SampleMetaDataAndInvalidationGeneratorImpl</metadatagenerator>
          <timeout>60</timeout>
        </cache-id>
        <invalidation>http://TradeSample.com:9080/service/GetQuote
          <invalidationgenerator>com.mycompany.SampleMetaDataAndInvalidationGeneratorImpl</invalidationgenerator>
        </invalidation>
      </cache-entry>
      

      The SampleIdGeneratorImpl class is a custom Java class that implements the com.websphere.cache.webservices.IdGenerator interface. The SampleIdGeneratorImpl class contains the getID method

      String getId(javax.xml.rpc.handler.soap.SOAPMessageContext messageContext)
      

      The following is an example of the SampleIdGeneratorImpl.java class.

      public class SampleIdGeneratorImpl implements IdGenerator {
      //The SampleIdGenerator class builds cache keys using SOAP header entries
          public String getId(javax.xml.rpc.handler.soap.SOAPMessageContext 
            messageContext) {
            ....
            // retrieve SOAP header entries from SOAPMessage
            SOAPHeader sh = soapEnvelope.getHeader();
             if (sh != null) {
              Iterator it = sh.examineHeaderElements("com.mycompany.actor");
              while (it.hasNext()) {
                 SOAPHeaderElement element =
                          (SOAPHeaderElement)it.next();
                Name name = element.getElementName();
                String headerEntryName = name.getLocalName();
                if (headerEntryName.equals("getQuote")){
                  String sNamespace = element.getNamespaceURI("");
                  if (sNamespace != null && !sNamespace.equals("")) {
                      headerEntryName = sNamespace + ":" + headerEntryName;
                    String quotes = element.getValue();
                  }
                  ...
                  ...
                  // create a method "parseAndSort" to parse and sort quotes
                  // By parsing and sorting quotes, you avoid duplicate cache 
                  // entries.
                  // quotes e.g. IBM,CSCO,MSFT,INTC
                  // to return a cache key "urn:stock:getQuote=CSCO,IBM,INTC,MSFT"
                  String sortQuotes = parseAndSort(quotes); 
                  cacheKey = headerEntryName + "=" + sortQuotes;
                 }
              }
          return cacheKey;
          }
        }
      
      

      The cache id for this sample is generated as http://TradeSample.com:9080/service/getquote:urn:stock:symbol=CSCO,IBM,INTC,MSFT.

      The SampleMetaDataAndInvalidationGeneratorImpl class is a custom Java class that implements the com.websphere.cache.webservices.MetaDataGenerator interface and the com.websphere.cache.webservices.InvalidationGenerator interface. The SampleMetaDataAndInvalidationGeneratorImpl class contains the setMetaData method and the getInvalidationIds method. We can also set up two smaller classes instead of this one large class. For example, create one class for the metadata generator and a different class for the invalidation generator. The following are method prototypes for the setMetaData method and the getInvalidationIds method:

      void setMetaData (javax.xml.rpc.handler.soap.SOAPMessageContext messageContext, 
        com.ibm.websphere.cache.webservices.JAXRPCEntryInfo entryInfo)
      String[] getInvalidationIds (javax.xml.rpc.handler.soap.SOAPMessageContext messageContext)
      

      An example of the SampleMetaDataAndInvalidationGeneratorImpl.java class follows:

      public class SampleMetaDataAndInvalidationGeneratorImpl implements MetaDataGenerator, InvalidationGenerator {
          //assigns time limit, and priority metadata
          public void setMetadata(javax.xml.rpc.handler.soap.SOAPMessageContext messageContext, com.ibm.websphere.cache.webservices.JAXRPCEntryInfo entryInfo) {
            ....
                      
          // retrieve SOAP header entries from SOAPMessage
            SOAPHeader sh = soapEnvelope.getHeader();
             if (sh != null) {
              Iterator it = sh.examineHeaderElements("com.mycompany.actor");
              while (it.hasNext()) {
                 SOAPHeaderElement element =
                          (SOAPHeaderElement)it.next();
                Name name = element.getElementName();
                String headerEntryName = name.getLocalName();
                                        if (headerEntryName.equals(“metadata”)) {
                // retrieve each metadata element and set metadata 
                        entryInfo.setTimeLimit(timeLimit);
                      entryInfo.setPriority(priority);
                  }
              }
          }
      
          //builds invalidation ids using SOAP header. 
          public String[] getInvalidationIds(javax.xml.rpc.handler.soap.SOAPMessageContext messageContext) {      ....
            // retrieve SOAP header entries from SOAPMessage
                      String[] invalidationIds = new String[1];
            SOAPHeader sh = soapEnvelope.getHeader();
             if (sh != null) {
              Iterator it = sh.examineHeaderElements("com.mycompany.actor");
              while (it.hasNext()) {
                 SOAPHeaderElement element =
                          (SOAPHeaderElement)it.next();
                Name name = element.getElementName();
                String headerEntryName = name.getLocalName();
                                        if (headerEntryName.equals("invalidation")) {
                String sNamespace = element.getNamespaceURI("");
                if (sNamespace != null && !sNamespace.equals("")) {
                    headerEntryName = sNamespace + ":symbol";
                  String quotes = element.getValue();
                }
                ...
                ...
                // create a method "parseAndSort" to parse and sort quotes
                // By parsing and sorting quotes, you avoid duplicate cache 
                // entries.
                // quotes e.g. SUNW,NT
                // to return a cache key "urn:stock:symbol=NT,SUNW"
                String sortQuotes = parseAndSort(quotes); 
                invalidationIds[0] = headerEntryName + "=" sortQuotes;
                   }
             }
          return invalidationIds;
          }
      }
      
      
      

      The invalidation id for this sample is generated as

      http://TradeSample.com:9080/service/getquote:urn:stock:symbol=NT,SUNW
      

      An example of the SOAP request generated by the client when using custom Java code follows:

      POST /wsgwsoap1/soaprpcrouter HTTP/1.1
      SOAPAction: ""
      Context-type: text/xml, charset=utf-8
      User-Agent: Java/1.4.1
      Host: localhost
      Accept: text.html, image/gif, image/jpeg, *; q=.2, */*; q=.2
      Connection: keep-alive
      Content-Length:645
      
      <?xml version="1.0" encoding="UTF-8"?>
      <soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Header>
        <getQuote soapenv:actor="com.mycompany.actor"
            xmlns="urn:stock">IBM,CSCO,MSFT,INTC</getQuote>
          <metaData soapenv:actor="com.mycompany.actor" xmlns="urn:stock">
            <priority>10</priority>
            <timeLimit>30000</timeLimit>
          </metaData>
          <invalidation soapenv:actor="com.mycompany.actor" 
            xmlns="urn:stock">SUNW, NT</invalidation>
      </soapenv:Header>
      <soapenv:Body
      soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding">
      <getQuote xmlns="urn:ibmwsgw#GetQuoteSample">
        <symbol xsi:type="xsd:string">IBM,CSCO,MSFT,INTC</symbol>
      </getQuote>
      </soapenv:Body>
      </soapenv:Envelope>
      

  • Save the cache policy to the appropriate directory.

    • If you are using the Web Services Gateway on SOAP channel 1, the directory is: <install_root>\installedApps\wsgwsoap1.servername.nodename.ear/wsgwsoap.war/WEB-INF

    • If you are using a simple JAX-RPC client in your application to invoke remote Web services, save your cache policy in the Web module WEB-INF of your JAX-RPC application.

     

    Result

    We can monitor the results of your Web services client cache policy by using the dynamic cache monitor. See Displaying cache information for more information.

     

    See also


    Web services client cache

     

    See Also


    Cachespec.xml file