 | Level: Introductory Greg Flurry, Senior Technical Staff Member, IBM Austin, Texas
15 Oct 2003 The latest versions of WebSphere Studio and WebSphere Application Server support J2EE Web services as defined by JSR-101 and JSR-109. This two-part article examines this support through several examples, covering server-side support in Part 1 and client-side support in Part 2.
Introduction The latest version of IBM ® WebSphere® Application Server -- Version 5.0.2 --
supports Web services in the JavaTM 2 Enterprise Edition (J2EE)
environment as defined by Java Community Process specifications JSR-109
and JSR-101. The latest version of WebSphere Studio Application Developer -- Version 5.1 --
supports WebSphere Application Server V5.0.2 and development of Web services for
J2EE. This series of articles examines the support for J2EE Web services
available in Application Developer V5.1 through a number of examples, with
emphasis on the new level of support. Part 1 (this article) examines support for the server environment,
while Part 2 examines support for the client environment.
Web services for J2EE The most important goal of Web services is interoperability. Perhaps the most important goal of J2EE is portability. The
JSR-109 specification, "Web Services for J2EE, Version 1.0" produced by the Java Community Process
(for more information, see Related Content),
combines these two important goals for the J2EE environment. JSR-109 identifies the various roles and responsibilities
required in producing and consuming Web services, the programming model and APIs for both the client and server, and the various artifacts
required to support Web services for both the client and server. JSR-109 leverages the JAX-RPC or JSR-101 specification,
"Java API for XML-Based RPC," to define parts of the overall J2EE environment, such as APIs and marshalling and unmarshalling. An excellent
introduction to JSR-109 and JSR-101 can be found in the article
Build interoperable Web services with JSR-109.
In the rest of this article, "JSR-109" refers to content in either JSR-109 or JSR-101. Particularly interesting is that JSR-109 defines two means for implementing
a Web service which runs in a J2EE environment. The first extends the JSR-101
programming model, which defines a Web service as a Java class running
in the Web container. The second uses a constrained implementation of a
stateless session EJB in the EJB container. We will examine both means in this article.
Web services in Application Developer V5.1 Application Developer has supported Web services development since its
introduction. Version 5.1 marks the first time, however, that support could
be based on accepted specifications for the Java and J2EE environments
which Application Developer targets, and it offers full support for JSR-109,
both server and client. As with earlier versions, Application Developer
5.1 provides wizards for producing the server-side and client-side artifacts
for Web services; it also includes specialized editors to manipulate some
of the new J2EE Web services artifacts such as the server-side and client-side
deployment descriptors. In this article, we will examine only the server-side tooling. In addition to support for J2EE Web services, Application Developer includes support for the guidelines produced by the
Web Services Interoperability Organization (WS-I). In particular, Application Developer is cognizant of
WS-I's Basic Profile 1.0. For example, Application
Developer supports the production of the document-literal and RPC-literal bindings as well as the more traditional RPC-encoded binding. We will now look at examples that encompasses of server side development of Web services with Application Developer V5.1.
We will focus on the differences from previous versions of the tool that result from support for JSR-109 or WS-I. The examples assume
familiarity with basic Application Developer tasks such as creating projects of various types, creating and editing files of various types,
running various wizards, including older versions of Web services wizards. If you are not familiar with such tasks, the help provided by
Application Developer is quite extension and should assist you in getting started. You can also refer to articles on earlier versions of the
tool; see the references for more information.
The Web container The first example examines the process for turning a JavaBean into a Web
service in the Web container, to be consistent with earlier Web services
examples. The basic JavaBean we will use is a simplistic implementation
of ubiquitous stock quote service, and is shown in the following code segment.
The StockFullQuote JavaBean uses as a return value what JSR-101 calls a "value type"
data bean called FullQuote, also shown in the code segment. For use with the EJB example
later in the article, FullQuote must be serializable. package wstest;
import java.util.Random;
public class StockFullQuote {
Random r = new Random();
public FullQuote getQuote(String symbol) {
int base = r.nextInt(100);
return new FullQuote(symbol, base+2, base+3, base+1);
}
}
package wstest;
public class FullQuote implements java.io.Serializable {
private String symbol;
private float current;
private float high;
private float low;
public FullQuote() {
}
protected FullQuote(String s, float c, float h, float l) {
symbol = s;
current = c;
high = h;
low = l;
}
public float getCurrent() {
return current;
}
public float getHigh() {
return high;
}
public float getLow() {
return low;
}
public String getSymbol() {
return symbol;
}
public void setCurrent(float float1) {
current = float1;
}
public void setHigh(float float1) {
high = float1;
}
public void setLow(float float1) {
low = float1;
}
public void setSymbol(String string) {
symbol = string;
}
} |
Creating the Web service We will first create a Web project in which to develop and deploy the Web service. Application Developer allows two
different forms of Web project; static Web projects are optimized for projects that contain static content such as HTML files; dynamic Web
projects can contain dynamic components such as servlets and JSPs. We must create a dynamic Web project; we will call it
"Services." Next we add the two JavaBeans described above the in the 'wstest' package to the Services project. When complete, the
Navigator view of the Web perspective should look like Figure 1.
Figure 1. Services project after JavaBean creation.
Next, we will use the new Web Services Wizard to turn the FullStockQuote bean into a J2EE-compliant Web
service and generate all the necessary artifacts for deployment. As with earlier versions of Application Developer, we start the wizard by
right-clicking on the StockFullQuote bean, then selecting New => Other => Web Services => Web Service => Next. The first
panel of the wizard, named Web Services, is the same as the previous versions of Application Developer; you can simply click Next. In
the next two panels, Service Deployment Configuration and Web Service JavaBean Selection, all the defaults are acceptable, so click Next
in each. You should now see the Web Service JavaBean Identity panel, shown in Figure 2.
Figure 2. Web Services Wizard: Web Service JavaBean Identity.
Figure 2 contains the first indication of the support for J2EE Web services. In the Style and Use section of the panel, there are three
combinations of style and use: Document/Literal and RPC/Literal are the two acceptable to WS-I, while RPC/Encoded is retained for older style
Web services interactions. If we select either of the first two options and click Next, the wizard proceeds normally. If we select
RPC/Encoded, however, the warning shown in Figure 3 is displayed to indicate the potential for interoperability problems due to the lack of
compliance with WS-I. Instead, we select Document/Literal and click Finish to complete the creation of the Web service.
Figure 3. Web Services Wizard: Interoperability Warning.
The artifacts The Web services wizard proceeds to create all of the artifacts necessary for a J2EE Web service. Figure 4 shows the
Navigator view of the Web perspective after the wizards has completed. The wizard has created the following Java classes:
- StockFullQuote_SEI
- This class defines the JSR-109 service endpoint interface (SEI) for the
Web service. It can be used by the client, or by implementers trying to
produce other implementations.Per JSR-109, the interfaces extends
java.rmi.Remote and has the same methods
as the Web service JavaBean, in this case getQuote().
- FullQuote_Deser, FullQuote_Ser, FullQuote_Helper
- These utility classes serve to allow Web service engines deserialize and
serialize the
FullQuote JavaBean. The first two actually do the (de)serialization and the third is used to
"find" the serializers and deserializers. These three utility
classes are not mandated by JSR-109, but they are used by the WebSphere
Web services runtime. While they are not referenced in any of the other
artifacts, the runtime infers the class names from schema information in
the WSDL file. If there were other complex data types in the SEI, the wizard would produce
corresponding utility classes for them as well.
Figure 4. Services project after Web service creation.
The wizard also produces a WSDL file for the Web service and, per JSR-109,
places it in the WEB-INF directory. The wizard puts a copy of the file in a WSDL directory under Web Content
for use by other Application Developer tools like the WSDL Browser. If you open the WSDL file StockFullQuote.wsdl,
by default you will open it with the new WSDL Editor. Figure 5 shows
the graphical pane of results of opening that file; Figure 5 does not show
the lower panes of the editor that offers textual details when you click on items in the graph.
Figure 5. WSDL Editor showing StockFullQuote.wsdl.
You can double click on the right-pointing blue arrow in the Types area, to expand the graphical definition of the schema, i.e., the types
and elements defined for the Web service. If you expand everything by clicking on the + symbols, you will see the full schema as shown
in Figure 6. You can switch between the graphical view in Figure 6 and a source view using the tabs at the lower left of the WSDL Editor.
Figure 6. WSDL Editor showing schema.
Return to the graph in Figure 5 by clicking on the left-pointing blue arrow at the upper left of the editor. Expand the
service element in the services area, then expand the PortType element, the operation and finally expand the messages. Figure 7 shows a
composite of the results of expansion, after clicking the input for the getQuote method on the top and clicking output
for the getQuote method on the bottom. As before, if you click on any item, you will see details in the lower panes of the
editor. You can easily see that the WSDL service element is named StockFullQuoteService (assigned by the wizard), and it contains a WSDL port
element named StockFullQuote which implements a WSDL portType also named StockFullQuote.
Figure 7. WSDL Editor showing expanded WSDL service element.
In Figure 4, you can also see the wizard has created Web services deployment descriptor for the server,
webservices.xml and placed it in the WEB-INF directory, as defined in JSR-109. The deployment descriptor defines to the
Web services environment the various deployment aspects of Web services for that environment. You can double-click on webservices.xml
to open it with the new Web Services Editor. Figure 8 shows the editor viewing webservices.xml for the Services project.
The tabs at the bottom of the editor let you navigate between the various aspects of the deployment descriptor. Figure 8 shows the
Web Services view, where you can see the StockFullQuoteService produced by the wizard. On the right side, you can see references to the WSDL
file described above and a mapping file, discussed below. You can also see a list of the ports, in this case the single port, StockQuoteFull,
defined for StockFullQuoteService.
Figure 8. Web Services Editor for the Services project - Web Services view.
Figure 9 shows the Ports Components view of the deployment descriptor. In this case, we see the required service endpoint interface
and implementation bean information. In this case, since we've used a Java bean in the Web container for the service implementation,
the latter contains a servlet link that associates the actual implementation class defined in web.xml. The following snippet of
web.xml shows how the linkage works to define the actual implementation of the service as the original StockFullQuote
JavaBean. <servlet>
<servlet-name>wstest_StockFullQuote</servlet-name>
<servlet-class>wstest.StockFullQuote</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet> |
For this simple service, no additional information is contained in webservice.xml.
Figure 9. Web Services Editor for the Services project - Port Components
view.
JSR-109 requires a mapping deployment descriptor that contains information
to correlate the mapping between the Java interface for the Web service
and WSDL definition of the Web service. As you can see from Figure 4 and
Figure 8, the wizard generates the mapping deployment descriptor, in this
case called StockFullQuote_mapping.xml, and references it appropriately in webservices.xml.
We will not examine the details, but Figure 10 shows a high level view
of the mapping file using Application Developer's XML Editor.
Figure 10. Mapping Deployment Descriptor.
Testing the Web service We will use Application Developer's Web Services Explorer to test the StockFullQuote service. The Web Services Wizard
probably already published the Services project to a WebSphere V5.0.2 test server and started the server; if that did not happen do so now.
Launch the Web Services Explorer (click the  icon) and bring up
the WSDL page (click on  icon). In the Navigator pane, click WSDL
Main to bring up the Open WSDL pane. In that pane, click Browse and you'll see the WSDL Browser dialog. In that dialog, you
can select the Services project and the StockFullQuote.wsdl file and click Go, then click Go in the Open WSDL pane
of the Explorer. In the Navigator pane of the Explorer, expand the WSDL and components in it until you see the getQuote operation; click
getQuote and you should see the Action pane appear as shown in Figure 11.
Figure 11. Web Services Explorer Action Pane.
Now enter any string in the text input field labeled 'symbol' and click Go. The Status pane (see Figure 12) now
shows the response from the Web service with a symbol of "xyz." If you want to see the details of the SOAP request and response,
click on the Source link. Figure 13 shows the results. From those results we conclude the Web service has been successfully created
and deployed in the Web container, compliant with JSR-109, all with little more than a few clicks.
Figure 12. Web Services Explorer Status Pane.
Figure 13. Web Services Explorer Status Pane - Source.
The EJB container We now look at server side support for the EJB container. First create
an EJB project called "EJBServices." Put the EJB project in a
different EAR project than the projects associated with the Web container
example; this minimizes the server restarts needed. Within the EJB project
create a stateless session EJB called "StockFullQuoteEJB" in
the package "wstest." Copy the FullQuote Java class from the Services project into the wstest
package of the EJBServices project. Add the following as a "business
logic" to StockFullQuoteEJBBean class, and promote the getQuote method to the remote interface. Random r = new Random();
public FullQuote getQuote(String symbol) {
int base = r.nextInt(100);
return new FullQuote(symbol, base+2, base+3, base+1);
} |
Now generate the deployment and RMIC code for the EJBServices project.
Add the project to the server and start the server if it not already started.
You may wish to test the EJB with the Universal Test Client to ensure the
EJB is working properly. When you finish, the Navigator view of the EJBServices
project looks like Figure 14
Figure 14. EJBServices project.
Creating the Web service To create a Web service from an EJB, we must first create a Web project
will serve as the "router" for Web service requests directed
at the EJB. Create a new dynamic Web project called MoreServices and deploy
it in the same EAR as the EJBServices projects. Now we will use the new Web Services Wizard to turn the EJB into a JSR-109 compliant Web service. In the J2EE Hierarchy
view, right-click on the StockFullQuoteEJB bean and select New => Other => Web Services => Web Service => Next to start the wizard. In
the Web Services panel, you should find the Web service type already selected as EJB Web service, so click Next. In the subsequent
Service Deployment Configuration panel shown in Figure 15, ensure that the Router project is set to MoreServices and that the EJB Project is
set to EJBServices, then click Next.
Figure 15. Web Services Wizard: Service Deployment Configuration.
In the subsequent Web Service EJB Selection panel, shown in Figure 16, you will see the information needed to route
requests from the servlet that receives the SOAP/HTTP request to the EJB. All the fields should be correct by default, so click Next.
Figure 16. Web Services Wizard: EJB Selection.
The subsequent Web Services Java Bean Identity panel is the same format as for the Web container example above (see
Figure 2). Some of the fields contain slightly different information to reflect the differences between the Web contain deployment and EJB
contain deployment of Web services; for example, the WSDL files is place in the META-INF directory of the EJB project instead of the WEB-INF
directory of the Web project. You should click Finish to let the wizard complete the necessary actions.
The artifacts Figure 17 shows the EJBService project after the wizard has finished. Packages without changes are collapsed. In the
wstest package, the wizard produces several classes like those produced for the Web container example; FullQuote_Deser,
FullQuote_Helper, and FullQuote_Ser are identical. Because the "business interface" is identical to the Web container
example, the implementation StockFullQuoteEJB_SEI is identical to that of StockFullQuote_SEI above. The Java
artifact, StockFullQuoteEJB_RI fulfills the JSR-109 requirements for a remote interface that exposes both standard EJB methods
and the "business interface" methods.
Figure 17. EJBService project after Web service creation.
Figure 17 also shows that the other required artifacts have been generated, but in this case in the META-INF
directory. You can see the WSDL file, the mapping deployment descriptor file, and the Web services deployment descriptor,
webservices.xml. Only that latter differs significantly from those artifacts produced for the Web container, because it is describing
an EJB Web service implementation. As you can see in Figure 18, the port component implementation details section indicate the Web service is
an EJB.
Figure 18. Port components in webservices.xml for EJBServices.
Testing the Web service We will use Application Developer's Web Services Explorer to test the StockFullQuoteEJB service as well. You might need
to restart the WebSphere V5.0.2 test server. Launch the Web Services Explorer if it is not running and browse to the MoreServices project and
the StockFullQuoteEJB.wsdl file and click Go, then click Go in the Open WSDL pane. In the Navigator pane of the
Explorer, expand the WSDL and components in it until you see the getQuote operation; click getQuote and you should see the Action pane
appear as shown in Figure 11. Enter a string in the text entry field labeled symbol and click Go. You will see a result something like
that shown in Figure 19, indicating successful invocation of the EJB. The results demonstrate that the Web service has been successfully
created and deployed in the EJB container, compliant with JSR-109, all with little more than a few clicks.
Figure 19. Web Services Explorer Status Pane.
Conclusion As you can see, Application Developer V5.1 makes it very easy to create, deploy, and test interoperable Web services in a JSR-109
compliant environment like WebSphere V5.0.2. For both Web container and EJB container based Web services, Application Developer can create
virtually all of the necessary artifacts. If changes in those artifacts are needed, Application Developer provides specialized editors to
greatly simplify the task. Application Developer V5.1 can really accelerate your Web services development for the J2EE environment!
Resources
About the author | | | Greg Flurry is a Senior Technical Staff Member in IBM's Emerging Technologies group
in Austin, Texas. His responsibilities include advancing IBM's e-business
technologies. You can contact Greg at flurry@us.ibm.com. |
Rate this page
| |
