Exercise 9.5 – Ping EGL Web Service - IBM fileExercise overview Use the following procedures to create an EGL web service application. 1. Create an EGL Web Project called “pingws”

Exercise 9.5 – Ping EGL Web ServiceBy Gilbert Herschberger (http://www.mindspring.com/~gchii/)Date Written : 7 April 2010

GoalIn this exercise, we will create “pingws”, the smallest possible web service application for an EGL web service. This EGL web service simply confirms (a) a connection from a web service client to a web service.

The word “ping” comes from the world of sonar, an electronic device to measure a distance and direction with underwater sound. A “ping” program is available on many operating systems to measure the distance to another host on the network.

SeriesThis document is part of an education and training series. Other exercises include:

● Exercise 3.2 – EGL-CE 1.0 and WAS-CE 2.1. In this exercise, we download and install WebSphere Application Server Community Edition 2.1.

● Exercise 9.2 - Ping HATS Web Service. The “pingwsh” project goes beyond “pingws” to confirm a connection to a host. In this exercise, create your first HATS web service and reduce the size of your web application by removing unused bits. This exercise features Rational Business Developer 7.5 and Rational HATS 7.5.

Target Runtime EnvironmentThe completed web service can be deployed to the following target application servers.

● WebSphere Application Server Community Edition 2.1

Target Development EnvironmentIn this exercise, the following software is used to develop a web service application.

● EGL Community Edition 1.0● WebSphere Application Server Community Edition 2.1

Exercise 9.5 - Ping EGL Web Service 1

Exercise overviewUse the following procedures to create an EGL web service application.

1. Create an EGL Web Project called “pingws”

2. Creating an EGL web service

3. Adding an operation called “getVersion”

4. Deploying an EGL Project

5. Testing with Web Services Explorer

6. Reducing web deployment descriptor

7. Removing files

1. Removing HTML pages

2. Removing images

3. Removing style sheets

4. Removing Java Script files

8. Exporting an EAR file

PrerequisitesThe following are prerequisites for this exercise.

1. EGL Community Edition has been installed.

2. WASCE v2.1 has been installed.

3. WASCE v2.1 Server Adapter has been installed.

4. Start your interactive development environment (IDE).

1. For Microsoft Windows, double-click the EGL-CE 1.0 ( ) icon on your Windows desktop to start your IDE.


5. Switch to the “eglws” (EGL Web Services) workspace.

1. For Microsoft Windows, type “C:\lab\eglws” in the directory field.

2. Press the OK button.

6. Close the Welcome view, if necessary.

1. Press the Close (X) icon on the Welcome view tab.


7. Switch to the EGL perspective, if necessary.

8. Confirm the service port setting is 8080.1. Pull down the Windows menu and select the Preferences option.

2. Expand the EGL folder.

3. Select the Services folder.

4. Type “8080” in the Port field.



9. Confirm the Build Automatically feature is enabled.


10. Switch to the Servers view. The Servers view displays a list of servers used by projects in this workspace. Confirm the Servers view now shows a document for IBM WASCE v2.1 Server at localhost as shown. If not, please see Exercise 3.2 – EGL-CE 1.0 and WASCE 2.1 in this series for more information on the download and installation of WAS-CE and its server adapter.

11. In this server document, confirm the Publish Automatically feature has been disabled.

1. Right-click on the WAS-CE v2.1 Server at localhost document and select the Open option.

2. In the Publish Automatically section, select the Never Publish Automatically option.

3. Save the document.


Procedure 1: Creating an EGL ProjectAn EGL Project is the closest thing to a EGL web service project. It provides more functionality than we want. We must first create an EGL Project and then work to remove the bits that are not required. Unfortunately, creating a pure web service project for EGL is not yet supported by version 1.0 of EGL-CE. The following procedure illustrates how to create an EGL web project called “pingrui”.

1. Pull down the File menu on the menu bar and select New | EGL Project option.

Result: The New EGL Project wizard is displayed.

2. Fill out the New EGL Project page of the New EGL Project wizard.

1. Type “pingrui” in the Name field.2. Confirm that the Use default location field is checked.

3. Press the Next button.

Result: The EGL Settings page is displayed.


3. Fill out the EGL Settings page of the New EGL Project wizard.

1. Confirm the “com.ibm.egl.rui_1.0.2” project is checked.

2. Uncheck the “com.ibm.egl.rui.dojo.runtime.google_1.3.2” project.

3. Press the Finish button.

Result: The “pingrui” EGL Project is created.

Procedure 2: Creating an EGL Web ServiceThe following procedure illustrates how to create an EGL web service.

1. Start WAS-CE.

1. Switch to the Servers view.

2. Select IBM WASCE v2.1 Server at localhost.

3. Press the Start icon and wait for the server to start.

2. Create an EGL package called “ping.services”.

1. Switch to the EGL Project view.

2. Expand the “pingrui” project.

3. Right-click on the EGL Source folder and select the New | Package option.

Result: The New Package wizard is displayed.


4. Fill out the EGL Package page of the New EGL Package wizard.

1. Confirm the Source folder field is “pingrui\EGLSource”.

2. Type “services.ping” in the Package name field.


Result: The “services.ping” package is created.

3. Create a web service.

1. Expand the EGL Source folder.

2. Right-click on the “services.ping” package and select the New | Service option.

Result: The New EGL Service Part wizard is displayed.


3. Fill out the New EGL Service Part page of the New EGL Service Part wizard as shown.

1. Confirm the Source folder field is “pingrui\EGLSource”.

2. Confirm the Package field is “services.ping”.3. Type “PingWS” in the EGL source file name field.4. Check the Create as Web (SOAP) service option.5. Press Finish button.

Result 1: The PingWS.egl source file is created and opened in the EGL source code editor.Result 2: The PingWS web service is added to the EGL build descriptor.


Procedure 3: Adding an operation called “getVersion”The following procedure illustrates how to edit the source code for an EGL service, using PingWS.egl as an example.

1. Start your IDE.2. Switch to the EGL perspective, if necessary.3. In the Project Explorer view, expand the “pingrui” project.4. Expand the EGL Source folder.5. Expand the “services.ping” package.6. Double-click on the PingWS.egl file.

Result: The PingWS.egl is opened in the EGL source code editor.7. Change line 7 to a comment.8. Change lines 10 and 11 to comments.9. Add the following lines before the last end statement.

1. function getVersion() returns (string)2. return (“0.0.0.1-wasce21”);3. endResult: The following is a listing for the complete source code.package services.ping;

// serviceservice PingWS

// Variable Declarations// variableName string;

// Function Declarations// function functionName()// end

function getVersion() returns (string)return ("0.0.0.1-wasce21");

endend

Procedure 4: Deploying a web serviceThe following procedure illustrates how to deploy a web service.

1. Right-click on the “pingrui” project and select the Deploy EGL Project option.

Result: The EGL Deployment dialog box is displayed.


2. Press the Yes button.

Result: The EGL deployment descriptor is displayed.

3. Press the New button.

Result: The New Dynamic Web Project wizard is displayed.


4. Fill out the Dynamic Web Project page of the New Dynamic Web Project wizard.

1. Type “pingws” in the Project name field.

2. Confirm the Use default field is checked.

3. Confirm the Target Runtime field is “IBM WASCE v2.1”.

4. Confirm the Dynamic Web Module version field is “2.5”.

5. Confirm the Configuration field is “Default Configuration for IBM WASCE v2.1”.

6. Confirm the Add project to an EAR is checked.

7. Confirm the EAR Project Name field is “pingwsEAR”.



Result: The Web Module page is displayed.

5. Fill in the Web Module page of the New Dynamic Web Project wizard.

1. Confirm the Context Root field is “pingws”.

2. Confirm the Content Directory field is “WebContent”.

3. Confirm the Java Source Directory is “src”.

4. Confirm the Generate deployment descriptor field is checked.


Result: The Geronimo Deployment Plan page is displayed.


6. Fill in the Geronimo Deployment Plan page of the New Dynamic Web Project wizard.

1. Type “lab” in the Group Id field.

2. Type “pingws” in the Artifact Id field.

3. Type “0.0.0.1” in the Version field.

4. Confirm the Artifact Type is “car”.

5. Confirm the Add a runtime dependency to Geronimo's shared library field is unchecked.


Result 1: The “pingws” project is created.

Result 2: The “pingwsEAR” project is created.

Result 3: The EGL deployment descriptor is displayed.

7. Save “pingrui.egldd”, the EGL deployment descriptor.

8. Right-click the “pingrui” project and select the Deploy EGL Project option (again).

Result 1: The “pingrui” project is deployed to the “pingws” project.

Result 2: The “pingwsEAR” project is published to WAS-CE.

Result 3: The server status is Synchronized.


9. Display the web service page. Open your favorite web browser to the following location: “http://localhost:8080/pingws/services/PingWS”.

10. Ask a service for its WSDL file. Open your favorite web browser to the following location: “http://localhost:8080/pingws/services/PingWS?WSDL”.


http://localhost:8080/pingws/services/PingWS

Procedure 5: Testing with Web Services Explorer.The following procedure illustrates how to test an EGL web service with the Web Services Explorer.

1. In the Project Explorer view, expand the “pingws” project.

2. Expand the WebContent folder.

3. Expand the WEB-INF folder.

4. Expand the wsdl folder.

5. Right-click the PingWS web service definition and select the Web Services | Test with Web Services Explorer option.

Result: The Web Services Explorer is displayed.

6. Confirm the endpoint is “http://localhost:8080/pingws/services/PingWS”.

7. In the Actions tab, click the “getVersion” operation.

Result: The Invoke a WSDL Operation page is displayed.

8. Press the Go button.

Result 1: The getVersion operation of the PingWS web service is invoked.

Result 2: The result is displayed in the Status tab.


9. Confirm that the Status tab contains the getVersionResponse of “0.0.0.1-wasce21”.

10. Hint 1: The following message indicates that Web Services Explorer sent a request and there was no response from the WAS-CE server.

1. The WAS-CE server is stopped. Start it.

2. The endpoint is incorrect, such as the wrong port. Correct the HTTP/1.1 port setting in the server document and deploy the EGL project again.

11. Hint 2: The following message indicates that Web Services Explorer sent a request and WAS-CE responded with page not found (HTTP 404).

1. The endpoint is incorrect, such as the wrong context. In this example, the path for the web service is “pingws/services/PingWS”, not “pingrui/services/PingWS”.

2. The Axis servlet or “/services/*” servlet mapping is missing from the web deployment descriptor (“web.xml”).


Procedure 6: Reducing web deployment descriptorServlets, filters, security roles, security constraints, welcome pages, context parameters and tag libraries are declared in a web deployment descriptor. The following procedure illustrates how to remove unneeded references from a web deployment descriptor.



3. Double-click on “Deployment Descriptor: pingws” to open the web deployment descriptor, “web.xml”. This document is not the EGL Deployment Descriptor.

Result: The web deployment descriptor for the project is displayed.

4. About Welcome Pages. An EGL web service project does not depend upon welcome pages. We can safely remove them.

1. Optionally, remove all welcome pages except for index.html and create an index.html document to summarize your web service project.

5. About Servlets. An EGL web service project for Tomcat depends upon Apache Axis. However, it does not depend upon the Axis Admin Servlet. We may remove the Axis Admin Servlet and the “/servlet/AdminServlet” mapping.

It does not depend upon EGL Rich UI Proxy. We may remove the EGLRichUIProxy servlet and the “/__proxy” mapping.

6. About Servlet Mappings. An EGL web service project for Tomcat depends upon the “/services/*” mapping. However, it does not depend upon the “/servlet/AxisServlet” and “*.jws” mapping. We may remove them.

7. About filters. An EGL web service project does not depend upon filters. We may remove the CompressionFilter filter and filter mappings.

8. Press the Save icon.

Procedure 7: Removing filesAt this point, we have a pure web services application because we did not create an EGL Rich UI handler. But what happens in a web services project when we create at least one handler and forget to uncheck the Deploy All Rich UI Handlers setting in the EGL Deployment Descriptor? The deploy process creates files that an EGL web service application does not use.

Caution: When deploying an EGL project, there is no undo button.

In this optional exercise, we will create an EGL Rich UI handler to illustrate the consequences on the deploy process.

1. Start your IDE.

2. Switch to the EGL perspective, if necessary.

3. Expand the “pingrui” project.

4. Create a “ping” package.


1. Right-click on the EGL Source folder and select the New | Package option.

Result: The New EGL Package wizard is displayed.

2. Type “ping” in the Name field.


Result: The “ping” package is created.

5. Create an EGL Rich UI handler.

1. Expand the EGL Source folder.

2. Right-click on the “ping” package and select the New | Rich UI Handler option.

Result: The New EGL Rich UI Handler part wizard is displayed.

6. Fill in the New Rich UI Handler part page of the New Rich UI Handler part wizard.

1. Type “PingSampler” in the Name field.


Result: The “PingSampler.egl” file is created and opened in the EGL source code editor.

7. Deploy the “pingrui” Project (to the “pingws” project).

1. Right-click on the “pingrui” project and select the Deploy EGL Project option.

8. Publish the “pingwsEAR” project to WAS-CE.

1. In the Servers view, press the Publish ( ) icon.


Procedure 7.1: Removing HTML pagesAn EGL web service application does not use HTML pages (*.html).

HTML pages may be deployed in the following folders and more:

● WebContent● WebContent/com/ibm/egl/rui/history

The following procedure illustrates how to remove HTML pages from a deployed project, using the “pingws/WebContent” folder as an example.



3. Select all HTML pages. (In this example, “PingSampler-en_US.html” is the only one.)

4. Right-click on a selected file and select the Delete option.

Result: The Delete Resources dialog box is displayed.


Result: There are no HTML pages in the WebContent folder.

Procedure 7.2: Removing imagesAn EGL web service application does not use images (*.gif, *.png).

Images may be deployed in the following folders and more:

● WebContent/css/tundra/images● WebContent/image● WebContent/icons

The following procedure illustrates how to remove images from a deployed project, using the “pingws/WebContent/image” folder as an example.



3. Expand the images folders.

4. Select all images, from ArrowDown.gif to TreeNodeT.gif.




Result: The images folder is empty.

Procedure 7.3: Removing style sheetsAn EGL web service application does not use cascading style sheets.


Style sheets may be deployed in the following folders and more:

● WebContent/css● WebContent/tundra● WebContent/tundra/form

The following procedure illustrates how to remove style sheets from a deployed project, using “pingws/WebContent/css” as an example.

1. In the Project Explorer view, expand the “pingws” project.2. Expand the WebContent folder.3. Expand the css folder.4. Select all style sheets, from com.ibm.egl.rui_1.0.2.css to theme.css.5. Right-click on a selected file and select the Delete option.

Result: The Delete Resources dialog box is displayed.6. Press the OK button.

Result: The stylesheets folder is empty.

Procedure 7.4: Removing JavaScript filesAn EGL web service application does not use JavaScript files.

JavaScript files may be deployed to the following folders:

● WebContent● WebContent/com/ibm/egl/rui/history● WebContent/com/ibm/egl/rui/infobus● WebContent/com/ibm/egl/rui/mvc● WebContent/com/ibm/egl/rui/widgets● WebContent/egl/messages

The following procedure illustrates how to remove these from a deployed project, using “pingws/WebContent” as an example.



3. Select all JavaScript (.js) files. (In this exercise, “rununit-eze$$rt.js” is the only one.)




Result: There are no more JavaScript files in the project.


Procedure 8: Exporting an EAR fileThe following procedure illustrates how to export an EAR file for WAS-CE, using the “pingwsEAR” enterprise application project as an example.

1. Start your IDE.

2. Switch to the EGL perspective.

3. In the Project Explorer view, right-click on the “pingwsEAR” project and select the Export | EAR File option.

Result: The Export wizard is displayed.

4. Fill in the page of the Export wizard as shown.

1. Confirm the EAR project field is “pingwsEAR”.

2. Type “C:\lab\pingwsEAR.ear” in the Destination field.

3. Confirm the Optimize for a specific server runtime is checked.

4. Confirm the Target Runtime field is “IBM WASCE v2.1”.

5. Confirm the Export source files field is unchecked.

6. Check the Overwrite existing file field.


Result: The web service project is exported to an enterprise application archive (EAR) file.


Production System – First StepsIn a production environment, the “pingws” web service application confirms a connection to a web service. It can be used by your web service client to confirm a connection to the web server and the version of the web service project before invoking any other web service.

This application can be the first EGL web service installed in a production system. Install it early in an EGL web service project to identify and resolve any problems with a production environment. This is part of a general troubleshooting strategy.

In general, the following steps are used.

1. Install and start the “pingwsEAR.ear” enterprise application. Likely, you will use the Administration Console of the target instance of WAS-CE to install a web application from “pingwsEAR.ear”. The exact procedure required to deploy an enterprise application on WAS-CE belongs to you. It is beyond the scope of this document.

2. Test with Web Services Explorer. Obtain a WSDL document from the production web service using the standard “?WSDL” suffix. For our exercise, the WSDL document is found at “http://localhost:8080/pingws/services/PingWS?WSDL”. Substitute “localhost:8080” with a production host and port.

3. Generate your web service client from the WSDL. Many web service clients are available. The only web service client that needs to be tested is the one that you are going to be using in a production system. Therefore, the exact procedure for testing your web service client belongs to you. It is beyond the scope of this document.


Exercise 9.5 – Ping EGL Web Service - IBM fileExercise overview Use the following procedures to create an EGL web service application. 1. Create an EGL Web Project called “pingws”

Documents