Tools Guide

CHAPTER 5    Web Service Wizard

This chapter describes the Web Service Wizard of Novell exteNd Workbench, which you can use to generate files for implementing and invoking Web Services. Topics include:

• About the wizard

• Using the wizard

• Panel sequence

• Panel details

    For an introduction to Web Service concepts, standards, and technologies, see the chapter on understanding Web Services in the Development Guide.

About the wizard

The Web Service Wizard can perform either of these tasks for you:

• Generate a standard (SOAP-based) Web Service that's implemented as a Java remote object. The wizard creates a servlet to handle access to your Web Service and its methods from HTTP SOAP requests.

• Generate the code needed for a Java-based consumer program to access any standard (SOAP-based) Web Service. The generated code handles all HTTP SOAP processing under the covers, enabling your consumer program to call the Web Service as a Java remote object and invoke its methods.

In both cases, the wizard produces Java source files based on JAX-RPC (Java API for XML-based RPC) and jBroker Web (the JAX-RPC implementation included with Novell exteNd). JAX-RPC is the J2EE specification that provides Web Service support.

You can use the generated files as is or modify them when necessary. The advantage of this Java-oriented approach is that you can deal with Web Services using the familiar technologies of RMI and J2EE instead of coding lower-level SOAP APIs.

How it works   Behind the scenes, the Web Service Wizard uses several different compilers to generate the output you request:

The wizard determines which compilers to run and in what order depending on the type of input you provide and options you select when filling in its panels.

Alternatives to the wizard   You can also run the individual wsdl2java, xsd2java, rmi2soap, and rmi2wsdl compilers manually from a command line. For more information, see the jBroker Web help.

Using the wizard

Here's where you'll learn about preparing to use the Web Service Wizard, running it, and working with its output:

Panel sequence

This section lists the panels you need to complete in the Web Service Wizard, depending on your scenario:

Panel details

This section describes the options on each panel of the Web Service Wizard. The panels are:

• Project location

• WAR project selection

• Class selection

• WSDL file selection

• Multiple namespace mapping

• EJB home interface selection

• EJB lookup information

• Method selection

• Class-generation and SOAP options

Project location

This panel is used to specify details about the project location (project, directory, package) where the wizard is to store Web Service files it generates. There are two variations of this panel:

• If you start with a WSDL file, you'll see:

  

• If you start with anything else (JavaBean, Java class, EJB session bean, or Java remote interface), you'll see:

  

  In this variation, you don't specify a package (because the wizard will get this information from your class or interface, which you supply on an upcoming panel).

To complete this panel:

1. Specify the project:

   Option	What to do
   Add to open project	Select a project where the wizard is to store generated files. This option lets you choose from a list of the projects currently open in Workbench. If you're generating a Web Service, you'll typically select a WAR project. When appropriate, you can select a JAR project instead, but then the wizard will prompt for a WAR project to map the Web Service's servlet. See WAR project selection. (When you generate a Web Service from a WSDL file, the wizard does not currently support selecting a JAR project. It requires you to select a WAR project.) If you're generating a Web Service consumer, you can select any type of project.
   Create project	Click this button if you want to create a new project to use. It displays the New Project dialog.     See Creating projects and subprojects.
   No project -- just write files to the disk	(This option is disabled. In the Web Service Wizard, generated files must be added to an open project.)

2. Specify the directory and package:

   Option	What to do
   Base directory	The default base directory is a src subdirectory located right under the project directory on your file system. If you want to select a different file system location, click Browse.
   Package	(If enabled) Specify the fully qualified Java package name to be used for generated classes (for example, com.myco.mypkg).
   File directory	This informational field shows the file system location where generated files will be stored. It is the result of combining Base directory and Package.
   Add the files to the root of the archive	(If enabled) Choose this option to place the generated files (and their package path, if any) at the root of the project archive.
   Add the files to the archive with this prefix	Choose this option to place the generated files (and their package path, if any) under a specified directory structure (prefix) in the project archive. For a WAR project, the prefix is automatically set to WEB-INF/classes.
   The files will be added to this location in the archive	(If displayed) This informational field shows the project archive location where generated files will be stored. It is the result of combining Prefix and Package.

3. Click Next.

WAR project selection

This panel is used to specify the required WAR project for a Web Service stored in a JAR project. The wizard will update this WAR's deployment descriptor (web.xml) with the servlet mapping for the Web Service.

To complete this panel:

1. Specify the following:

   Option	What to do
   WAR project	Select the WAR project for the Web Service's servlet mapping. This option lets you choose a WAR project currently open in Workbench.
   Create project	Click this button if you want to create a new WAR project to use. It displays the New Project dialog.     See Creating projects and subprojects.

2. Click Next.

Class selection

This panel is used to select a compiled class from which the wizard is to generate Web Service files. Supported choices include:

• A JavaBean or other Java class

• An EJB session bean interface or class

• A Java remote interface

By default, this panel finds the compiled classes in the selected project's build directory and lists them in the Available Classes box. For a WAR project, this list comes specifically from WEB-INF/classes in the build directory.

To select from the current list:

1. Click an item in the Available Classes list.

2. Click Next.

To refine the current list:

• Click one of the Class Filter radio buttons to narrow the Available Classes list to classes of a particular kind.

To list classes from another location:

• Click the browse (...) button for Class location (directory or JAR) to select a different directory or JAR file.

  This refreshes the Available Classes list to show just the compiled classes from that new location.

WSDL file selection

This panel is used to select a WSDL file from which the wizard is to generate Web Service files. You can select it from your project, from your file system, or from the Web (by specifying an URL).

NOTE:   If you're planning to generate a new Web Service from a WSDL file, you may need to edit that WSDL file beforehand to make sure the SOAP address in the service definition specifies the correct binding URL. The Web Service Wizard will use this URL in the files it generates for your Web Service.

By default, this panel finds the .wsdl files in the selected project and lists them in the WSDL Files In Project box.

To select from the current list:

1. Click an item in the WSDL Files In Project list to make it the WSDL file to use.

2. Click Next.

To select from the file system:

1. Click the browse (...) button for WSDL file or URL to use to select a WSDL file from your file system.

2. Click Next.

To specify a file by URL:

1. Type the URL for the target WSDL file in WSDL file or URL to use. For example:

     http://upload.eraserver.net/circle24/autoloan.asmx?wsdl
   

2. Click Next.

Multiple namespace mapping

This panel is used when you're generating from a WSDL file that uses multiple namespaces for the complex types in its XML schema. It lets you map each namespace to a separate Java package.

NOTE:   The mappings on this panel are used only if the option Map complex XML types to Java types is checked on the next panel ( Class-generation and SOAP options).

This panel lists the appropriate namespaces and fills in a default package name for each one. You can edit any or all of these package names. Just make sure you specify a unique package name for each namespace.

To edit the namespace-to-package mappings:

1. Double-click any name in the Package column to edit it, then type the text you want.

   (You can't edit the names in the Namespace column.)

2. When you're done editing package names, click Next.

EJB home interface selection

This panel is used to select the home interface that corresponds to an EJB session bean class or remote interface you've specified on the class selection panel.

By default, this panel looks in the location of the EJB session bean class or remote interface to find home interfaces (compiled classes that extend javax.ejb.EJBHome). If there are any, it lists them in the Available Classes box.

To select from the current list:

1. Click an item in the Available Classes list to make it the Selected Class.

2. Click Next.

To list classes from another location:

• Click the browse (...) button for Class location (directory or JAR) to select a different directory or JAR file.

  This refreshes the Available Classes list to show just the compiled classes from that new location.

EJB lookup information

This panel is used to specify information that the Web Service will need to do a JNDI lookup for a selected EJB session bean. (JNDI is the Java Naming and Directory Interface.)

This panel displays default initial context values appropriate for looking up a session bean deployed to the Novell exteNd Application Server. For information on what other J2EE servers require, consult their documentation.

To complete this panel:

1. Specify the Deployed JNDI Name:

   Option	What to do
   Lookup String	Specify the subcontext and JNDI name under which the session bean is registered on the target J2EE server. For example, to look up the session bean whose JNDI name is SBMyEJB in the ejb subcontext: ejb/SBMyEJB

   The wizard includes this information in the ejb-ref declaration it generates within the deployment descriptor web.xml. To learn how it is used at runtime to do a JNDI lookup, see the getSessionBean() method of xxxDelegate.java (the delegate class generated for the tie servlet).

2. Specify Initial Context Information:

   Option	What to do
   Factory Class	Specify the package prefix and name of an InitialContext factory class that's appropriate for the target J2EE server.
   Provider URL	Specify the URL for the JNDI namespace of the target J2EE server.
   User ID	Specify a valid user name that has authority to log on to the target J2EE server and access the session bean.
   Password	Specify the password for User ID.

   The wizard includes this information in the servlet declaration it generates within the deployment descriptor web.xml. To learn how these values are used at runtime, see the getInitialContext() method of xxxDelegate.java.

3. Click Next.

Method selection

This panel is used to select the methods you want to expose when generating a Web Service from a JavaBean or other Java class.

This panel examines the selected class and lists its eligible methods in the Available Methods box.

To select methods to expose:

1. Use the Add and Add All buttons to move one or more items from Available Methods to Selected Methods.

   If necessary, you can use Remove and Remove All to move one or more items back.

2. Click Next.

Class-generation and SOAP options

This panel is used to select the Web Service files to generate (including skeleton, tie, and stub classes) and to specify SOAP implementation details to encode in those files. There are two variations of this panel:

• If you start with a WSDL file, you'll see:

  

• If you start with anything else (JavaBean, Java class, EJB session bean, or Java remote interface), you'll see:

  

  Note that only this variation provides the SOAP options and the ability to generate a WSDL file.

To complete this panel:

1. Specify Generation Options:

   Option	What to do
   Generate stubs	Check this option to generate classes for consuming the Web Service, including service classes, a stub class, and a simple client application. You'll get the following source files: xxxService.java xxxServiceImpl.java xxx_Stub.java xxxClient.java
   Generate skeletons	Check this option to generate classes for implementing the Web Service. Then choose one of these implementation models: Tie-based    Generates skeleton and tie servlet classes used to handle requests for your Web Service and delegate method calls to a separate implementation class. You'll get the following source files: xxx_ServiceSkeleton.java xxx_ServiceTieSkeleton.java xxxTie.java If you start with a JavaBean, Java class, or EJB session bean, you'll also get this source file (used to delegate to your class): xxxDelegate.java Not tie-based    Generates just a skeleton servlet class used to handle requests for your Web Service. You'll get the following source file: xxx_ServiceSkeleton.java
   Generate WSDL file	(If displayed) Check this option to generate the following file: xxx.wsdl It describes your Web Service in standard WSDL format, which is useful when publishing to a registry. The wizard stores this file in the base directory of your source tree (commonly named src).
   Generate jBroker Web 1.x compatible classes	Check this option to generate the specified files according to the original jBroker Web (Version 1.x) conventions for: File names Stub access in client code Except for these conventions, the generated files will conform to the latest version of jBroker Web. This option is appropriate only if you're maintaining an application that originated in jBroker Web 1.x and aren't yet ready to switch to the current conventions (which are based on JAX-RPC and may require some changes to existing code).     For details on what this option generates, see the chapter on generating Web Services in the Development Guide.
   Directory with local XSD files	(If displayed) When the selected WSDL file relies on imported XSD files for its type definitions, you can optionally specify a local directory that contains copies of them. If the wizard can't access a particular XSD file based on the location specified in the WSDL file, it will look for that XSD file in your local directory.     For more information about XSD files, see the WSDL specification.
   Map complex XML types to Java types	(If displayed) Check this option if the wizard should try to map complex types defined in the selected WSDL file (via XML Schema) to specific Java types. Uncheck this option if the wizard should map all complex XML types to the org.w3c.dom.Element Java type.

2. Specify SOAP Options (if displayed):

   Option	What to do
   Target namespace	Specify the target namespace for SOAP messages produced by the generated stub and skeleton classes. Method and parameter names are scoped to this namespace when SOAP messages go over the wire. You can accept the default value or specify any string for the namespace. It doesn't have any special semantics beyond providing a scope for SOAP messages. When generating a WSDL file, the wizard uses this value for the targetNamespace definition.
   Service address	Specify the URL to be used as the binding for accessing your Web Service. The wizard includes this binding information in the following generated files: The stub class (xxx_Stub.java) and service implementation class (xxxServiceImpl.java) use it as the default URL for binding to the Web Service. The WSDL file (xxx.wsdl) uses it as the SOAP address in the service definition. The default value for this option includes the name of the selected WAR project and the servlet mapping for the Web Service. For example: http://localhost/WebServiceSample/MyObject If you plan to deploy the Web Service to the Novell exteNd Application Server, you need to insert the name of the target database in the URL: http://localhost/WebServiceSampleDB/WebServiceSample/MyObject
   Binding style	Choose one of the following: Document style & literal encoding    In this format, the SOAP message body contains just the XML document being exchanged and message parts map to elements literally defined in the WSDL file's XML schema RPC style & SOAP encoding    In this format, the SOAP message body contains argument and return values, individually wrapped in ad hoc elements that the recipient must interpret by applying specified encoding rules to each message part's type When making this choice, consider the requirements of any other Web Service environments your Web Service must interoperate with. In most cases either style should work, but some environments may favor a particular style.

3. Click Finish.

	Tools Guide

Copyright © 2001, 2002, 2003 SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.