9.3 Stateless Session Bean Web Service Example

This section describes an example application that illustrates how to put into practice the techniques just presented. This Web service example application builds on the Benefits Enrollment application discussed in previous chapters.

Star Enterprise decides to develop a more dynamic integration between its benefits enrollment system and the health care providers' medical and dental insurance plan systems. This enhanced integration is intended to dynamically and automatically update insurance plan information in the benefits enrollment system and will free Star Enterprise personnel from the time-consuming task of manually updating data about doctors and plan costs whenever an insurance provider changes its plan. The dynamic integration envisioned by Star Enterprise requires real-time communication between Star Enterprise's enrollment system and the insurance providers' systems. Thus, this is a good scenario for use of a Web service.

Star Enterprise works with Premium Health to develop a Web service for its insurance plan administration. Premium Health provides insurance plans to the employees of Star Enterprise, which hosts the Web service. Plan administrators at Premium Health can modify plan information dynamically by "pushing" updates to Star Enterprise whenever a plan changes.

The insurance plan administration Web service consists of the InsurancePlanAdminEJB stateless session bean. This bean implements the business logic of the Web service.

9.3.1 InsurancePlanAdminEJB Stateless Session Bean

The InsurancePlanAdminEJB stateless session bean contains business methods that allow plan administrators to obtain existing plan information, add doctors, and modify plan costs. The bean consists of the InsurancePlanAdmin service endpoint interface and the InsurancePlanAdminBean class. Note that there is no home interface and no remote interface.

InsurancePlanAdmin Service Interface

The InsurancePlanAdminEJB stateless session bean provides the InsurancePlanAdmin Web service interface, which defines the bean's functionality. InsurancePlanAdmin is a JAX-RPC-compliant service endpoint interface. Code Example 9.1 shows the code for the interface:

Code Example 9.1 The InsurancePlanAdmin Service Endpoint Interface

 public interface InsurancePlanAdmin extends Remote {     void createInsurancePlan(String planId, String planName,            int planType, double coverageFactor, double ageFactor,            double smokerCost) throws RemoteException;     PlanInfo getPlanInfo(String planId) throws RemoteException;     void addDoctors(String planId, DoctorInfo[] doctors)            throws RemoteException;     void removeDoctors(String planId, DoctorInfo[] doctors)            throws RemoteException;     DoctorInfo[] getAllDoctors(String planId)            throws RemoteException;     void setSmokerCost(String planId, double cost)            throws RemoteException;     void setCoverageFactor(String planId, double s)            throws RemoteException;     void setAgeFactor(String planId, double s)            throws RemoteException; } 

The InsurancePlanAdmin interface follows the rules for a JAX-RPC service endpoint interface. Its methods' types are either Java primitive types or JAX-RPC value types. The two value types, PlanInfo and DoctorInfo, contain information about insurance plans and doctors (Code Example 9.2):

Code Example 9.2 The DoctorInfo and PlanInfo Classes

 public class DoctorInfo implements java.io.Serializable {     public String firstName;     public String lastName;     public String specialty;     public String[] hospitals;     public int practiceSince; } public class PlanInfo implements java.io.Serializable {     public String planId;     public String planName;     public int planType;     public double coverageFactor;     public double ageFactor;     public double smokerCost; } 

The DoctorInfo and PlanInfo classes follow the JAX-RPC rules for value types. All their fields are public, and the types of the fields are Java primitives. An alternative way of designing JAX-RPC value types is to use the JavaBeans design pattern, whereby each private field foo needs to have a corresponding getFoo and setFoo method. When a value class follows the JAX-RPC rules, it can be mapped to XML schema types. In addition, instances of these classes can be serialized to XML elements in the SOAP messages that carry requests and responses between Web services.

InsurancePlanAdminBean Class

The InsurancePlanAdminEJB's business methods are implemented in the InsurancePlanAdminBean class. In addition to the bean's business methods, this class implements the usual set of methods required for a stateless session bean. See Code Example A.13 on page 420 for the complete code listing for this class.

The business methods of the InsurancePlanAdminBean class invoke methods on the PlanEJB bean through the PlanHome and Plan interfaces. (Section 8.2.5, PlanEJB Entity Bean, on page 266 describes the PlanEJB bean and its interfaces.) InsurancePlanAdminBean acts as a local client of PlanEJB. Code Example 9.3 shows the business method addDoctors, which accesses the PlanEJB bean:

Code Example 9.3 The addDoctors Method to Access PlanEJB

 public void addDoctors(String planId, DoctorInfo[] doctors) {     try {        Plan plan = planHome.findByPrimaryKey(planId);        for ( int i=0; i<doctors.length; i++ ) {            // find or create a Doctor bean            DoctorPkey pkey =               new DoctorPkey(doctors[i].firstName,                      doctors[i].lastName);            Doctor doctor;            try {                doctor = doctorHome.findByPrimaryKey(pkey);            } catch ( FinderException fe ) {                doctor = doctorHome.create(doctors[i].firstName,                       doctors[i].lastName,                       doctors[i].specialty,                       doctors[i].hospitals,                       doctors[i].practiceSince);            }            plan.addDoctor(doctor);         }     } catch ( Exception ex ) {         throw new EJBException(ex);     } } 

The state of the various insurance plan beans is stored in BenefitsDatabase. (See Section 8.2.9, The Benefits Database, on page 284.) Over the course of time, operations invoked by plan administrators from the insurance companies result in changes to the content of the insurance plans. These changes are saved as part of the persistent state of PlanEJB instances in BenefitsDatabase. Thus, the InsurancePlanAdminEJB bean and the InsurancePlanAdmin Web service provided by Star Enterprise serve to expose selected portions of its internal enterprise applications and data to Star Enterprise's partner insurance companies.

9.3.2 Developing and Packaging the Web Service

Star Enterprise followed the first approach described in Section 9.2.1, Developing a New Web Service, for developing the InsurancePlanAdmin Web service; Star Enterprise started with the Java service endpoint interface for the Web service and used a JAX-RPC-compliant tool to generate the WSDL for the Web service. (See Code Example A.14 on page 424 for a listing of the InsurancePlanAdminWeb WSDL document.) This WSDL document can be used as the basis for connecting to the InsurancePlanAdmin Web service from any insurance provider's enterprise. The important point to note here is that insurance providers may use any software technology, including non-Java infrastructures, to access the InsurancePlanAdmin Web service once they have the WSDL description of the Web service.

After developing the InsurancePlanAdmin interface and InsurancePlanAdminBean stateless session bean class, Star Enterprise packages them into an ejb-jar file, insurance-admin.jar, which contains all classes referenced from the bean class and interface, such as the DoctorInfo and PlanInfo classes. It also contains the WSDL file, Web services deployment descriptor, and XML-Java mapping file. The stubs, skeletons, and serialization/deserialization code for translating SOAP requests into invocations on the bean class are not packaged with the ejb-jar file. Instead, they are generated by the JAX-RPC-compliant tools provided by the container at deployment time.

The insurance-admin.jar archive is then packaged along with the other Benefits Enrollment application components into the benefits.ear J2EE application archive. Packaging the application components into the same J2EE application archive is necessary because the InsurancePlanAdmin bean accesses PlanEJB through its local interfaces. Because they rely on local interfaces, they both need to be in the same application.