Creating a JAX-WS Web Service and Clients with EJB 3.1 Singleton Bean

Overview

    Purpose

    This tutorial covers  creating an EJB 3.1  singleton session bean and exposing the singleton session bean  as a JAX-WS web service and  consuming the web service using different types of web service clients.

    Time to Complete

    Approximately 45 minutes.

    Introduction

    This example demonstrates the use of the EJB 3.1 singleton session bean and exposing the singleton session bean to create a JAX-WS web service and also illustrates creating web service clients to consume the web service. EJB 3.1 specification allows EJB's to be developed in a web application.

    Java EE 6 web services technologies include Java API for XML Web Services (JAX-WS) and Java API for RESTful Web Services (JAX-RS). JAX-WS simplifies the task of developing web services using Java technology. 

    Singleton session bean:

    Singleton session beans were introduced as part of the EJB 3.1 specification. They are instantiated only once per application and exist for the life cycle of the application. They support concurrent access. Singleton session beans provide shared data access to clients and components within an application. It maintains its state between client invocations but that state is not required to survive container shutdown or crash. Singleton session beans are defined using the  @Singleton annotation. In cases where the container is distributed over many virtual machines, each application will have one bean instance of the singleton for each JVM.

    Web Service Clients:

    Stateless session beans and Singleton session beans may have web service clients. A web service client accesses a session bean through the web service client view. The web service client view is described by the WSDL document for the web service that the bean implements. WSDL is an XML format for describing a web service as a set of endpoints operating on messages. The abstract description of the service is bound to an XML based protocol (SOAP) and underlying transport (HTTP or HTTPS) by means of which the messages are conveyed between client and server.

    The web service client view of an enterprise bean is location independent and remotable. Web service clients may be Java clients or clients not written in the Java programming language. A web service client that is a Java client accesses the web service by means of the JAX-WS or JAX-RPC client APIs.

    In this tutorial, you will create a Java EE 6 Web Application and add the following components to it - a singleton session bean, CounterBean and implement a getHits() method in it. The singleton session bean provides a central counter service.  Next you will expose the singleton session bean as  a JAX-WS web service called CounterService. You will deploy the web service to GlassFish server and test the web service  You will develop two clients to consume this web service - a Java class in a  Java SE application  and a jsp page in a web application. 

    Hardware and Software Requirements

    The following is a list of hardware and software requirements:

    • Download and install Java JDK 7 from this link.
    • Download and install NetBeans 7.1.2 with Java EE which includes GlassFish 3.1.2 (Java EE download bundle) from this link. During installation, be sure to check the box to install GlassFish. JUnit is an optional installation and not required for this tutorial.

    Prerequisites

    Before starting this tutorial, you should:

    •  Have the software installed as listed under Hardware and Software Requirements section.
    •  Ensure NetBeans is running.

Creating a Web Application

    To create a Java EE  Web Application, perform the following steps in the NetBeans IDE.


    Create a new Web Application.

    Select File->New Project from the NetBeans menu.

    Select the Java Web category and a project type of  Web Application.

    Click  Next.

    Enter project name as EJBWebServicesDemo and click Next.

    Verify the following :

    GlassFish Server 3.1.2  is selected as the server.

    Java EE 6 Web is selected as Java EE Version.

    Click Finish.

    You should now have a Web Application project.

Creating a Singleton Session Bean

    This section demonstrates the creation of an  EJB 3.1 singleton session bean.  

    Right-click  EJBWebServicesDemo project and select  New -> Session Bean.

    Specify the Session Bean information as follows:

    EJB Name: CounterBean

    Package Name: com.example

    Select Singleton for Session Type

    Select Local for Create Interface

    Click Finish.

    Edit CounterBean.java.

    a.  Import the following packages.

    import javax.ejb.Lock;
    import javax.ejb.LockType;


    b. Create an instance variable hits and initialize it to 1.

    private int hits = 1;

    c. Implement  a  getHits() method.

        @Lock(LockType.READ)
        public int getHits() {
            return hits++;
        }
     

    A singleton bean always supports concurrent access. The @Lock(LockType.READ) and @Lock(LockType.WRITE) annotations are used to specify concurrency locking attributes. Specifying the @Lock annotation on the bean class means that it applies to all applicable business methods of the class

    Edit CounterBeanLocal.java , it is the local interface of the CounterBean singleton session bean.

    a. In the projects tab, select EJBWebServicesDemo project.

    b. Expand Source Packages > com.example and select CounterBeanLocal.java.

    c. Double-click CounterBeanLocal.java to open it in the code editor.

    d.  Add the below code to declare getHits method.

          public int getHits();


     

Creating a Web Service

    To create a  JAX-WS  web service perform the below steps in NetBeans IDE.

    Right-click on the  EJBWebServicesDemo project and select New->Other.

    In the New File window, select  category of  Web Services and a file type of  Web Service.

    Click Next.

    Specify the web service  information as follows:

    a.  Web Service Name: CounterService

    b. Package Name: com.service

    c.  Select  Create Web Service from Existing Session Bean

    d.  For the option Enterprise Bean, click Browse

    e. In the Browse Enterprise Bean dialog box,  select  EJBWebServicesDemo project and expand.

    f. Select CounterBean.

    g. Click OK.

    h. Click Finish.


    The Projects tab displays the structure of the new web service and the source code is shown in the editor area.

    Examine the code of the  CounterService web service generated by the IDE.


    For developing a JAX-WS web service a java class is  annotated with the javax.jws.WebService annotation. The @WebService annotation defines the class as a web service endpoint. A service endpoint interface or service endpoint implementation (SEI) is a Java interface or class, that declares the methods that a client can invoke on the service. The getHits method is annotated with the @WebMethod annotation which  exposes the  method to web service clients.

Deploying and Testing  the Web Service

    To deploy and test the web service, perform the following steps in NetBeans IDE. You can follow the progress of these operations in the EJBWebServicesDemo and the GlassFish server  tabs in the Output window.

    Right-click  EJBWebServicesDemo project in the Projects window and select  Build. 

    In the Projects window, right-click EJBWebServicesDemo and select Deploy.



    This command builds and packages the application into EJBWebServicesDemo.war, deploys this WAR file to the GlassFish Server.
    Verify  the deployed application in GlassFish server.

    a. In the Services tab, expand the Servers node.

    b. Expand the GlassFish Server node.

    c. In the GlassFish Server node, expand the Applications node, you  see EJBWebServicesDemo deployed.

    d.  Next expand the Web Services node, you see the  CounterService  deployed.

    To test the getHits method of CounterService, complete the below  steps.

    a. In the Projects tab, expand the Web Services node of the EJBWebServicesDemo project.

    b. Right-click CounterService node, and select Test Web Service.


    The tester page opens in the browser.

    Click getHits,  the getHits Method invocation page is displayed. Under Method returned,  the response from the getHits method is displayed.

     

Consuming the Web Service

    Now that you have deployed the web service, you need to create a client to make use of the web service's getHits method. In this section  you create two clients— a Java class in a Java SE application, and a JSP page in a web application.

      Client 1: Java Class in Java SE Application

        In this section you create a  stand-alone application client that accesses the getHits method of CounterService web service.

        Create a new  Java SE  Application.

        Select File->New Project from the NetBeans menu.

        Select the Java  category and a project type of  Java Application.

        Click  Next.

        Enter  project name as CounterServiceClient. 

        Ensure Create Main Class option is selected.

        Click Finish.


        You should now have a  Java SE  Application project.

        To create a web service client.

        a. Right-click on the CounterServiceClient project in the Projects window  and select New ->Other

        b. In the New File window, select  category of Web Services and a file type of Web Service Client.

        c. Click Next.

        The New Web Service Client wizard opens.

        Specify the web service  information as follows:

        a. Ensure Project is selected as the WSDL source.

        b. Click Browse.

        c. Select CounterService web service in the EJBWebServicesDemo project.

        d. Click OK.


        e. Do not select a package name, leave this field empty.

        f. Click Finish.


        Verify the creation of  web services client.

        a. In the Projects tab, select  CounterServiceClient project.

        b. Expand the Web Services References node.

        c. Expand the CounterService node  till the getHits method is displayed.

        Edit  CounterServiceClient.java

        a. In the projects tab, select CounterServiceClient project.

        b. Expand Source packages > Counterserviceclient package.

        c. Double-click CounterServiceClient.java to open it in the code editor.

        d. To invoke the web service, drag the getHits node below the main method.



        You  see the following code generated.

        Note:  Alternatively, instead of dragging the getHits node, you can right-click in the editor and then  select Insert Code > Call Web Service Operation.

        Modify the main method, add the below lines of code.

        int count=getHits();
        System.out.println(" The no of application hits is "+ count);


        Right-click CounterServiceClient project and select Run.

        Verify the output in the Output window.


        Note: On subsequent execution of the project the counter value increases by 1.

      Client 2: JSP page in a Web Application

        In this section, you create web application and accesses the getHits method of CounterService web service in the default JSP page, index.jsp.

        Create a new Web Application.

        Select File->New Project from the NetBeans menu.

        Select the Java Web category and a project type of  Web Application.

        Click  Next.


        Enter  project name as CounterWSJSPClient and click Next.


        Verify the following :

        GlassFish Server 3.1.2 is selected as the server.

        Java EE 6 Web is selected as Java EE Version.

        Click Finish.


        You should now have a Web Application project with default index.jsp.

        To create a web service client.

        a.  Right-click CounterWSJSPClient project in the Projects window and select New-> Web Service Client

        b.  Click Next


        The New Web Service Client wizard opens.
        Specify the web service  client information as follows:

        a.  Ensure Project is selected as the WSDL source.

        b. Click Browse

        c. Select CounterService web service in the EJBWebServicesDemo project.

        d. Click OK.

        e. Do not select a package name, leave this field empty.

        f.  Click Finish.


        The New Web Service Client wizard opens.
        Verify the creation of web service client.

        a. In the Projects tab, select  CounterWSJSPClient project.

        b. Expand the Web Services References node.

        c. Expand the CounterService till the getHits method is displayed.



        Edit index.jsp

        a. In the Projects tab, select CounterWSJSPClient project.

        b. Expand Web Pages folder.

        c. Double-click index.jsp to open it in the code editor.


        d. Modify the <h1> tags to display,  " The Application Hits are".

        To invoke the web service

        Drag the getHits operation to the client's index.jsp page, and drop it below the <h1> tags.



        The code for invoking the service's operation is now generated in the index.jsp page.



        In the Projects window, right-click CounterWSJSPClient and select Run.



        The application is built and deployed, and the browser opens, displaying the application hit counter: An example output is as below:



        Note: On subsequent browser refresh the count gets incremented by 1

Summary

    In this tutorial, you have learned how to:

     

    • Create JAX-WS web service
    • Create a singleton session bean
    • Expose the singleton session bean  as a JAX-WS web service
    • Deploy and test web service
    • Create web service clients - Java SE client and  web application

    Resources

    Credits

    • Lead Curriculum Developer: Anjana Shenoy

To help navigate this Oracle by Example, note the following:

Hiding Header Buttons:
Click the Title to hide the buttons in the header. To show the buttons again, simply click the Title again.
Topic List Button:
A list of all the topics. Click one of the topics to navigate to that section.
Expand/Collapse All Topics:
To show/hide all the detail for all the sections. By default, all topics are collapsed
Show/Hide All Images:
To show/hide all the screenshots. By default, all images are displayed.
Print:
To print the content. The content currently displayed or hidden will be printed.

To navigate to a particular section in this tutorial, select the topic from the list.