Development and Deployment Guide

Develop and deploy J2EE Web services usingWebSphere Application Server Community EditionCreate a J2EE sample brokerage application using EclipseWTP tooling

Skill Level: Intermediate

Manu T. George ([email protected])Staff Software EngineerIBM

21 Mar 2007

Java™ 2 Platform, Enterprise Edition (J2EE) 1.4 supports two types of Web serviceendpoints: Plain Old Java Object (POJO) and Enterprise JavaBeans (EJB)endpoints. IBM® WebSphere® Application Server Community Edition (also referredto as Community Edition in this tutorial) is a J2EE 1.4-certified application server thatprovides support for these two types of Web service endpoints. This tutorial showsyou how to use the Eclipse Web Tools Platform (WTP) to create an enterpriseapplication that implements both POJO and EJB Web service endpoints, using IBMDB2® Express-C as the database for the application. You'll use the CommunityEdition server adapter (formerly known as the Eclipse plug-in) to deploy theapplication to an Community Edition instance. And finally, you'll develop a client tocall the Web services.

Section 1. Before you start

About this tutorial

This tutorial shows you how to use many of the tools included in the Eclipse WebTools Platform (WTP) to create a J2EE sample brokerage application that

Develop and deploy J2EE Web services using WebSphere Application Server Community Edition© Copyright IBM Corporation 1994, 2008. All rights reserved. of 49

mailto:[email protected]

http://www.ibm.com/legal/copytrade.shtml

implements both POJO and EJB Web service endpoints. You'll use IBM DB2®Express-C as the database for the application, and you'll use the Community Editionserver adapter to deploy the application to an Community Edition instance.Afterward, you'll use the Eclipse WTP Web service testing functions to test your Webservices and write clients to invoke them.

Prerequisites

To succeed with this tutorial, you should be familiar with Java development ingeneral and, specifically, server-side Java development. You should understand thegeneral concepts behind relational databases and be familiar with basic J2EEconcepts, such as deployment descriptors and WAR archives. You should also befamiliar with XML, XML schemas, Eclipse, and the Eclipse WTP. Prior experiencewith application servers, Web services, and relational databases is alsorecommended.

System requirements

You need to download the following required (no-charge) applications to follow alongwith this tutorial and work with the sample code included:

• IBM DB2 Express-C 9

• IBM WebSphere Application Server Community Edition V1.1

• The WebSphere Application Server Community Edition server adapter(formerly called the Eclipse plugin)

• The Eclipse IDE with Web Tools Platform

• The Java Web Services Developer Pack (Java WSDP) 2.0

• JDK 1.4.2_08 from Sun Microsystems

Your hardware configuration should include the following:

• Support for the JDK/JRE listed above with at least 512MB of mainmemory (1GB recommended)

• At least 10MB of additional free disk space to install the softwarecomponents and examples

The instructions in this tutorial are based on a Microsoft® Windows® operatingsystem. All of the tools and techniques covered in this tutorial also work on Linux®and UNIX® operating systems.

developerWorks® ibm.com/developerWorks

Develop and deploy J2EE Web services using WebSphere Application Server Community Edition of 49 © Copyright IBM Corporation 1994, 2008. All rights reserved.

http://www.ibm.com/developerworks/downloads/im/udbexp/?S_TACT=105AGX44&S_CMP=WASCE

http://www.ibm.com/developerworks/downloads/ws/wasce/?S_TACT=105AGX44&S_CMP=WASCE

http://download.boulder.ibm.com/ibmdl/pub/software/websphere/wasce/updates/?S_TACT=105AGX44&S_CMP=WASCE

http://download.eclipse.org/webtools/downloads/

http://java.sun.com/webservices/downloads/2.0_preview_webservicespack.html


Section 2. Get started -- an overview of J2EE Webservices

A Web service is a software component that can be invoked over a network and thatuses a standardized XML messaging system for data exchange. It can be accessedover standard network protocols, such as Simple Mail Transfer Protocol (SMTP) andHTTP using SOAP as the messaging system. A Web service is described via theWeb Services Description Language (WSDL) specification (see Resources for a linkto more WSDL content), and it can be registered in a Universal Description,Discovery, and Integration (UDDI) registry where interested clients can look up theservice. The clients of the Web service can be written in any language and on anyplatform, and they can invoke the service by following the rules in the WSDL file.

Two of the important specifications that are used by Web services are:

• WSDL -- A language for describing Web services as a set of endpointsoperating on messages containing either document-oriented orprocedure-oriented information.

• SOAP -- An XML-based object invocation protocol (see Resources for alink to more SOAP content).

In J2EE 1.4, Web services can be implemented using two types of endpoints:POJOs, or servlet endpoints, and EJB endpoints:

• A Web service is called a POJO Web service if the serviceimplementation class is an ordinary java object. In Community Edition,such a Web service is registered as a servlet in the Web application'sdeployment descriptor.

• A Web service is called an EJB Web service if the service implementationclass is a stateless session bean, and the methods in the session beanclass are exposed for invocation using SOAP calls.

Implement J2EE Web services in Community Edition

Community Edition V1.1 supports J2EE Web services by using Apache Axis 1.4(see Resources for a link to more information on Axis). Axis is a Web service runtime from the Apache Software Foundation. It's configured using GBeans and isplugged in to Community Edition. It provides support for both types of J2EE Web

ibm.com/developerWorks developerWorks®



service endpoints described earlier. In the case of a POJO Web service, therequest-response flow is shown in Figure 1. Note: This graphic presents a simplifiedview, and it doesn't show all the details of the integration of Axis with CommunityEdition.

Figure 1. POJO Web service handling in WebSphere Application ServerCommunity Edition

In the flow of events depicted in Figure 1, first the Web service is deployed in theserver using custom Community Edition deployers. During the deployment process,all the information in the deployment descriptor is extracted by the deployer andpopulated into a GBean -- namely, AxisWebServiceContainer. Now, during thestartup of the application, all the servlets are registered with Tomcat. During theregistration process, a custom servlet called POJOWebServiceServlet is registeredfor URLs corresponding to POJO Web services. The AxisWebServiceContainerand the POJO representing the Web service are put in the ServletContext, and theircorresponding keys are passed to the POJOWebServiceServlet as initializationparameters. Now, whenever the Web service is invoked using its configured URL,the POJOWebServiceServlet is invoked, and it looks up theAxisWebServiceContainer and POJO and passes them to Axis along with therequest and response objects. Axis then invokes the required method on the POJOand returns the response. In the case of an EJB Web service, the EJB container --OpenEJB -- also comes as a layer between the request and response. A simplifiedrepresentation of the request-response flow in the case of an EJB Web service isshown in Figure 2.

Figure 2. EJB Web service handling in WebSphere Application ServerCommunity Edition

Note that the enterprise bean is hosted in the EJB container. It's invoked by theEJBContainerProvider class, which is the pivot handler that's registered in Axis.




So, the pivot handler, which is a custom one packaged with Community Edition,takes care of invoking the session bean deployed in the OpenEJB container. Also, avalve is registered -- EJBWebServiceValve -- which lets the Web service requestsbe processed in a custom manner. This valve takes care of invoking the methods onthe AxisWebServiceContainer class.

Section 3. Application overview

The application included with this tutorial (see the Download section) represents anonline brokerage tool that's used to buy and sell stocks. The application has thefollowing five pages:

• Login

• Registration

• User Details

• Available Stocks

• User Portfolio

The application provides the following two Web services:

• StockService

• UserStockService

Figure 3 shows the application flow.

Figure 3. Online brokerage application flow




The user is first shown the Login page. From there, the user enters his or her username and password and submits the page. After validation of the user's credentials,the Available Stocks page is displayed, where the user can view all the stocks thatare for sale on the exchange at that time. The user can choose to buy any stock(provided there's enough money in his or her account) by clicking the Buy button.After the transaction completes successfully, the user is brought back to theAvailable Stocks page.

Clicking the View Your Portfolio link takes the user to his or her portfolio, whichshows all the stocks the user owns. The user can sell whichever stock he or sheowns from this page. This page also shows the user's free cash in the user cashfield. If the user is new, he or she can go to the Registration page by clicking theRegister button on the Login page. The user can then enter all the fields and clickSubmit to register. He or she can also view the available stocks and his or herportfolio in a stand-alone client by invoking two Web services: StockService andUserStockService, respectively.

Section 4. Set up the database




Create the database using the DB2 Express-C Control Center

In the following section, you'll create a database and tables for users and groups inthe DB2 Express-C Control Center by using the following steps:

1. Open the Control Center.

2. Right-click All Databases, and select Create Database > Standard.

3. Enter TRADEDB as the database name.

4. Click Finish.

A new database called TRADEDB is created and listed under All Databases (seeFigure 4).

Figure 4. New database listing

Create tables using the Control Center




In the previous section, you created a database called TRADEDB. Now you'll createtables for users (USERS), stocks (STOCKS), and user accounts(TRADINGACCOUNT) within that database. The fields within the different tables areshown in Table 1.

Table 1. USERS

Field name Data type Key

userid VARCHAR(15)PRIMARYKEY NOTNULL

name VARCHAR(50)

password VARCHAR(24)

address VARCHAR(96)

cash DECIMAL

Table 2. STOCKS


ID VARCHAR(8)PRIMARYKEY NOTNULL

name VARCHAR(100)

Price DECIMAL

Table 3. TRADINGACCOUNT


userid VARCHAR(15)FOREIGNKEY NOTNULL

stockid VARCHAR(18)FOREIGNKEY NOTNULL

quantity INT

To create the tables, follow this procedure:

1. Click Tables under TRADEDB, then right-click Create.

2. Enter USERS as the table name, and click Next.

3. Add a column to the table, then click Add and enter the column name.




4. Select Data type (nullable or not), and click Apply.

5. Repeat steps 3 and 4 to add and name all columns.

6. Click Next > Next > Next to navigate to the screen titled Define keys onnew table. Click Add Primary.

7. From the available columns, select the column for primary key, and clickFinish.

8. Follow steps 1-7 to create all three tables.

9. Right-click the TRADINGACCOUNT table, then click Select alter.

10. In the dialog box shown, select the Keys tab.

11. Click Add Foreign.

12. In the PARENT table (or nickname section), select the schema as theschema where you have created these tables.

13. Select STOCKS as the name of the table. This shows the primary keySTOCKS in the primary key list.

14. In the Available columns section, select STOCKID, and click the > button.

15. Click OK.

16. Repeat this procedure, and map the USERID field of the USERS table toUSERID of TRADINGACCOUNT.

After you complete the previous steps, the tables are created under theADMINISTRATOR schema. (Note: Schema assignment depends on the Windowslogin that you're using. If you log in as db2admin, the tables are created under theDB2ADMIN schema.) After creation, the tables can be viewed in the DB2 Express-CControl Center, as shown in Figure 5.

Figure 5. Tables in DB2 Express-C Control Center




Put values into tables

Now follow these instructions to populate the tables with values (see Figure 6):

1. Select the USERS table from the TRADEDB Tables area.

2. Right-click USERS, then click Open > Add row.

3. Enter the values, and select Commit.

4. After you've entered all values, click Close.

5. Follow the same steps for all other tables. Note that you can use thevalues in the db2_brokerage.sql file, which is in the sql directory.

Figure 6. Putting values into tables




Create a table using scripts

Alternatively, you can also create the database, tables, and data using an SQL scriptby performing the following steps. The sample in this tutorial has a script file calleddb2_brokerage.sql; execute this script from a DB2 command line to create thedatabase and tables as follows:

1. Create a DB2 command window from the Windows command prompt bytyping db2cw. This opens another command window for entering DB2commands.

2. Execute the script file from the DB2 command window (db2 -tvfdb2_brokerage.sql). This path should be given if db2_brokerage.sql is inthe same directory where the command is executed. Otherwise, you mustgive the full path instead of db2_brokerage.sql.

If there are no errors, you should see all SQL commands executed successfully. Thescript creates the database and all the related tables, as shown in Figure 7.

Figure 7. Database and related tables




Section 5. Create the Web application

This section gives you detailed steps on using the Eclipse WTP to create a Webapplication.




Install the server run time

Create a new Community Edition V1.1 server run time by following these steps:

1. Run Eclipse WTP by double-clicking eclipse.exe from the location whereyou extracted the WTP platform. You can also run eclipse.exe from thecommand line.

2. Click Window > Open Perspective > Other > J2EE to open the J2EEperspective.

3. Select the Servers tab at the bottom right of the screen.

4. Right-click New > Server.

5. Select IBM > WebSphere Application Server Community Edition v1.1Server, then click Next.

6. In the next screen, select the appropriate JRE, and fill in the ApplicationServer Installation Directory field with the installation directory(C:\ProgramFiles\IBM\WebSphere\AppServerCommunityEdition), then clickFinish. An Community Edition V1.1 instance is created in the Serversview.

Develop the application

In this section, you'll create a WAR file that contains pages for the application, andyou'll add it to an EAR file.

Create a Web application

Create a Web application by following these steps:

1. Run Eclipse WTP by double-clicking eclipse.exe from the location whereyou extracted the WTP platform. You can also run eclipse.exe from thecommand line.

2. Select File > New Project > Web > Dynamic Web project.

3. Enter BrokerageWebApp for the project name, and enter WebsphereCommunity Edition Server 1.1 as the target run time.




4. Click Next > Next.

5. Enter the context root /brokerage.

6. Click Next.

7. Configure the Geronimo Deployment Plan as follows:

• Under Group ID, enter wasce-samples.

• Under Artifact ID, enter brokerage-web.

• Under Version, enter 1.0.

• Under Artifact Type, enter war.

8. Click Finish.

Create an enterprise application

Create an enterprise application by following these steps (see Figure 8):

1. Run Eclipse WTP by double-clicking eclipse.exe from where youextracted the WTP platform. You can also run eclipse.exe from thecommand line.

2. Select File > New Project > J2EE > Enterprise application project.

3. Enter BrokerageApp for the project name, and enter WebsphereCommunity Edition Server 1.1 as the target run time.

4. Click Next > Next.

5. Check both BrokerageEjb and BrokerageWebApp in the J2EE Modulesto add to the EAR page.

6. Click Next.

7. Configure the Geronimo Deployment Plan as follows:

• Under Group ID, enter wasce-samples.

• Under Artifact ID, enter brokerage.

• Under Version, enter 1.0.

• Under Artifact Type, enter car.

8. Click Finish.




Figure 8. Create the applications within Eclipse WTP

Import the source files into Eclipse WTP

1. Select and expand the BrokerageWebApp project.

2. Right-click the BrokerageWebApp project, and select Import > Import.

3. From the Import dialog box, select General > File System, and clickNext.

4. From the File System dialog box, browse to where you extracted thecompressed file provided with the article, and in From Directory, select<zip-file-directory>/web-src/.

5. Expand the web-src directory in the left pane, and select com.

6. Select Into Folder as the BrokerageWebApp/src, and click Finish.

7. Similarly, import the source files in <zip-file-directory>/ejb-src/ toBrokerageEjb/ejbModule.

8. Right-click BrokerageWebApp, and select Build Path > ConfigureBuild Path.

9. In the Java Build Path dialog box, select the Projects tab.

10. Click Add, select BrokerageEjb in the Required Project Selection dialogbox, then select OK.

11. Return to the Java Build Path dialog box, and select OK.

12. Clean the projects.

You now have all the classes imported. To import the JavaServer Pages (JSP) files,perform the following steps. The JSP files are also imported into Eclipse:

1. Right-click BrokerageWebApp, and select Import > Import.

2. In the Import dialog box, select General > File System, then click Next.

3. From the File System dialog box, browse to the JSPs directory in thebrokerage.zip file, which contains all the JSPs, and click OK. The JSPsare listed in the right pane.

4. Select all the JSPs, change the Into folder to point toBrokerageWebApp/WebContent, and click Finish. This imports all theJSP files to the WebContent directory.

Section 6. Use XDoclet to generate J2EE artifacts inEclipse WTP

You can choose to develop classes manually or use XDoclet. To create anenterprise bean using XDoclet, use the following steps:

1. Right-click the package you want your EJB class to belong to.

2. Select New > Other.

3. In the New dialog box, select JB/XDoclet Enterprise JavaBean, andclick Next. (Note: If you get an error stating that the annotation provider is




not set correctly, go to Window > Preferences > Xdoclet, and click theXDoclet. Set the XDoclet Home tag to point to the home directory ofXDoclet in your system. Select the right version, and click OK.)

4. Select Session Bean, then click Next.

5. In the Enterprise JavaBean dialog box, enter the relevant information, andclick Next.

6. Continue entering the remaining information, and then click Next >Finish.

XDoclet makes it convenient to generate much of your boilerplate code, because itallows you to create many other necessary J2EE artifacts. Because you've alreadyimported all the EJB components needed for this application, it's not necessary to gothrough this step.

Section 7. Generate the WSDL files and mapping filesfor Web services

As mentioned earlier in this tutorial, this application contains two Web services: Oneis exposed as a servlet endpoint, and the other is exposed as an EJB endpoint.Community Edition doesn't provide a mechanism for generating the Java API forXML-based RPC (JAX-RPC) mapping files. You can use the Apache AxisWSDL2Java and Java2WSDL tools to generate the WSDL/Stubs, but you need touse the wscompile utility of the Java WSDP to generate the JAX-RPC mapping files.You can also use the Java WSDP to generate the WSDL. In the Java WSDPdirectory of the sample application archive provided with this article, you'll find theconfiguration files that you can use to generate the WSDL and JAX-RPC mappingfiles for the two Web services -- config_s for StockService and config_us forUserStockService. The commands for running wscompile to generate the mappingfiles are given in Listings 1 and 2. (Note: The lines in these two listings were brokendue to space constraints.)

Here, <dest-dir> equals the absolute path of the directory to put the generated

classes, WSDL, and mapping files. <workspace> equals the absolute path of theEclipse workspace directory. And <wasce_home> equals the Community Editioninstallation directory.

Listing 1. Commands for running wscompile to generate mapping files

wscompile -gen:server -d <dest-dir> -mapping<dest-dir>\mapping.xml -cp "<wasce_home>\repository\org\apache\geronimo\specs\geronimo-j2ee_1.4_spec\1.1\geronimo-j2ee_1.4_spec-1.1.jar;<workspace>\BrokerageEjb\build\classes;<workspace>\BrokerageWebApp\build\classes;"C:\wscompile\config_s.xml

Listing 2. Commands for running wscompile to generate mapping files,continued

wscompile -gen:server -d C:\wscompile -mappingC:\wscompile\mapping.xml -cp"<wasce_home>\repository\org\apache\geronimo\specs\geronimo-j2ee_1.4_spec\1.1\geronimo-j2ee_1.4_spec-1.1.jar;<workspace>\BrokerageEjb\build\classes;" C:\wscompile\config_us.xml

Note: After installing the Java WSDP, you can add <JWSDP_HOME>\jaxrpc\binto the PATH environment variable so that you can access wscompile from thecommand prompt. The default value of JWSDP_HOME is C:\Sun\jwsdp-2.0.

After generating the WSDL and mapping files for each Web service, put them in theappropriate locations in the Eclipse projects:

• For the stateless session bean endpoint (such as UserStockService), putthe mapping.xml file directly inside the META-INF directory in ejbModule.

• Inside the same directory, create a subdirectory called wsdl, and copy theWSDL file to that directory.

• Similarly, for the servlet endpoint, copy the mapping.xml file to theWEB-INF directory and the WSDL file to WEB-INF/wsdl.

(Note: If you're using the same destination directory, generate the files for one Webservice first, and after copying the files, clean the output directory before generatingthe files for the next Web service. You can also access the generated files from thegenerated files directory in the brokerage directory.)

Section 8. Write the deployment descriptors

In this section, you learn about writing the J2EE- and Geronimo-specific deploymentdescriptors.

Write the J2EE-specific deployment descriptors

Because you have EJB servlets and Web services together in this application, youneed to write five J2EE deployment descriptors -- one each for the Web module, theEJB module, and the EAR file, and two for the two Web services. All the descriptorsare present in the j2ee-descriptors directory. (Note: Going through the individualdeployment descriptors and what their elements mean is beyond the scope of thistutorial; you can refer to the J2EE specification for this information.)

Because the Eclipse WTP provides schema-based editors for each of the plans, youdon't need to manually write these descriptors. To create plans using the editor,follow these steps, and refer to Figure 9:

1. Within Eclipse, select the BrokerageWebApp project, and expand it toshow its contents.

2. Click Deployment Descriptor to open the web.xml file in an editor.

3. Select the Design tab of the editor to open a new editor showing a treestructure.

4. Right-click the web-app to display all the possible operations you can dousing the editor. The editor shows all the children you can add andremove.

5. Refer to the deployment descriptors in the j2ee-descriptors directory ofthe brokerage.zip file, and create the descriptors. Alternatively, you canjust import the descriptors to the META-INF and WEB-INF directories.

Figure 9. Create the applications within Eclipse WTP




Write the Geronimo-specific deployment descriptors

Next, you need to write the Geronimo-specific deployment descriptors for the Web(geronimo-web.xml) and EJB (openejb-jar.xml) modules and the entire enterpriseapplication (geronimo-application.xml). The descriptors are shown below and arealso present in the Geronimo-descriptors directory.

Deployment descriptor #1: geronimo-web.xml

The geronimo-web.xml file is created in the WEB-INF directory of the web-app:

1. Double-click the geronimo-web.xml file, which opens the CommunityEdition Deployment Plan Editor, as shown in Figure 10.Figure 10. Deployment Plan Editor




2. Click the Naming tab of the Community Edition Deployment Plan Editor.

3. In the Resource References section, click the Add button. This brings upthe Resource Reference Details screen.

4. Enter jdbc/TradeDB as the Reference Name, and enter TradeDS asthe Resource Link.

5. Click Finish.Figure 11. Resource Reference Details




6. Click the Deployment tab in the Community Edition Deployment PlanEditor to open the Deployment Configuration screen.

7. Click Add, and add two dependencies with the following details:

• Group ID: geronimo

• Artifact ID: axis

• Version: 1.1

• Artifact type: car

• Group ID: console.dbpool

• Artifact ID: TradeDS

• Version: 1.0

• Artifact type: rar

8. This creates the deployment plan for the Web application. When you clickthe Source tab, the contents of the plan should appear as shown inListing 3. Alternatively, you can enter the contents of Listing 3 directly intothe Source editor.Listing 3. Entry into the Source editor




<?xml version="1.0" encoding="UTF-8"?><web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.1" xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"><sys:environment>

<sys:moduleId><sys:groupId>wasce-samples</sys:groupId><sys:artifactId>brokerage-web</sys:artifactId><sys:version>1.0</sys:version><sys:type>war</sys:type>

</sys:moduleId><sys:dependencies><sys:dependency>

<sys:groupId>geronimo</sys:groupId><sys:artifactId>axis</sys:artifactId><sys:version>1.1</sys:version><sys:type>car</sys:type>

</sys:dependency><sys:dependency>

<sys:groupId>console.dbpool</sys:groupId><sys:artifactId>TradeDS</sys:artifactId><sys:version>1.0</sys:version><sys:type>rar</sys:type>

</sys:dependency></sys:dependencies>

</sys:environment><context-root>/brokerage</context-root><nam:resource-ref>

<nam:ref-name>jdbc/TradeDB</nam:ref-name><nam:resource-link>TradeDS</nam:resource-link>

</nam:resource-ref></web-app>

(Note: Lines two through four in Listing 3 were broken due to space constraints.)

Listing 3 shows the geronimo-web.xml file. Here, the environment tag representsthe Web application environment. It defines the module ID of the Web module aswell as the dependencies -- for example, the modules on which this moduledepends. The context-root tag gives the context root of the Web application tobe /brokerage. The other important tag is the resource-ref tag, which is usedto map the name jdbc/TradeDB to the database pool TradeDS, which you'lldeploy in the following sections. This results in the corresponding data source beingbound to java: comp/env/jdbc/TradeDB in Java Naming and Directory Interface(JNDI).

Deployment descriptor #2: openejb-jar.xml

The openejb-jar.xml file is created in the META-INF directory of the EJB module, asshown in Listing 4.

Listing 4. openejb-jar.xml

<?xml version="1.0" encoding="UTF-8"?><openejb-jarxmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1"xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.1" xmlns:pkgen="http://www.openejb.org/xml/ns/pkgen-2.0" xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"><sys:environment>

<sys:moduleId><sys:groupId>wasce-samples</sys:groupId><sys:artifactId>BrokerageEJB</sys:artifactId><sys:version>1.0</sys:version><sys:type>car</sys:type>

</sys:moduleId><sys:dependencies>

<sys:dependency><sys:groupId>geronimo</sys:groupId><sys:artifactId>tomcat</sys:artifactId><sys:version>1.1</sys:version><sys:type>car</sys:type>

</sys:dependency><sys:dependency>

<sys:groupId>console.dbpool</sys:groupId><sys:artifactId>TradeDS</sys:artifactId><sys:version>1.0</sys:version><sys:type>rar</sys:type>

</sys:dependency></sys:dependencies>

</sys:environment><enterprise-beans>

<session><ejb-name>UserStock</ejb-name><jndi-name>ejb/UserStockBean</jndi-name><nam:resource-ref>

<nam:ref-name>jdbc/TradeDB</nam:ref-name><nam:resource-link>TradeDS</nam:resource-link>

</nam:resource-ref></session>

</enterprise-beans></openejb-jar>

(Note: Lines two through five in Listing 4 were broken due to space constraints.)

The openejb-jar.xml file also contains the module ID and dependency declarations. Ithas a session element that's used to map the name of the bean to a jndi-name inthis case. The resource-ref element is also present. The Community EditionDeployment Plan Editor for openejb-jar.xml is shown in Figure 12.

Figure 12. Deployment plan editor

Deployment descriptor #3: geronimo-application.xml

The geronimo-application.xml file is created in the META-INF directory of the EAR --for example, in the BrokerageApp project in EarContent/META-INF (see Listing 5).

Listing 5. geronimo-application.xml

<?xml version="1.0" encoding="UTF-8"?><applicationxmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"xmlns:sec="http://geronimo.apache.org/xml/ns/security-1.1" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"application-name="BrokerageApp"><sys:environment>

<sys:moduleId><sys:groupId>wasce-samples</sys:groupId><sys:artifactId>brokerage</sys:artifactId><sys:version>1.1</sys:version><sys:type>car</sys:type>

</sys:moduleId></sys:environment>

</application>

(Note: The second and third lines in Listing 5 were broken due to space constraints.)

You don't need to make any changes to this file for this application. The WTP alsoprovides schema-based XML editors for writing the plans. The schema-based editorfor ejb-plan is shown in Figure 13.

Figure 13. Schema-based editor

If double-clicking the Community Edition-specific deployment plan doesn't open it inthe Plan Editor, right-click the Community Edition-specific deployment plan file, andselect Open with Community Edition Deployment Plan Editor. This opens theeditor.

Section 9. Import the project into Eclipse WTP

The sample application bundled with this tutorial contains a source compressed filefor the EAR file, which can be imported into the Eclipse WTP following the stepsbelow:




1. Select File > Import > J2EE, select EAR File, and click Next.

2. Click Browse, select the file to import -- for example, BrokerageApp.ear-- and click Next.

3. Click Next after selecting both the Web and EJB modules.

4. Click Finish.

5. Click I agree in the license dialog. The EAR file is imported, and therespective Eclipse projects are created.

6. Right-click on the BrokerageApp project, and select the TargetedRuntimes option.

7. Select Websphere Community Edition Server v1.1 as the target runtime, and click OK.

8. Rebuild all the projects. Four errors and 16 warnings remain, but ignorethese for the time being.

Define a server

To deploy an application, you first need to create a server in the Eclipse WTP byfollowing the steps below:

1. Right-click within the Servers Tab window, and select New Server (seeFigure 14).Figure 14. Define a new server




2. Select Websphere Application Server Community 1.1 Server, thenclick Next.

3. In the New Server dialog box, fill in the Application Server InstallationDirectory field so that it points to the server home directory, and clickNext.

4. Enter the server details as shown in Figure 15.Figure 15. Populate new server fields




5. Click Finish.

Start the server, and log in to the console

To start the server and log in to the console, follow these steps:

1. In the Servers tab, right-click Community Edition 1.1, and select Start.This starts the server inside Eclipse.

2. When the server status becomes started, right-click the server icon again,and select Launch Community Edition Console.

3. Now enter the user name as system and the password as manager, andclick the Login button. This takes you to the Welcome page of theadministration console.

Deploy the database pool

A database pool is necessary to connect to DB2. You can create this by deploying adatabase pool plan using the wizard that's available in the Community EditionConsole. Do the following:

1. Log on to the Community Edition Console.




2. Under Services, select Database Pools.

3. Select Using the Geronimo Database Pools Wizard.

4. Enter TradeDS in the field Name for Database Pools, and click Next.

5. Enter the details shown in Figure 16, and click Next.Figure 16. Populate the Create Database Pool screen

6. You can test the connection to check for any errors and then deploy thedata source.

7. You may see a license-related error. To work around this error, go backand click the Skip Test and Show Plan button.

8. Copy the deployment plan to a file, and save it asdb2-datasource-plan.xml.

9. Add a dependency to the DB2 license .jar file in the repository, as shownin Listing 6.Listing 6. Add dependency to DB2 license .jar file

<dep:dependency>

<dep:groupId>com.ibm.db2</dep:groupId><dep:artifactId>db2jcc_license_cu</dep:artifactId><dep:version>8.2</dep:version><dep: type>jar</dep:type></dep:dependency>

10. Now you can deploy the pool by deploying this plan. Select the DeployNew option from the console.

11. Select tranql-connector-db2-xa-1.1.rar for the archive anddb2-datasource-plan.xml for the plan.

12. Click Install.

13. Once you deploy the pool, it's started and running. You can also use theplan file, provided in the plans directory of brokerage.zip, after editing theproperties to reflect your database configuration. Remember that the useryou configure in the plan should have access to the schema where youcreated the tables.Figure 17. Installed J2EE connectors

Section 10. Deploy the application

This section describes how to deploy the application using the Admin console. Toget started, follow these steps:

1. Right-click the server icon, and select Add and remove projects.

2. In the Add and Remove Projects dialog box, select BrokerageApp, andclick Add to add this project to the Configured projects list.

3. Click Finish.

4. Right-click the server icon, and select Publish to deploy the application.

Note: If deployment fails with the exceptionjava.lang.IllegalArgumentException: targetPath is absolute,follow these steps:

1. Shut down Eclipse, restart it, and then try again. The problem may stopoccurring.

2. If step 1 doesn't solve the problem, export the .ear file to a temporarylocation, open it with an extraction tool, and remove the http: directoryfrom the WAR file inside the EAR file.

Now you need to deploy this application using the Admin console (see Figures 18and 19).

Figure 18. Deployment using the Admin console




Figure 19. Deployment using the Admin console




Section 11. Test the application

Now that you've successfully deployed the application, it's time to begin the testingprocess. In this section, you'll learn how to use the Web Services Explorer toolprovided within the WTP.

Access the application

Perform the following steps to access the application:

1. Within the Navigator area, select Web Application(BrokerageWebApp).

2. Right-click and select Run As, and then select Run on Server.




3. Choose an existing server. Select Community Edition 1.1, the serveryou defined earlier.

4. If the project is already added, select Next and Finish.

5. The application is available at http://localhost:8080/brokerage/.Figure 20. Access the application

Using the application: Application flow

Now you're ready to try out a few tasks with the application! To get started, followthese steps:

1. Log in to the application by entering the user name j2ee and passwordpassword. You're taken to the Available Stocks page.

2. Under one of the available stocks, enter the quantity 2, and select theBuy radio button.

3. Click the Buy Stock button.




4. After the request is submitted, click the View Your Portfolio link, whichtakes you to the Portfolio screen. You can sell stocks similarly here.Figure 21. Available Stocks page

Figure 22. Portfolio page




5. Click the User Info button to access the page showing user details.Figure 23. User details




6. If you want to register a new user, click the Register button on the Loginpage to access the registration page where you can enter user details.

Invoke and test the Web services

The next step is to test the Web services using the WTP tool.

Web Services Explorer

The WTP provides a tool called Web Services Explorer that lets you test the Webservices you've deployed. The following steps describe how to use the WebServices Explorer to invoke the Web services that you deployed for testing:

1. After the brokerage application is deployed, the Project Explorer pane ofEclipse shows a node called JSR - 109 Web Services.

2. Expand this node to reveal two subnodes called Clients and Services.

3. Expand the Services node to reveal two subnodes representing the twoWeb services that you deployed.Figure 24. Using Web Services Explorer




4. Start the server if it's not already started.

5. Right-click StockService, and select Test with Web Services Explorer.This brings up the screen shown in Figure 25.Figure 25. Test with Web Services Explorer




6. Click the getStocks link under Operations to bring up the Actions screen.

7. Click Go to invoke the Web service. The output is shown in the Statuspane, as shown in Figure 26.Figure 26. The Status pane




Generate the Web services client

The Eclipse WTP also provides the functionality to generate Web services clientsusing the application server's Web service run time. In this application, the run timeis Apache Axis (see Resources for a link to more information on Axis). The followingsteps illustrate the procedure to generate a Web service client using Eclipse:

1. Select File > New > Project > Web > Dynamic Web Project, then clickNext.

2. Give the project name as ServiceClient, and click Finish to create theproject.

3. Once the brokerage application is deployed, the Project Explorer pane ofEclipse shows a node called JSR - 109 Web Services.

4. Expand this node to reveal two subnodes called Clients and Services.

5. Expand the Services node to reveal two subnodes representing the twoWeb services that you deployed.




6. Start the server if it's not already started.

7. Right-click UserStockService, and select Generate Client. This bringsup the screen shown in Figure 27.Figure 27. Web services client

8. Click the BrokerageWebApp Client project link, select Service Client asthe Client project, and click OK.

9. Click Finish. This generates the following classes inside the ServiceClientproject:

• UserStockIF

• UserStockIFBindingStub

• UserStockIFProxy

• UserStockService

• UserStockServiceLocator

Now you can write a client that uses these classes and invoke the Web service inthe Client class:




1. Import the contents in the client directory from the extracted file (providedwith this article) to the respective directories (for example, import web.xmland geronimo-web.xml into WEB-INF; import source files to src; andimport .jsp files to the root of the WebContent directory).

2. In the Client class, create a UserStockServiceLocator instancecall in the getUserStockIFPort method to get a handle to theUserStockIFProxy object. Invoke the getUserStocks method on theproxy to get the result.

Listing 7 shows the code for the client.

Listing 7. Code to invoke the Web services in Client class

package com.dev.trade.client;

import java.io.IOException;import java.rmi.RemoteException;

import javax.servlet.ServletException;import javax.servlet.http.HttpServlet;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;import javax.xml.rpc.ServiceException;

import com.dev.trade.service.UserStockIF;import com.dev.trade.service.UserStockService;import com.dev.trade.service.UserStockServiceLocator;import com.dev.trade.service.types.Stock;

public class ClientServlet extends HttpServlet {

protected void doGet(HttpServletRequest arg0,HttpServletResponse arg1)

throws ServletException, IOException {

listUserStocks(arg0, arg1);}

protected void doPost(HttpServletRequest arg0,HttpServletResponse arg1)

throws ServletException, IOException {// TODO Auto-generated method stublistUserStocks(arg0, arg1);

}

public void listUserStocks(HttpServletRequest request,HttpServletResponse response) throws IOException {

String name = (String) request.getParameter("name");String password = (String)

request.getParameter("password");UserStockService userStockService = (UserStockService)

new UserStockServiceLocator();UserStockIF userStockIF = null;try {userStockIF = userStockService.getUserStockIFPort();

} catch (ServiceException e) {// TODO Auto-generated catch blocke.printStackTrace();

}




Stock[] stocks = null;try {stocks = userStockIF.getUserStocks(name, password);

} catch (RemoteException e) {// TODO Auto-generated catch blocke.printStackTrace();

}response.getWriter().print("<table border=\"1\"

cellspacing=\"1\"><tr><td colspan=\"4\" align=\"center\">" + name + "'s

Stocks</td></tr><tr><td>Id</td><td> Name </td><td> Price

</td><td> Quantity</td></tr>");

for (int i = 0; i < stocks.length; i++) {

response.getWriter().print("<tr><td>" +stocks[i].getId() + "</td><td>"

+ stocks[i].getName() +"</td><td>"

+ stocks[i].getPrice() +"</td><td>"

+ stocks[i].getQuantity() +"</td></tr>");

}

}}

Run the Web service client

The following steps are necessary to run the Web service client:

1. Compile the ServiceClient project.

2. Right-click the server icon in the Servers pane, and select Add RemoveProjects.

3. Select ServiceClient, add it to Configure Projects, and click Finish. TheServiceClient client module is now deployed.

4. Right-click ServiceClient, then select Run on Server > Finish. Thisbrings up the User Stocks client JSP.

5. Enter the user ID J2EE and the password password, then click SubmitQuery to get a listing of the user's stocks.Figure 28. User's stocks

Section 12. Summary

Hopefully this tutorial has helped you learn how to develop Web servicesapplications using Eclipse WTP and the WebSphere Application Server CommunityEdition server adapter. Using many of the tools included with the Eclipse WTP andthe Community Edition server adapter, you created a J2EE sample brokerageapplication. You learned how XDoclet can be configured and used with the WTP togenerate the boilerplate code required in J2EE applications. Along the way, you sawsome of the wizards and editors provided by WTP, as well as specific editorsprovided by the Community Edition server adapter. You learned how to create adata source to connect to DB2 Express-C in Community Edition and how to deploythe application to Community Edition from Eclipse using the server adapter. Yougenerated the mapping and WSDL files required to deploy Web services using thewscompile tool packaged with Sun Microsystem's Java WSDP tool. Finally, you usedthe Web service testing functions provided by the Eclipse WTP to test your Webservices, and you wrote clients to invoke them. I welcome your feedback on thistutorial posted to the developerWorks IBM WebSphere Application ServerCommunity Edition and Apache Geronimo forum.



http://www.ibm.com/developerworks/forums/dw_forum.jsp?forum=541&cat=51

http://www.ibm.com/developerworks/forums/dw_forum.jsp?forum=541&cat=51


Downloads

Description Name Size Download method

Tutorial source code brokerage.zip 65KB HTTP

Information about download methods



http://download.boulder.ibm.com/ibmdl/pub/software/dw/webservices/brokerage.zip

http://www.ibm.com/developerworks/library/whichmethod.html


Resources

Learn

• See "Using the Eclipse Plug-in for WebSphere Application Server CommunityEdition" (developerWorks, April 2006) for more information on the plug-in.

• Visit the WebSphere Application Server Community Edition content area hereon developerWorks for a comprehensive set of tools and resources.

• Get product documentation for WebSphere Application Server CommunityEdition.

• "Get started with WebSphere Application Server Community Edition" (April2006, developerWorks) today using this helpful guide.

• Read the developerWorks article "Using the Web console in WebSphereApplication Server Community Edition" to get started using the Web console.

• Learn more about "Using the Eclipse Plug-in for WebSphere Application ServerCommunity Edition" (developerWorks, April 2006).

• Explore the WebSphere Application Server Community Edition technicalsupport offerings available from IBM.

• Get more information on WSDL.

• Get more information on the SOAP specification.

• Check out the developerWorks Apache Geronimo project area for articles,tutorials, and other resources to help you get started developing with Geronimotoday.

• Visit the Apache Geronimo Web site.

• Check out the IBM Support for Apache Geronimo offering, which lets youdevelop Geronimo applications backed by world-class IBM support.

• Visit the developerWorks Open source zone for extensive how-to information,tools, and project updates to help you develop with open source technologiesand use them with IBM's products.

• Stay current with developerWorks technical events and webcasts.

• Browse for books on these and other technical topics at the Safari bookstore.

Get products and technologies

• Download the WebSphere Application Server Community Edition serveradapter (formerly known as the Eclipse plug-in).

• Download the Eclipse Web Tools Platform from eclipse.org.



http://www-128.ibm.com/developerworks/websphere/library/techarticles/0604_sun/0604_sun.html

http://www-128.ibm.com/developerworks/websphere/library/techarticles/0604_sun/0604_sun.html

http://www.ibm.com/developerworks/websphere/zones/was/wasce.html

http://publib.boulder.ibm.com/wasce/Front_en.html

http://publib.boulder.ibm.com/wasce/Front_en.html

http://www.ibm.com/developerworks/websphere/techjournal/0512_gawor/0512_gawor.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0608_krishnasamy/0608_krishnasamy.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0608_krishnasamy/0608_krishnasamy.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0604_sun/0604_sun.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0604_sun/0604_sun.html

http://www-306.ibm.com/software/webservers/appserv/community/detail/table.html

http://www-306.ibm.com/software/webservers/appserv/community/detail/table.html

http://www.ibm.com/developerworks/search/searchResults.jsp?searchType=1&searchSite=dW&searchScope=dW&query=wsdl

http://www.ibm.com/developerworks/search/searchResults.jsp?searchType=1&searchSite=dW&searchScope=dW&query=soap

http://www.ibm.com/developerworks/opensource/top-projects/geronimo.html

http://geronimo.apache.org/

http://www.ibm.com/software/webservers/appserv/geronimo/?S_TACT=105AGX44&S_CMP=GRNMO

http://www.ibm.com/developerworks/opensource

http://www.ibm.com/developerworks/offers/techbriefings/?S_TACT=105AGX44

http://safari.bvdep.com/?x=1&portal=bvdep&uicode=&Key=&GUID=D1F1DB57-50AF-4998-99-DA-6D-BB-A5-E0-E4-0B



http://www.eclipse.org/webtools/main.php


• Download Apache Axis, a Java platform for creating and deploying Webservices applications.

• Download your free copy of WebSphere Application Server Community Edition-- a lightweight J2EE application server built on Apache Geronimo open sourcetechnology that is designed to help you accelerate your development anddeployment efforts.

• Download free software for rapid results, and kick-start your Java applicationdevelopment.

• Innovate your next open source development project with IBM trial software,available for download or on DVD.

Discuss

• Participate in the discussion forum for this content.

• Get involved in the developerWorks community by participating indeveloperWorks blogs.

About the author

Manu T. GeorgeManu T. George is a Staff Software Engineer for IBM in the India Software Labs,Bangalore. He is a part of the IBM WebSphere Application Server Community EditionLevel 3 Support Team. He received a bachelor's degree in applied electronics fromthe College of Engineering at Trivandrum.

Trademarks

IBM, the IBM logo, DB2, and WebSphere are registered trademarks of IBM in theUnited States, other countries, or both.Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.Microsoft and Windows are trademarks of Microsoft Corporation in the United States,other countries, or both.UNIX is a registered trademark of The Open Group in the United States and othercountries.Linux is a registered trademark of Linus Torvalds in the United States, othercountries, or both.



http://ws.apache.org/axis/

http://www-128.ibm.com/developerworks/downloads/ws/wasce/?S_TACT=105AGX44&S_CMP=WASCE

http://www.ibm.com/developerworks/kickstart/?S_TACT=105AGX44&S_CMP=WASCE

http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX44

http://www-128.ibm.com/developerworks/forums/dw_forum.jsp?forum=541&cat=51

http://www.ibm.com/developerworks/blogs/


Development and Deployment Guide

Documents

Transcript of Development and Deployment Guide