Table of Contents
This chapter describes how to create and deploy JAX-RPC web services whose endpoint is a Java class or an EJB.
JEUS provides a command-line tool and an Apache Ant tool to facilitate an easier JAX-RPC web service creation. Use the following steps to create and deploy JAX-RPC web services.
Configure the service configuration file (service-config.xml).
Create the WSDL file and JAX-RPC mapping file for Java EE web services.
Configure the web service deployment descriptors ('webservices.xml' and 'jeus-webservices-dd.xml')
Package and deploy the generated web service modules.
For more information, refer to JEUS Reference Book. "4.9. java2wsdl", JEUS Reference Book. "4.10. wsdl2java", JEUS Reference Book. "5.5.1. java2wsdl", and JEUS Reference Book. "5.5.2. wsdl2java".
JEUS JAX-RPC web services define the settings related to instantiating web services module in an XML file called 'service-config.xml'.
<?xml version="1.0" encoding="UTF-8"?>
<web-services-config xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<service>
<service-name>DocLitEchoService</service-name>
<target-namespace>urn:DocLitService</target-namespace>
<output-wsdl-file>DocLitEchoService.wsdl</output-wsdl-file>
<output-jaxrpc-mapping-file>
DocLitEchoService-mapping.xml
</output-jaxrpc-mapping-file>
<style>wrapped</style>
<interface>
<endpoint-interface-class>
jeustest.webservices.java2wsdl.doclit.Echo
</endpoint-interface-class>
</interface>
</service>
</web-services-config>The previous configuration instantiates a web service called DocLitEchoService, which is configured with the <servicename> element. The generated WSDL and mapping files are 'DocLitEchoService.wsdl' and 'DocListEchoService-mapping.xml' respectively. Service style is set to 'WRAPPED', and the web service endpoint is set to the Java class file 'jeustest.webservices.java2wsdl.doclit.Echo'.
For more information about the service-config.xml file, refer to "26. Configuring jeus-webservices-config.xml" of the "JEUS XML Reference Guide".
JEUS JAX-RPC web services provide a command-line tool and Ant Task for instantiating web services. Either tool can be used depending on preference.
JAX-RPC web services provide the command-line tool for creating a web service.
Usage: java2wsdl [options] configuration_file where [options] include: -classpath <path> specify where to find input class files -cp <path> same as -classpath <path> -d <directory> specify where to place generated output files -verbose [optional] turn verbose mode on
To instantiate the web service by using the service-config.xml file shown in "22.1.1. Configuring Service Configuration File", execute command from the command line.
The following is an example of executing the command by assuming that the compiled Java class back-end files exist in the 'JEUS_HOME/sample/classes' folder.
JEUS_HOME/sample$java2wsdl -cp ./classes service-config.xml
The WSDL file (DocLitEchoService.wsdl) and JAX-RPC mapping file (DocLitEchoService-mapping.xml) are created when the previous command is executed.
JEUS JAX-RPC web services provide an Ant Task called 'java2wsdl'. It takes the service configuration file path as an input and generates the WSDL file and JAX-RPC mapping file.
Compile the Java class files with the following command.
ant compile
The WSDL file and JAX-RPC mapping file are created in the './build' directory.
The compile Ant Task is internally processed in the order of '-pre-compile', 'do-compile', and '-postcompile'. The '-post-compile' process creates the WSDL file and JAX-RPC mapping file as shown in the following.
<target name="-post-compile">
<mkdir dir="${build.war.dir}/WEB-INF/wsdl"/>
<antcall target="java2wsdl">
<param name="java2wsdl.option"
value="-classpath ${build.classes.dir}
-d ${build.war.dir}/WEB-INF ${src.conf}/service-config.xml" />
</antcall>
</target>
For more information about java2wsdl Ant Task, refer to JEUS Reference Book. "5.5.1. java2wsdl".
The web service deployment descriptor (DD) file is an XML file that contains the deployment configurations. The web service DD file provides a web service engine with information about web service deployment and web service back-end search methods.
There are 2 kinds of web service DD files. First one is the webservices.xml file, a standard web service DD file defined by the Java EE web services specification. The other one is the 'jeus-webservicesdd. xml' file, a JEUS specific deployment descriptor file.
The name of the Java EE web services DD file must be 'webservices.xml'.
[Example 22.1] << webservices.xml >>
<?xml version="1.0"?>
<webservices version="1.1" xmlns="http://java.sun.com/xml/ns/j2ee">
<webservice-description>
<webservice-description-name>DocLitEchoService
</webservice-description-name>
<wsdl-file>WEB-INF/wsdl/DocLitEchoService.wsdl</wsdl-file>
<jaxrpc-mapping-file>
WEB-INF/DocLitEchoService-mapping.xml
</jaxrpc-mapping-file>
<port-component>
<port-component-name>EchoPort</port-component-name>
<wsdl-port xmlns:ns2="urn:DocLitService">
ns2:EchoPort
</wsdl-port>
<service-endpoint-interface>
jeustest.webservices.java2wsdl.doclit.Echo
</service-endpoint-interface>
<service-impl-bean>
<servlet-link>EchoServlet</servlet-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
In the previous example, the service name is
'DocListEchoService'. The WSDL file path is the 'WEB-INF/wsdl' directory
of the WAR file, and the name of the file is 'DocListEchoService.wsdl'.
The JAX-RPC mapping file path is the 'WEB-INF' directory, and the name
of the file is 'DocLitEchoService-mapping.xml'. In order to access the
service, the port named 'EchoPort' in the WSDL must be used and an SEI
and Servlet must be created for this port. For more information, refer
to "Chapter 25. Creating JAX-RPC Web Service Configuration File".
The name of the JEUS web services DD file must be 'jeus-webservices-dd.xml'.
[Example 22.2] << jeus-webservices-dd.xml >>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jeus-webservices-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<service>
<webservice-description-name>
DocLitEchoService
</webservice-description-name>
<port>
<port-component-name>EchoPort</port-component-name>
</port>
</service>
</jeus-webservices-dd>
For more information, refer to "22. Configuring jeus-client-dd.xml" of the "JEUS XML Reference Guide".
Java web services package Java classes and web service DD files like web modules. Web service modules are packaged into an EAR (Enterprise Application Archive) file that contains the web application WAR and EJB JAR files.
For more information about JEUS web container and web application, refer to JEUS Web Engine Guide. "Chapter 3. Web Contexts".
The main purpose of Servlet DD file (web.xml) is to define a runtime environment for Servlet and JSP components. Since Java web services run embedded in a Servlet at runtime, the web.xml file is needed to deploy web services.
The following is a sample web.xml file.
[Example 22.3] << web.xml >>
<?xml version="1.0"?>
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
<servlet>
<servlet-name>EchoServlet</servlet-name>
<servlet-class>
jeustest.webservices.java2wsdl.doclit.EchoImpl
</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>EchoServlet</servlet-name>
<url-pattern>/DocLitEchoService</url-pattern>
</servlet-mapping>
</web-app>
The <servlet-class> element includes a class name as
a node value, which contains the full package name of the Java class
that implements the actual web service. The <url-pattern>
element, which is a child element of the <servlet-mapping>
element, contains the URL used to connect to the web service.
JEUS web module deployment descriptor defines the context of a web module to be deployed. The file name is the same as the jeus-web-dd.xml file.
The following is a JEUS web module DD of a web service with 'DocListEchoService' as the context.
[Example 22.4] << jeus-web-dd.xml >>
<?xml version="1.0" encoding="UTF-8"?>
<jeus-web-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<context-path>/DocLitEchoService</context-path>
<enable-jsp>true</enable-jsp>
<auto-reload>
<enable-reload>false</enable-reload>
<check-on-demand>false</check-on-demand>
</auto-reload>
<max-instance-pool-size>-1</max-instance-pool-size>
<session-config>
<tracking-mode>
<url>false</url>
</tracking-mode>
</session-config>
</jeus-web-dd>
A WAR (Web Archive) file is one of the compressed JAR files with the '.war' extension, and the file is compressed by following the zlib algorithm standard, which is a compression and decompression algorithm. It is used only for binding web components such as servlet and JSP, and has the following directory structure.
WAR
|
+-- WEB-INF
|-- web.xml (Servlet DD)
|-- webservices.xml (Standard Web service DD)
|-- jeus-webservices-dd.xml (JEUS Web service DD)
|-- jeus-web-dd.xml (JEUS Web module DD)
|-- Jax-rpc mapping file
+-- wsdl
|
+-- wsdl file
|
+-- classes
|
+-- Java class component and handler implementation
Archive the created WSDL file, JAX-RPC mapping file, standard web service DD (webservices.xml), JEUS web service DD (jeus-webservices-dd.xml), servlet DD (web.xml), and JEUS web module DD into a WAR file with the aforementioned structure.
If the paths for WSDL file and JAX-RPC mapping file are configured in the <wsdl-file> and <jaxrpc- mapping-file> elements of the webservices.xml file, they do not have to follow the previous structure.
This section describes how to package and deploy EAR files.
A Java EE application is an independent business solution that can utilize web component, EJB, or JavaEE connectors, and it can be packaged into an EAR (Enterprise Archive) file. An EAR file contains the application deployment descriptors and may contain additional Java EE components and connectors packaged as EJB JAR, WAR, or RAR file.
A Java web service is packaged into a WAR file since it is created using the servlet programming model. An EJB endpoint is packaged into an EJB JAR file because an EJB is where SOAP messages are handled.
EAR
|
+-- WAR file
|
+-- JAR file
|
+-- EJB Web service component
|
+-- META-INF
|
+-- Standard application.xml file
JavaEE components packaged into an EAR file are defined in the application.xml file of the 'META-INF' directory.
The following is a sample application.xml file of an EAR application that contains a web module as a Java EE component.
[Example 22.5] << application.xml >>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application version="6"
xmlns="http://java.sun.com/xml/ns/javaee">
<module>
<web>
<web-uri>DocLitEchoService.war</web-uri>
<context-root>DocLitEchoService</context-root>
</web>
</module>
</application>
The package name and the module context information of the
web module are configured in the <web> element.
The deployment procedures for web services are identical to those for other Java EE applications. After the EAR package has been deployed, the web service can be invoked via the Internet.
The following is the URL of the deployed service.
http://host:port/DocLitEchoService/DocLitEchoServiceAfter implementing the web service using EJB, the business logic of the EJB needs to be converted into a web service and deployed. The instantiation and deployment of an EJB web service is identical to that of a Java web service. JEUS provides a command-line tool and Apache Ant tool to facilitate an easier creation of JAX-RPC web services.
Use the following steps to instantiate and deploy a web service.
Configure the web service configuration file (service-config.xml).
Create the WSDL file and JAX-RPC mapping file for Java EE web services.
Configure the web service deployment descriptors. (webservices.xml, jeus-webservices-dd.xml, and ejb-jar.xml)
Package and deploy the web service modules.
For more information, refer to JEUS Reference Book. "4.9. java2wsdl", JEUS Reference Book. "4.10. wsdl2java", JEUS Reference Book. "5.5.1. java2wsdl", and JEUS Reference Book. "5.5.2. wsdl2java".
The following is a sample configuration file called 'service-config.xml'.
[Example 22.6] << service-config.xml >>
<?xml version="1.0"?>
<web-services-config xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<service>
<service-name>AddressBookService</service-name>
<target-namespace>urn:AddressBookService</target-namespace>
<style>wrapped</style>
<use>literal</use>
<interface>
<endpoint-interface-class>
address.AddressBookIF
</endpoint-interface-class>
</interface>
</service>
</web-services-config>
The previous configuration instantiates a web service called AddressBookService which is configured in the <service-name> element and the generated WSDL and mapping files are 'AddressBookService.wsdl' and 'AddressBookService-mapping.xml' respectively. Service style is configured to 'WRAPPED' and web service endpoint is set to the Java class file called 'address.AddressBookIF'.
For more information about the service-config.xml file, refer to "26. Configuring jeus-webservices-config.xml" of the "JEUS XML Reference Guide".
JEUS JAX-RPC web services provide a command-line tool and Ant Task for instantiating web services. Either tool can be used depending on preference.
JEUS JAX-RPC web services provide a command-line tool for creating web services.
Usage: java2wsdl [options] configuration_file where [options] include: -classpath <path> specify where to find input class files -cp <path> same as -classpath <path> -d <directory> specify where to place generated output files -level <log-level> specify a log level -verbose [optional] turn verbose mode on
To instantiate the web service by using the service-config.xml file shown in the previous section, execute the following command, assuming that the compiled Java class back-end files exist in the 'JEUS_HOME/sample/classes' folder.
JEUS_HOME/sample$java2wsdl -cp ./classes ejb-service-config.xmlWhen you execute the previous command, WSDL file (AddressBookService.wsdl) and JAX-RPC mapping file (AddressBookService-mapping.xml) are created.
JEUS JAX-RPC web services provide an Ant Task called 'java2wsdl' for creating web services. It takes the service configuration file path as an input and generates the WSDL file and JAX-RPC mapping file.
Compile the Java class files with the following command.
ant compile
The WSDL file and JAX-RPC mapping file are created under the './build' directory.
The compile Ant Task is internally processed in the order of '-pre-compile', 'do-compile', and '-postcompile'. The '-post-compile' process that creates the WSDL file and JAX-RPC mapping file shown in the following.
<target name="-post-compile">
<mkdir dir="${build.classes.dir}/META-INF/wsdl"/>
<antcall target="java2wsdl">
<param name="java2wsdl.option"
value="-classpath ${build.classes.dir}
-d ${build.classes.dir}/META-INF ${src.conf}/ejb-service-config.xml" />
</antcall>
</target>Enter the file path of the service configuration file by using the 'configufilepath' attribute of the <java2wsdl> element, and enter the file path of the compiled Java class files by using the 'refid' attribute of the <classpath> element. After executing these commands, a WSDL file and JAX-RPC mapping file are created.
For more information about the 'java2wsdl' task, refer to JEUS Reference Book. "5.5.1. java2wsdl".
Web services DD (Deployment Descriptor) file is an XML file that contains the deployment configurations. The file provides the web service engine with information about web service deployment and web service back-end search methods.
There are two kinds of web services DD file. First one is the webservices.xml file, a standard web service DD file defined by the Java EE web services specification. The other one is the 'jeus-webservicesdd. xml' file, a JEUS specific deployment descriptor file.
The name of the Java EE web service DD file must be 'webservices.xml'.
[Example 22.7] << webservices.xml >>
<?xml version="1.0"?>
<webservices version="1.1" xmlns="http://java.sun.com/xml/ns/j2ee">
<webservice-description>
<webservice-description-name>
AddressBookService
</webservice-description-name>
<wsdl-file>
META-INF/wsdl/AddressBookService.wsdl
</wsdl-file>
<jaxrpc-mapping-file>
META-INF/AddressBookService-mapping.xml
</jaxrpc-mapping-file>
<port-component>
<port-component-name>
AddressBookIFPort
</port-component-name>
<wsdl-port xmlns:ns2="urn:AddressBookService">
ns2:AddressBookIFPort
</wsdl-port>
<service-endpoint-interface>
address.AddressBookIF
</service-endpoint-interface>
<service-impl-bean>
<ejb-link>AddressEJB</ejb-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
In the file, the service name is 'AddressBookService'. The
WSDL file path is the 'WEB-INF/wsdl' directory of the JAR package, and
the name of the file is 'AddressBookService.wsdl'. The JAX-RPC mapping
file path is the 'META-INF' directory, and the name of the file is
'AddressBookServicemapping. xml'.
In order to connect to the service, the port named 'AddressBookIFPort' in the WSDL must be used and an SEI and EJB must be created for this port.
The name of the JEUS web services DD file must be 'jeus-webservices-dd.xml'.
[Example 22.8] << jeus-webservices-dd.xml >>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jeus-webservices-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<ejb-context-path>webservice</ejb-context-path>
<service>
<webservice-description-name>
AddressBookService
</webservice-description-name>
<port>
<port-component-name>
AddressBookIFPort
</port-component-name>
<ejb-endpoint-url>
/AddressBookService
</ejb-endpoint-url>
</port>
</service>
</jeus-webservices-dd>
The URL for invoking an EJB web service is configured in the
JEUS web services deployment descriptor file. The URL consists of a
context path and URL pattern. The context path is set in the
<ejb-contextpath> element, and the URL pattern is set in the
<ejb-endpoint-url> element within the <port> element.
The following is the actual URL for invoking the web service.
http://host:port/webservice/AddressBookService
An EJB-based web service is packaged with the web services DD and WSDL into an EJB JAR package. The EJB JAR package is then packaged into a standard enterprise application EAR file with other web application WAR and EJB JAR packages.
The following is a sample ejb-jar.xml file.
[Example 22.9] << ejb-jar.xml >>
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"
version="2.1">
<display-name>AddressEJB</display-name>
<enterprise-beans>
<session>
<display-name>AddressEJB</display-name>
<ejb-name>AddressEJB</ejb-name>
<service-endpoint>
address.AddressBookIF
</service-endpoint>
<ejb-class>address.AddressBookEJB</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
</session>
</enterprise-beans>
</ejb-jar>
The node value of the <ejb-class> element is the
bean class name that implements the actual web service logic. The
<service-endpoint> element contains the SEI class name.
The following is a sample JEUS EJB deployment descriptor called 'jeus-ejb-dd.xml'.
[Example 22.10] << jeus-ejb-dd.xml >>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jeus-ejb-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus">
<beanlist>
<jeus-bean>
<ejb-name>AddressEJB</ejb-name>
<export-name>AddressEJB</export-name>
</jeus-bean>
</beanlist>
</jeus-ejb-dd>
Package the EJB implementation classes, SEI, web service deployment descriptor, and EJB deployment descriptor into a JAR file.
The following is the structure of the JAR file.
JAR
|
+-- META-INF
|-- ejb-jar.xml (Standard EJB DD)
|-- webservices.xml (Standard Web service DD)
|-- jeus-webservices-dd.xml (JEUS Web service DD)
|-- jeus-ejb-dd.xml (JEUS EJB DD)
+-- Jax-rpc mapping file
+-- wsdl
|
+-- wsdl file
|
+-- EJB class component, J2EE Portable Artifact
If the paths for WSDL file and JAX-RPC mapping file are configured in the <wsdl-file> and <jax-rpc-mapping-file> elements of the webservices.xml file, they do not have to follow the previous structure.
This section describes how to package and deploy EAR files.
A Java EE application is an independent business solution that can utilize web component, EJB, or JavaEE connectors, and it can be packaged into an Enterprise Archive (EAR) file. An EAR file contains the application deployment descriptors and may contain additional Java EE components and connectors packaged as EJB JAR, WAR, or RAR file.
The JAX-RPC service endpoint (JSE) is packaged into a WAR file since it is created using a servlet programming model. An EJB endpoint is packaged into an EJB JAR file because an EJB is where SOAP messages are handled.
EAR
|
+-- WAR file
|
+-- JSE(JAX-RPC Servlet Endpoint) Web service component
|
+-- JAR file
|
+-- EJB Web service component
|
+-- META-INF
|
+-- Standard application.xml file
JavaEE components packaged into an EAR file are defined in the application.xml file of the 'META-INF' directory.
The following is a sample application.xml file of an EAR application that contains a web module as a Java EE component.
[Example 22.11] << application.xml >>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application version="6"
xmlns:ns1="http://java.sun.com/xml/ns/javaee">
<module>
<ejb>AddressBook.jar</ejb>
</module>
</application>
The JAR package name of the EJB-based web service is
configured in the <ejb> element.
The deployment procedures for web services are identical to those for other Java EE applications. After the EAR package has been deployed, web services can be invoked via the Internet.