CreatingDeveloping Web Services

Creating/Developing Web Services

As we mentioned in the opening section of this chapter, the good news is that Oracle makes creating Web Services from existing code really easy for developers. In fact, by using Oracle JDeveloper 10 g , any PL/SQL package or Java class can be turned into a Web Service by using the point-and-click options demonstrated in this chapter. All examples in this chapter were created using Oracle JDeveloper 10 g .

Start a New Project

When working with a new set of codes, such as the following Web Services application, it is always a good idea to start a new project in Oracle JDeveloper 10 g . Projects are also known as applications in Oracle JDeveloper 10 g . In the Applications Navigator, which is shown in Figure 17-2, right-click on Applications and choose New Application Workspace.

Figure 17-2: The Applications Navigator

The application needs to be named before working with it. For this example, as shown in Figure 17-3, the application is called Oracle10gWebServices. Files that constitute the application can be placed into a directory of your choice. Select No Application Template. Then click OK.

Figure 17-3: Name your application

At this point, you will have a blank application with a single project in it. You re now ready to begin creating your Web Services.

It s best if you don t have any spaces in you application name. This can cause a problem when creating the Web Service. It has been known to return an internal error (No. 500) with a java compiler (javac) error. This is due to the space in the enterprise application name.

Java Class-Based Web Services

In each of the examples below, we have existing Java classes we ve written that we d like to make available to the world via a Web Service. Java classes can be deployed as stateless or stateful Web Services ”meaning that state is either preserved or not preserved between calls to the Web Service, respectively.

Stateless Java Web Services

For this example, we have an existing Java class that returns the current status of a database (i.e., up or down). Each time the class is called, the current status of the database will be displayed; it is not necessary to note if the class has been called previously, so this is an example of a stateless Java Web Service.

It s now time to add this existing Java class to my project. Click the Add to Project button, find the existing stateless Java class that you wish to add, as shown in Figure 17-4, and click Open .

Figure 17-4: Add a file to the project

If the file you re adding is not in the directory that you created your application in, you ll need to verify that you wish to add this directory to your project source path , as shown in Figure 17-5.

Figure 17-5: Add the project source path

At this point, the Java class is now part of your project. In Oracle JDeveloper 10 g , there are two ways to create a Web Service from this class. One method is to right-click on the class and then select Generate Web Service from Class (displayed in Figure 17-6):

Figure 17-6: Options for the java class

Using this method automatically generates all of the necessary components to turn this class into a Web Service without prompting you for any options. This option will name the Web Service MyWebService1, expose all of the available methods in the class, and create a stateless class. Given this class only has one method (we wish to expose that method) and the desire is to create a stateless class, this method of automated Web Service creation works just fine. If you choose this method of Web Service creation, you can skip down to the section labeled Web Service Object Generated at this point.

The other method that can be used to create a Web Service is the wizard-based approach. Selecting File New from the main Oracle JDeveloper 10 g menu will bring up the New Gallery window, as shown in Figure 17-7.

Figure 17-7: The New Gallery window

Under the General category, select Web Services. You ll note that there are a number of options available for Web Services. The first option is Java Web Service. Select it, and then click OK. This starts a three-step wizard process, which ends up with the same results as the above right-click option. However, it does allow greater flexibility because the developer can specify choices relating to the generation and behavior of the Web Service as he goes through the wizard. Either option also allows modification of the Web Service with a three-tab Web Service modification window.

In Step 1, shown in Figure 17-8, a Java class needs to be selected that will be the basis of the Web Service you are attempting to create. In this figure, the DatabaseStatus Java class was selected ”it was named DatabaseStatus.

Figure 17-8: Step 1 of 3 in the Web Service wizard

Next, the methods to be exposed in the Web Service are selected (see Figure 17-9). Because this is going to be a stateless Web Service, the Stateful check box is left unselected . Clicking Next moves us to Step 3 in the wizard.

Figure 17-9: Step 2 of 3 in the Web Service wizard

At this point, you can choose the port of your application server and the application server that this Web Service will be deployed to (commonly referred to as an endpoint), as well as the name space for the WSDL file that is generated (see Figure 17-10). The other fields on this page (Endpoint and Target Namespace) are automatically filled in (and not editable) based on the application server you choose to deploy the Web Service to.

Figure 17-10: Step 3 of 3 in the Web Service wizard

If you haven t previously created an application server deployment profile, you can click on New at this time.

Once the appropriate fields on this page have been filled in, click Next.

The final page congratulates you on the completion of the creation of your Web Service, as shown in Figure 17-11. Simply click Finish at this point.

Figure 17-11: Create Web Service finishing page

Web Service Object Generated

The Applications Navigator will now include two new objects, as shown in Figure 17-12. The objects include the new Web Service (named DatabaseStatus) and the Web Service deployment resource (WebServices.deploy).

Figure 17-12: Applications Navigator with new Web Service object

Web Service Object Components

Click on the new Web Service object (i.e., the first DatabaseStatus object in Figure 17-12). As shown in Figure 17-13, two objects appear in the structure window: a WSDL file and a Java file. You can select either object and view the contents of these automatically generated files. Oracle JDeveloper 10 g automatically creates the WSDL file based on the inputs and outputs of the methods exposed. This is a prime example of the power of Oracle JDeveloper 10 g ˜s Web Service wizard. If you read through the WSDL, you ll also understand why so many books require a considerable number of pages to discuss XML (the basis of the WSDL file) and WSDL structure. Using Oracle JDeveloper 10 g , the developer is spared the details of learning the intricate syntax of XML and WSDL and only needs to focus on the purpose they fulfill in the Web Services architecture.

Figure 17-13: Web Service structure

Editing the Web Service Object

If you double-click the Web Service object, a three-tab form will pop up allowing you to edit the Web Service object. This should look very familiar, as the three tabs are the same as the three steps in the wizard (see Figure 17-14). If any of the fields are modified in the pop-up, the underlying Java and WSDL files are changed correspondingly.

Figure 17-14: Edit Web Service object

We ll revisit deploying and executing this Web Service after covering stateful Java Web Services and PL/SQL-based Web Services. If you re interested in these topics, see the respective sections below.

Stateful Java Web Services

For this example, we had an existing Java class called DOMESTICTAPI that queries data from an Excel spreadsheet and returns batches of data as individual result sets. Because we plan on calling the service numerous times to get our complete result set, this Web Service needs to maintain state (i.e., know that it has been called before) between calls.

First, our Java class needs to be included in our project. Click the Add to Project icon to add the DOMESTICTAPI Java class as we did in Figure 17-4. Again, there are two ways to create a Web Service for this Java class. The object can be right-clicked, then edited, or the developer can go through the three-step Web Service wizard. For this example, we re going to right-click the object, then edit the object that JDeveloper creates. After the object is generated (see Figure 17-15), it is named MyWebService1. To edit the object, you can double-click it in the Applications Navigator window or right-click the object, then select Edit.

Figure 17-15: Web Service for DOMESTICTAPI

At this point, we renamed the Web Service to DOMESTICTAPI (the same name as the Java class). We then clicked on the Methods tab as you see in Figure 17-16. The Web Service is made stateful by clicking the Stateful check box. We changed the timeout (seconds) from 0 to 20.

Figure 17-16: Methods tab for DOMESTICTAPI

Our thinking here is that you re going to retrieve the next record set within 20 seconds or you must be done fetching records. If the same user calls this stateful Web Service after the 20-second time-out, she will get the beginning of the record set once again ” i.e., it will start over.

You can see in Figure 17-16 that the fetchTable method is grayed out. By clicking this method, then clicking the Why Not? button, as shown in Figure 17-17, you ll get a description as to why this method cannot be exposed as part of the Web Service.

Figure 17-17: The Why not? Button and its functionality

In this case, it s because the oracle.sql.ARRAY object doesn t have an XML schema mapping. For this Web Service, we created another method called fetchTableSet and a record set called DOMESTICSet to return my data set using standard datatypes. Once the changes are made and you click OK the wizard will notice that the changes made require regenerating the corresponding WSDL and Java files. Given these files already exist (and may have been hand-edited by you), Oracle JDeveloper 10 g will prompt you, as shown in Figure 17-18, to confirm that you want to lose the changes.

Figure 17-18: Confirmation for generation

Similar to the information shown in Figure 17-12, the new Web Service object will appear in the Navigation Window. We ll talk about the deployment and use of this stateful Java Class Web Service shortly.

PL/SQL-based Web Services

For this example, we will expose the COMPANY PL/SQL package that comes with the SCOTT example schema if you have created your test database by selecting the Load demo schemas option in the Database Configuration Assistant Wizard. This package contains procedures and functions to add new employees ; retrieve an employee record, address, or status; set employee information; etc. This is a good example of a real-world package that can be exposed via a Web Service.

To create a PL/SQL-based Web Service, click File New from the main JDeveloper menu. In the list of new gallery options shown in Figure 17-7, PL/SQL Web Service is one of the options available. Select this option and click OK. The PL/SQL Web Service publishing wizard begins, as shown in Figure 17-19. Click Next on this page.

Figure 17-19: The Create PL/SQL Web Service welcome page

The PL/SQL Web Service creation wizard has three steps (see Figure 17-20). You ll need to select a database connection. If a database connection has not previously been established, click New to create a new Java Database Connectivity (JDBC) connection to a specific username or schema (and password) in the database. In Figure 17-20, the SCOTT schema and specific package called COMPANY (from the drop-down list of packages in the SCOTT schema) was selected. A unique name is also provided for the service (COMPANY). The Web Service is packaged into a specific Java package (which is similar in concept to Oracle schemas). In this example, the Web Service is packaged into the same package as the other Web Services previously created, which is Generated.

Figure 17-20: Step 1 of 3 for create PL/SQL Web Service wizard

It s now time to select which program units (procedures and functions) are to be exposed to the public in your Web Service (see Figure 17-21).

Figure 17-21: Selecting program units to expose in the Web Service

We clicked on the Select All button. Again, you ll notice that some of the functions cannot be exposed. If you need to expose these functions, click the function, then click Why Not? You ll need to solve the problem before you create this Web Service. Once you re done, click Next.

As you can see from Figure 17-22, the final step is the same as the final step when creating a Java class-based Web Service. The location of your target application server needs to be selected. The final page in the wizard is a success message.

Figure 17-22: Step 3 of 3 for the PL/SQL Web Service wizard

Once you ve completed the PL/SQL wizard, as shown in Figure 17-23, Oracle JDeveloper 10 g will generate all of the necessary components for your PL/SQL-based Web Service.

Figure 17-23: PL/SQL Web Service generator