Develop SCA services from existing WSDL files

Develop SCA services from existing WSDL files

We can develop a Service Component Architecture (SCA) service implementation when starting with an existing WSDL file.

Locate the WSDL file that defines the SCA service to implement. We can develop a WSDL file or obtain one from an existing SCA service. The WSDL file describes the service interface as a WSDL portType and includes XSD schema definitions of the business data.
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.

There are two ways to develop an SCA service implementation:

Top-down development starting with an existing Web Services Description Language (WSDL)

Bottom-up development starting from existing Java code that uses JAXB data types

The top-down development approach takes advantage of the interoperable XML-based WSDL, and XSD interface and data definitions.
This task describes the steps when using the top-down development approach to develop an SCA service implementation in Java when starting from a WSDL interface and XSD data definitions.
Best practice: It is a best practice to use the top-down methodology to develop SCA service implementations because this approach uses the capabilities of the XML interface description and provides greater ease in interoperability across platforms, bindings, and programming languages. bprac
Use the wsimport command-line tool to generate the Java representations of the business service interfaces and the business data when an existing WSDL file describes the wanted SCA service interface as a WSDL portType, along with XSD schema definitions of the business data. The wsimport tool generates Java classes that we can use to write a Java implementation that reflects your business logic. The result is a Plain Old Java Object (POJO) implementation of the generated interface using the generated JAXB data types. By adding the @Service annotation to the Java implementation, the annotation defines the Java implementation as an SCA service implementation.
The generated annotated Java classes that correspond to your business data contain all the necessary information that the JAXB runtime environment requires to build and parse the XML for marshaling and unmarshaling. In other words, the data programming model is limited to object instantiation and the use of getter and setter methods, and we do not need to write code to convert the data between the XML wire format and the Java application.
Supported configurations: The product uses XML marshaling as defined by JAXB to marshal and unmarshal data across a remotable interface. If we start with a remotable Java interface for the implementation rather than starting with a WSDL portType interface, be careful when selecting the input and output Java data types and ensure that you understand which data is preserved across JAXB marshaling and unmarshalling. However, when authoring an implementation on a local interface, we can use any Java type because local interfaces use pass-by-reference semantics, which implies no data is copied..
Supported configurations: The product does not support using a WSDL file when the Java mapping requires holder classes. The product uses the JAX-WS specification to define the mapping between WSDL files and Java, including the mapping between a WSDL portType object and a Java interface. When we have WSDL portType objects with operations that use in-out parameters or operations that use multiple output parameters, the JAX-WS specification uses instances of the javax.xml.ws.Holder class in the mapping of the WSDL portType object to a Java interface. When using the product, do not use a WSDL file when the Java mapping requires holder classes. Instead, use a WSDL file that does not map to holder classes.
When you develop an SCA service when starting from an existing WSDL file, the interface is considered a remotable interface. The remotable interface uses pass-by-value semantics, which implies the data is copied.
We can use and deploy the resulting Java implementation as an SCA component defined in a composite definition. The composite definition defines SCA artifacts, such as service references, imports, and exports. The component is defined in terms of development artifacts such as the WSDL, the Java implementation, and bindings defined during deployment.
The JAXB APIs require that you register Java class types to marshal or unmarshall with a JAXBContext class. The product runtime environment registers these Java class types for you by introspecting the Java interface. When this introspection occurs, be careful of possible problems when polymorphism (inheritance) is used. When an interface is defined in terms of a base superclass type, and to pass argument instances of a derived subclass type at run time, the subclasses are not known to the JAXBContext class by simply introspecting the interface parameter types.
In JAXB, we can use the javax.xml.bind.annotation.XmlSeeAlso annotation to solve this problem with polymorphism. Place the @XmlSeeAlso annotation on the generated Java interface that is generated with the @WebService annotation, to refer to additional JAXB derived subclass classes added to the JAXBContext class along with those classes introspected from the interface parameters.

Use the wsimport command-line tool to develop SCA Java representations of the business service interfaces and the business data.
The wsimport tool processes a WSDL file and generates Java classes and the JAXB data types used to create the SCA service.
It is important to include all generated classes within the application archive, including the classes that you might not directly reference in the Java implementation. Even if we have simple interfaces that pass simple parameter types like String and Integer, or where no JAXB data types are necessary, be sure to include all classes, including indirect references, in this code generation step.

Run the wsimport command to generate the artifacts.

The wsimport tool is located in the app_server_root/bin/ directory.

app_server_root\bin\wsimport.bat -keep wsdl_URL

app_server_root/bin/wsimport.sh -keep wsdl_URL
(iseries)
app_server_root/bin/wsimport -keep wsdl_URL

The -keep option specifies to keep the generated Java source files and the compiled class files.

Locate the Java interface that directly corresponds to the WSDL portType from the generated artifacts. The interface is generated with an @WebService annotation, and it is an interface and not a class file.

Complete the implementation of the SCA service. Write a Java implementation of the generated Java interface that reflects the business logic. The Java implementation is a Plain Old Java Object (POJO) implementation of the generated interface using the generated JAXB data types. This implementation is annotated based on the SCA Java component implementation programming model.

Annotate the Java implementation. Add the @Service annotation to the Java implementation to specify this implementation is an SCA service. When you complete this step, we have created an SCA component implementation.

Define a component within a composite definition using this component implementation. In the definition of your composite, define a component that refers to the original WSDL portType interface and the SCA implementation.

Under the <component> element, create a <implementation.java> child element that refers to the class name of the POJO component implementation.

Under the <component> element, create a <service> child element.

Under the <service> element, create a <interface.wsdl ..> element that refers to the WSDL portType. The @name attribute of the <service> element must match the unqualified class name of the Java interface.

You now have a component with a well-defined component name and service name with a well-defined interface.
In addition to these aspects of the component definition described by these development procedures, there are other aspects of defining a component. These aspects include adding bindings, configuring property values, defining intents, attaching policy sets, and resolving references. We can create multiple components using this same implementation, but all component definitions are the same with respect to the <implementation.java>, <interface.wsdl> and <service> elements described in this step.

Deploy the SCA service by creating the SCA business level application from a deployable composite.
In the previous step, you defined a component providing the SCA service within a composite definition. This composite is either a deployable composite, or one used recursively as a composite implementation of a component in a higher-level composite. To learn how to deploy the SCA service, read about deploying and administering business-level applications.

Results

You have created an SCA implementation by starting with an existing WSDL file.

Example

The following example illustrates using an existing WSDL interface to generate a Java interface used to create a Java implementation that is an SCA service.
Copy the following sample account.wsdl WSDL file to a temporary directory.
<?xml version="1.0" encoding="UTF-8"?> 

<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
     xmlns:account="http://www.myaccount.com/account"
     targetNamespace="http://www.myaccount.com/account"
     name="AccountService">

      <wsdl:types>
         <schema targetNamespace="http://www.myaccount.com/account"
             xmlns="http://www.w3.org/2001/XMLSchema"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:account="http://www.myaccount.com/account">

               <element name="computeAccountAverage">
                 <complexType>
                     <sequence>
                         <element name="account" type="account:Account" />
                         <element name="days" type="xsd:int" />
                     </sequence>
                 </complexType>
             </element>
             <element name="computeAccountAverageResponse">
                 <complexType>
                     <sequence>
                         <element name="return" type="xsd:float" />
                     </sequence>
                 </complexType>
             </element>

             <complexType name="Account">
                 <attribute name="accountNumber" type="xsd:int" />
                 <attribute name="accountID" type="xsd:string" />
                 <attribute name="accountType" type="xsd:string" />
                 <attribute name="balance" type="xsd:float" />
             </complexType>

          </schema>
     </wsdl:types>

     <wsdl:message name="computeAccountAverageRequest">
         <wsdl:part element="account:computeAccountAverage"
             name="parameters" />
     </wsdl:message>

     <wsdl:message name="computeAccountAverageResponse">
         <wsdl:part element="account:computeAccountAverageResponse"
             name="parameters" />
     </wsdl:message>

     <wsdl:portType name="AccountService">
         <wsdl:operation name="computeAccountAverage">
             <wsdl:input message="account:computeAccountAverageRequest" name="accountReq"/>
             <wsdl:output message="account:computeAccountAverageResponse" name="accountResp"/>
         </wsdl:operation>
     </wsdl:portType>

     <wsdl:binding name="AccountServiceSOAP" type="account:AccountService">
         <soap:binding style="document"
             transport="http://schemas.xmlsoap.org/soap/http" />
         <wsdl:operation name="computeAccountAverage"> 
            <soap:operation
                 soapAction="computeAccountAverage" />
             <wsdl:input name="accountReq"> 
                <soap:body use="literal" />
             </wsdl:input>
             <wsdl:output name="accountResp">
                 <soap:body use="literal" />
             </wsdl:output>
         </wsdl:operation>

      </wsdl:binding>

     <wsdl:service name="AccountWSDLService">
         <wsdl:port binding="account:AccountServiceSOAP"
             name="AccountServicePort">
             <soap:address location=""/>
         </wsdl:port>
     </wsdl:service>
</wsdl:definitions>
Run the wsimport command from the app_server_root/bin/ directory.

app_server_root\bin\wsimport.bat -keep -verbose account.wsdl

Run the wsimport command,
app_server_root/bin/wsimport.sh -keep -verbose account.wsdl

(iseries)
app_server_root/bin/wsimport -keep -verbose account.wsdl
After generating the template files using the wsimport command, the following Java files are generated:
com/myaccount/account/Account.java
com/myaccount/account/AccountService.java
com/myaccount/account/AccountWSDLService.java
com/myaccount/account/ComputeAccountAverage.java
com/myaccount/account/ComputeAccountAverageResponse.java
com/myaccount/account/ObjectFactory.java
com/myaccount/account/package-info.java
Identify the generated Java interface from the generated classes.
//
// Generated By:JAX-WS RI IBM 2.1.1 in JDK 6 (JAXB RI IBM JAXB 2.1.3 in JDK 1.6)
//
package com.myaccount.account;
...
@WebService(name = "AccountService", targetNamespace = "http://www.myaccount.com/account")

public interface AccountService {
    /**
     *
     * @param days
     * @param account
     * @return
     *     returns float
     */
    @WebMethod(action = "computeAccountAverage")
    @WebResult(targetNamespace = "")
    @RequestWrapper(localName = "computeAccountAverage", 
                    targetNamespace = "http://www.myaccount.com/account", 
                    className = "com.myaccount.account.ComputeAccountAverage")

    @ResponseWrapper(localName = "computeAccountAverageResponse", 
                     targetNamespace = "http://www.myaccount.com/account", 
                     className = "com.myaccount.account.ComputeAccountAverageResponse")
    public float computeAccountAverage(
        @WebParam(name = "account", targetNamespace = "")
        Account account, @WebParam(name = "days", targetNamespace = "")
        int days);

}
This code example is a Java interface, not merely a Java class. The @WebService annotation is present in this Java interface. It is important to know that this example is not the same as the generated @WebServiceClient class, com.myaccount.account.AccountWSDLService, which is not an interface and is not needed in the SCA application.
Complete the implementation of the SCA service by writing a Java implementation of this generated Java interface. Be sure to add the SCA @Service annotation to the implementation.
package com.myaccount.account;
import org.osoa.sca.annotations.Service;
@Service(AccountService.class) 
public class AccountServiceImpl implements AccountService
    public float computeAccountAverage( Account account, int days) {

        // Write the business logic here.  Account is a 
        // generated JAXB type and so use the JAXB programming model. 
        // For example, object instantation is performed using  
        // the ObjectFactory.createAccount()) method. 
    }
}
By completing this step, we have completed a component implementation. Not only is this component implementation a Java implementation of a Java interface, but the @Service annotation signifies that this is a Java component implementation of an SCA service interface. The implementation class itself does not need all the JAX-WS or JAXB annotations. The runtime environment loads the appropriate annotations from the generated classes that the implementation refers to.
Create a component using the component implementation. We create a component definition in a composite that references the original WSDL portType interface and the SCA implementation. In SCA, a component is a configured instance of a component implementation. There are other aspects of defining a component that are not shown here such as configuring bindings, configuring property values, defining intents, attaching policy sets, and resolving references. Shown here are the aspects of component creation that are common for all component definitions using the implementation developed in this example. This example also includes bindings we can modify or omit for other components using this component implementation.
<?xml version="1.0" encoding="UTF-8"?>

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
     targetNamespace="http://account.customer"
         name="accountComposite">
     <component name="BankingComponent">
         <implementation.java class="com.myaccount.account.AccountServiceImpl"/>

         

         <service name="AccountService">

              

             <interface.wsdl interface="http://www.myaccount.com/account#wsdl.interface(AccountService)" />
             <binding.ws/>

  

          </service>
     </component>
</composite>
After the component is defined as part of a deployable composite, either directly or recursively through use of one or more layers of components with composite implementation, you are ready to deploy the SCA service by creating an SCA business level application.
Related concepts

SCA in WebSphere Application Server: Overview
SCA components
SCA composites
SCA domain

Related tasks

Develop SCA services with existing Java code
Deploy and administering business-level applications
Develop SCA service clients
Specify bindings in an SCA environment
Manage policy sets using the administrative console
wsimport command for JAX-WS applications

Considerations for developing SCA applications using EJB bindings
Service Component Architecture specifications and APIs