The following topics describe the HTTP Binding Component.

About the HTTP Binding Component
HTTP Binding Component Features
HTTP/SOAP Extensibility Elements
Managing the HTTP Binding Component

About the HTTP Binding Component

The HTTP (SOAP) Binding Component provides external connectivity for SOAP over HTTP in a JBI 1.0 compliant environment.

The JBI platform allows software vendors to provide services that can be invoked by external components using different protocols. These services are represented as JBI Service Engines and implement the business logic of the service. JBI Binding Components implement the protocol transformations between abstract messages handled by the JBI Service Engines and concrete messages of the protocol.

The HTTP (SOAP) Binding Component enables external components to invoke services, hosted by the JBI platform, using SOAP messages over the HTTP/HTTPS protocol. It also allows JBI Service Engines to invoke external web services using the same SOAP over HTTP/HTTPS protocol.

The transformation of abstract messages to SOAP messages occurs in the HTTP Binding Component. WSDL extensibility elements, as defined in the WSDL 1.1 and the SOAP 1.1 specifications, are used to properly configure this transformation. These WSDL extensibility elements are part of the <binding> and <service> sections of WSDL documents. These WSDL documents are the major artifacts included in a Service Unit, the JBI deployable unit into a Binding Component. Both the binding and service section of a WSDL document must be properly configured to determine how the message is transformed and the destination of that message.

top

HTTP/SOAP Binding Component Architecture

The SOAP binding enables external components to invoke web services hosted by the JBI platform using SOAP messages over the HTTP protocol. It also allows JBI engines to expose its services. The web service can be unsecured or secured, using HTTP over SSL, TLS, or some other technology.

The SOAP binding primarily resides in the JBI framework. It leverages the services offered by the web container to receive incoming web service requests. The Binding components are based on standards and do not use any proprietary API to promote reusability across different J2EE based JBI platforms. The binding does not use any web container services for outbound web services requests.

The SOAP binding Component supports Basic Profile 1.0 and Basic Security Profile. The binding addresses basic profile requirements for messaging (XML representation of SOAP messages, including fault messages, SOAP processing model, and use of SOAP in HTTP) and transport level security.

The SOAP binding can exist in four valid states, INIT, START, STOP, and SHUTDOWN. The HTTP/SOAP Binding Components in both the containers accept requests only when the binding is in START state.

HTTP BC as a Service Provider

In the case of outbound message flow, where the HTTP Binding Component is being “invoked” by other components and engines, the Binding Component acts as a service provider. In this role, the HTTP Binding Component converts a normalized message, received as part of the message exchange with other components, to an HTTP/SOAP message. After the HTTP/SOAP message is created as a result of the message conversion, the message is sent to an HTTP destination.

The HTTP Binding Component uses the "SOAP with Attachments API for Java" (SAAJ) 1.2 to handle all outbound requests. SAAJ provides a standard way to send XML documents over the Internet from the Java platform.

HTTP BC as a Proxy Consumer

In the case of inbound message flow, where the HTTP Binding Component consumes the services of other components and engines, the HTTP Binding Component acts as a proxy consumer. In this role, the HTTP Binding Component converts the received HTTP/SOAP type message to a normalized message. The normalized message is then sent, as part of the message exchange, to another component as a service request.

top

Specifications Used with HTTP BC

The HTTP BC adheres to the following specifications.

WSDL 1.1 Specification

The HTTP Binding Component supports the WSDL 1.1 specification. This specification defines the XML format that describes services (as an abstract set of operations) supported by one or more ports that operate on abstract messages containing either document-oriented or procedure-oriented information. These operations and messages are bound to network protocols and message formats in order to define an endpoint. Similar endpoints are consolidated to created services. The WSDL is used to describe the collection of services and their messages, defining the message format or network protocols used to communicate.

SOAP Binding Definitions Outlined in the WSDL 1.1

The HTTP/SOAP Binding Component supports the WSDL 1.1 specification. To extend the functionality of the WSDL 1.1 specification for SOAP, the HTTP/SOAP Binding Component implements the SOAP binding definitions outlined in the WSDL 1.1 specification. By empowering the Binding Component with an implementation of the WSDL 1.1 SOAP binding, the Binding Component can:

• Indicate that a binding is bound to the SOAP 1.1 protocol
• Specify an address for a SOAP endpoint
• Identify the URI for the SOAPAction HTTP header for the HTTP binding of SOAP
• Provide definition for Headers that are transmitted as part of the SOAP Envelope

SOAP 1.1 Specification

The SOAP 1.1 specification defines a mechanism that expresses messaging semantics by providing a modular packaging model and encoding mechanisms that encode data within modules. To accomplish this, SOAP is comprised of three components:

• The SOAP envelope
• The SOAP encoding rules
• The SOAP RPC representation

In addition to these three components, the SOAP 1.1 specification defines protocol bindings that describe how a SOAP message can be carried in an HTTP message.

WS-I Basic Profile 1.0

The HTTP Binding Component supports WS-I Basic Profile 1.0 to promote interoperability across different web services implementations.

top

HTTP Binding Component Features

Features of the the HTTP/SOAP Binding Component include:

• Supports the WSDL 1.1 and SOAP 1.1 specifications (the RI example uses WSDL 2.0, SOAP 1.2). Message exchanges to and from this BC make use of the JBI WSDL 1.1 wrapper for the normalized message.
• Implements the SOAP binding from the WSDL 1.1 spec (not HTTP Get/Post or Mime bindings)
• Follows WS-I 1.0 conventions and adds additional support for non-conforming components
• Supports Document and RPC style web services
• Supports literal use
• Supports the common convention of WSDL retrieval using <service uri>?wsdl
• Uses XML Catalogs following the OASIS Committee Specification - these allow the component to resolve schemas locally without resorting to network access
• Packages an embedded HTTP server (Grizzly)
• Uses asynchronous I/O (NIO) in the server to service 1000s of concurrent incoming requests
• Outbound requests are currently handled using SAAJ 1.2
• The HTTP BC currently only handles ports that are not serviced by the application server
• Supports JBI service unit deployments to define the web services to provision or consume
• Makes use of the WSDL extensibility (standard SOAP extensions) to define external communication details for the web services to provision or consume.

Component Configuration

To support component configuration at installation and run-time, the HTTP BC uses the following conventions:

• Configuration defaults are present in the JBI descriptor of the BC
• The default configuration can be overridden using JBI installation configuration parameters at installation time
• At run-time, a custom JMX MBean exposes the configuration and allows relevant settings to be changed on-the-fly

top

HTTP/SOAP Extensibility Elements

The HTTP Binding Component contains both HTTP and SOAP Extensibility Elements.

SOAP WSDL Extensibility Elements

The SOAP WSDL extensibility elements allow you to configure two sets of information for the HTTP Binding Component: SOAP connectivity information and SOAP binding information, to convert WSDL messages to and from SOAP messages. Most of this information is taken from Section 3 of the WSDL 1.1 Specification.

SOAP Connectivity

The SOAP address Element

The SOAP address extensibility element allows the user to specify the connectivity information to the SOAP server.

The SOAP address element attributes:

The following is a sample usage of the SOAP address extensibility element defined for a service port:

<port binding="y:binding" name="soapEndpoint">
   <soap:address location="http://myhost:7676/some/additional/context" />
</port>

SOAP Binding

The SOAP extensibility elements for binding abstract WSDL messages to SOAP messages fall into several sections. Each section signifies how the binding should occur. At the binding level, the configuration applies to the entire port type. At the operation level, the configuration applies only to the operation. At the message level, the configuration applies to that particular message, regardless of whether the message is input or output.

The SOAP binding Element

The purpose of the SOAP binding element is to indicate that the binding is bound to the SOAP protocol format: Envelope, Header and Body. This element makes no claim as to the encoding or format of the message (e.g. that it necessarily follows section 5 of the SOAP 1.1 specification).

SOAP binding element attributes:

The SOAP binding element MUST be present when using the SOAP binding. Example:

<definitions .... >
    <binding .... >
        <soap:binding transport="uri"? style="rpc|document"?>
    </binding>
</definitions>

The style attribute value is the default style attribute for each contained operation. If the style attribute is omitted, it is assumed to be "document".

The value of the required transport attribute indicates the transport to use to deliver SOAP messages. The URI value http://schemas.xmlsoap.org/soap/http corresponds to the HTTP binding in the SOAP specification. Other URIs may be used here to indicate other transports (such as SMTP, FTP, etc.).

The SOAP operation Element

The purpose of the SOAP operation element is to provide binding information from the abstract operation to the concrete SOAP operation.

SOAP operation element attributes:

Example:

<definitions .... >
    <binding .... >
        <operation .... >
           <soap:operation soapAction="uri"? style="rpc|document"?>?
        </operation>
    </binding>
</definitions>

The style attribute indicates whether the operation is RPC-oriented (messages containing parameters and return values) or document-oriented (messages containing documents). This information may be used to select an appropriate programming model. The value of this attribute also affects the way in which the body of the SOAP message is constructed. If the attribute is not specified, it defaults to the value specified in the soap:binding element. If the soap:binding element does not specify a style, it is assumed to be "document".

The soapAction attribute specifies the value of the SOAPAction header for this operation. This URI value should be used directly as the value for the SOAPAction header. No attempt should be made to make a relative URI value absolute when making the request. For the HTTP protocol binding of SOAP, this value is required (it has no default value). For other SOAP protocol bindings, it MUST NOT be specified, and the soap:operation element can be omitted.

The SOAP body Element

The purpose of the SOAP body element is to provide binding information from the abstract operation to the concrete SOAP operation.

SOAP body element attributes:

Example:

<definitions .... >
    <binding .... >
        <operation .... >
           <input>
               <soap:body parts="nmtokens"? use="literal|encoded"?
                          encodingStyle="uri-list"? namespace="uri"?>
           </input>
           <output>
               <soap:body parts="nmtokens"? use="literal|encoded"?
                          encodingStyle="uri-list"? namespace="uri"?>
           </output>
        </operation>
    </binding>
</definitions>

The optional parts attribute of type nmtokens indicates which parts appear somewhere within the SOAP Body portion of the message (other parts of a message may appear in other portions of the message, such as when SOAP is used in conjunction with the multipart/related MIME binding). If the parts attribute is omitted, then all parts defined by the message are assumed to be included in the SOAP Body portion.

The required use attribute indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message.

If use is encoded, then each message part references an abstract type using the type attribute. These abstract types are used to produce a concrete message by applying an encoding that is specified by the encodingStyle attribute. The part names, types and value of the namespace attribute are all inputs to the encoding, although the namespace attribute only applies to content that is not explicitly defined by the abstract types. If the referenced encoding style allows variations in its format (as does the SOAP encoding), then all variations MUST be supported ("reader makes right").

If use is literal, then each part references a concrete schema definition using either the element or type attribute. In the first case, the element referenced by the part will appear directly under the Body element (for document style bindings) or under an accessor element named after the message part (in rpc style). In the second, the type referenced by the part becomes the schema type of the enclosing element (Body for document style or part accessor element for rpc style).

For an example that illustrates "defining the contents of a composite Body using a type," see section 2.3.1. The value of the encodingStyle attribute may be used when the use is literal, to indicate that the concrete format was derived using a particular encoding (such as the SOAP encoding), but that only the specified variation is supported ("writer makes right").

The value of the encodingStyle attribute is a list of URIs, each separated by a single space. The URI's represent encodings used within the message, in order of most restrictive to least restrictive (exactly like the encodingStyle attribute defined in the SOAP specification).

The SOAP fault Element

The fault element specifies the contents of SOAP Fault Details element. It is patterned after the body element.

SOAP fault element attributes:

Example:

<definitions .... >
    <binding .... >
        <operation .... >
           <fault>*
               <soap:fault name="nmtoken" use="literal|encoded"
                                 encodingStyle="uri-list"? namespace="uri"?>
           </fault>
        </operation>
    </binding>
</definitions>

The name attribute relates the soap:fault to the wsdl:fault defined for the operation. The fault message MUST have a single part.

The use, encodingStyle and namespace attributes are all used in the same way as with Body, only style="document" is assumed, since faults do not contain parameters.

The SOAP header and headerfault Elements

The header and headerfault elements allow headers to be defined that are transmitted inside the Header element of the SOAP Envelope. It is not necessary to exhaustively list all headers that appear in the SOAP Envelope using header. For example, extensions to WSDL may imply specific headers should be added to the actual payload and it is not required to list those headers here.

SOAP header element attributes:

SOAP headerfault element attributes:

Example:

<definitions .... >
    <binding .... >
        <operation .... >
           <input>
             <soap:header message="qname" part="nmtoken" use="literal|encoded"
                          encodingStyle="uri-list"? namespace="uri"?>*
               <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                 encodingStyle="uri-list"? namespace="uri"?/>*
             <soap:header>                                
           </input>
           <output>
               <soap:header message="qname" part="nmtoken" use="literal|encoded"
                            encodingStyle="uri-list"? namespace="uri"?>*
                 <soap:headerfault message="qname" part="nmtoken" use="literal|encoded"
                                   encodingStyle="uri-list"? namespace="uri"?/>*
               <soap:header>                                
           </output>
        </operation>
    </binding>
</definitions>

The use, encodingStyle and namespace attributes are all used in the same way as with Body, only style="document" is assumed since headers do not contain parameters.

Together, the message attribute (of type QName) and the part attribute (of type nmtoken) reference the message part that defines the header type.

The optional headerfault elements which appear inside the header and have the same syntax as the header, allow specification of the header types used to transmit error information pertaining to the header, and defined by the header. The SOAP specification states that errors pertaining to headers must be returned in the headers. This mechanism allows specification of the format of such headers.

HTTP Binding WSDL Extensibility Elements

The HTTP extensibility elements describe interactions between a web browser and a web site through HTTP 1.1's GET and POST verbs. This allows applications other than web browsers to interact with the site. The following protocol-specific information may be specified:

• An indication that a binding uses HTTP GET or POST
• An address for the port
• A relative address for each operation (relative to the base address defined by the port)

The information here is broken up into two main sections: how the user may configure an endpoint to an HTTP service, and how the user specifies configuration to map WSDL messages to HTTP messages

HTTP Connectivity

The HTTP address Element

The HTTP address extensibility element allows the user to specify connectivity information to the HTTP server.

The HTTP address element attributes:

The following is a sample usage of the HTTP address extensibility element defined for a service port:

<port binding="y:binding" name="soapEndpoint">
   <http:address location="http://myhost:7676/some/additional/context" />
</port>

HTTP Binding

The HTTP extensibility elements for binding abstract WSDL messages to HTTP messages fall into several sections. Each section signifies how the binding should occur. At the binding level, the configuration applies to the entire port type. At the operation level, the configuration applies only to the operation. At the message level, the configuration applies to that particular message, regardless of whether it is input or output.

The HTTP binding Element

The purpose of the HTTP binding element is to signify that the binding is bound to the HTTP protocol.

HTTP binding element attributes:

The HTTP binding element MUST be present when using the HTTP binding. Example:

<definitions .... >
    <binding .... >
        <http:binding verb="nmtoken" />
    </binding>
</definitions>

The value of the required verb attribute indicates the HTTP verb. Common values are GET or POST, but others may be used. Note that HTTP verbs are case sensitive.

The HTTP operation Element

The purpose of the HTTP operation element is to provide binding information from the abstract operation to the concrete HTTP operation.

HTTP operation element attributes:

Example:

<definitions .... >
    <binding .... >
        <operation .... >
           <soap:operation location="uri" />
        </operation>
    </binding>
</definitions>

The location attribute specifies a relative URI for the operation. This URI is combined with the URI specified in the http:address element to form the full URI for the HTTP request. The URI value MUST be a relative URI.

The HTTP urlEncoded Element

The urlEncoded element indicates that all of the message parts are encoded into the HTTP request URI using the standard URI-encoding rules (name1=value&name2=value...). The names of the parameters correspond to the names of the message parts. Each value contributed by the part is encoded using a name=value pair. This may be used with GET to specify URL encoding, or with POST to specify a FORM-POST. For GET, the "?" character is automatically appended as necessary.

Example:

<definitions .... >
    <binding .... >
        <operation .... >
           <input .... >
               <http:urlEncoded/>
           </input>
           <output .... >
               <-- mime elements -->
           </output>
        </operation>
    </binding>
</definitions>

The SOAP urlReplacement Element

The urlReplacement element indicates that all the message parts are encoded into the HTTP request URI using a replacement algorithm:

• The relative URI value of http:operation is searched for a set of search patterns
• The search occurs before the value of the http:operation is combined with the value of the location attribute from http:address
• There is one search pattern for each message part. The search pattern string is the name of the message part surrounded with parentheses "(" and ")".
• For each match, the value of the corresponding message part is substituted for the match at the location of the match
• Matches are performed before any values are replaced (replaced values do not trigger additional matches)

Message parts MUST NOT have repeating values.

The HTTP urlReplacement Elements

Example:

<definitions .... >
    <binding .... >
        <operation .... >
           <input .... >
               <http:urlReplacement/>
           </input>
           <output .... >
               <-- mime elements -->
           </output>
        </operation>
    </binding>
</definitions>

top

Managing the HTTP Binding Component

JBI 1.0 does not directly define many of the HTTP BC specific run-time monitoring and management capabilities (with some exceptions, for example: lifecycle extensions). It does however provide access to the Java Management Extensions (JMX) infrastructure. The HTTP BC therefore uses the following additional conventions to support enhanced management:

• For monitoring purposes, the BC directly creates and manipulates a monitoring object and registers it as an MBean
• Standard interfaces allow the GUI to understand the capabilities provided by the monitoring MBean
• For management purposes, an MBean is registered that exposes the configuration properties as MBean attributes and advanced management functionality as MBean methods

Configuring for Firewalls and Proxies

Additional configuration is required for the HTTP BC on intranets where firewalls are configured in such a way that access to external http servers occurs through proxies. For example, you may be able to access a machine from a browser, but the BC cannot connect, throwing an UnknownHostException.

Currently there is no specific proxy configuration support for the HTTP BC, so you must rely on the platform support configuration. For instance, (and this may not be the final recommended approach) you may need to add the system properties to the JVM options in the AS admin console:

1. Click on Application Server in the tree\JVM settings\JVM options
2. Select "Add JVM Option" to add two entries:
   
   
   • Dhttp.proxyHost=myProxyServer.com
   • Dhttp.proxyPort=80

The proxy may also requires authentication/authorization. The HTTP BC currently does not have this feature (that is, setting the HTTP property "Proxy-Authorization" with a base 64 encoded username:password).

Limitations

Currently, The HTTP / SOAP BC only handles ports that are not serviced by the application
server.

Frequently Asked Questions

This section presents common questions or scenarios that users may have when using this binding component. This section addresses the questions or scenarios.

1. Does the Binding Component support Faults defined on operations in both directions (that is, our application calling external WS and external clients calling our WS? What is the support for "fault not defined" (server/client) on WSDL operations?

   Yes, it will handle faults for web services for both inbound and outbound invocations.

   • For faults defined in the WSDL, the fault is converted to/from the standard normalized message format using the WSDL 1.1 wrapper defined in the JBI spec.

   • For faults defined in the WSDL, the fault is converted to/from the standard normalized message format using the WSDL 1.1 wrapper defined in the JBI spec.

2. How does the Binding Component handle services on different ports?

   For services defined on ports that are not served by the application server, it contains an embedded server that will listen on those ports. For services defined on an application server port, a servlet needs to be deployed to handle the "services" context.

3. When there are multiple operations defined in a Porttype/'Interface' bound to the same SOAP address URI, how does the BC know which one to invoke?

   It uses either the soapAction or the message signature to distinguish requests, depending on which one is unique within the WSDL definition (and present in the request). If neither is unique or present in the request, a fault will be returned indicating the ambiguity.

top