Index Changes
This is version 5. It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

Using the HTTP Binding Component with the HTTP GET method

This document details the support of the HTTP GET method in the HTTP Binding Component.

Overview

The HTTP Binding Component (HTTP BC) is a component in the JBI environment that is used as a provider proxy to provide connectivity to services in the JBI environment, or as consumer proxy to invoke services.

The HTTP BC implements the HTTP 1.1 GET binding defined in the WSDL 1.1 Specification, enabling applications to consume or provide services via the JBI environment using a web browser-like HTTP GET interaction.

Configuration

To set up the HTTP BC to function for HTTP GET interactions, the description (WSDL) file of the service to which the BC is the proxy, needs to utilize the following HTTP Binding language elements defined in the WSDL 1.1 Specification:

  • A <http:binding> element to indicate that a WSDL binding uses HTTP GET.
  • A <http:address> element to represent the address of the port.
  • A <http:operation> element to represent a relative address for each operation, that is relative to the base <http:address> defined by the port.
  • A <http:urlEncoded> and <http:urlReplacement> element to indicate how all the message parts of a request are encoded and made a part of the HTTP request URI.

Binding Details

The following subsections detail the current extent to which these HTTP Binding language elements are supported and implemented by the HTTP BC. Unless indicated otherwise, all WSDL elements described below are defined in the namespace http://schemas.xmlsoap.org/wsdl/http/.

<http:binding>

  • This element indicates that the binding uses the HTTP protocol.
  • This element must be specified as a subordinate element of a <wsdl:binding/>.
  • This element requires a verb attribute that specifies the HTTP method to use (e.g., GET, POST, PUT, DELETE, OPTIONS, HEAD, and others).
  • NOTE: Currently, the HTTP BC only supports the values, GET and POST (please note HTTP methods are case-sensitive).
  • Example:
<http:binding verb=”GET”/>

<http:address>

  • This element represents the address of the port.
  • This element must be specified as a subordinate element of a <wsdl:port/>.
  • This element requires a location attribute that specifies the base URI for the port.
  • Example:
<http:address location=”http://localhost/MyService/MyPort”/>

<http:operation>

  • This element represents an address for an operation.
  • This element must be specified as a subordinate element of a <wsdl:operation/>.
  • This element requires a location attribute (just like the <http:address> element) that specifies a relative URI for the operation.
  • The <http:address> element, described earlier, addresses the port, and since a port can have multiple operations, this element represents a relative address to a particular operation; the value of this element's location attribute is appended to the value of the <http:address> location attribute to form the full URI for a request to this port and to this specific operation.
The HTTP BC supports a blank location attribute value for this element.
  • Example:
Given:
<http:operation location=”Submit”>
<http:address location=”http://localhost/MyService/MyPort”>

Evaluated: Full HTTP request URI is http://localhost/MyService/MyPort/Submit

<http:urlEncoded>

  • This element is used to indicate that all message parts that make up the input message will be encoded into the request URI using query-string encoding:
    • Name-value pair formatted as name=value
    • Ampersand-delimited name-value pairs: name1=value1&name2=value2&...
    • Message part names will comprise the names in each pair; message part values will comprise the values in each pair.
  • This element must be specified as a subordinate element of a <wsdl:input/>.
  • The HTTP BC supports <http:urlEncoded> only for the GET method; <http:urlEncoded> is ignored for the POST method. For an explanation, please see http://wiki.open-esb.java.net/Wiki.jsp?page=HttpPostUrlProcessing, and the Using the HTTP Binding Component with the HTTP POST Method documentation.
  • Example:
Given this description:
<wsd:message name=”MyMessage”>
<wsdl:part name=”partA” type=”xsd:string”/>
<wsdl:part name=”partB” type=”xsd:string”/>
</wsdl:message>
...
<wsdl:portType name=”MyPortType”>
<wsdl:operation name=”MyOperation”>
<wsdl:input message=”MyMessage”/>
</wsdl:operation>
</wsdl:portType>
...
<wsdl:binding name=”MyBinding type=”MyPortType”>
<http:binding verb=”GET”/>
<wsdl:operation name=”MyOperation”>
<wsdl:input>
<http:urlEncoded/>
</wsdl:input>
</wsdl:operation>
</wsdl:binding>
...
<wsdl:service name=”MyService”>
<wsdl:port name=”Port1” binding=”MyBinding”>
<http:address location=”http://localhost/MyService/MyPort”/>
</wsdl:port>
</wsdl:service>


Given this input mapping:
part partA -> value valueY
part partB -> value valueZ

Evaluation:
The full HTTP request URL: http://localhost/MyService/MyPort/MyOperation?partA=valueY&partB=valueZ

<http:urlReplacement/>

Given this description:
<wsd:message name=”MyMessage”>
<wsdl:part name=”partA” type=”xsd:string”/>
<wsdl:part name=”partB” type=”xsd:string”/>
</wsdl:message>
...
<wsdl:portType name=”MyPortType”>
<wsdl:operation name=”MyOperation”>
<wsdl:input message=”MyMessage”/>
</wsdl:operation>
</wsdl:portType>
...
<wsdl:binding name=”MyBinding” type=”MyPortType”>
<http:binding verb=”GET”/>
<wsdl:operation name=”MyOperation/(partA)/subcategory/(partB)”>
<wsdl:input>
<http:urlReplacement/>
</wsdl:input>
</wsdl:operation>
</wsdl:binding>
...
<wsdl:service name=”MyService”>
<wsdl:port name=”Port1” binding=”MyBinding”>
<http:address location=”http://localhost/MyService/MyPort”/>
</wsdl:port>
</wsdl:service>


Given this input mapping:
part partA -> value valueY
part partB -> value valueZ

Evaluation:
The full HTTP request URL is http://localhost/MyService/MyPort/MyOperation/valueY/subcategory/valueZ

Examples

The following examples assume knowledge in using the NetBeans IDE; in using the IDE's WSDL editor, which supports the WSDL 1.1 Specification's HTTP Binding; in using the BPEL editor, and in using the BPEL and Composite Application project types. Users can choose to create service descriptions (or retrieve them from extant services) using other tools, but eventually these artifacts need to be imported into NetBeans projects to be part of the building and deployment of JBI Composite Applications.

Example: Provider Proxy

We wish to expose a web service thru the JBI environment that uses an HTTP binding. In such a scenario, the HTTP BC will function as an intermediary for the actual service, providing the means for applications to use the service using a HTTP GET-style interface. We will implement the service as a BPEL process. We will configure the HTTP BC to process requests as HTTP GET query-string requests.

1. Create a BPEL Project in NetBeans.


2. Create a new WSDL document in the BPEL Project. In the new-file creation wizard, specify the parameters necessary to describe a request-response service operation with HTTP Binding:





3. The NetBeans WSDL Editor generates the service description based on the parameters specified in the preceeding file creation wizard. Note the HTTP Binding elements, <http:binding>, <http:operation>, <http:address>, and <http:urlEncoded>, are already present in the service description.


4. Create a new BPEL process that implements the service's operation. In this example, we implement an “echo” operation that outputs the input without further modification.



5. Build the BPEL project. Upon completion of this step, the service implementation is done.

6. Create a Composite Application project to prepare the BPEL project for deployment in the JBI environment.

7. Add the BPEL project to the Composite Application project as a JBI module.




8. Build and deploy the Composite Application project.

9. Open the WSDL file created from step 2, and note the location value of the <http:address> element:

<http:address location=”http://localhost:${HttpDefaultPort}/EchoService/EchoServicePort”/>

The segment ${HttpDefaultPort}}} is special token understood by the HTTP BC that is substituted with a real value as specified in the property sheet of the HTTP BC node in the Services view:

10. Start a web browser and issue the following request:

http://localhost:9080/EchoService/EchoServicePort?part=Widget
  • ${HttpDefaultPort} is substituted with 9080, as configured.
  • The concatenation of the <http:address> and <http:operation> location values consists of http://localhost:9080/EchoService/EchoServicePort and “” (blank value), respectively.
  • The service describes an input message consisting of one part named part, that is of type xs:string. It also describes an output message defined similarly.
  • The service declares query-string encoding by the use of the <http:urlEncoded> element. As previously described, this encodes message parts as name-value pairs using the name and value of each part, respectively, thus: part=Widget is the name-value pair that represents the message part named part mapped to a xs:string value of Widget.

Example: Consumer Proxy

Suppose, instead, that the service described in the previous example is an existing and active service that we wish to call. But instead of accessing the service using a web browser (as we did in the previous example), or some other standalone, client program, we instead use the HTTP BC and the JBI environment to consume the service. One general use-case is a BPEL workflow that involves (a) sending a request to a service, (b) making a decision based on the service response, and (c) performing divergent BPEL activities based on that decision. In effect, the BPEL workflow is its own service, that utilizes the HTTP BC to call another service as part of its orchestration.

1. Create and deploy the service described in the previous example, Provider Proxy. We will utilize that service in the role of an “external” service that we will call within a separate BPEL orchestration.

Note: even though this service is, in fact, deployed in the JBI environment, it will still be used as an external service in the sense that all HTTP BC communication, between consumer and provider, is performed “over the wire”. No internal JBI routing “cheating” occurs that shortcuts the service invocation, omitting or reducing the use of the HTTP communications protocol.

2. Create another BPEL project, and import the description of the deployed service into it.




3. Create a new service WSDL file. This file describes the service represented by the BPEL process that is created in the next step. This service will utilize SOAP Binding, unlike the external service that we've already defined to use HTTP Binding.

Note: There are two services in this example, and it is important to understand their distinction! The service WSDL imported in the previous step describes an existing, independent service that the BPEL process will call. The service WSDL created in this step describes the service that the BPEL process itself provides (i.e., the service it provides is the ability, in part, to call the other service).





4.Create a BPEL process. In the following illustrations, the BPEL workflow:


  • Receives a request


  • Invokes a service (the service created and deployed in step 1), forwarding to it the request received previously.
  • Evaluates the service response by computing its length.


  • If the response is 5 characters or less, the BPEL process replies with the response surrounded by parentheses.


  • If the response is more than 5 characters, the BPEL process replies with the response content surrounded by '+' characters.


5. Build the BPEL project. Upon completion of this step, the service implementation is done.

6. Create a Composite Application project, and add the BPEL project to the Composite Application project.

7. Build and deploy the Composite Application project.

8. Create a test case in the Composite Application project. When prompted for the WSDL document to test, select the WSDL file for the BPEL process, not for the service that the BPEL process is intended to invoke. The test's purpose is to execute the BPEL process, so that external service call occurs from within the JBI environment and through the HTTP BC.





9. Specify test input that is 5 characters of less in length, to demonstrate the result of executing one of two activity paths in the BPEL process.


10. Create a second test case that uses test input that is greater than 5 characters, to demonstrate the alternate activity path in the BPEL process.





11. Execute both tests and observe the test output.






JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This particular version was published on 09-May-08 18:27 PM, -0700 by NoelDAng