The <definitions> Element

The <definitions> element allows you to specify global declarations of namespaces that are visible through the WSDL document. It acts as a container for service description. Listing 6-1 shows an example <definitions> element that defines a target namespace and other namespaces that are referred to by a credit service.

Listing 6-1.  The <definitions> Element in CreditService.wsdl

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definitions targetNamespace="http://www.apress.com/ejb3/credit" ←
name="CreditService" xmlns:tns="http://www.apress.com/ejb3/credit" ←
xmlns:xsd="http://www.w3.org/2001/XMLSchema" ←
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"←
xmlns=http://schemas.xmlsoap.org/wsdl//>

The <types> Element

The <types> element is used to define the data types for the <message> element. XML schema definitions (XSDs) are most commonly used to specify the data types. Listing 6-2 shows an example <types> element that provides the schema location for the credit service.

Listing 6-2.  The <types> Element in CreditService.wsdl

  <types>
    <xsd:schema>
<xsd:import namespace="http://www.apress.com/ejb3/credit"←
    schemaLocation="CreditServiceBeanService_schema1.xsd"/>
    </xsd:schema>
  </types>

The <message> Element

The <message> element is used to define the format of data exchanged between a Web service consumer and a Web service provider. Listing 6-3 shows an example of two <message> elements: CreditCheck and CreditCheckResponse.

Listing 6-3.  The <message> Element in CreditService.wsdl

  <message name="CreditCheck">
    <part name="parameters" element="tns:CreditCheck"/>
  </message>
  <message name="CreditCheckResponse">
    <part name="parameters" element="tns:CreditCheckResponse"/>
  </message>

The <portType> Element

The <portType> element is used to specify the operations of the Web service. Listing 6-4 shows the <portType> element for the credit service with the CreditCheck operation.

Listing 6-4.  The <portType> Element in CreditService.wsdl

<portType name="CreditCheckEndpointBean">
  <operation name="CreditCheck">
    <input message="tns:CreditCheck"/>
    <output message="tns:CreditCheckResponse"/>
  </operation>
</portType>

The <binding> Element

The <binding> element describes the protocol, data format, and security for a <portType> element. The standard bindings are HTTP or SOAP; or you can create one of your own.

The “bindings” part of the WSDL specification is flexible—it allows you to provide your own bindings environment instead of the default SOAP-over-HTTP model. This flexibility of the specification has been widely exploited by WSIF (Web Services Invocation Framework), which is an Apache open source project. WSIF provides a nice way to expose existing Java, EJB, JMS (Java Message Service), and JCA-based components as Web services with native bindings, which provide better performance and that support native transactions. Listing 6-5 shows the <binding> element for the credit service, using SOAP-over-HTTP.

Listing 6-5.  The <binding> Element in CreditService.wsdl

  <binding name="CreditCheckEndpointBeanPortBinding"←
type="tns:CreditCheckEndpointBean"> ←
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" ←
style="document"/>
    <operation name="CreditCheck">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

The service implementation definition part of the WSDL document identifies a Web service. It contains the following elements:

<service>
<port>

The <service> Element

The <service> element contains a collection of <port> elements where each port is associated with an endpoint (a network address location or URL). Listing 6-6 shows an example of a <service> element for the credit service.

Listing 6-6.  The <service> Element in CreditService.wsdl

  <service name="CreditService">
    <port name="CreditCheckEndpointBeanPort" ←
binding="tns:CreditCheckEndpointBeanPortBinding">
      <soap:address location="http://localhost:64082/CreditService/CreditCheckEndpointBean"/>
    </port>
  </service>

Listing 6-7 shows the complete WSDL document for the credit service that we are going to develop later in the chapter.

Listing 6-7.  The Complete WSDL Document for CreditService.wsdl

  <?xml version='1.0' encoding='UTF-8'?>
  <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.apress.com/ejb/credit" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://www.apress.com/ejb/credit" name="CreditService">
    <types>
    <xsd:schema>
      <xsd:import namespace="http://www.apress.com/ejb3/credit"←
        schemaLocation="CreditServiceBeanService_schema1.xsd"/>
    </xsd:schema>
    </types>
    <message name="CreditCheck">
      <part name="parameters" element="tns:CreditCheck"/>
    </message>
    <message name="CreditCheckResponse">
      <part name="parameters" element="tns:CreditCheckResponse"/>
    </message>
    <portType name="CreditCheckEndpointBean">
      <operation name="CreditCheck">
        <input message="tns:CreditCheck"/>
        <output message="tns:CreditCheckResponse"/>
      </operation>
    </portType>
    <binding name="CreditCheckEndpointBeanPortBinding" type="tns:CreditCheckEndpointBean">
      <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
      <operation name="CreditCheck">
        <soap:operation soapAction=""/>
        <input>
          <soap:body use="literal"/>
        </input>
        <output>
          <soap:body use="literal"/>
        </output>
      </operation>
    </binding>
    <service name="CreditService">
      <port name="CreditCheckEndpointBeanPort" binding="tns:CreditCheckEndpointBeanPortBinding">
        <soap:address location="http://localhost:64082/CreditService/CreditCheckEndpointBean"/>
      </port>
    </service>
  </definitions>

RESTful Web Services

RESTful Web services are services that are built based on the above-mentioned REST principles. RESTful Web services use HTTP and implement operations that map to common HTTP methods as shown in Table 6-1.

Listing 6-8 shows a simple RESTful Web service named CreditCheck that takes a credit card number as an input and returns true or false based on its validity. For simplicity sake, our method always returns true.

Listing 6-8.  CreditCheck.java

package com.apress.ejb.chapter06.services;
import javax.ws.rs.Consumes;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

@Path("creditCheck")
public class CreditCheck {
    @PUT
    @Consumes("text/plain")
    @Produces("text/plain")
    @Path("isValid")
    public boolean isValid(@PathParam("cardNumber")String ccNumber) {
        return true;
    }
}

Users can invoke the isValid method in CreditCheck as follows, and ccNumber will be assigned the value 12345.

<host>:<port>/<resource>/creditCheck/isValid/12345">http://<host>:<port>/<resource>/creditCheck/isValid/12345

RESTful vs. SOAP-Based Web Services

Table 6-2 lists the important difference and similarities between RESTful Web service and SOAP-based Web service.

Creating a Bean Class

A stateless session bean class is any standard Java class that has a class-level annotation of @Stateless. Starting with version 3, the EJB specification doesn’t mandate the requirement of SEIs. Providing an SEI along with a bean class is optional. In the use case in which the bean class will be published as a Web service without any service endpoint interface, the bean class will have the additional class-level annotation @WebService (JSR 181). The @WebService annotation is in the javax.jws package, and it marks the bean class as an implementation for a SOAP-based Web service.

The @WebService annotation takes the parameters described in Table 6-3.

To illustrate a stateless session bean that gets published as a Web service, we will create a CreditServiceEndpointBean that will be published as CreditService.

In Listing 6-9, we have a Java class, CreditCheckEndpointBean, which has two class-level annotations: @Stateless and @WebService. The @Stateless annotation provides an additional parameter to mark the bean as CreditCheckEndpointBean. If the same class is exposed to remote or local clients, those clients will access the stateless session bean with that name. The @WebService annotation provides two additional parameters: one to mark the service name as CreditService and the other to specify the target namespace (instead of using the default Java package structure).

Listing 6-9.  CreditCheckEndpointBean.java

package com.apress.ejb.chapter06.services;
import javax.ejb.Stateless;
import javax.jws.WebMethod;
import javax.jws.WebService;

@Stateless(name = "CreditCheckEndpointBean")
@WebService(serviceName = "CreditService", targetNamespace = "http://www.apress.com/ejb/credit")
public class CreditCheckEndpointBean  {
    public CreditCheckEndpointBean() {
    }

}

The @WebMethod annotation defined in JSR 181 allows you to customize the method that is exposed as a Web service operation. If no @WebMethod annotations are specified in the bean class that has the @WebService annotation, then all public methods are exposed as Web service operations.

The @WebMethod annotation takes the parameters described in Table 6-4.

In Listing 6-10, we have added the following method into the CreditCheckEndpointBean class, which will be exposed as a Web service operation. The operation name is customized as CreditCheck using @WebMethod parameters. The method takes a java.lang.String parameter (which is the credit card number) and returns a java.lang.boolean value of true or false, depending on whether the credit card is valid. For simplicity’s sake, we will always return true.

Listing 6-10.  The validateCC Method in CreditCheckEndpointBean.java

@WebMethod(operationName="CreditCheck" )
public boolean validateCC(String cc){
return true;
}

Web Service Endpoint Interface

JAX-WS doesn’t mandate the requirement of an SEI to implement a Web service endpoint. You can use the annotations provided in JSR 181 to mark the bean class as a Web service and one or more business methods as Web service operations. In the use case in which an SEI is defined for a stateless session bean, the following should be observed:

• The SEI must have a javax.jws.WebService annotation.
• One or more methods can have a javax.jws.WebMethod annotation.
• All method parameters and return types should be compatible with the JAXB XML schema mapping definition.
• Arguments and return types of methods must be valid JAX-RPC value types, which include Java primitives (int, long, and so on), Java classes (String, Date, and so forth), Java Beans, and arrays.
• throws clauses must include a java.rmi.RemoteException in addition to any other application exceptions.

In our examples, we are adding annotations to the bean class itself, as shown in Listings 6-9 and 6-10.

Listing 6-11 illustrates a service endpoint interface for the use case in which an SEI is provided, and Listing 6-12 shows the CreditCheckEndpointBean class implementing the SEI.

Listing 6-11.  A Service Endpoint Interface for the Use Case

@WebService(serviceName="CreditService",targetNamespace="http://www.apress.com/ejb/credit")
public interface CreditCheckEndpoint {

    @WebMethod(operationName="CreditCheck")
      public boolean validateCC(String cc);
}

Listing 6-12.  The CreditCheckEndpointBean Class Implementing the SEI

@Stateless
public class CreditCheckEndpointBean implements CreditCheckEndpoint {
    public CreditCheckEndpointBean() {
    }
    //implementation goes here
}

Generating Web Service Proxy Classes

We will start by generating stubs for the CreditService WSDL document using the Web Service Client wizard provided by the NetBeans IDE. Invoke the Web Service Client wizard from the context menu of Chapter06-WebServiceSamples-ejb node, as shown in Figure 6-12.

In the Web Service Client wizard, select the WSDL URL radio button, and enter the WSDL File URL that you had bookmarked in the earlier section (see Figure 6-10). We also need to specify the package where the client Java artifacts will be generated. We will generate these artifacts in the com.apress.ejb.chapter06.services.client package. Enter these details, as shown in Figure 6-13, and finish the wizard.

Once the stubs are generated and compiled, we can see artifacts under Generated Sources (jax-ws) node.

Once the stubs are generated and compiled, the next step is to create a client that will consume CreditService.

The JAX-WS specification provides the @WebServiceRef annotations that can be used to declare a reference to a Web service, which in our case is CreditService.

The @WebServiceRef annotation can take the parameters described in Table 6-5.

Developing a Web Service Client Program

The @WebServiceRef annotation either provides a reference to the SEI generated by the container, or a reference to the SEI provided by the application developer. Listing 6-13 shows a servlet class that is going to be a Web service client. In this servlet class, CreditServiceClient, we are using dependency injection to inject the credit service that we have deployed earlier as a Web service. The @WebServiceRef annotation is used to inject the CreditService that has been generated as the proxy class. Once we have the injected the available resource, we use that proxy class to get the Web service port using the getCreditCheckEndpointBeanPort() method. After successfully getting the port, we can invoke the operations that are available on the port. In our case, we have defined only one operation, creditCheck. You can see that this is being invoked with a credit card number of 12345678.

Listing 6-13.  CreditServiceClient.java

package com.apress.ejb.chapter06.client;
import com.apress.ejb.chapter06.services.client.CreditCheckEndpointBean;
import com.apress.ejb.chapter06.services.client.CreditService;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.WebServiceRef;

@WebServlet(name = "CreditServiceClient", urlPatterns = {"/CreditServiceClient"})
public class CreditServiceClient extends HttpServlet {
      @WebServiceRef(wsdlLocation = "http://localhost:64082/CreditService/CreditCheckEndpointBean?WSDL")
      CreditService service;
    protected void processRequest(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        response.setContentType("text/html;charset=UTF-8");
        PrintWriter out = response.getWriter();
        try {
            out.println("<html>");
            out.println("<head>");
            out.println("<title>Servlet CreditServiceClient</title>");
            out.println("</head>");
            out.println("<body>");
            CreditCheckEndpointBean creditService = service.getCreditCheckEndpointBeanPort();
            out.println("<h1>Credit Check returned: " + creditService.creditCheck("12345678") + "</h1>");
            out.println("</body>");
            out.println("</html>");
        } finally {
            out.close();
        }
    }
    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        processRequest(request, response);
    }

    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        processRequest(request, response);
    }

    @Override
    public String getServletInfo() {
        return "Short description";
    }
}

Compiling the Client Class

Invoke the context menu on the Chapter06-WebServiceSamples-war node, and build the client by selecting the Clean and Build menu option, as shown in Figure 6-15.

Running the Web Service Client

Once we have compiled the client, we need to set CreditServiceClient as the run target. Open the Project Properties dialog by invoking the context menu on the Chapter06-WebServiceSamples node, and select the Properties menu option. Set CreditServiceClient as the run target, as shown in Figure 6-16.

To run the client servlet, invoke the context menu on the Chapter06-WebServiceSamples node, and select the Run menu option, as shown in Figure 6-17.

Once the CreditServiceClient runs successfully, NetBeans will open your default browser and execute the selected servlet. Here is the output from CreditServiceClient servlet.