Creating a Web Service Client

The Sun ONE Studio 4, Enterprise Edition for Java IDE gives you several ways to create a web service client without writing client code. This chapter describes the IDE tools and procedures that you can use to do each of the following tasks:

• Generate a client from a Sun ONE Studio 4, Enterprise Edition for Java web service
• Generate a client from WSDL
• Generate a client from a UDDI registry entry

If you are creating your own web service and clients in the IDE, you can set the default test client for the service. For further information, see .

---

Creating a Client From a Local Web Service

This section assumes that you start with an existing web service developed in the IDE.

You can automatically generate a simple client and client SOAP proxy that is adequate for testing your web service during development. You can then edit the client or replace it entirely by a more sophisticated client that can be used for business purposes.

Creating the Client

You can create a client starting at a package node, a web service node, or the IDE's main window menu.

To start at a web service node:

1. Open the New Web Service Client wizard from the Explorer by right-clicking the web service node (the one with the blue sphere icon ) and choosing New Client.

The New Client dialog box is displayed, as illustrated in FIGURE 3-1.

 FIGURE 3-1 New Client From Web Service Dialog Box

2. Ensure that the Package field specifies the desired location in which to create the web service client.

Click Browse to find and select a package of your choice.

3. In the Name field, type a name for the new web service client.

If you enter the name of a web service client that already exists in the package designated in the wizard, the IDE displays a highlighted message: A web service client with this name already exists in package.

4. Click OK.

Your new web service client is displayed in the Explorer. A client node () appears under the designated package.

To start at a Java package node:

1. Right-click a Java package node and choose New Web Services Web Service Client.

Alternatively, Choose File New Template Web Services Web Services Web Service Client from the IDE's main window.

In this case the IDE displays the Web Service Client dialog box, as illustrated in FIGURE 3-2.

 FIGURE 3-2 New Web Service Client Dialog Box

2. Set the desired name and package.

3. Select Local Web Service for Source.

4. Click Next to open a browse window, select the desired web service in the browse window, and click Finish.

Your new web service client is displayed in the Explorer. A client node () appears under the designated package.

Setting the Client's SOAP Runtime Property

The IDE can generate a client that uses the JAX-RPC runtime (the default) the kSOAP runtime, or the Apache SOAP runtime. kSOAP is a SOAP API suitable for the Java 2 Microedition. Apache SOAP clients are supported for compatibility with the previous release of the IDE.

To change the client type:

1. Create the client.

2. Right-click the client node and choose Properties. The Soap Runtime property has the default value JAX-RPC.

3. Click the property value. The choices JAXRPC, Apache SOAP, and kSoap are displayed, as shown in FIGURE 3-3. Choose kSoap.

When you generate the client, a kSOAP proxy is created.

 FIGURE 3-3 Client SOAP Runtime Property

---

Note - The rest of this chapter assumes a JAX-RPC client, unless otherwise specified.

---

Generating the Client

To generate the client's SOAP proxy and test user interface (HTML and JSP pages), right-click the web service client node in the Explorer, and choose Generate Client Proxy.

During the generation process, the IDE analyzes the web service's WSDL and issues validation warning and error messages if there are problems such as invalid data types (for example, a user object that is not a valid JavaBean component). Validation is particularly important when you are creating a client from someone else's web service, such as a web service accessed through a UDDI registry. IDE validation is based on the JAX-RPC reference implementation.

The IDE puts the generated objects in the same package as the client. A Generated Documents node contains HTML and JSP pages that invoke the SOAP proxy classes.

If the client's SOAP Runtime property is kSoap or Apache SOAP, the IDE generates a single proxy class and puts it in a node named xxxProxy, where xxx is the client name. If the client's SOAP Runtime property is JAXRPC, the IDE generates many proxy classes and puts them in a node named xxxGenClient, where xxx is the client name.

The Explorer hierarchy for a JAX-RPC client is illustrated in FIGURE 3-4.

 FIGURE 3-4 Client Documents and GenClient Nodes in Explorer Hierarchical Display

[ D ]

The Client HTML Pages and JSP Pages

The following client documents are generated:

• One JSP page for each method or XML operation. Each of these JSP pages provides the functionality to execute its corresponding business method or XML operation and format the results in HTML. During development, you can use the JSP pages as a client for testing your business methods and XML operations. Web page designers can customize the generated JSP pages and use them as the basis for more sophisticated, user-friendly clients.
• One HTML welcome page. The welcome page displays one HTML form for all generated JSP pages. The HTML form provides the URLs needed to invoke the JSP pages. The forms includes fields for user input when input parameters are required.
• One HTML error page.

The names of the welcome page and error page appear as properties of the client node in the IDE.

To view the HTML or JSP code, right-click the node of the desired document and choose Open. Code samples for a welcome page and a JSP page are illustrated in FIGURE 3-5 and FIGURE 3-6.

 FIGURE 3-5 Client Sample HTML Welcome Page

 FIGURE 3-6 Client Sample JSP Page

The Client SOAP Proxy

FIGURE 3-7 shows an Explorer view of some of the proxy classes generated for a JAX-RPC client. To view the Java source code, right-click a class or method node and choose OPEN.

The IDE lets you edit the proxy source, but if you regenerate the client in the IDE, your proxy source changes are not preserved.

 FIGURE 3-7 Client SOAP Proxy GenClient Node

You can use the generated proxy with a Java Swing client or more sophisticated HTML and JSP pages.

Using Your Own Front End Client Components

Clients that use the kSOAP runtime execute on small J2ME devices such as cell phones and PDAs, whose user interfaces are typically constrained by the display limitations. Developers often use Java AWT, WML, and other presentation technologies to create the user interfaces.

If you set a client's SOAP Runtime property to kSoap, the IDE does not create a Generated Documents node and does not generate HTML or JSP pages.

If the client's SOAP Runtime property is JAX-RPC or Apache SOAP, you might want to suppress the generated documents under certain circumstances. For example, if you already have a front-end business client, you might want the IDE to generate only the client SOAP proxy, and to display your own client components. To do this:

1. Create the client.

2. Right-click the client node and choose Properties. The Generate Presentation property has the default value True.

3. Change the Generate Presentation property value to False.

When you generate the client, only the client SOAP proxy is created.

4. (Optional) Right-click the client node and choose Add References to Documents.

You can add references to documents created outside the IDE, such as HTML and JSP pages created in a web design tool, if you mount the directory containing the documents so they are visible in the IDE Explorer.

The IDE displays the Add Reference to Documents browser. Navigate to a folder that contains your own HTML and JSP pages and click OK in the browser to add the references to your client. The IDE creates a Documents folder containing the references. The Documents folder appears in the Explorer under the client node, on the same hierarchy level as the client's Generated Documents folder.

You can also right-click the client node and add references to Libraries and Classes. The IDE includes them in your test application's WAR file. The libraries and classes can be used to build a Swing test client.

---

Caution - Nodes within a referenced folder are links that represent actual files or folders. Deleting a reference to file or folder deletes only the reference, leaving the referenced file or folder intact. However, deleting a node inside a referenced folder deletes the file or folder that the node is linked to. Do not delete nodes within a referenced folder unless you want to delete actual files or folders.

---

Assembling the Client Application

To assemble the client application, right-click the client node in the Explorer and choose Assemble. The IDE creates a WAR file and displays a node in the Explorer with the WAR icon () and a name of the form clientName_Client.

To view the contents of the WAR file, right-click its node in the Explorer and choose View WAR Content. The display is illustrated in FIGURE 3-8.

If you change your web service and regenerate its runtime classes, you can cause the IDE to automatically regenerate the client. To do this, right-click the client in the Explorer and choose Refetch WSDL. This causes the client proxy and documents to be regenerated. (The Refetch WSDL command name refers to an internal WSDL that is based on the service and associated with the client. This WSDL is not displayed in the Explorer.)

You can then reassemble the client. Alternatively, the client will be automatically reassembled the next time you execute it.

 FIGURE 3-8 Client Sample WAR File Display

Deploying and Executing the Client

The web service referenced by your client must be currently deployed.

• To deploy the client, right-click its node in the Explorer and choose Deploy.
• To execute the client, right-click its node in the Explorer and choose Execute.

If you are using a Sun ONE Application Server 7 server, deploy and then execute.

If you are using the built-in Apache Tomcat web server it is not necessary to deploy as a separate step. When you choose Execute, the IDE automatically starts the web server, deploys the client application, and displays the client's welcome page in your default web browser. The result is illustrated in FIGURE 3-9.

Alternatively, you can make the client the default test client, as explained in . Then you can start the client by right-clicking the J2EE application of your web service and choosing Execute.

 FIGURE 3-9 Client Welcome Page

[ D ]

FIGURE 3-10 illustrates a display from the generated test client of a restaurant review application.

 FIGURE 3-10 Client Output Display of Collection of Customer Reviews

[ D ]

---

Note - The generated test client displays a collection of restaurant reviews as an XML document, including the SOAP envelope. In a production client intended for end users, you would probably eliminate the display of technical information and format the output in a more user-friendly manner.

---

---

Creating a Client From WSDL

WSDL provides a portable representation of the external interfaces of a web service. See for the procedure to create a WSDL description of your web service. See WSDL and for other information about WSDL and UDDI registries.

WSDL can be useful even if you are not using a UDDI registry. Several people on a project might be developing different kinds of clients, perhaps in different locations or on different schedules. They can be given copies of the WSDL to generate clients. A WSDL file is an XML document and can be put on a shared network drive, sent as an email attachment, or passed around on a disk. The developers must also have network access to a runtime instance of the web service to test their clients.

The following procedure assumes that you have a WSDL file, that the file name extension is .wsdl, and that the directory containing the file is mounted in the IDE. The .wsdl file appears as a node in the Explorer with a green sphere icon (). If someone gives you a WSDL file that does not satisfy this naming convention, you can rename it or make a copy with a file-name extension of .wsdl.

To generate a client from WSDL:

1. Choose File New Template Web Services Web Services Web Service Client from the IDE's main window.

The IDE displays the Web Service Client dialog box, as illustrated in FIGURE 3-2.

2. Set the desired name and package, and select Local WSDL File for Source.

3. Click Next to open a browse window.

4. Select the WSDL node in the browse window.

5. Click Finish.

The IDE creates a client node.

6. Right-click the client node in the Explorer and choose Generate Client Proxy.

The IDE creates the client SOAP proxy with its own node. The IDE also creates a set of HTML and JSP pages in the Generated Documents node under the client node.

7. The remaining steps, including assembly, deployment, and execution, are the same as in Creating a Client From a Local Web Service.

To generate only the client SOAP proxy, without the Generated Documents node:

1. Right-click the WSDL node in the Explorer, and choose Generate Client Proxy.

The IDE creates the client SOAP proxy with its own node.

2. Create your own client component that makes calls to the client SOAP proxy.

This might be the best approach if you already have fully developed clients that you can easily customize to use the client SOAP proxy, or if you want to use a type of client that is different from the HTML and JSP pages generated by the IDE, such as a Java Swing client.

---

Creating a Client From a UDDI Registry

Some of the business needs and scenarios that might lead you to create a client from a UDDI registry are described in Chapter 1.

Creating a Client: Planning and Implementation

The work flow consists of these tasks:

• Deciding your criteria for selecting a web service
• Selecting a UDDI registry to search
• Searching the UDDI registry for a web service
• Downloading information about the web service
• Generating the client
• Customizing the client

Task 1 requires advance planning and is part of the process of designing your application. It is not enough to consider the characteristics of the web service. You also have to think about the business that is providing the service, what kind of support the business offers, and how much your use of the service will cost. The analysis is simplified if you are using a private registry and the service provider is a part of your own project or enterprise, or perhaps a business partner collaborating on your project.

Creating a Client: Procedure

This section describes how to use the IDE to select a registry, search the registry for a service, and generate a client that can access a runtime instance of the service.

1. Right-click a Java package node and choose New Web Services Web Service Client.

Alternatively, Choose File New Template Web Services Web Services Web Service Client from the IDE's main window.

The IDE displays the Web Service Client dialog box, as illustrated in FIGURE 3-11.

 FIGURE 3-11 New Web Service Client Wizard

2. Set the desired name and package, and select the UDDI Registry Web Service radio button for Source.

3. Click Next to display the Select a UDDI Registry dialog box, as illustrated in FIGURE 3-12.

The dialog box displays a list of UDDI registries. Select the desired registry or click Edit to edit registry information or change the default registry (see ).

---

Note - The initial default registry in the IDE is the internal UDDI registry that is bundled with the IDE. For further information about this registry, see .

---

 FIGURE 3-12 UDDI Registry Selection Dialog Box

Most UDDI registries provide browser-based tools for registry searches and for adding, editing, and deleting registry entries. The Browser Tools URL for a registry is one of the properties that you can edit in the IDE (see ).

To search a selected registry with its own browser tools:

a. Select the "Search for service using a web browser" radio button.

The Launch Browser button becomes active.

If you already have the web service's registry key from a previous search, paste the value into the Service Key field and click Next. The IDE displays the final wizard step in which you can click Finish to create the client, bypassing intermediate UDDI registry search steps.

b. Click Launch Browser.

The IDE opens your default web browser at the Browser Tools URL web page.

c. Use the browser tools to locate the web service that you want to access with your client.

d. Copy the web service registry key and paste it into the Service Key field in the Select a UDDI Registry dialog box.

e. Click Next.

The IDE displays the final wizard step in which you can click Finish to create the client, bypassing intermediate UDDI registry search steps.

The remainder of this procedure assumes that you do your search through the IDE wizard. This is the default radio button under "How to Find Web Service."

4. Select a registry from the UDDI Registry list and click Next to display the UDDI Registry Search dialog box, as illustrated in FIGURE 3-13.

 FIGURE 3-13 UDDI Registry Search Dialog Box

[ D ]

You can search for businesses whose names contain a string that you specify. You can also base your search on a type other than business name. The list of search types is shown in FIGURE 3-14.

 FIGURE 3-14 UDDI Registry Search Types

[ D ]

You can search on tModel name, NAICS code name, or ISO 3166 code name.

You can also search for a D-U-N-S business identifier or Thomas Registry business identifier, in which case the search is for a value "Equal To" rather than "Containing." You might know the identifier from a previous search. If you are using a private UDDI registry, someone in your project or enterprise might give you the identifier.

---

Note - If the search type requires an exact value, the label in the UDDI Registry Search dialog box (FIGURE 3-13) changes from Containing to Equal To.

---

For NAICS or ISO 3166 code name searches, you can enter either a name or a code in the Containing field. For example:

• Select ISO 3166 and specify a search string of United Kingdom or GB.
• Select NAICS and specify a search string of Other Financial Vehicles or 52599.

A search on tModel Name returns all businesses that contain services that are based on the tModels matching the search string.

A search on NAICS Code Name or ISO 3166 Code Name returns all businesses that have categories matching the search string.

---

Note - When you specify a string in the Containing field, the IDE wraps your string in a wildcard: %yourstring%. You can optionally insert more wildcards. For example, you can search for a business whose name contains the string bio%tech, where % matches any string. String searches are case-insensitive.

---

The remainder of this procedure assumes that you search on business name.

5. Specify a string in the Containing field and click Search.

The Matching Businesses table displays all businesses in the registry whose names contain your search string, as illustrated in FIGURE 3-15. Each business is listed with its name and an optional description. The number of matching businesses is also displayed.

You can select a business from the table and proceed to Step 7 of this procedure.

Depending on your search string and the size of the registry, your search might return a large number of businesses. This is most likely to occur with public registries, which are expected eventually to grow to tens of thousands or even millions of entries. If the list returned by your search is too large, you can enter a more carefully chosen search string or you can use the registry browser tools to perform a more advanced search.

---

Note - In a realistic scenario, a development team or planners probably have a pretty good idea what businesses they are interested in. The main problem finding a business in the registry might be getting the correct spelling or (in the case of a large enterprise with many divisions, departments, and projects) finding out which of its names is used in the registry. Registry search features can help, but in many cases this information is managed by the appropriate project leaders.

---

 FIGURE 3-15 UDDI Registry Search Dialog Box With Matching Businesses

6. Click Filter Businesses to further refine your search.

There might be services in the registry that have no WSDL tModel entries. Since you can't create clients for those services, the IDE enables you to filter them out of the Matching Businesses table. When you click Filter Businesses, the IDE searches the UDDI registry for services associated with the businesses in your result set. The IDE checks the services for tModels that have an OverviewDoc with an OverviewURL field that begins with "http://" and ends with either "wsdl" or "asmx". Businesses that fail this test are filtered out of the Matching Businesses table.

The IDE displays a progress monitor window with a Cancel button, as illustrated in FIGURE 3-16. The filtering process can take some time. If it takes too long, you can click Cancel and start over with a more refined search string.

 FIGURE 3-16 UDDI Registry Filter Business Progress Monitor

7. Select a business from the Search Results list.

The IDE displays services associated with the selected business, as illustrated in FIGURE 3-17, and activates the Next button. Only services with WSDL tModel entries are displayed.

---

Note - The registry might not have enough information about a business or service to guide your decision. Public registries are still in their infancy and can be viewed as elements of a broader web service infrastructure in which usage patterns and practices will emerge over time. A private registry gives the registry owner more control of the criteria for publishing services. For example, a private registry might have standards for documenting entries and requirements about the runtime availability of services that are published to the registry. There might be a distinction between services available for development and testing, and services available for use in production applications.

---

 FIGURE 3-17 UDDI Registry Select Service

8. Select a service and click Next to display the Service Interface dialog box, as illustrated in FIGURE 3-18.

The dialog box shows detail information about the service and the tModels and WSDL that it references.

For the service, you see the name, network endpoint, and key. The network endpoint is the URL that a client can use to access the runtime service instance.

For each WSDL tModel, you see name and overview URL. The overview URL is the locator for the WSDL that the IDE uses to create your client.

---

Note - A web service provider might publish several tModels for a given service instance. For example, one tModel might allow full use of the service methods and another tModel might provide access to a subset of the service methods. This is reflected in clients generated from the two different tModels.

---

 FIGURE 3-18 UDDI Registry Display Service Details and tModel

9. Select a WSDL tModel and click Finish to complete the client creation procedure.

The IDE creates your web service client. It appears in the Explorer under the designated package as a new client node.

10. The remaining steps, including assembly, deployment, and execution, are the same as in Creating a Client From a Local Web Service.

---

The Service Endpoint URL

For your client to access a service instance at runtime, the client proxy must have the endpoint URL of the service. The IDE can set a default URL in the proxy, or the URL can be passed to the proxy at runtime in its serviceURL parameter, which overrides the default.

The client JSP pages generated by the IDE do not pass the URL at runtime, but assume that the client proxy has a default value for serviceURL. The default URL comes from the WSDL that is used to generate the client proxy.

As explained earlier in this chapter, you can generate a client from your own web service, from a WSDL file displayed in the IDE, or from a service that you find in a UDDI registry. In all of these cases, the IDE creates a hidden file containing WSDL that describes the web service, and the IDE creates the client based on the WSDL. The hidden file, which has a file name extension of .wsdx, cannot be displayed or modified in the IDE. However, you can find the hidden file in the same directory as the client, make a copy of the file with a file name extension of .wsdl, and pass it around so that other developers can generate clients in their instances of the IDE.

---

Note - If you edit the WSDL in the hidden file outside the IDE, your changes will be lost the next time you generate the client.

---

The default URL in the hidden WSDL file is derived as follows:

• If you generate a client from your own web service, the IDE sets the service URL equal to the SOAP RPC URL property of your service.
• If you explicitly generate WSDL from your own web service, the WSDL is visible in the Explorer, and the IDE sets the service URL equal to the SOAP RPC URL property of your service. If someone gives you WSDL directly as an XML document, it might or might not contain the service URL. The WSDL is visible in the Explorer if the file containing it has a name with a .wsdl extension and the directory containing it is mounted in the IDE.
• If you select a visible WSDL file in the Explorer and generate a client, the IDE copies the WSDL to a hidden file with a .wsdx extension, and uses the latter to generate the client. If the WSDL does not contain a value for service URL, the proxy is generated without a default value for the service URL.
• If you generate a client from a UDDI registry, the WSDL is downloaded to your IDE and stored as a hidden file with a .wsdx file extension. If the UDDI service entry provides a URL, the IDE puts that URL into the downloaded WSDL, regardless of whether a URL is coded in the original WSDL.
• If the generated proxy does not have a default value because none was provided in the scenarios described above, the service URL must be passed to the proxy at runtime.