Web Services

Java EE 5 supports two types of web services, namely POJO web services and EJB web services. The only element that we need to add to the Apache Geronimo deployment plan is a service-ref element, which is required to map the web service proxy to a JNDI location. Thus, in order to create a Java EE web service in Apache Geronimo, we do not need to add entries in the server-specific deployment plans. This element, and the sub-elements that comprise it, are shown in the following four figures:

The following figure shows the service-completion Type element:

The following figure shows the port-completion Type element:

The following figure shows the port Type element:

The elements in the service-ref element are explained below:

• service-ref-name: The name of the service reference. This name will be the name under which the web service proxy object will be bound in the local JNDI context of the application or component.

• service-completion: This element is used in case only a partial WSDL is available for the service that we are trying to reference. It contains information that is not present in the WSDL, but that is required to access the web service. It contains the following elements:

  • service-name: This is the name of the service that this service-completion element provides information for.

  • port-completion: Information about the ports and their bindings. This element consists of the following two subelements:

    • binding-name: The name of the binding for which this port-completion element provides information.

    • port: Information about the port, which overrides or augments the information that is given in the WSDL. This element is the only element required if we have a completed WSDL.

• port: This element maps the ports in the WSDL to their actual physical locations.

  • port-name: Name of the port that is being mapped

  • protocol: The protocol that is required to be used to access this web service

  • host: The host on which this web service resides

  • port: The TCP/IP port on the host where the web service can be accessed

  • uri: The URI of the service

  • credentials-name: The name of the login module that will store the username and password of the current user

  Applications deployed on Apache Geronimo are capable of accessing secured web services, which needs the clients to be authenticated. To access such web services, a new login module needs to be used, that is, org.apache.geronimo.security.realm.providers.NamedUsernamePasswordCredentialLoginModule.This security realm saves the credentials of the current user, and then later in the service-ref element we need to specify the credentials-name element to match the name attribute of this login module.

  
  

EAR sample application

We will now show the deployment of a sample application that sets up an application-specific JavaMail session, and also declares an EJB web service. The application is a part of a library management system that does the following:

• Lists the books that have been lent to members of the library

• Sends a mail to each of the members that have a book in their possession with the due dates and fine information

The two use cases can be executed from a web client using a JSP and the second use case can also be executed from a Java EE Application client. The application will send mails through an EJB component which will also be a web service. The books and the information on the members will be picked from a database by using a servlet and JDBC. We will be discussing the plans of the application, along with the output, below. The application is present in the samples/LibraryApp directory. The application consists of the following modules:

• web: This consists of a JSP, namely, list.jsp, which lists the members and the books lent to them. It also contains two servlets, namely, ListServlet and PopulateDBServlet. The context-root of the application is /LibraryApp, and the mappings of the servlets are /list and /SetupDB. The PopulateDBServlet should be called once after installation to create and populate the database. The ListServlet can be used to list the members and the books lent to them. It can also be made to send a mail to all of the members by passing the parameter sendMail=true in the request.

• EJB: This consists of the MailBean stateless session bean and its local and remote business interfaces. The remote business interface is also configured to be the service interface, and this bean is exposed as a web service.

• client: This consists of the application client that will consume the webservice MailService that is exposed by the previous module, and uses it to send mails to the member regarding the books that they have borrowed from the library.

All of the above modules are packaged into an EAR file, and the plan for this file is shown in the listing below.

<?xml version="1.0" encoding="UTF-8"?>
<application>
...
<module>
<web>LibraryApp-web-1.0.war</web>
<web-app>
<context-root>/LibraryApp</context-root>
<resource-ref>
<ref-name>jdbc/DataSource</ref-name>
<resource-link>DerbyTestPool</resource-link>
</resource-ref>
</web-app>
</module>
<module>
<ejb>LibraryApp-ejb-1.0.jar</ejb>
<openejb-jar>
<enterprise-beans>
<session>
<ejb-name>MailBean</ejb-name>
<web-service-address>/Mail/MailService </web-service-address>
<resource-ref>
<ref-name>jdbc/DataSource</ref-name>
<resource-link>DerbyTestPool</resource-link>
</resource-ref>
</session>
</enterprise-beans>
</openejb-jar>
</module>
<module>
<java>LibraryApp-client-1.0.jar</java>
<application-client>
(...)
<service-ref>
<service-ref-name>service/SendMail</service-ref-name>
<port>
<port-name>MailServiceSOAP11port</port-name>
<protocol>http</protocol>
<host>localhost</host>
<port>8080</port>
<uri>/Mail/MailService</uri>
</port>
</service-ref>
</application-client>
</module>
(...)
</application>

Each of the module elements encapsulates a plan for one of the modules (web, EJB, or appclient).

In the case of the web module, there is a resource-reference to jdbc/DataSource that is mapped to an actual database pool that we define later in the plan, namely, DerbyTestPool. In the EJB module's plan, we override the location of the web service it exposes (which is optional) and also map the same resource-reference. In the application client's deployment plan, we map a service-reference to the location of the service.

You can see the JavaMail configuration in the following plan:

<application>
...
<gbean name="mail/MailSession" class="org.apache.geronimo.mail.MailGBean">
<attribute name="transportProtocol">smtp</attribute>
<attribute name="jndiName">mail/MailSession</attribute>
<attribute name="properties">
mail.debug=true
mail.smtp.host=127.0.0.1
mail.smtp.auth=false
mail.smtp.port=25
</attribute>
<reference name="Protocols">
<name>JavaMailProtocol.smtp</name>
</reference>
</gbean>
<gbean name="SMTPTransport" class="org.apache.geronimo.mail.SMTPTransportGBean">
<attribute name="host">localhost</attribute>
<attribute name="port">25</attribute>
</gbean>
</application>

Deploying an EJB web service

In order to deploy an EJB as a web service, you do not need to make any changes to the Geronimo-specific deployment descriptor. You can override the location where the web service will be deployed through the web-service-address tag, as shown in the plan. All of the other configuration can be performed via annotations. These are shown in the sample code below:

package com.packtpub.library.ejb;
import javax.annotation.Resource;
import javax.ejb.Stateless;
import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.mail.Session;
import javax.sql.DataSource;
import com.packtpub.library.ListUtility;
@Stateless(name="MailBean")
@WebService(serviceName = "MailService", portName="MailServiceSOAP11port", // endpointInterface = "com.packtpub.library.ejb.MailBusinessRemote", targetNamespace = "http://ejb.library.packt.com", wsdlLocation = "META-INF/wsdl/MailService.wsdl") public class MailBean implements MailBusinessRemote, MailBusinessLocal{
@Resource(name="mail/MailSession") Session mailSession;
@Resource(name="jdbc/DataSource") private DataSource ds;
@WebMethod
public void sendMail() { try { ListUtility.sendMail(ds, mailSession);
} catch (Exception e) { System.out.println("Sending of email failed: " +e.getMessage());
}
}
}
package com.packtpub.library.ejb;
import java.rmi.RemoteException;
import javax.ejb.EJBException;
import javax.ejb.Remote;
import javax.jws.WebMethod;
import javax.jws.WebService;
@Remote
public interface MailBusinessRemote {
public void sendMail() throws RemoteException,EJBException;
}

You can see the interface and the EJB that has been annotated with the metadata that is required to expose them as a web service. Apache Geronimo has the capability to generate the WSDL from this, or you can also use Ant/Maven/Eclipse plugins of the Axis2 java2wsdl tooling. For more samples, please refer to the Geronimo documentation.

 java -Dorg.apache.geronimo.jaxws.builder.useSimpleFinder=true -Djava.endorsed.dirs=lib/endorsed -javaagent:bin/jpa.jar -jar bin/server.jar.