Utility Tools

CHAPTER 10

Web Service Wizard

This chapter describes the Web Service Wizard of the Novell exteNd Director development environment, 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 Web Service Basics.

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 the Novell exteNd Web Services SDK (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 Web Services SDK 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

• Web Service type mappings

• EJB home interface selection

• EJB lookup information

• Method selection

• Binding style

• Schema information

• 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. 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 that's currently open.
   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

NOTE:   This panel won't let you select an EJB or remote interface that defines overloaded method names. Overloaded method names are not allowed in Web Service interfaces (as of WSDL 1.2). You must remove them from your class before starting the wizard.

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:   This panel won't let you select a WSDL file that defines overloaded method names. Overloaded method names are not allowed in Web Service interfaces (as of WSDL 1.2). You must remove them from your WSDL file before starting the wizard.

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 Create new Java types for complex XML types is selected on the Web Service type mappings panel.

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.

Web Service type mappings

This panel is used to specify how data types are to be mapped when you're generating from a WSDL file. It provides choices for handling the complex types and simple types defined in the WSDL (via XML Schema).

To specify how data types are to be mapped:

1. Do one of the following:

   If you want to	Do this
   Map the complex types defined in the selected WSDL file to specific Java types	Select the radio button Create new Java types for complex XML types. If the WSDL file specifies RPC as the binding style, this radio button is automatically selected; you can't unselect it. Uncheck the option JAX-RPC 1.0 compatibility for simple XML types unless you need it to avoid changing code in an existing project. Checking this option tells the wizard to handle simple types (and any affected complex types) the way it did prior to exteNd 5.2 (when the Web Services SDK followed JAX-RPC 1.0). That means it will generate a JavaBean for each simple type. Unchecking this option tells the wizard to handle simple types according to the latest supported JAX-RPC specification. That means simple types will be mapped directly to the most basic types they specify. If you're regenerating an existing project that includes simple type JavaBeans and you don't want to disrupt code that accesses those JavaBeans, you should check this option.     For more information, see the Web Services SDK help.
   Map all complex types to one selected built-in type that lets you access the Web Service data as XML (instead of Java classes)	Select the radio button Use a single built-in type for complex XML types. Select one of the following radio buttons to specify which built-in type to use: java.lang.Object org.w3c.dom.Element javax.xml.transform.Source

2. 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.

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.

NOTE:   Overloaded method names are not allowed in Web Service interfaces (as of WSDL 1.2). As a result, this panel lets you select no more than one method with a given name.

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.

Binding style

This panel is used to specify the binding style when generating a Web Service from a JavaBean, Java class, EJB session bean, or Java remote interface.

To specify the binding style:

1. 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.

2. Click Next.

Schema information

These panels are used to specify XML Schema information to include in the WSDL file you generate for a Web Service. The Web Service Wizard prompts for this information if:

• You're generating from a class (JavaBean, Java class, EJB session bean, or Java remote interface) that defines method parameters (arguments or return values) of type org.w3c.dom.Element

  AND

• You specified the Document style & literal encoding option on the Binding style panel

There are two related Schema information panels:

• On the Schema includes panel, you specify the path or URL of zero or more Schema (XSD) files to include in the generated WSDL.

  

• On the Method type mapping panel, you specify how each Element method parameter maps to a qualified name in one of those Schemas.

  

  As an alternative, you can map a parameter to a sample XML instance data file. In that case, the wizard generates the Schema information for you based on the instance data.

NOTE:   The information on these panels is used only if the option Generate WSDL file is checked on the Class-generation and SOAP options panel.

To specify Schema includes:

1. Use the Add button to specify the path or URL of each Schema (XSD) file to include in the list.

   If necessary, you can use the Delete button to remove one or more selected files from the list.

2. Click Next.

To specify method type mapping:

1. For each method parameter listed on the panel, do one of the following:

   If you want to	Do this
   Map a method parameter to a qualified name in a listed Schema	Select the row of information for that parameter. In the Element Type Details section, select the Schema radio button. Select a qualified name from the Schema element list.
   Map a method parameter to an instance data file	Select the row of information for that parameter. In the Element Type Details section, select the Sample XML Data radio button. Use the browse (...) button to select the XML file containing the appropriate instance data.
   Skip mapping a method parameter	Select the row of information for that parameter. In the Element Type Details section, select the Unspecified radio button. The parameter will be represented as type any in the generated WSDL.

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:

  

  Only this variation provides the ability to generate a WSDL file.

NOTE:   When you create a new Web Service from WSDL, the Web Service Wizard does not generate a new or updated copy of that WSDL file for you. That means you must edit the WSDL yourself if you want it to reflect changes you've specified via the wizard (such as an override of the default Service address URL).

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 the Web Services SDK. 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 If you choose jBroker Web 1.x compatibility.
   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.

2. Specify SOAP Options:

   Option	What to do
   Target namespace	(If displayed) 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. If you are generating from WSDL, you can override the default value of Service address (which is obtained from the WSDL) by specifying a different URL in this option. If you are generating from Java, 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

3. Click Finish.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...