Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop SCA composites > Specify bindings in an SCA environment

Configure the SCA web services binding

We can expose a Service Component Architecture (SCA) application as a web service by configuring the SCA web services binding.

Web services technology plays an important role in most service-oriented architecture (SOA) solutions relevant today, including SCA. The web service binding type enables SCA applications to expose services as web services to external clients and gives SCA components access to external web services. External clients that access SCA services exposed as web services might or might not be implemented as an SCA component. We can use the web service binding element <binding.ws> within either a component service or a component reference definition. When this binding is used with a component service, the web service binding type enables clients to access a service that is offered by a particular component as a web service. If the web service binding is used with a component reference, components in an SCA composite can consume an external web service and access it like any other SCA component.

The product supports WSDL Version 1.1 definitions that also conform to the WS-I Basic Profile Version 1.1 and Simple SOAP Binding Profile 1.0 standards, and use the document literal style. All these conditions are required for support.

The SCA web services binding applies to the services and references of components. The web service binding defines the manner in which a service is made available as a web service, and in which a reference can invoke a web service. This binding is a WSDL-based binding; meaning that the binding either references an existing WSDL document or enables you to specify enough information to generate a WSDL document.

You can typically use the same policy set functionality, that you use for defining qualities of service on JEE-based web services that are running in the application server, to define quality of service definitions on SCA clients and services that use the SCA web service binding. When the instructions for administratively configuring these policy set definitions are different for SCA-based web services than they are for Java EE-based web services, then special topics and instructions are provided in this information center. If there are no special instructions for SCA, configure the corresponding quality of service on the SCA-based web service the same way that you would configure that quality of service for a Java EE-based web service.

The SCA web services binding provides support for providing and consuming services using the SOAP v1.1 over HTTP and SOAP V1.2 over HTTP protocols.

The product does not support the following functions:

• Java API for XML-Based Web Services (JAX-WS) handlers when using the SCA web services binding
• MTOM or SOAP with Attachments (SwA) binary message optimizations

Use the SCA web services binding without implementing JAX-WS handlers. Do not use SwA binary message optimizations or MTOM optimizations for transferring binary data between SCA clients and services that use the SCA web services binding. Instead of implementing MTOM or SwA binary message optimizations to send binary data, use the base64Binary XML Schema Definition (XSD) encoding to embed the data within the SOAP message.

Procedure

• Configure an SCA service with the SCA web services binding.

  Depending on whether you develop your SCA service using the top-down development approach starting with an existing WSDL file or you develop your SCA service using the bottom-up development approach starting with existing Java code, you might or might not have a WSDL file available. Additionally, the WSDL file might define only a portType or it might include a port definition as well.

  • For SCA applications that are developed top-down starting from a WSDL port, refer to the port definition in the existing WSDL file by adding a <binding.ws> element as a child of your <service> element. An example of the syntax for this step follows:

    <binding.ws wsdlElement=”
    <port target Namespace>#wsdl.port(
    <service name attr>/
    <port name attr>)”/> 

    The location attribute of the <address> element for the port is ignored by the runtime environment in determining the URL at which your service is invoked.

    The following example demonstrates the relationship between the WSDL file and the composite definition for this scenario:

    WSDL file

    <wsdl:definitions targetNamespace="http://www.ibm.com/" xmlns:tns="http://www.ibm.com/" …>       ….
    
    <wsdl:portType name="MyPortType ">       ….
    
    <wsdl:binding name="MyBinding" type="tns:MyPortType">       ….
    
    <wsdl:service name="MyService">   
    <wsdl:port binding="tns:MyBinding" name="MyPort">       
    <wsdlsoap:address location=""/>   
    </wsdl:port>
    </wsdl:service>
    

    Composite definition

    <composite…>
    <component name="MyComponent"> 
    <implementation.java class="test.MyCompImpl"/>   
    <service name="GuessAndGreetWrapped">       
    <interface.wsdl interface="http://www.ibm.com/#wsdl.interface(MyPortType)" />       
    <binding.ws wsdlElement="http:// www.ibm.com/#wsdl.port(MyService/MyPort)" />   
    </service>
    </component>       …
    
    </composite> 

  • For SCA applications that are developed top-down starting from a WSDL portType, create an empty <binding.ws> element as the child of your <service> element. Creating the empty <binding.ws> element directs the runtime environment to generate a port that corresponds to your WSDL portType definition. The generated port uses a SOAP 1.1 over HTTP WSDL binding.

    The following example demonstrates the relationship between the WSDL file and the composite definition for this scenario:

    WSDL file

    <wsdl:definitions targetNamespace="http://www.ibm.com/" xmlns:tns="http://www.ibm.com/" …>       ….
    
    <wsdl:portType name="MyPortType ">
    

    Composite definition

    <composite…>
    <component name="MyComponent"> 
    <implementation.java class="test.MyCompImpl"/>   
    <service name="GuessAndGreetWrapped">       
    <interface.wsdl interface="http://www.ibm.com/#wsdl.interface(MyPortType)" />              
    <binding.ws/>
      
    </service>
    </component>       …
    
    </composite> 

  • For SCA applications that are developed bottom-up starting from existing Java code, create an empty <binding.ws> element as the child of your <service> element. Creating the empty <binding.ws> element directs the runtime environment to generate a WSDL portType that corresponds to your Java interface, and a port with a SOAP 1.1 over HTTP WSDL binding.

    The following example demonstrates the <binding.ws> element within the composite definition for this scenario:

    Composite definition

    <composite…>
    <component name="MyComponent"> 
    <implementation.java class="test.MyCompImpl"/>   
    <service name="GuessAndGreetWrapped">       
    <binding.ws/>   
    </service>
    </component>       …
    
    </composite> 

• Test the endpoint for your deployed SCA service.

  After you configure the SCA service with an SCA web services binding, you can test the endpoint for your deployed SCA service. With one exception, the URL format for the endpoint is the following:

  http://
  <host>:
  <port_of_default_host>/Component_name/Service_name
  

  For SCA services that are configured using wsdlElement#wsdl.service, the ports are appended; for example:

  http://
  <host>:
  <port_of_default_host>/Component_name/Service_name/Port_name
  

  Access the endpoint with a web browser displays the Axis2 cover page.

• View WSDL or XSD documents for the SCA service with the web service binding.

  Append the query string ?wsdl to the endpoint URL. Accessing the URL with a web browser returns the outermost WSDL. We can then view included and imported documents using relative URLs.

• Configure an SCA reference (client) with an SCA web services binding.

  1. Configure the reference with an <interface.wsdl> element that refers to the portType of the target service. After we have obtained a WSDL portType from the web services provider, you can configure the <interface.wsdl>. Read about developing SCA service clients to learn how to configure the reference with an <interface.wsdl>.
  2. Resolve the SCA reference to an actual endpoint of a deployed web service using one of the mechanisms provided by the SCA web services binding support.

     • When the target web service is deployed as an SCA component service in the same domain as the client component, you can resolve the reference to the target component using the <reference> @target attribute. Using this attribute eliminates the need to know the specific URL of the deployed target service. For example:

       <!-- The composite definition for the target service. -->
       <component name="TargetComponent">
       <implementation.java …/>  
       <service name="MyService">      
       <interface.wsdl … />      
       <binding.ws … />   
       </service>
       </component> 

       <!— The composite definition for the client when the client is in same SCA domain as the target component. -->
       <component name="ClientComponent">
       <implementation.java …/>
        
       <!-- Resolution done using the @target annotation. -->  
       <reference name="myRef" target=”TargetComponent/MyService”>       
       <interface.wsdl … />
             
       <!-- The binding does not need endpoint-related info added. -->       
       <binding.ws/>  
       </reference>
       </component> 

     • If the target web service is not an SCA service in the same domain as the client, use a binding-specific endpoint resolution mechanism. We can also resolve a reference to an SCA service in the same domain by using the binding-specific mechanisms, instead of using the @target annotation.

       1. We can define the endpoint for a deployed web service in an existing WSDL file that is obtained from a service provider. In this case, the client composite definition refers to the WSDL port of the target service which also specifies the endpoint from the <wsdlsoap:address> @location attribute. For example:

          <wsdlsoap:address location="http://host:port/ComponentName/ServiceName"/> 

          The client points to the WSDL port using a @wsdlElement attribute on the <binding.ws> element using the following syntax:

          <port target Namespace>#wsdl.port(
          <service name attr>/
          <port name attr>)”/> 

          The following example WSDL and composite definitions illustrate defining an endpoint for a deployed web service.

          <!-- An example WSDL file.   -->
          
          
          <wsdl:definitions targetNamespace=”http://my.work/test/”
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
              xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"   … >
          <wsdl:service name="MyService">
          <wsdl:port binding="…" name="MyPort">  
          <wsdlsoap:address
                     location="http://www.mywork.com:9080/TargetComponent/MyService "/>
          </wsdl:port>
          </wsdl:service>
          </wsdl:definitions> 

          <!-- An example composite definition.   -->
          <component name="ClientComponent">
          <implementation.java …/>  
          <reference name="myRef">     
          <interface.wsdl … />     
          <binding.ws wsdlElement="http://my.work/test/#wsdl.port(MyService/MyPort)”/>
           
          </reference>
          </component> 

       2. We can add the endpoint to the composite definition when the endpoint is not present in the WSDL file. In this case, add the @uri attribute to the <binding.ws> element to specify the endpoint.

          <!-- An example WSDL file.   -->
          
          
          <wsdl:definitions targetNamespace=”http://my.work/test/”
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
              xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/"   … >
          <wsdl:service name="MyService">
          <wsdl:port binding="…" name="MyPort">
           
          <!-- Here, the endpoint not specified in the WSDL. -->   
          <wsdlsoap:address   location=""/>
          </wsdl:port>
          </wsdl:service>
          </wsdl:definitions> 

          <!-- An example composite definition.   -->
          <component name="ClientComponent">
          <implementation.java …/>  
          <reference name="myRef">       
          <interface.wsdl … />       
          <binding.ws wsdlElement="http://my.work/test/#wsdl.port(MyService/MyPort)”
                       uri=”http://www.mywork.com:9080/TargetComponent/MyService” />  
          </reference>
          </component> 

• (optional) If your service or reference interface is bidirectional such that a callback is defined, also configure the web service binding on the callback.

  • Configure callback for your SCA web services binding using the WSDL port.

    Configure callback for your SCA web services binding is similar to configuring an SCA service with the SCA web services binding; however, you add a second service, the callback. When you configure an SCA service with the SCA web services binding, you define a WSDL port, either explicitly by pointing directly to a WSDL port definition, or implicitly by giving the runtime enough information to calculate a WSDL port. Similarly, also define a WSDL port for the callback. A difference for the callback is that the runtime environment defines the WSDL port used for the callback because the runtime environment must keep this port tightly coupled to the forward call. Therefore, the most you can do when developing your SCA application using the top-down approach and defining a callback for this service, is to point to a WSDL binding. For example:

    <!-- Configuring a service with callback with web service binding -->
    <component name="HelloWorldServiceComponent">      
    <implementation.java class="…" />      
    <service name="HelloWorldService">           
    <interface.wsdl interface=”http://www.ibm.com/sca/#wsdl.interface(HelloWorld)”
                          callbackInterface=” http://www.ibm.com/sca/#wsdl.interface(HelloWorldCallback)”/>           
    <binding.ws wsdlElement="http://www.ibm.com/sca/#wsdl.port(HelloWorldService/HelloWorldSoapPort)"/>           
    <callback>               
    <binding.ws wsdlElement="http://www.ibm.com/sca/#wsdl.binding(HelloWorldCallbackSoapBinding)" />           
    </callback>      
    </service>
    </component> 

    The following example shows a configuration of a client component with reference to this service with callback defined. The reference and service configuration each share the same view of which direction is the forward direction and which is the callback direction.

    <!-- Configuring a reference with callback with web service binding. -->
    <component name="HelloWorldClientComponent">      
    <implementation.java class="…" />      
    <reference name="helloWorldRef">           
    <interface.wsdl interface=”http://www.ibm.com/sca/#wsdl.interface(HelloWorld)”
                      callbackInterface=” http://www.ibm.com/sca/#wsdl.interface(HelloWorldCallback)”/>      
    <binding.ws wsdlElement="http://www.ibm.com/sca/#wsdl.port(HelloWorldService/HelloWorldSoapPort)"/>      
    <callback>
             
    <binding.ws wsdlElement="http://www.ibm.com/sca/#wsdl.binding(HelloWorldCallbackSoapBinding)" />      
    </callback>    
    </service>
    </component>
    

  • Configure callback for your SCA web services binding using the WSDL portType.

    Similar to the scenario of configuring a service with a web service binding when starting with a WSDL port, you also configure an empty <binding.ws> element to configure callback using the WSDL portType. The following composite definition example illustrates the scenario when starting with two WSDL portType definitions that has such that one interface uses a forward direction and the other interface uses callback:

    <!-- Configuring a service with callback with web service binding -->
    <component name="HelloWorldServiceComponent">      
    <implementation.java class="…" />      
    <service name="HelloWorldService">          
    <interface.wsdl interface=”http://www.ibm.com/sca/#wsdl.interface(HelloWorld)”
                     callbackInterface=” http://www.ibm.com/sca/#wsdl.interface(HelloWorldCallback)”/>          
    <binding.ws/>          
    <callback>             
    <binding.ws/>          
    </callback>      
    </service>
    </component>
    

    <!-- Configuring a reference with callback with web service binding -->
    <component name="HelloWorldClientComponent">      
    <implementation.java class="…" />      
    <reference name="helloWorldRef">         
    <interface.wsdl interface=”http://www.ibm.com/sca/#wsdl.interface(HelloWorld)”
                    callbackInterface=” http://www.ibm.com/sca/#wsdl.interface(HelloWorldCallback)”/>
            
    <binding.ws/>         
    <callback>           
    <binding.ws/>
            
    </callback>
         
    </service>
    </component> 

  • Configure callback for your SCA web services binding using the Java interface.

    For the bottom-up case starting with a Java interface, the composite definition is identical to the WSDL port and portType scenarios, except that replace the <interface.wsdl> elements with the <interface.java> element. For example:

    <interface.java interface="helloworld.HelloWorldService"
             callbackInterface="helloworld.HelloWorldCallback"/>
    

Results

You have a configured SCA web services binding service or reference. There are additional ways for the web service binding function to generate a WSDL port that are not described in this topic. However, these additional methods that rely on WSDL generation at run time add dependencies on the runtime environment that can cause problematic results.

For an example that is not problematic, suppose you write a service using the bottom-up style, starting from a Java interface, and deploy the service with an empty element. This directs the runtime environment to generate the WSDL port for this service. Also suppose an SCA client is developed with access to the original Java classes used to write the service implementation. This SCA client is used to test the SCA service using a client-side reference with web service binding. We can configure this reference without any knowledge of the service WSDL. In this case, the reference interface is the original Java interface of the service, and you can resolve the reference using the <reference> @target mechanism. See the resolving SCA references documentation for more information about using the <reference> element to resolve an SCA reference using the @target attribute. Using this approach, there is no WSDL to obtain or refer to in constructing the client. This works because the product runtime environment maps the service-side Java to WSDL in an identical manner as it maps the client-side Java to WSDL.

In contrast, the following scenario is problematic. Suppose that you write an SCA client with a web service binding reference to a web service that is hosted on a platform other than the product. It might seem reasonable to generate your Java client from the service provider, and then ignore the WSDL from that point on, avoiding the additional syntax in your client-side composite definition. To do this, you use the <binding.ws> element @uri attribute to specify the endpoint URL where the service is hosted. This scenario is problematic because it forces the runtime environment to generate a WSDL port for the client which might result in subtle mismatches between the WSDL generated for the client side and the actual WSDL port description of the deployed web service.

You can avoid these potential problems by ensuring that client package references the original WSDL obtained from a web service provider. If you use the shortcut of omitting a client-side reference to the WSDL, be sure to do so only in the case when you are sure the WSDL port that is generated for the client is identical to the WSDL port of the deployed service because the service port is generated using the same algorithm.

What to do next

Deploy your composite that has the SCA web services binding service or reference. If the composite uses a bidirectional interface as an SCA service interface and a NullPointerException results when you add your SCA module or application to a business-level application (for example, using the wsadmin AdminTask.addCompUnit command), you might need to add the SCA @Callback annotation to the forward Java interface.

A NullPointerException can occur whether you are using a top-down development style (starting from WSDL or XSD) or a bottom-up style (starting from Java). With the top-down style, a composite definition typically includes a bidirectional interface definition such as the following:

<interface.wsdl interface="http://forward.my/intf#wsdl.interface(ForwardIntf)"
    callbackInterface="http://callback.my/intf#wsdl.interface(CallbackIntf)"/> 

With the bottom-up style, a composite definition typically includes a bidirectional interface definition such as the following:

<interface.java interface="my.forward.intf.ForwardIntf"
    callbackInterface="my.callback.intf.CallbackIntf"/> 

The NullPointerException can occur if the forward Java interface is not annotated with @Callback, or more specifically @org.osoa.sca.annotations.Callback. In the top-down example, the forward Java interface is the class generated from portType, http://forward.my/intf/ForwardIntf using the wsimport tool or my.forward.intf.ForwardIntf if the default options are used. In the bottom-up example, the forward Java interface is the class my.forward.intf.ForwardIntf.

To fix the NullPointerException problem, add the @Callback annotation to the forward Java interface and recompile. The @Callback annotation is a class-level annotation with a single argument, the callback interface Class object; for example:

...
import org.osoa.sca.annotations.Callback
@Callback(my.callback.intf.CallbackIntf.class)
public interface ForwardIntf  {
...

If you are using the recommended top-down development style, the forward Java interface is a generated class. It is generated from the WSDL portType using the wsimport tool. Use the -s or -keep option so that wsimport generates the Java source files, and then add the @Callback annotation manually to the generated class and recompile.

Related

Configure web service binding custom endpoints to support a proxy server
Configure the SCA web services binding to transport SOAP messages over JMS
Web services policy sets
SCA components
SCA composites
SCA domain
Specify bindings in an SCA environment
Resolve SCA references
Develop SCA services with existing Java code
Manage policies in a policy set
Deploy and administering business-level applications
Develop SCA service clients
Manage policy sets
Export WSDL and XSD documents using scripting
wsimport command for JAX-WS applications

Related

Service Component Architecture specifications and APIs

+

Search Tips   |   Advanced Search