Creating the Reminder Web Service - XML

In this section, you will create the Reminder Web service as explained in the case study. The Web service requires use of a database. The following sections discuss the SQL Server database structure. However, because we are developing the application in Java and will be using the JDBC-ODBC bridge to access the database, you can also use any other type of database.

The ReminderService Database

The ReminderService database contains the following tables:

• Users. This table has a list of users who have signed up with the service. This table contains the user's login name, password, and e-mail ID. The structure of the table is shown in Figure.

Structure of the Users Table



• Occasions. This table contains a list of occasions for which the service can send a reminder. The fields in the table include Occasion ID, details, and suggestions for a gift for that occasion. The structure of the table is given in Figure.

Structure of the Occasions Table



• Reminders. This table contains the reminders stored by various users. The structure of the table is shown in Figure.

Structure of the Reminders Table

Next, you will look at the stored procedures created for the database. Here is the code for the AddNewUser stored procedure:

Next, create the AddReminder stored procedure that allows a user to store the reminder for any occasion:

Last, the GetReminders stored procedure that allows a user to view his reminders is created, as shown in the following code:

Next, you will create the Java class that forms the basis of the Reminder Web service.

Creating the Java Class

The Java class, whose functionality will be exposed as a Web service, will call the stored procedures to access the data in the ReminderService database. Before you construct the Java classes, you need to configure the ODBC data source to establish backend connectivity in the class.

Configuring the ODBC Data Source

The Java class will make use of the JDBC-ODBC bridge to connect to the database. This implies that you have to configure an ODBC database, which you can accomplish as follows:

1. From the Control Panel, select Administrative Tools, and double-click Data Sources (ODBC) application. This brings up the dialog box shown in Figure.

ODBC Data Source Administrator Window



The dialog box shows a list of data sources that are already configured. To create a new data source, click on the Add button. This brings up the Create New Data Source dialog box, which is shown in Figure

Create New Data Source Dialog Box



2. Select the driver for the database you are using. In this project, we are using the SQL Server 2000 database; therefore, we will select the SQL Server driver. Click on the Finish button. This closes the window and opens the Create a New Data Source to SQL Server dialog box shown in Figure

Create a New Data Source to SQL Server Dialog Box



3. Enter the name and a description for the data source, and select the local SQL Server installation from the drop-down list. Click on the Next button to bring up the page of the dialog box shown in Figure.

Configuring the Authentication Options



This page allows you to select the appropriate authentication type. Select the SQL Server authentication, provide the username and password, and click on the Next button. This brings up the page shown in Figure.

Selecting the Default Database



4. Select the default database, which is the ReminderService database. Click on the Next button. This brings up a page with some additional configuration details, such as language. Click on the Finish button to open the Test page of the wizard, as shown in Figure.

Testing the Data Source Connection

• Click on the Test Data Source button to check the connection to the database.

Creating the ReminderService Class

You will now create the ReminderService class. This class will contain three public methods:

• addUser(). This method registers a new user for the reminder service.
• addReminder(). This method adds a new reminder for the user for a particular date.
• GetReminders(). This method retrieves a list of all the reminders for a user.

Note?/td>As you can see, this list is not conclusive. You will need more methods, for example, to modify or delete reminders, which you can develop later.

Each of the preceding methods reads or writes from the database. We will now introduce you to using JDBC to connect to a data source, which further connects to the database, and then reads and writes data from it.

First, you will have to connect to the ODBC data source that is configured and make use of it from within your Java class. To do so, you first have to load the required driver by using the following code:

Next, you must retrieve the connection with the database. To do so, use the following code:

You will be using Callable and Prepared statements in this class to access the database. Callable statements allow you to call stored procedures from JDBC applications.

A CallableStatement object is created using the prepareCall() method in the Connection class, and the general syntax of the method is as shown next:

In the preceding syntax, ? represents the parameters and the return values to be passed and retrieved from the method.

The following is a section of the ReminderService Java class that shows the AddReminder stored procedure being called using a CallableStatement:

To create a PreparedStatement, you would use the prepareStatement() method of the Connection class. The PreparedStatement() method takes an SQL string and passes it to the underlying database. The database verifies the syntax and does the query plan optimization but does not run the command. Instead, it returns a handle to the JDBC driver, which is then stored in a PreparedStatement object. You can use this object to execute the SQL command. Prepared statements are efficient. The repared Statement class has three methods: executeQuery(), executeUpdate(), and execute(), none of which take parameters.

Here is an example of a prepared statement being used in the Java class that is created for the Reminder service:

Here is the code for the complete Java class:

In the preceding code, notice that the main() method is marked as a comment block. You can use this method to test the functionality of the class before you create the Web service from it.

Creating and Deploying the Web Service

You are going to use the JDeveloper's Web Service Publishing Wizard to create a J2EE Web service from the Java class you created earlier. To run the JDeveloper for Oracle9i, run <JDeveloper_Home>JdevBinjdevw.exe. The user interface of JDeveloper is shown in Figure.

The JDeveloper IDE

Connecting to Oracle9i Containers for J2EE

You need to run the Oracle Containers for J2EE server. To do this, from your <OC4J_HomeJ2EEHome> folder, where you have installed it, execute the following command from the command line:

Next, you need to set up a connection to the Oracle9i containers, which enables you to deploy your Web service to the application server. To do this, perform the following steps:

1. Expand the Connections node in the Navigator, and choose New Connection from the Application Server context menu, as shown in Figure.

Creating a New Application Server Connection.



The Connection Wizard is shown in Figure.

The Connection Wizard



2. Click on the Next button on the Welcome page, and in the resulting page, shown in Figure, enter the name of the connection or Connection1.

Naming the Connection



3. Click on the Next button to display the authentication page shown in Figure.

Authentication Information Page



This requires the authentication information to connect to OC4J. Enter the username as Admin and the password you would have given while setting up OC4J.

4. Click on the Next button. This brings up the Connection page shown in Figure.

Connection Page in the Connection Wizard



Enter the data for the local machine name, the target Web site, and the path for the local directory where the admin.jar file is located.

5. Click on the Next button to display the Test page shown in Figure.

Testing the Connection



6. Click on the Test Connection button. If the test succeeds, then click on the Finish button to establish a connection to the OC4J server.

Now that you have an OC4J connection, you can use the JDeveloper's Web Service Publishing Wizard to create your J2EE Web service.

Using JDeveloper to Create a J2EE Web Service

Perform the following steps to create a J2EE Web service:

1. Create a new workspace by selecting File, New, Workspace in the menu. Name the workspace and the project appropriately.
2. From the Project menu, select Add to Project and add the Java file, which you created in the preceding step, to the project. In the resulting dialog box, select Yes.

Note?/td>Just to keep all files together, you might want to copy the Java file to the workspace project folder that will be created under the < Jdev_Home > jdev mywork folder.

3. Right-click on the Java file name in the Explorer and select Build to compile and build your class.
4. Select File, New from the project menu, and in the resulting dialog box shown in Figure, select Project to create a new project.

New Project Dialog Box



5. Select Web Services in the Categories pane and Web service in the Items page. This will display the Web Service Publishing Wizard shown in Figure.

Web Service Publishing Wizard



6. Click on the Next button on the Welcome page to display the page shown in Figure.

Step 1 Page of the Web Service Publishing Wizard



7. Click on the Browse button to open the Class Browser dialog box, shown in Figure.

The Class Browser Dialog Box



8. Select the ReminderService class and click on the OK button to close the window. The Web service will have the same name as the class. You can change the name of the Web service if you want. Let the Deployment platform be Oracle J2EE Web server.
9. Click on the Next button to display the Exposed Methods page shown in Figure.

Step 2 Page of the Web Service Publishing Wizard



10. Click on the Select All button to select all methods that are available in the original Java class.
11. Click on the Next button to display the File Locations page displayed in Figure.

Step 3 Page of the Web Service Publishing Wizard



12. On this page, select the Connection1 connection, which you created earlier, as the Application server endpoint. The target namespace will contain a namespace http://tempuri.org. You can change it if you want to.
13. Click on the OK button. If you haven't changed the target namespace, this displays a warning message. Ignore the message. The following files are generated:
    • A WSDL document
    • WebService.deploy
    • Web.xml
    • A ReminderService interface file

The WSDL document contains a description of the Web service. Various tools use the WSDL document to create Web service clients. The content of the WSDL document created by the wizard is explained next:

Because the target namespace was not changed, the namespace remains as http://tempuri.org:

One of the methods exposed by the Web service, getReminders(), returns an array of strings. Here is the complexType declaration for that:

The Web service defines three operations: addUser, addReminder, and getReminder. Each of these operations uses two messages. For example, the addUser operation has the corresponding Request and Response message declarations shown next:

The port type and the operation declarations are shown next. As mentioned earlier, each of the operations uses a Request and a Response message defined earlier:

Note?/td>Notice the value of the location attribute of the soap:address tag. This tells you the URL where the Web service can be accessed.

Next, look at the deployment file. This file contains a list of the files to be deployed, the connection to which the Web service will be deployed, and the name of the WAR file that will be generated.

The web.xml file, shown next, contains information on the Web service and the servlet deployment:

Last, look at the interface file that defines the interface of the Web service:

Now that you have used the Web Service Publishing Wizard to create the files needed for your Web service, you need to deploy the Web service.

To deploy the Web service, perform the following steps:

1. Select the Webservices.deploy file from the Navigator and right-click to display the context menu.
2. From the menu, select the Deploy To option and select Connection1. It will take a moment, but when it is done, you will have created and deployed a J2EE Web service.

Next, you will create a Java application that will test this Web service.

Testing the Web Service

This section shows you how to test your new J2EE Web service by creating an application that invokes one of the methods exposed by the Web service. The first client application will be created by using the JDeveloper for Oracle9i. Next, we will use Cape Clear's CapeStudio 3.0 to create test client applications in Visual Basic 6.0 and Java.

Creating the Client Application by Using JDeveloper

First, you need to create a Web service stub. You can then add this stub to a new project or to the existing project.

To do so, perform the following steps:

1. Add a new empty project to the workspace. Then invoke the ReminderClient project. With the ReminderClient project selected, select New from the File menu.
2. In the resulting gallery window, select Web Services in the Categories pane. Select the Web service Stub/Skeleton option in the Items pane, as shown in Figure.

Creating a Stub/Skeleton for a Web Service



The Web Service Stub/Skeleton Wizard is displayed, as shown in Figure.

The Web Service Stub/Skeleton Wizard



3. If the welcome message is showing, click on the Next button to display the page shown in Figure.

The Select Web Service Description Page of the Stub/Skeleton Wizard



4. Browse to the WSDL file that you created and click on the Open button. In Generation Options, make sure that Generate Client- Side Stubs is selected and that other options are not selected.
5. Click on the Next button to display the Select Stubs/Skeletons to Generate page, shown in Figure.

The Select Stubs/Skeletons to Generate Page of the Stub/Skeleton Wizard



6. In the resulting page, ensure that all methods are selected. You can change the name of the package and the class. After you make the required selection and changes, click on the Finish button to generate the stub.

Here is the content of the ReminderServiceStub.java file:

package mypackage1; import oracle.soap.transport.http.OracleSOAPHTTPConnection; import java.net.URL; import org.apache.soap.Constants; import org.apache.soap.Fault; import org.apache.soap.SOAPException; import org.apache.soap.rpc.Call; import org.apache.soap.rpc.Parameter; import org.apache.soap.rpc.Response; import java.util.Vector; import java.util.Properties; /** * Generated by the Oracle9i JDeveloper Web Services Stub/Skeleton Generator. * Date Created: Sat Jul 13 03:02:41 IST 2002 * WSDL URL: file:/D:/jdev/jdev/mywork/WS1/P1/ReminderService.wsdl */ public class ReminderServiceStub { public String endpoint = " http://saik:8888/WS1-P1-contextroot/ ReminderService"; private OracleSOAPHTTPConnection m_httpConnection = null; public ReminderServiceStub() { m_httpConnection = new OracleSOAPHTTPConnection(); } public void addUser(String sUserName, String sPass) throws Exception { URL endpointURL = new URL(endpoint); Call call = new Call(); call.setSOAPTransport(m_httpConnection); call.setTargetObjectURI("ReminderService"); call.setMethodName("addUser"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); Vector params = new Vector(); params.addElement(new Parameter("sUserName" , String.class, sUserName, null)); params.addElement(new Parameter ("sPass", String.class, sPass, null)); call.setParams(params); Response response = call.invoke(endpointURL, ""); if (!response.generatedFault()) { Parameter result = response.getReturnValue(); } else { Fault fault = response.getFault(); throw new SOAPException(fault.getFaultCode(), fault.getFaultString()); } } public void addReminder(String sUserName, String sPass, String sDate, Integer nOccasionID, String sDetails) throws Exception { URL endpointURL = new URL(endpoint); Call call = new Call(); call.setSOAPTransport(m_httpConnection); call.setTargetObjectURI("ReminderService"); call.setMethodName("addReminder"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); Vector params = new Vector(); params.addElement(new Parameter(" sUserName", String.class, sUserName, null)); params.addElement(new Parameter(" sPass", String.class, sPass, null)); params.addElement(new Parameter(" sDate", String.class, sDate, null)); params.addElement(new Parameter(" nOccasionID", Integer.class, nOccasionID, null)); params.addElement(new Parameter(" sDetails", String.class, sDetails, null)); call.setParams(params); Response response = call.invoke (endpointURL, ""); if (!response.generatedFault()) { Parameter result = response.getReturnValue(); } else { Fault fault = response.getFault(); throw new SOAPException(fault. getFaultCode(),fault.getFaultString()); } } public String[] getReminders(String sUserName) throws Exception { String[] returnVal = null; URL endpointURL = new URL(endpoint); Call call = new Call(); call.setSOAPTransport(m_httpConnection); call.setTargetObjectURI("ReminderService"); call.setMethodName("getReminders"); call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC); Vector params = new Vector(); params.addElement(new Parameter(" sUserName", String.class, sUserName, null)); call.setParams(params); Response response = call.invoke(endpointURL, ""); if(!response.generatedFault()) { Parameter result = response.getReturnValue(); returnVal = (String[])result.getValue(); } else { Fault fault = response.getFault(); throw new SOAPException(fault. getFaultCode(),fault.getFaultString()); } return returnVal; } public void setMaintainSession(boolean maintainSession) { m_httpConnection.setMaintainSession(maintainSession); } public boolean getMaintainSession() { return m_httpConnection.getMaintainSession(); } public void setTransportProperties(Properties props) { m_httpConnection.setProperties(props); } public Properties getTransportProperties() { return m_httpConnection.getProperties(); } }

Note how neatly the methods in the stub encapsulate those in the Web service. Each method accepts the parameters from a client application and then makes a call to the Web service by using HTTP. Next, the method passes the parameters to the appropriate methods of the Web service.

7. Right-click on the ReminderServiceStub.java file in the Navigator and select Build to build the class.

Finally, you will create an application that will invoke the Web service. To do so, perform the following steps:

1. Right-click on the project ReminderServiceClient and select New Class from the context menu. This brings up the New dialog box, shown in Figure. Click on the OK button.

The New Dialog Box



2. In the resulting New Class dialog box, enter the name of the class as Client1. The package name should be the same as that of the stub created earlier.
3. Select the Generate Main Method check box. This ensures that a main() method is added to the generated code.
4. Click on the OK button. The generated code is displayed in the code editor. Add the following code to call the Web service method:

Run the application and check the returned values.

Creating Client Applications by Using CapeStudio

Cape Clear offers an easy-to-use set of tools called CapeStudio for creating and deploying Web services. You also can use CapeStudio to create client applications for Web services created using other tools.

In this section, you will use a tool called WSDL Assistant, which is part of CapeStudio, to create client applications for the Java Web service you created earlier.

Creating a Visual Basic 6.0 Client

To generate a Visual Basic 6.0 client for the Web service you created earlier, you will use the WSDL Assistant tool that is part of the CapeStudio software. Figure shows the interface of the WSDL Assistant.

WSDL Client Tool.

In the text box labeled WSDL File, enter the path for the WSDL file of the ReminderService Web service. Specify an output directory where the files for the client can be generated. In the Generate section of the page, select the Client option button. Then, select the VB option button and enter the Project name. Click on the Generate button.

The assistant will create a Visual Basic 6.0, Standard EXE type project in the folder you specified. Open the project, and you will find the definition for a class that is a proxy of the Web service.

A class called ReminderServicePortTypeClient is created. This class has a property called endpoint that is used to set and get the value for the Web service endpoint. The property is initialized to the endpoint in the WSDL:

The following is the implementation for the addUser() method in the class, which, in turn, calls the addUser() method of the ReminderService Web service. The generated code uses the Soap Toolkit methods to serialize the method call into a SOAP message and then calls the Web service.

Note?/td>You need to download the Microsoft SOAP Toolkit ver2.0 SP 2.0 and install it because the code generated for the Visual Basic client uses it.

This is a Standard EXE project. Therefore, to execute this application, you need to add a form or a main procedure.

Add a form to the project and set it as the startup object in the Project Properties dialog box. Add a button to the form and the code to invoke a Web service method, as shown next:

Here, the code invokes the getReminders() method and displays the first reminder it returns. Run the application and check the functioning of both the client and the Web service.

Creating a Java Client

Run the WSDL Assistant and follow the same steps as before. Select Java as the client type and generate the Web service client. The assistant creates the following files for you in the folder that you specified:

• ReminderServiceBindingClient.java. This file has the ReminderServiceBindingClient class that has the interface, which defines the methods exposed by the Web service.
• ReminderServiceBindingClientImpl.java. This file has the ReminderServiceBindingClientImpl class, which implements the above interface at the client end.
• ReminderServiceBindingClientFactory.java. This file has the ReminderServiceBindingClientFactory classs, which creates the client proxy object. The class has a create() method that is used to create the proxy object.
• ReminderServiceBindingClientMainline.java. This file has a simple client application implementation, which you can compile and execute to test the working of the Web service.

Following is the definition of the ReminderServiceBindingClient class:

Following is the definition of the ReminderServiceBindingClientImpl class:

Following is the definition of the ReminderServiceBindingClientFactory class:

Following is the client application. The client application calls the exposed methods of the Web service one after the other by passing dummy parameters and checks for an error:

You will also find two more folders created: classes and lib. The Classes folder will contain the compiled classes for all generated Java files. The Lib folder has all the compiled classes along with the required support files packaged into a .jar file.

Set the class path to include the xerces.jar, xalan.jar, common.jar, capeconnect.jar, soapdirect.jar, and wsdl4j.jar files in the Capeclear capestudio3.0 lib folder. Execute the ReminderServiceBindingClientMainline class to run the test Java client application and verify the functioning of the Web service.