Developing Web Services

WebLogic Workshop fully supports creating and using Web services. With Workshop, you can create Web services from scratch or extend an existing Web service. Workshop also supports creating control wrappers around existing Web services, whether they were created with Workshop or exist outside WebLogic Server.

To create a Web service, follow the steps shown in Figure 9.3:

1. Select the folder where the Web service will be created.

2. Choose File, New, Web Service from the WebLogic Workshop menu.

3. In the New File dialog box, enter a filename for the Web service and click Create.

Figure 9.3. Creating Web services.

From a Workshop development perspective, Web services look much like controls. Web services have methods, can support callbacks, and can use other controls, EJBs, or J2EE services. You can add methods simply by dragging them from the Data Palette, as you would with a control or Page Flow.

Exposing Web Services Beyond Workshop

Web services are typically created to make a service or an interface available to the outside world. WebLogic Workshop Web services are no different, and external Web service consumers can easily use them.

Examine the creditServices Web service, which the Wonderland Casino requires to support checking a player's credit limit. creditServices supports the checklimit method, which takes a string name and a bet in the form of an integer and returns true or false, depending on whether the player's bet is within his or her limit. Table 9.1 lists some of the more important components created for the creditServices Web service.

Table 9.1. Web Services Components

COMPONENT	EXAMPLE	DESCRIPTION
Overall URL	http://localhost:7001/CasinoServicesWS/support/creditServices.jws	The URL to the service's main page. All Web services automatically generate a set of JSP pages in support of using the Web service. The URL is created from the URL of the running instance of Workshop and the path to the Web service.
WSDL	http://localhost:7001/CasinoServicesWS/support/creditServices.jws?WSDL	A complete WSDL description of the Web service, which external clients can use to access the service. Note that for Web services that provide callbacks, two sets of WSDL are supplied, one with and one without callback definitions.
Support JARs	creditServices.jar and webservicesclient.jar	Client support JAR files that can be used standalone Java clients to call the Web service as though it were a local class.
Support pages	Overview, Console, Test Form, and Test XML	Workshop generates a set of JSP pages containing support for the Web services. The Overview page provides downloadable client JAR files, WSDL, and so on. Test Form provides a simple JSP with entries for each method of the Web service. The Test XML page is a example of the XML used to call service methods.

Using Web Services Within Workshop Applications

Although a Web service is typically used to make a service available to the outside world, often you want to use a previously defined Web service from within a Workshop application. The following list illustrates three possible situations in which you would access Web services from within a Workshop application:

• Web service within the same project as the caller The Web service is defined in the calling application as a JWS file.

• Web service in a Web services project The Web service is developed in another Workshop project, but within the same application.

• External Web server The Web service is external to the application.

THE target-namespace PROPERTY

By default, newly created Web services do not have a defined namespace. For those unfamiliar with the concept of namespaces, simply consider them as a way to control name collisions. Typically, a namespace is defined by using the Web name of the entity that has developed the service (for example, www.samspublishing.com ), followed by details of the service. For example, you could use the namespace www.samspublishing.com/81kickstart/casino/supportservices as the target namespace of the Web service to ensure that no other services with the same name will be confused with yours.

The simplest situation is having a Web service contained within the same project as the Web or portal application. In this case, you can simply right-click the Web service JWS file, and choose Generate Service Control. A control with the same name as the Web service is created, with Control.jcx added to the end of the name. Drag and drop the newly created control onto a Page Flow or any other consumer, and use it as you normally would.

If the Web service is nonlocal , you need to access its WSDL to create a control wrapper. WebLogic Workshop can easily create a WSDL file from a Web service. To do this, right-click the Web service, and choose Generate WSDL File. A WSDL file is created with the same name as the Web service, but it ends in Contract.wsdl . Workshop is smart enough to keep the associated WSDL file synchronized with its Web service parent. Changes to the Web service's methods or signatures cause an update to the associated WSDL.

To create a Web service control around an external Web service within a Page Flow, follow the steps shown in Figure 9.4:

1. Select the folder where the Web service control will be created, and from the Data Palette's Add menu, choose Web Service.

2. Enter a variable name for the control instance.

3. Select the Create a New Web Service Control to Use option, and enter a Java Control Extension (JCX) name. A common convention is to use all uppercase letters for the JCX name or add WS to the end.

4. Browse to the WSDL file defining the interface to the Web service. For those Web services within the same application but in a control project, you can browse to the directory containing the WSDL file. For external Web services, you can enter a fully qualified URL to the WSDL file.

5. Click Create.

Figure 9.4. Creating a Web service control from an external Web service.

Workshop then creates a JCX file defined by the selected WSDL that can be used like any other control. It's important to note that the newly created control represents the Web service as it was defined by the WSDL file at its moment of creation. If the underlying Web service changes, such as modifying a method signature, the control instance will not match the running service. Be careful to ensure that the Web service is stable before you create a control from it.

Using Web Services from Standalone Applications

As you've seen, using Web services from within a Workshop application is easy. But what about using Workshop-created Web services from within a standalone Java client or JSP page?

PREPARING TO RUN client.java

Windows developers can run the client example by modifying the prompt.cmd file found in chapter09standalone and pointing the BEA_HOME directory to the location of your WebLogic Platform install. Double-clicking the command file opens a property-configured DOS window with the appropriate classpath and path settings. Unix developers need only run the commEnv.sh shell script found in weblogic81/common/bin and add the provided JAR files to the classpath.

Workshop-based Web services provide proxy JAR files that enable standalone clients to call Web services directly. Listing 9.1 details a simple Java client that uses the checkcredit method of the client service's Web service.

Listing 9.1. client.java

 import weblogic.jws.proxies.*; public class client {     public static void main(String[] args) {         try {             System.out.println("Attempting to get credit services proxy");  CreditServices_Impl proxy = new CreditServices_Impl();   System.out.println("Using proxy to get service object instance");   CreditServicesSoap sp = proxy.getcreditServicesSoap();   System.out.println("Calling service method");   System.out.println("check credit(Al,100) returned:" +   + sp.checkcredit("Al",100));  System.out.println("check credit(Tom,1000) returned:" +                 sp.checkcredit("Tom",1000));             System.out.println("check credit(Unknown,1000) returned:" +                 sp.checkcredit("Unknown",1000));         }         catch (Exception e) {             e.printStackTrace();         }     } } 

Using a Web service from a Java client requires first downloading the client proxy JAR and its associated Web service's support JAR file (in this example, creditServices.jar and webservicesclient.jar ), and then adding them to the application's classpath.

After you've obtained the required JARs, using the Web service is a three-step coding process:

1. Obtain a handle to the proxy implementation of the service. Using the CreditServices Web service, you simply append _Impl to the name of the Web service. Notice that Workshop capitalizes the first letter of the name:

    CreditServices_Impl proxy = new CreditServices_Impl(); 

2. Obtain a handle to a SOAP proxy:

    CreditServicesSoap sp = proxy.getcreditServicesSoap(); 

   For all practical purposes, you can think of the SOAP proxy as though it were an instance of a local Java object implementing the actual business method you're interested in.

3. Finally, call the method of interest:

    System.out.println("check credit(Al,100) returned:" +     sp.checkcredit("Al",100)); 

JAVA CLIENTS AND WEB SERVICE URLS

It is assumed that the URL of the Web service implementation the client is using is the same as the URL where the client JAR file was downloaded. However, the actual URL is contained in the client JAR file WSDL within the WSDL address element. You can change this element if needed to access the same Web service at a different location, perhaps when moving from development to testing or from testing to production.

Of course, you can also use the client normally from a JSP by writing similar code, but embedding it appropriately within <% and %> JSP tags.