The specification Web Services for Java EE, JSR 109 defines two ways of implementing a web service. One way is based on the Java class programming model -- the web service is implemented by a Java class that runs in a web container. The other way is based on the Enterprise JavaBeans (EJB) programming model -- the web service is implemented as a stateless session bean that runs in an EJB container. A previous Tech Tip, Developing Web Services Using JAX-WS, described how to develop a web service using the Java class programming model and Java API for XML Web Services (JAX-WS) 2.0, JSR 224. In the following tip, you'll learn how to develop a web service using JAX-WS and the EJB programming model. In particular, you'll learn how to use an EJB 3.0 stateless session bean to implement a Calculator service -- the same Calculator service that was covered in the previous Tech Tip.

A sample package accompanies this tip. It demonstrates a standalone Java client accessing the EJB 3.0-based Calculator service. The example uses an open source reference implementation of Java EE 5 called GlassFish. You can download GlassFish from the GlassFish Community Downloads page.

Writing the EJB 3.0 Stateless Session Bean Class

Let's start by creating the stateless session bean for the service. One of the significant improvements in the Java EE 5 platform is a much simpler EJB programming model as defined in the Enterprise JavaBeans 3.0 Specification, JSR-220. One of the simplifications is that a bean implementation class is no longer required to implement the javax.ejb.SessionBean or javax.ejb.EntityBean interface. You can declare a class a session bean or entity bean simply by annotating it. For example, you can declare a class a stateless session bean by annotating it with the @Stateless annotation.

EJB 3.0 does specify additional rules for the bean implementation class:

• It must be declared public and must have a default constructor that doesn't take any arguments.
  
  
• It must not be final or abstract and must be a top-level class.
  
  
• It must not define a finalize() method.

Another simplification in EJB 3.0 is that a component interface or home interface is no longer required for a session bean. The one interface a session bean needs is a business interface that defines the business methods for the bean. Unlike business methods in a component interface, the business methods in a business interface are not required to throw java.remote.RemoteException. However the business methods can define throws clauses for arbitrary application exceptions. The EJB 3.0 business methods should not be static and final.

Given these simplifications and rules, here is a stateless session bean for the Calculator class that conforms to the EJB 3.0 programming model (you can find the source code for the Calculator class in the endpoint directory of the installed sample package):

    package endpoint;       import javax.ejb.Stateless;       @Stateless      public class Calculator {        public Calculator() {}       public int add(int i, int j) {          int k = i +j ;          System.out.println(i + "+" + j +" = " + k);          return k;       }    } 

Because the EJB 3.0 bean doesn't need to implement the javax.ejb.SessionBean interface, it no longer needs to include unimplemented lifecycle methods such as ejbActivate and ejbPassivate. This results in a much simpler and cleaner class. Various annotations defined in EJB 3.0 reduce the burden on developers and deployers by reducing or eliminating the need to write a deployment descriptor for the component.

Marking the EJB 3.0 Bean as a Web Service

To mark a bean as a web service simply annotate the class with the @WebService annotation. This is an annotation type defined in the javax.jws.WebService package, and is specified in Web Services Metadata for the Java Platform, JSR 181. Here is the code for Calculator class marked as a web service:

    package endpoint;       import javax.ejb.Stateless;    import javax.jws.WebService;     @Stateless    @WebService    public class Calculator {        public Calculator() {}       public int add(int i, int j) {          int k = i +j ;          System.out.println(i + "+" + j +" = " + k);          return k;       }    } 

Marking a Java class with a @WebService annotation makes it a service implementation class. Note that you don't have to implement a service endpoint interface. According to the JSR 109, you only need to provide a javax.jws.WebService-annotated service implementation bean. Deployment tools can then be used to generate a service endpoint interface, as well as a WSDL document, using JAX-WS rules for Java WSDL mapping.

Packaging the Web Service

A web service based on the EJB programming model needs to be packaged as a JAR file. Using the @WebService annotation, you only need to package the service implementation bean class (with its dependent classes, if any) and the service endpoint interface class (if explicitly provided). Additionally, the @Stateless annotation frees you from packaging ejb-jar.xml. By comparison, in the JAX-RPC style of packaging web services based on EJB 2.0 or earlier, you were responsible for providing the service endpoint interface class, the service implementation bean class (and dependent classes), generated portable artifacts, the JAX-RPC mapping file, and a web services deployment descriptor (webservices.xml and ejb-jar.xml).

With JSR 224, JSR 109, JSR 181 and JSR 220, an application server deployment tool can generate all the necessary artifacts such as a deployment descriptor (if not explicitly provided by the user) for deploying the web service. These artifacts, bundled in the EJB JAR file, are deployed in an EJB container. A deployer can choose to overwrite values specified by the @WebService and @Stateless annotations by explicitly providing any of the previously-mentioned artifacts and packaging them in the EJB module at the time of deployment. For this tip, the following files are packaged in the EJB module to be deployed:

   endpoint/Calculator.class   endpoint/jaxws/Add.class   endpoint/jaxws/AddResponse.class 

The rest of the deployment artifacts are generated by the application server (in this case, GlassFish).

Writing the Client

After you deploy the web service, you can access it from a client program. A client uses a @WebServiceRef annotation to declare a reference to an EJB 3.0-based web service. The @WebServiceRef annotation is in the javax.xml.ws package, and is specified in JAX-WS 2.0 Web Services Metadata for the Java Platform, JSR 181. If you examine the source code JAXWSClient, the client program used in this tip (you can find the source code for JAXWSClient in the client directory of the installed sample package), you'll notice the following:

    @WebServiceRef(wsdlLocation=     "http://localhost:8080/CalculatorService/Calculator?WSDL")    static endpoint.CalculatorService service; 

The value of the wsdlLocation parameter in @WebServiceRef is a URL that points to the location of the WSDL file for the referenced service. (The @WebServiceRef annotation supports additional properties that are optional. These optional properties are specified in section 7.9 of the JAX-WS 2.0 specification.) The static variable named service will be injected by the application client container.

Looking further at the source code for JAXWSClient, you'll notice the following line:

    endpoint.Calculator port = service.getCalculatorPort(); 

The service object provides the method, getCalculatorPort, to access the Calculator port of the web service. Note that both endpoint.CalculatorService and endpoint.Calculator are portable artifacts that are generated by using the wsimport utility. The wsimport utility is used to generate JAX-WS artifacts (it is invoked as part of the build-client step when you run the example program.)

After you get the port, you can invoke a business method on it just as though you invoke a Java method on an object. For example, the following line in JAXWSClient invokes the add method in Calculator:

   int ret = port.add(i, 10); 

Running the Sample Code

A sample package accompanies this tip. It demonstrates the techniques covered in the tip. To install and run the sample:

1. If you haven't already done so, download GlassFish from the GlassFish Community Downloads page.
   
   
2. Set the following environment variables:
   
   GLASSFISH_HOME: This should point to where you installed GlassFish (for example C:\Sun\AppServer)
   
   ANT_HOME: This should point to where ant is installed. Ant is included in the GlassFish bundle that you downloaded. (In Windows, it's in the lib\ant subdirectory.)
   
   JAVA_HOME: This should point to the location of JDK 5.0 on your system.
   
   Also, add the ant location to your PATH environment variable.
   
   
3. Download the sample package for the tip and extract its contents. You should now see the newly extracted directory as <sample_install_dir>/ttmar2006ejb-ws, where <sample_install_dir> is the directory in which you installed the sample package. For example, if you extracted the contents to C:\ on a Windows machine, then your newly created directory should be at C:\ttmar2006ejb-ws. The ejb-techtip directory below ttmar2006ejb-ws contains the source files and other support file for the sample.
   
   
4. Change to the ejb-techtip directory and edit the build.properties files as appropriate. For example, if the admin host is remote, change the value of admin.host from the default (localhost) to the appropriate remote host.
   
   
5. Start GlassFish by entering the following command:
   
   <GF_install_dir>/bin/asadmin start-domain domain1
   
   where <GF_install_dir> is the directory in which you installed GlassFish.
   
   
6. In the ejb-techtip directory, execute the following commands:
   
   ant build
   
   This creates a build directory, compiles the classes, and puts the compiled classes in the build directory. It also creates an archive directory, creates a JAR file, and puts the JAR file in the archive directory.
   
   ant deploy
   
   This deploys the JAR file on GlassFish.
   
   ant build-client
   
   This generates portable artifacts and compiles the client source code.
   
   ant run
   
   This runs the application client and invokes the add operation in the Calculator service 10 times, adding 10 to the numbers 0-to-9. You should see the following in response:
   
   run:
   
   

        [echo] Executing appclient with client class as      client.JAXWSClient     [exec] Retrieving port from the service      endpoint.CalculatorService@159780d     [exec] Invoking add operation on the calculator port     [exec] Adding : 0 + 10 = 10     [exec] Adding : 1 + 10 = 11     [exec] Adding : 2 + 10 = 12     [exec] Adding : 3 + 10 = 13     [exec] Adding : 4 + 10 = 14     [exec] Adding : 5 + 10 = 15     [exec] Adding : 6 + 10 = 16     [exec] Adding : 7 + 10 = 17     [exec] Adding : 8 + 10 = 18     [exec] Adding : 9 + 10 = 19 

7. To undeploy the EJB Module from GlassFish, execute the following command:
   
   ant undeploy

About the Author

Manisha Umbarje is a member of the product engineering group for the Sun Java System Application Server.

One of the areas significantly enhanced in Java 2 Platform, Standard Edition (J2SE) 5.0 is monitoring and management. Among the key features J2SE 5.0 introduced is an instrumented Java virtual machine (JVM) and a java.lang.management API for monitoring and managing the JVM. The API enables local and remote access to a variety of JVM-related information such as memory usage, thread state, class loading activity, and garbage collection statistics. This enhanced and integrated support for management and monitoring can be used by any J2SE 5.0-based administration application.

GlassFish and MBeans

One tool that takes advantage of these capabilities is GlassFish, an open source application server implementation of Java EE 5. The GlassFish application server leverages all of the J2SE 5.0-based monitoring and management enhancements in its administration infrastructure. This includes the use of the platform MBean server to register application server MBeans. Management Beans (or "MBeans") are Java objects that follow design patterns conforming to the Java Management Extensions (JMX) specification -- they are used for instrumenting resources. This tip assumes that you're familiar with the basics of JMX. For an introduction to JMX, see the Tech Tip Understanding JMX Technology.

The platform MBean server, also introduced in J2SE 5.0, is a JMX-based agent built into the JVM, that gives management applications access to MBeans. The agent can be shared by all managed components running in the JVM. Through the platform MBean server, GlassFish can provide a comprehensive and consolidated monitoring and management view of the system and application-specific MBeans. GlassFish uses this built-in agent instead of creating an instance of its own agent (as was required previous to J2SE 5.0). Because application server MBeans are registered in the platform MBean server repository, tools such as the Java Monitoring and Management Console (JConsole) can display information about all resources instrumented by the application server MBeans.

GlassFish and Custom MBeans

Significantly, you can extend GlassFish's administration features by creating and registering your own custom MBeans. Custom MBeans allow dynamic injection of monitoring and management features. In addition, instrumented custom MBean attributes can be persisted so that they survive even if the application server needs to be restarted. One place where custom MBeans demonstrate their utility is in GlassFish's Self Management Framework. This is a rule-based event management system, where users can add custom actions, implemented as custom MBeans, to the rules that govern the system.

Example: Extending Monitoring and Management Capabilities

This tip presents an example that uses custom MBeans to extend GlassFish's monitoring and management features. The example extends a Java EE application that processes data that it gets periodically from a web service. The administrative extension is to add an event to be monitored and an action for the application to take in response to that event.

The event is an update to a list of email addresses. The action is to send emails to the updated list of email addresses. In this scenario, a custom MBean, which is also a client of the web service, would update the list of email addresses after polling the web service. However, to simplify things in this example, the string of email addresses is an attribute of the custom MBean. A user directly modifies the list using JConsole. When the attribute is modified, a listening custom MBean is notified. The listening custom MBean then processes the event by sending emails to the updated list of email addresses (that is, the updated value of the attribute).

A sample archive accompanies this tip. It contains the source code and compiled classes for the example. It also includes javadoc for the classes used in the example.

Step 1: Setup

Let's start by doing some initial setup. If you haven't already done so, download GlassFish from the GlassFish Downloads page. Then set the following environment variables:

• GLASSFISH_HOME. This should point to where you installed GlassFish (for example C:\Sun\AppServer)
  
  
• JAVA_HOME. This should point to the location of JDK 5.0 on your system.

Step 2: Start GlassFish

Start GlassFish by entering the following command:

       <GF_install_dir>/bin/asadmin start-domain domain1 

where <GF_install_dir> is the directory in which you installed GlassFish.

Step 3: Download the sample archive:

Download the sample archive for the tip and extract its contents:

    jar xvf ttmar2006custmbean.jar 

Step 4: Create the custom MBeans

This example uses two custom MBeans, one for the event source, and one to listen for the event (the event "sink"). You can find the source code for the two custom MBeans in the techtip/src directory.

A custom MBean requires an MBean interface and an MBean implementation class. The custom MBean interface for the event source is EventSourceCustomMBean, and its implementation class is EventSourceCustom. The custom MBean interface for the event sink is EventSinkCustomMBean and its implementation class is EventSinkCustom.

After you create the source files for the custom MBeans, you can compile the files into the com.example.mbeans package structure (this is optional -- the compiled classes are in the sample archive). To compile the files, enter the following:

    javac -d . EventSourceCustom.java EventSourceCustomMBean.java     javac -d . EventSinkCustom.java EventSinkCustomMBean.java  

When you compile the EventSinkCustom class, you need to make sure that the files mail.jar and activation.jar are in your classpath.

Step 5: Copy the Custom MBean classes

Copy the com/example/mbeans directory and it contents to the MBean classloader directory. The MBean classloader directory is <domain>/applications/mbeans, where <domain> is the domain where the application is deployed. For this example, assume that the application is deployed in the default GlassFish domain, domain1. So copy the com/example/mbeans directory and its contents to <GF_install_dir>/glassfish/domains/domain1/applications/mbeans. This will create the /com/example/mbeans directory and copy the custom MBean class and interface to <GF_install_dir>/glassfish/domains/domain1/applications/mbeans.

Step 6: Deploy the Event Source Custom MBean

Deploy the event source custom MBean, EventSourceCustom, as follows (the command should be entered on one line):

    <GF_install_dir>/bin/asadmin create-mbean --user admin     --passwordfile password.txt --port 4848     com.example.mbeans.EventSourceCustom   

This registers EventSourceCustom in the platform MBean server.

You can verify that the custom MBean has been deployed by issuing the following command (the command should be entered on one line):

    <GF_install_dir>/bin/asadmin list-mbeans --user admin     --passwordfile password.txt   

In response, you should see the following:

    com.example.mbeans.EventSourceCustom     user:impl-class-name=com.example.mbeans.EventSourceCustom,    name=com.example.mbeans.EventSourceCustom Enabled    Command list-mbeans executed successfully. 

Step 7: Deploy the Event Sink Custom MBean

Deploy the event sink custom MBean, EventSinkCustom, as follows (the command should be entered on one line):

    <GF_install_dir>/bin/asadmin create-mbean --user admin     --passwordfile password.txt --port 4848 --objectname     "user:impl-class-name=com.example.mbeans.EventSinkCustom,     name=custom-event-sink"     --attributes HostName=<yourmailserver>:Id=<yourId>:    Password=<yourpw> com.example.mbeans.EventSinkCustom 

Notice the HostName, Id, and Password parameters in the command. These parameters need to be specified for connection to a mail server. The parameters are attributes of the custom MBean. Replace <yourmailserver> with the name of your mail server, <yourId> with your user identification, and <yourpw> with your password.

As mentioned earlier, instrumented custom MBean attributes can be persisted so that they survive even if the application server needs to be restarted. So in specifying the parameters in the command, it configures the runtime parameters of the custom MBean. However after the MBean is created, the parameters persist across server restarts.

Again, you can verify that the custom MBean has been deployed by issuing the following command (the command should be entered on one line):

    <GF_install_dir>/bin/asadmin list-mbeans --user admin     --passwordfile password.txt   

In response, you should see the following:

    com.example.mbeans.EventSourceCustom     user:impl-class-name=com.example.mbeans.EventSourceCustom,    name=com.example.mbeans.EventSourceCustom Enabled    com.example.mbeans.EventSinkCustom     user:impl-class-name=com.example.mbeans.Event    SinkCustom, name=custom-event-sink Enabled    Command list-mbeans executed successfully.       

Step 8: Update the email list

In this example, you use JConsole to update an attribute of the custom MBean that contains a string of email addresses.

Start JConsole by issuing the following command:

    <JAVA_HOME>/bin/jconsole 

When you start JConsole, you should see a connection dialog box with tabs for local, remote, and advanced JMX connections. Click the Remote tab, and enter the appropriate host (localhost), port (GlassFish's JMX connection server listens at port 8686), user name (admin), and password (adminadmin) values.

Click the Connect button in the display for the remote tab. This connects to the platform MBean server using an RMI connector. In the subsequent Connection window, click on the MBeans tab. Expand the user branch in the MBean tree in the left pane of the window. Continue expanding the branches below the user branch until you see the server entry below com.example.mbeans.EventSourceCustom. Then click on the server entry. You should see information about the MBean in the Info tab in the right pane of the window.

Click the Attributes tab in the right pane of the window. Then enter your email address in the value field for the attribute EmailRecipientsString.

The event source custom MBean sends a notification when you change the EmailRecipientsString attribute. It listens for the notification as defined by the AttributeChangeNotification class, and fetches the new value of this attribute. Here's the code in EventSinkCustom that takes these actions:

    AttributeChangeNotification attrnotif =         (AttributeChangeNotification) notif;     String newEmailIdStr = (String)attrnotif.getNewValue(); 

The event sink custom MBean then sends email to the updated addresses.

Step 9: Check for the email

Check your email to verify that the listening custom MBean sent an email to your address. Your should receive the following message:

This message has been generated and sent as part of the Glassfish Techtip sample example execution

For further information, see the following:

• Sun Java System Application Server Platform Edition 9 Administration Guide
• Using JConsole
• GlassFish Project - Self Management home page

About the Author

Nandini Ektare is a member of Sun Java System Application Server Development group at Sun Microsystems Inc. Her areas of interest include JMX and Java EE.

Kedar Mhaswade is a staff engineer at Sun Microsystems Inc. He is a member of the Expert Group for JSR 003: Java Management Extensions. His areas of interest include open source software, JMX, and Java EE.

• Core Java Technologies Tech Tips. Get tips on using core Java technologies and APIs, such as those in the Java 2 Platform, Standard Edition (J2SE).
• Wireless Developer Tech Tips. Get tips on using wireless Java technologies and APIs, such as those in the Java 2 Platform, Micro Edition (J2ME).