Developer’s Guide

Borland ®
™
P r ev i e w Web Services Kit for Java
Release 3
Borland Software Corporation
100 Enterprise Way, Scotts Valley, CA 95066-3249
www.borland.com
Refer to the file DEPLOY.HTML located in the redist directory of your product for a complete list of files that you can
distribute in accordance with the product License Statement and Limited Warranty.
Borland Software Corporation may have patents and/or pending patent applications covering subject matter in this
document. Please refer to the product CD or the About dialog box for the list of applicable patents. The furnishing of
this document does not give you any license to these patents.
COPYRIGHT © 2001–2002 Borland Software Corporation. All rights reserved. All Borland brand and product names
are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries.
All other marks are the property of their respective owners.
For third-party conditions and disclaimers, see the Release Notes on your product CD.
Printed in the U.S.A.
websvcsdg beta0602
0203040506-9 8 7 6 5 4 3 2 1
PDF
 Contents
Chapter 1 Chapter 5
Introduction 1-1 Working with WSDL 5-1
Documentation conventions . . . . . . . . . . . 1-2 Working with WSDL in JBuilder . . . . . . . . . 5-2
Note to Macintosh users . . . . . . . . . . . . 1-4 Import WSDL wizard . . . . . . . . . . . . . . 5-2
Contacting Borland developer support . . . . . 1-4 Export Class As A Web Service wizard . . . . 5-3
Online resources . . . . . . . . . . . . . . . . 1-5
World Wide Web . . . . . . . . . . . . . . . . 1-5 Chapter 6
Borland newsgroups . . . . . . . . . . . . . . 1-5 The WSDD file 6-1
Usenet newsgroups . . . . . . . . . . . . . . 1-5
Reporting bugs . . . . . . . . . . . . . . . . . 1-6 Chapter 7
Developing EJBs as web services 7-1
Chapter 2 Customizing deployment . . . . . . . . . . . . . 7-4
Introducing web services 2-1 Modifying the deployment node
The architecture of web services . . . . . . . . . 2-1 properties. . . . . . . . . . . . . . . . . . . . 7-4
Web service standards . . . . . . . . . . . . . . . 2-2 Editing the WSDD file . . . . . . . . . . . . . 7-4
The Simple Object Access Protocol
(SOAP) . . . . . . . . . . . . . . . . . . . . . 2-2 Chapter 8
Web Services Description Language Browsing and publishing web
(WSDL) . . . . . . . . . . . . . . . . . . . . 2-3
Universal Description, Discovery and services 8-1
Integration (UDDI) . . . . . . . . . . . . . . 2-4 Web Services Explorer overview . . . . . . . . . 8-1
Web Services Inspection Language UDDI overview . . . . . . . . . . . . . . . . . . . 8-2
(WSIL) . . . . . . . . . . . . . . . . . . . . . 2-4 UDDI terms and definitions . . . . . . . . . . 8-3
The Borland Web Services Kit for Java . . . . . 2-4 Axis overview . . . . . . . . . . . . . . . . . . . . 8-5
WSIL overview . . . . . . . . . . . . . . . . . . . 8-5
Chapter 3 Adding and deleting nodes in the
Explorer’s tree . . . . . . . . . . . . . . . . . . . 8-5
Working with SOAP servers 3-1 Searching a UDDI registry . . . . . . . . . . . . . 8-7
Working with SOAP servers in JBuilder. . . . . 3-1
Finding a business. . . . . . . . . . . . . . . . 8-7
Working with the SOAP Server wizard . . . 3-2
Searching by name. . . . . . . . . . . . . . 8-7
Selecting a SOAP toolkit . . . . . . . . . . 3-3
Searching by category . . . . . . . . . . . . 8-9
Defining a runtime configuration
Searching by identifier . . . . . . . . . . 8-11
for the SOAP server. . . . . . . . . . . . 3-4
Finding a service . . . . . . . . . . . . . . . 8-11
Examining the WebApp node. . . . . . . . . 3-4
Finding a tModel . . . . . . . . . . . . . . . 8-12
Starting the SOAP server . . . . . . . . . . . 3-4
Searching by name. . . . . . . . . . . . . 8-12
Setting build options . . . . . . . . . . . . . . 3-5
Examining UDDI query results . . . . . . . . . 8-13
For more information . . . . . . . . . . . . . 3-5
Detail pages in the Web Services
Explorer. . . . . . . . . . . . . . . . . . . . 8-13
Chapter 4 Details page . . . . . . . . . . . . . . . . 8-14
Monitoring SOAP messages 4-1 Business Details page . . . . . . . . . . . 8-14
Creating a new TCP/IP Monitor . . . . . . . . . 4-1 Service Details page . . . . . . . . . . . . 8-14
Monitoring a service’s SOAP messages . . . . . 4-3 Binding Details page . . . . . . . . . . . 8-14

i
 TModel Instance Details page . . . . . . . 8-14 Step 3: Importing the WSDL file . . . . . . . . 10-2
TModel Details page . . . . . . . . . . . . 8-14 Step 4: Implementing the service . . . . . . . . 10-4
Searching an Axis server for web services . . . 8-14 Step 5: Creating the Public web application . . 10-4
Displaying services. . . . . . . . . . . . . . . 8-15 Step 6: Creating a JSP that invokes the
Accessing remote Axis servers . . . . . . . . 8-16 web service. . . . . . . . . . . . . . . . . . . . 10-5
Searching web services with WSIL Step 7: Implementing the bean . . . . . . . . . 10-7
documents . . . . . . . . . . . . . . . . . . . . 8-17 Step 8: Invoking the web service . . . . . . . . 10-9
Services node . . . . . . . . . . . . . . . . . . 8-17
Links node . . . . . . . . . . . . . . . . . . . 8-18 Chapter 11
Executing a search . . . . . . . . . . . . . . . 8-19 Tutorial: Publishing a bean as a
Publishing web services in a UDDI registry . . 8-20
Publishing a web service . . . . . . . . . . . 8-20
web service 11-1
Step 1: Creating a new project . . . . . . . . . . 11-1
Publishing a tModel . . . . . . . . . . . . . . 8-21
Step 2: Creating a sample Java bean . . . . . . 11-2
Publishing a web service from an
Step 3: Exporting the sample bean as a
Axis server . . . . . . . . . . . . . . . . . . 8-22
web service. . . . . . . . . . . . . . . . . . . . 11-2
Monitoring UDDI messages . . . . . . . . . . . 8-23
Step 4: Creating a new SOAP server . . . . . . 11-3
Generating Java classes . . . . . . . . . . . . . . 8-23
Step 5: Running and testing the web service. . 11-4
Chapter 9 Chapter 12
Tutorial: Generating Java classes Tutorial: Using the Web Services
from a WSDL file 9-1 Explorer 12-1
Step 1: Creating a SOAP server. . . . . . . . . . 9-2
Overview . . . . . . . . . . . . . . . . . . . . . 12-1
Step 2: Generating the Java classes. . . . . . . . 9-3
About this tutorial . . . . . . . . . . . . . . . . 12-2
Step 3: Looking at the deployment descriptor . 9-5
Step 1: Browsing all web services at the
Step 4: Creating a test class . . . . . . . . . . . . 9-6
XMethods site . . . . . . . . . . . . . . . . . . 12-2
Step 2: Browsing tModels . . . . . . . . . . . . 12-5
Chapter 10 Step 3: Finding software publishers at
Tutorial: Generating a web service the Microsoft UDDI site . . . . . . . . . . . . 12-6
from a WSDL document 10-1 Step 4: Generating Java classes . . . . . . . . . 12-7
Step 1: Creating a new project . . . . . . . . . . 10-1
Step 2: Creating a new SOAP server . . . . . . . 10-2 Index I-1

ii
 Chapter

1
Introduction
Chapter1

This is a feature of the The Web Services Developer’s Guide explains how to use the Borland Web
Borland Web Services Kit Services Kit for Java to create, browse, and publish web services.
for Java.
The Web Services Developer’s Guide contains the following chapters:
• Chapter 2, “Introducing web services”
Provides an overview of web services and the features of the Borland
Web Services Kit for Java.
• Chapter 3, “Working with SOAP servers”
Explains how to create a SOAP server using the SOAP Server wizard
and how to run the SOAP server in the JBuilder IDE.
• Chapter 4, “Monitoring SOAP messages”
Describes how to use the TCP Monitor to monitor the SOAP envelopes
as they’re transported between the client and the server.
• Chapter 5, “Working with WSDL”
Give an overview of WSDL and explains how to use the Import WSDL
wizard and the Export Class As A Web Service wizard.
• Chapter 6, “The WSDD file”
Discusses the deploy.wsdd file which is generated by the Import WSDL
wizard and the Export Class As A Web Service wizard.
• Chapter 7, “Developing EJBs as web services”
Describes how to publish Enterprise JavaBeans as web services.
• Chapter 8, “Browsing and publishing web services”
Describes how to use the Web Services Explorer to browse and publish
web services.

Introduction 1-1
Documentation conventions

• Tutorials:
• Chapter 9, “Tutorial: Generating Java classes from a WSDL file”
Explains how to use the Import WSDL wizard to generate the Java
classes for a simple web service from a WSDL file.
• Chapter 10, “Tutorial: Generating a web service from a WSDL
document”
Explains how to use the Import WSDL wizard to generate Java
classes for a web service, then implement the classes to provide
access to AltaVista’s BabelFish translation service.
• Chapter 11, “Tutorial: Publishing a bean as a web service”
Explains how to use the Export Class As A Web Service wizard to
publish a JavaBean as a web service, exposing selected methods to
the web service consumer.
• Chapter 12, “Tutorial: Using the Web Services Explorer”
Explains how to use the Web Services Explorer to browse and
publish web services.
For definitions of any unfamiliar Java terms, see “Java glossaries” in
Introducing JBuilder.

Documentation conventions
The Borland documentation for JBuilder uses the typefaces and symbols
described in the table below to indicate special text.
There are special considerations on the Macintosh platform. Please see
“Note to Macintosh users” on page 1-4 for more information.

Table 1.1 Typeface and symbol conventions

Typeface Meaning
Monospace type Monospaced type represents the following:
• text as it appears onscreen
• anything you must type, such as “Enter Hello World in the
Title field of the Application wizard.”
• file names
• path names
• directory and folder names
• commands, such as SET PATH, CLASSPATH
• Java code
• Java data types, such as boolean, int, and long.
• Java identifiers, such as names of variables, classes, interfaces,
components, properties, methods, and events
• package names
• argument names
• field names
• Java keywords, such as void and static

1-2 Developer’s Guide

 Documentation conventions

Table 1.1 Typeface and symbol conventions (continued)

Typeface Meaning
Bold Bold is used for java tools, bmj (Borland Make for Java), bcj
(Borland Compiler for Java), and compiler options. For example:
javac, bmj, -classpath.
Italics Italicized words are used for new terms being defined, for book
titles, and occasionally for emphasis.
Keycaps This typeface indicates a key on your keyboard, such as “Press
Esc to exit a menu.”
[] Square brackets in text or syntax listings enclose optional items.
Do not type the brackets.
<> Angle brackets in text or syntax listings indicate a variable string;
type in a string appropriate for your code. Do not type the angle
brackets.
Angle brackets are also used in HTML tags.
Additionally, angle brackets are used for JBuilder and JDK
directories. For example, <jbuilder> is a placeholder for the
current version of the JBuilder directory, such as jbuilder7, and
<.jbuilder> represents the current JBuilder directory for storing
JBuilder settings, such as .jbuilder7. Also, <jdk> is used as a
placeholder for the current JDK directory.
... In code examples, an ellipsis indicates code that is missing from
the example. On a button, an ellipsis indicates that the button
links to a selection dialog box.

JBuilder is available on multiple platforms. See the table below for a

description of platforms and directory conventions used in the
documentation.

Table 1.2 Platform conventions and directories

Item Meaning
Paths All paths in the documentation are indicated with a forward
slash (/).
For Windows platforms, use a backslash (\).
Home directory The location of the home directory varies by platform and is
indicated with a placeholder, <home>.
• For UNIX and Linux, the home directory can vary. For
example, it could be /user/<username> or /home/<username>
• For Windows 95/98, the home directory is C:\Windows
• For Windows NT, the home directory is C:\Winnt\
Profiles\<username>
• For Windows 2000, the home directory is C:\Documents
and Settings\<username>
<jbuilder> directory The <jbuilder> directory contains the JBuilder installation,
including program files, documentation, libraries, JDK,
samples, and other files. This directory is named after the
current version of JBuilder, such as jbuilder7.

Introduction 1-3
Contacting Borland developer support

Table 1.2 Platform conventions and directories (continued)

Item Meaning
<.jbuilder> directory The <.jbuilder> directory, where JBuilder settings are stored,
is located in the home directory. This directory is named
after the current version of JBuilder, such as .jbuilder7.
jbproject directory The jbproject directory, which contains project, class,
source, backup, and other files, is located in the home
directory. JBuilder saves files to this default path.
<jdk> directory The <jdk> directory represents the current Java Development
Kit. For example, jbuilder7/jdk1.3/ would be represented in
the documentation as <jbuilder>/<jdk>/.
Screen shots Screen shots reflect the Metal Look & Feel on various
platforms.

Note to Macintosh users

JBuilder is designed to support Macintosh OS X so seamlessly that
JBuilder will have the look and feel of a native application. The Macintosh
platform has conventions of appearance and style that vary from
JBuilder’s own; where that happens, JBuilder supports the Mac look and
feel. This means that there are some variations between what JBuilder
looks like on the Mac and how it is presented in the documentation. For
instance, this documentation uses the word “directory” where Mac uses
the word “folder.” For further information on Macintosh OS X paths,
terminology, and UI conventions, please consult the documentation that
comes with your OS X installation.

Contacting Borland developer support

Borland offers a variety of support options. These include free services on
the Internet, where you can search our extensive information base and
connect with other users of Borland products. In addition, you can choose
from several categories of support, ranging from support on installation of
the Borland product to fee-based consultant-level support and extensive
assistance.
For more information about Borland’s developer support services, see our
web site at http://www.borland.com/devsupport/, call Borland Assist at
(800) 523-7070, or contact our Sales Department at (831) 431-1064.
When contacting support, be prepared to provide complete information
about your environment, the version of the product you are using, and a
detailed description of the problem.
For support on third-party tools or documentation, contact the vendor of
the tool.

1-4 Developer’s Guide

 Contacting Borland developer support

Online resources
You can get information from any of these online sources:

World Wide Web http://www.borland.com/

FTP ftp.borland.com
Technical documents available by anonymous ftp.
Listserv To subscribe to electronic newsletters, use the
online form at:
http://www.borland.com/contact/listserv.html
or, for Borland’s international listserver,
http://www.borland.com/contact/intlist.html

World Wide Web

Check www.borland.com regularly. The JBuilder Product Team posts
white papers, competitive analyses, answers to frequently asked
questions, sample applications, updated software, updated
documentation, and information about new and existing products.
You may want to check these URLs in particular:
• http://www.borland.com/jbuilder/ (updated software and other files)
• http://www.borland.com/techpubs/jbuilder/ (updated
documentation and other files)
• http://community.borland.com/ (contains our web-based news
magazine for developers)

Borland newsgroups
You can register JBuilder and participate in many threaded discussion
groups devoted to JBuilder.
You can find user-supported newsgroups for JBuilder and other Borland
products at http://www.borland.com/newsgroups/

Usenet newsgroups
The following Usenet groups are devoted to Java and related
programming issues:
• news:comp.lang.java.advocacy
• news:comp.lang.java.announce
• news:comp.lang.java.beans
• news:comp.lang.java.databases

Introduction 1-5
Contacting Borland developer support

• news:comp.lang.java.gui
• news:comp.lang.java.help
• news:comp.lang.java.machine
• news:comp.lang.java.programmer
• news:comp.lang.java.security
• news:comp.lang.java.softwaretools
Note These newsgroups are maintained by users and are not official Borland
sites.

Reporting bugs
If you find what you think may be a bug in the software, please report it in
the Support Programs page at http://www.borland.com/devsupport/
namerica/. Click the “Reporting Defects” link to bring up the Entry Form.
When you report a bug, please include all the steps needed to reproduce
the bug, including any special environmental settings you used and other
programs you were using with JBuilder. Please be specific about the
expected behavior versus what actually happened.
If you have comments (compliments, suggestions, or issues) with the
JBuilder documentation, you may email jpgpubs@borland.com. This is for
documentation issues only. Please note that you must address support
issues to developer support.
JBuilder is made by developers for developers. We really value your
input, because it helps us to improve our product.

1-6 Developer’s Guide

 Chapter

Introducing web services

Chapter2
2
This is a feature of the A web service is a software module performing a discrete task or set of
Borland Web Services Kit tasks that can be found and invoked over a network including and
for Java. especially the World Wide Web. The developer can create a client
application that invokes a series of web services through remote
procedure calls (RPC) to provide some or most of the application’s logic.
A published web service describes itself so that developers can locate the
web service and evaluate its suitability for their needs.
As an example, a company could provide a web service to their customers
to check inventory on products before they order. Another example is the
Federal Express package tracking service that customers can use to track
their shipments.
Web services use SOAP (Simple Object Access Protocol) and HTTP as the
transport layer. SOAP messages are actually XML documents that are sent
between a web service and the calling application.
Web services can be written in any language and run on any platform. A
client of a web service can be written in any language and run on any
platform. So, for example, a client written using Delphi and running on
Windows could call a web service written in Java and running on Linux.

The architecture of web services

The web services architecture permits the development of web services
that encapsulate all levels of business functionality. In other words, a web
service can be very simple, such as one that returns the current
temperature, or it can be a full-fledged application. The architecture also
allows multiple web services to be combined to create new functionality.

Introducing web services 2-1

Web service standards

The web services architecture has three distinct roles: a provider, a

requestor, and a broker. The provider creates the web service and makes it
available to clients who want to use it. A requestor is a client application
that consumes the web service. The requested web service can also be a
client of other web services. The broker provides a way for the provider
and the requestor of a web service to interact.
The three roles of provider, requestor, and broker interact with each other
through the operations of publish, find, and bind. A provider informs the
broker about the existence of the web service by using the broker’s publish
interface to make the service accessible to clients. The information
published describes the service and specifies where the service is located.
The requestor consults the broker to locate a published web service. With
the information it gained from the broker about the web service, the
requestor is able to bind, or invoke, the web service.
This diagram summarizes how the provider, requestor, and broker
interact with each other:
Figure 2.1 Web service roles and operations

Web service standards

The standards on which web service development is based are evolving
technologies. The primary players are SOAP (Simple Object Access
Protocol), WSDL (Web Services Description Language), UDDI (Universal
Description, Discovery, and Integration), and WSIL (Web Services
Inspection Language).

The Simple Object Access Protocol (SOAP)

SOAP is a transport-independent messaging protocol. Each SOAP
message is an XML document. SOAP uses one-way messages, although
it’s possible to combine messages into request-and-response sequences.

2-2 Developer’s Guide

 Web service standards

The SOAP specification defines the format of the XML message, but not its
content and how it is actually sent. SOAP does, however, specify how
SOAP messages are routed over HTTP.
Each SOAP document has a root <Envelope> element. Within the
“envelope” are two parts: a header and a body. The header contains
routing or context data. It can be empty. The body contains the actual
message. It too can be empty.
Here is an example of a simple SOAP message sent over HTTP that
requests the current stock price of Borland:
POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "urn:stock-quote-services"

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetLastTradePrice xmlns:m="Some-URI">
<symbol>BORL</symbol>
</m:GetLastTradePrice>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
For more information about SOAP, start with the SOAP documents on the
World Wide Consortium web site at http://www.w3.org/2002/ws/.
Also visit the Apache SOAP site at http://xml.apache.org/soap/.

Web Services Description Language (WSDL)

A web service is useless unless others can find out what it does and how
to call it. Developers must know enough information about a web service
so they can write a client program that calls it. WSDL is an XML-based
language used to define web services and describe how to access them.
Specifically, it describes the data and message contracts a web service
offers. By examining a web service’s WSDL document, developers will
know what methods are available and how to call them using the proper
parameters.
For in-depth information about WSDL, see the Web Services Description
Language 1.1 specification at http://www.w3.org/TR/wsdl on the
World Wide Web Consortium web site.

Introducing web services 2-3

The Borland Web Services Kit for Java

Universal Description, Discovery and Integration (UDDI)

UDDI is an evolving standard for describing, publishing, and finding the
web services that a business provides. It’s a specification for a distributed
registry of information on web services. Once a web service is developed
and a WSDL document describing it is created, there needs to be a way to
get the WSDL information into the hands of the users who might want to
use the web service it describes. By registering the web service in a UDDI
registry, potential users have a way to look up and learn about the web
service’s existence.
To describe the content of a UDDI registry, most sources offer the analogy
of a telephone directory. In the “white pages” part of the registry entry is
information such as the name, address, telephone number, and so on of
the business that offers one or more web services. The “yellow pages”
section identifies what type of business it is and categorizes it by industry.
The “green pages” part provides the data about the web services the
business offers.
To read more about UDDI, see the UDDI.org web site at
http://www.uddi.org.

Web Services Inspection Language (WSIL)

WSIL, like UDDI, provides a method of service discovery for web
services. Unlike UDDI, WSIL uses a de-centralized, distributed model,
rather than a centralized model. WSIL documents, which are essentially
pointers to lists of services, allow consumers of web services to browse
available services on web sites. The WSIL specification provides standards
for using XML-formatted documents to inspect a site for services and a set
of rules for how the information is made available. A WSIL document
gathers multiple references to pre-existing service description documents
in one document. The WSIL document is then hosted by the provider of
the service, so consumers can find out about available services.
For more information on the Web Services Inspection Language
(WS-Inspection) 1.0 specification, see http://www-106.ibm.com/
developerworks/webservices/library/ws-wsilspec.html.

The Borland Web Services Kit for Java

Although it’s useful to learn about the technologies behind web services,
you don’t have to do such things as actually create the SOAP messages
and WSDL descriptions yourself. The Borland Web Services Kit for Java
can do these things for you.

2-4 Developer’s Guide

 The Borland Web Services Kit for Java

The Borland Web Services Kit for Java can use either the Apache SOAP 2.2
or Apache Axis toolkits for its SOAP support. JBuilder can generate the
WSDL document for a web service you’ve created. It can also take an
existing WSDL for a web service and create the Java files so you can create
a client that invokes the web service. Another option is to use the
generated Java code to implement the web service yourself. It can also
quickly create a web application that hosts a SOAP server.
The Borland Web Services Kit for Java includes a Web Services Explorer
that you can use to search for web services that fit your needs, as well as
publish to a UDDI registry.
To see a sample JavaServer Page client that invokes a web service to
translate words from one language to another, open the Basic Web
Service.jpx project in the JBuilder samples/webservices/ directory.

Introducing web services 2-5

2-6 Developer’s Guide
 Chapter

Working with SOAP servers

Chapter3
3
This is a feature of the Simple Object Access Protocol (SOAP) is a transport-independent
Borland Web Services Kit messaging protocol. Each SOAP message is an XML document. SOAP
for Java. uses one-way messages, although it’s possible to combine messages into
request-and-response sequences.
The SOAP specification defines the format of the XML message, but not its
content and how it’s actually sent. SOAP does, however, specify how
SOAP messages are routed over HTTP.
Each SOAP document has a root <Envelope> element. Within the
“envelope” are two parts: a header and a body. The header contains
routing or context data and can be empty. The body, which contains the
actual message, can also be empty.
A SOAP server provides the ability to send and receive SOAP messages.

Working with SOAP servers in JBuilder

The Web Services Kit adds the SOAP Server wizard to JBuilder. This
allows you to quickly create a SOAP server for your web application.
Once a web service is deployed to a SOAP server, the web service can
receive and send SOAP messages to and from client applications.
The SOAP server must be hosted by a web application. If your project
doesn’t have an existing web application, the SOAP Server wizard opens
the Web Application wizard first. For more information on web
applications, see “Working with WebApps and WAR files” in the Web
Application Developer’s Guide.

Working with SOAP servers 3-1

Working with SOAP servers in JBuilder

Once the WebApp is created, the SOAP Server wizard is displayed. The
SOAP Server wizard generates the following nodes and files and adds
them to your WebApp:
• A SOAP toolkit node—the name of this node is dependent upon the
toolkit selected in the wizard—(<> brackets indicate it’s not really a
file). The Export Class As A Web Service and Import WSDL wizards
create a deploy.wsdd file which will appear under this node. For more
information on the deploy.wsdd file, see Chapter 6, “The WSDD file.”
• An EJB-SOAP toolkit node—the name of this node is dependent upon
the toolkit selected in the wizard—(<> brackets indicate it’s not really a
file). All stateless session beans in the project are autodeployed. The
deployment information is generated in one deploy.wsdd file per EJB
module. At build time the EJB classes in the deployment files are
deployed to the axis server.
• A Deployment Descriptors node—the wizard adds the appropriate
SOAP information to the web.xml file that describes the deployment
• A Root Directory node—the wizard adds contents to this node
according to the toolkit selected in the wizard

Working with the SOAP Server wizard

To access the SOAP Server wizard,
1 Choose File|New to open the object gallery.
2 Click the Web Services tab and double-click the SOAP Server icon.
If your current project doesn’t already contain a WebApp, the Web
Application wizard appears. Use it to specify the name for the new
WebApp and the directory that will serve as the WebApp’s root directory.
If you are using the Apache SOAP 2 toolkit, you might specify soap as the
WebApp name and soap as the directory. If you are using the Apache Axis
toolkit, you might specify axis as the WebApp name and axis as the
directory.
Important The name of the WebApp and the WebApp’s root directory must match
the root directory given for the SOAP address in the WSDL file used to
describe the web service.
Once you click OK, the SOAP Server wizard appears.
If your current project already contains one or more WebApps, the SOAP
Server wizard appears as soon as you double-click its icon in the object
gallery.
Tip If your project already contains a WebApp, but you would like to create a
different WebApp to host the SOAP Server, you must run the Web

3-2 Developer’s Guide

 Working with SOAP servers in JBuilder

Application wizard before running the SOAP Server wizard. The SOAP
Server wizard only lets you select from existing WebApps.
On the first page of the SOAP Server wizard, you select the WebApp to
host the SOAP Server and select a SOAP toolkit.
If your project contains just a single WebApp, its name appears in the
WebApp field of the SOAP Server wizard. If more than one WebApp
exists, select the WebApp you want to host the SOAP server from the
WebApp drop-down list.
For more information about WebApps, see “Working with WebApps and
WAR files” in the Web Application Developer’s Guide.

Selecting a SOAP toolkit

The Toolkit field in the SOAP Server wizard gives you a choice of all
registered SOAP toolkits. There are two SOAP toolkits which are bundled
with the Borland Web Services Kit for Java: the Apache Axis toolkit or the
Apache SOAP 2 toolkit. The Toolkit field could contain additional toolkit
plugins if they are available on your machine.
The Copy Admin/Console To WebApp option copies files into the Root
Directory folder so that you can use the toolkits’ UI to administer the
SOAP server. Check this option if you would like these files added to the
WebApp. The Copy Admin/Console To WebApp option could
potentially be disabled if you are using a toolkit which reports that it
doesn’t have an admin/console. Both the Apache Axis toolkit and the
Apaches SOAP 2 toolkit do have an admin/console, so this option is
enabled for both of them.

Apache Axis
The Apache Axis toolkit is an open-source implementation of SOAP, the
next generation of Apache SOAP 2.0. Axis is a rewrite of Apache SOAP 2.0
that uses SAX instead of DOM. It’s a more modular, flexible, and a higher
performance implementation of SOAP than Apache SOAP 2.0.

See also
• Axis at http://xml.apache.org/axis/
• Apache Axis documentation in <jbuilder>/extras/xml-axis/java/docs/
index.html

Apache SOAP 2
The Apache SOAP 2 toolkit is an open-source implementation of SOAP
1.1 developed by the Apache SOAP community. This implementation of
SOAP uses DOM.

Working with SOAP servers 3-3

Working with SOAP servers in JBuilder

See also
• Apache SOAP at http://xml.apache.org/soap/
• Apache SOAP 2 documentation in the <jbuilder>/extras/apache-soap/
docs/index.html

Defining a runtime configuration for the SOAP server

On the second page of the SOAP Server wizard, you can optionally define
a runtime configuration for the SOAP Server. The SOAP server requires a
Server type runtime configuration for the server to run.
If no Server type runtime configuration exists and you don’t choose to
define one on this page, a runtime configuration called “Webservices
Server” is automatically added for you. This runtime configuration uses
the default Server configuration for the project as defined on the Server
page of the Project Properties dialog box.
For more information on runtime configurations, see “Setting runtime
configurations” in Building Applications with JBuilder.

Examining the WebApp node

After creating a SOAP server with the SOAP Server wizard, you can
expand the WebApp node in the project pane to view the nodes the
wizards added. You’ll see a toolkit node, a Deployment Descriptors node,
and a Root Directory node. If you added files to administer the WebApp
in the Root Directory, expand that node to see the files.
For more information about WebApps, see “Working with WebApps and
WAR files” in the Web Application Developer’s Guide.

Starting the SOAP server

To run the SOAP server, you must have a Server runtime configuration
which uses an appropriate web server. The SOAP Server wizard adds a
Server runtime configuration to your project automatically, if an
appropriate runtime configuration doesn’t already exist. For more
information about runtime configurations, see “Setting runtime
configurations” in Building Applications with JBuilder.
Once you have an appropriate runtime configuration, you can start the
SOAP server in several ways. If you right-click any servlet, JSP, or HTML
file in the project pane and select Web Run from the context menu, the
server starts up. The server can also be started by choosing Run|Run
Project when your Server runtime configuration is the default runtime
configuration, or by clicking the small arrow next to the Run icon in the

3-4 Developer’s Guide

 Working with SOAP servers in JBuilder

toolbar and selecting your Server run configuration from the list. You can
view the server’s progress in the message pane.
If you chose to copy the Admin/console files to the WebApp node when
you created the SOAP server, you can now expand the Root Directory
node, right-click the index.html file and select Web Run from the context
menu to reach the admin UI for the Axis toolkit. The file to Web Run for
the Apache Soap 2 toolkit is admin/index.html. With the default IDE
settings, Web Run when the web server is already running will cause the
file to be accessed off the web server.

Setting build options

The Build page of the Project Properties dialog box has a SOAP build
option for controlling deployment at build time.
To access the SOAP build option:
1 Choose Project|Project Properties to open the Project Properties dialog
box.
2 Choose the Build tab and click the SOAP tab.
The Regenerate Deployment At Build Time option is set by default. If this
option is set, deployment files are regenerated whenever the project is
built.
Each toolkit has its own final deployment file, comprised of multiple
separate deploys. For Axis, each deploy.wsdd is combined into a
server-config.wsdd, which is not shown in the JBuilder project. Any manual
edits to the deployment files are overwritten by the toolkit. If you edit
server-config.wsdd, turn off the SOAP build option or the WSDD will be
overwritten by the toolkit when you build the project.

For more information

The following tutorials create a SOAP server as one of the steps in creating
a web service:
• Chapter 9, “Tutorial: Generating Java classes from a WSDL file”
• Chapter 10, “Tutorial: Generating a web service from a WSDL
document”
• Chapter 11, “Tutorial: Publishing a bean as a web service”
For more information about WSDL, see Chapter 5, “Working with
WSDL.”
For more information about WebApps, see “Working with WebApps and
WAR files” in the Web Application Developer’s Guide.

Working with SOAP servers 3-5

3-6 Developer’s Guide
 Chapter

Monitoring SOAP messages

Chapter4
4
This is a feature of the The TCP Monitor, available from the Tools Menu, allows you to monitor
Borland Web Services Kit the SOAP envelopes as they’re transported between the client and the
for Java. server. TCP, Transmission Control Protocol, is the most common Internet
transport layer protocol. The TCP Monitor actually sits between the SOAP
client and server. The client sends its request to the TCP Monitor, which
then forwards it on to the server. Responses from the server are in turn
sent to the TCP Monitor and then to the client. You can monitor these
messages locally to test the service or listen over a connection.
The TCP Monitor supports these features:
• Adding multiple listener ports
• Editing SOAP messages
• Resending SOAP messages
• Viewing a history of requests and responses
• Saving requests and responses to a file
You can set up the TCP Monitor to act as a listener or use a proxy if you’re
behind a firewall. The various SOAP toolkits have different levels of
support for proxy servers and different usages. Consult the toolkit
documentation for information on how to set up for use with a proxy
server.

Creating a new TCP/IP Monitor

By default, the TCP monitor sets the client port to 8082 and the server port
to 8080.

Monitoring SOAP messages 4-1

Creating a new TCP/IP Monitor

To create a new port to listen to,

1 Choose Tools|TCP Monitor to open the TCP Monitor.
2 Choose the Admin tab.
3 Enter a port number to listen on, such as 8082 for localhost. This should
be a port that won’t be in use by the service.
4 Choose Act As A Listener.
5 Enter the Target Host Name for the destination server that you want to
monitor, such as 127.0.0.1 for localhost. If you enter a name instead of
an address, such as services.xmethods.net, be sure to remove the
protocol from the address (http://).
6 Enter the Target Port Number for the server, such as 8080. This is the
destination port that you want to monitor.

7 Click the Add button to add this new TCP/IP Monitor. A new page is
added.
8 Choose the new Port tab to monitor the messages.
9 Modify the client to send and receive its messages to the TCP Monitor
on the listen port. Change the address and port number in your code
but don’t remove the context and service target in the address. For
example, the context and service target in this address "http://
localhost:8082/soap/servlet/rpcrouter" is soap/servlet/rpcrouter and
should remain unchanged.
10 Rebuild the client to save the changes.
11 Run the application on the web server.
12 Interact with the web service and view the SOAP requests and
responses in the TCP Monitor. You can also make any necessary edits

4-2 Developer’s Guide

 Monitoring a service’s SOAP messages

to requests in the TCP Monitor and resend them, as well as save request
and response messages to disk.

Monitoring a service’s SOAP messages

Let’s look at a web services sample and monitor the SOAP messages with
the TCP Monitor. In this example, you’ll create a web service, modify the
client’s URL to point to the port that the TCP Monitor listens on, rebuild
the client, run the service test case, and monitor the messages between the
client and the server.
1 Create a web service as described in Steps 1 through 4 of Chapter 11,
“Tutorial: Publishing a bean as a web service.”
2 Open Bean1ServiceLocator.java in the <project name>_generated package
and change the URL for the service port address from the 8080 to 8082.
The TCP Monitor is set up by default to listen to messages on port 8082.
You want to redirect the client to the listening port so the Monitor can
receive the messages.
3 Choose Tools|TCP Monitor to open the TCP Monitor. Notice that the
listen port is set to 8082 and the destination port to 8080. These are the
default TCP Monitor settings.
Note You can change the default settings at any time. Choose the Stop button
and edit the Listen Port, Host, and Port fields. You can also create a new
TCP Monitor on the Admin page.

Monitoring SOAP messages 4-3

Monitoring a service’s SOAP messages

4 Expand the axis node’s Root directory, right-click index.html, and

choose Web Run Using Webservices Server to run the SOAP server.
5 Right-click the test case, Bean1ServiceTestCase.java, and choose Run Test
Using Defaults.
6 Return to the TCP Monitor to see the request and response sent from
the client and server to the Monitor.

4-4 Developer’s Guide

 Chapter

Working with WSDL

Chapter5
5
This is a feature of the A web service is useless unless others can find out what it does and how
Borland Web Services Kit to call it. Developers must know enough information about a web service
for Java. so they can write a client program that calls it. WSDL (Web Services
Description Language) is written in XML and describes a web service as
well as how to access it.
A WSDL document exposes the web service’s method signature, protocol
to be used, network address, and data format. With the information
available in the WSDL document, a programmer can write an application
to interface with a web service. By examining a web service’s WSDL
document, developers know what methods are available and how to call
them using the proper parameters.
To discover other web services and their corresponding WSDL documents
and to publish web services, programmers can use the UDDI Business
Registry where businesses register their services.
For in-depth information about WSDL, see the Web Services Description
Language 1.1 specification at http://www.w3.org/TR/wsdl on the
World Wide Web Consortium web site.

See also
• Chapter 9, “Tutorial: Generating Java classes from a WSDL file”
• Chapter 10, “Tutorial: Generating a web service from a WSDL
document”
• Chapter 11, “Tutorial: Publishing a bean as a web service”
• Chapter 8, “Browsing and publishing web services”

Working with WSDL 5-1

Working with WSDL in JBuilder

Working with WSDL in JBuilder

The Borland Web Services Kit adds the following features to JBuilder to
help you work with WSDL:
• Import WSDL wizard—generates Java classes from an existing WSDL
file.
• Export Class As A Web Service wizard—generates a WSDL file from an
existing Java class and exposes selected methods of the class as a web
service.
These wizards are available on the Web Services page of the object gallery
(File|New). They are also available on the context menu in the project
pane for .wsdl and .java files.

Import WSDL wizard

The Import WSDL wizard generates Java classes which contain the
methods required to implement or interface with the web service defined
in the WSDL. It can generate both the server side and client side classes, or
the client side only. It can optionally generate a JUnit test case to test
interaction with the generated web service. You add code to the generated
classes to implement the methods as desired. The Import WSDL wizard
also generates a deploy.wsdd file which provides deployment information
to the SOAP server.
Depending on the settings you select, the Import WSDL wizard generates
some or all of the following files:

Table 5.1 Files generated by the Import WSDL wizard

File name Description
<type name>.java A class for each complexType in the WSDL.
<service name>Service.java A service interface which defines a get method
for each port listed in the service element of the
WSDL. This service interface defines a factory
class to get a stub instance.
<service name>ServiceLocator.java A locator class which is the implementation of
the service interface.
<service name>TestCase.java An optional JUnit test case for testing the web
service.
<WSDL file name>PortType.java An interface for each portType in the WSDL. You
will use the implementation of this interface to
call the remote methods.
<WSDL file An implementation class for the portType
name>SoapBindingImpl.java interface.
<WSDL file An optional skeleton class to encapsulate an
name>SoapBindingSkeleton.java implementation for the server.

5-2 Developer’s Guide

 Working with WSDL in JBuilder

Table 5.1 Files generated by the Import WSDL wizard (continued)

File name Description
<WSDL file A stub class which acts as a proxy for a remote
name>SoapBindingStub.java web service. This allows you to call the web
service as if it were a local object.
deploy.wsdd An XML file that provides deployment
information to the SOAP server.

The wizard generates a package name based on the WSDL’s target

namespace or uses one that you specify, as well as adding any necessary
project libraries.
The Import WSDL wizard is available on the Web Services tab of the
object gallery. You can also right-click any WSDL file in the project pane
and select Import WSDL from the context menu.
For a tutorial which creates a basic application from a WSDL file, see
Chapter 9, “Tutorial: Generating Java classes from a WSDL file.” For a
tutorial which uses a WSDL file to access a more complex remote web
service, see Chapter 10, “Tutorial: Generating a web service from a WSDL
document.”

Export Class As A Web Service wizard

The Export Class As A Web Service wizard is used to publish a class as a
web service, exposing the public methods you choose to consumers of the
web service. You can use this wizard to publish any Java class as a web
service; for example, a JavaBean or EJB. The wizard generates Java files
which implement the web service and call the exposed methods, as well as
a WSDL which defines and describes the web service. The Export Class As
A Web Service wizard also generates a deploy.wsdd file which provides
deployment information to the SOAP server.
The Export Class As A Web Service wizard generates the following files:

Table 5.2 Files generated by the Export Class As A Web Service wizard
File name Description
<class name>PortType.java An interface for each portType in the WSDL.
You will use the implementation of this
interface to call the remote methods.
<class name>Service.java A service interface which defines a get
method for each port listed in the service
element of the WSDL. This service interface
defines a factory class to get a stub instance.
<class name>ServiceLocator.java A locator class which is the implementation of
the service interface.
<class name>ServiceTestCase.java An optional JUnit test case for testing the web
service.

Working with WSDL 5-3

Working with WSDL in JBuilder

Table 5.2 Files generated by the Export Class As A Web Service wizard (continued)
File name Description
<class A stub class which acts as a proxy for a remote
name>ServicePortSoapBindingStub.java web service. This allows you to call the web
service as if it were a local object. This class
implements the <class name>PortType.java
interface.
<class name>.wsdl The WSDL file which describes the web
service.
deploy.wsdd An XML file that provides deployment
information to the SOAP server.

The wizard generates a package name based on the package name of the
class with _generated appended to it.
The Export Class As A Web Service can optionally generate client stub
classes. If the Generate Client Stub option is selected on the first page of
the wizard, the wizard goes from three steps to five steps. The additional
two steps provide the same functionality as the Import WSDL wizard and
generate a client stub from a WSDL document.
The Export Class As A Web Service wizard is available on the Web
Services tab of the object gallery. You can also right-click any .java file in
the project pane and select Export Class As Web Service from the context
menu.
For a tutorial which uses the Export Class As A Web Service wizard to
publish a JavaBean as a web service, see Chapter 11, “Tutorial: Publishing
a bean as a web service.” For more information about SOAP, see
Chapter 3, “Working with SOAP servers.” For more information about the
deploy.wsdd file, see Chapter 6, “The WSDD file.”

5-4 Developer’s Guide

 Chapter

The WSDD file

Chapter6
6
This is a feature of the The Import WSDL and Export Class As A Web Service wizards create a
Borland Web Services Kit deploy.wsdd (web services deployment descriptor) XML file. The
for Java. deploy.wsdd file provides deployment information to a SOAP server.
The deploy.wsdd file is displayed in the Toolkit node in the WebApp node
of the project pane. When it’s displayed in the project pane, the file name
will be preceded by [<package name>] to differentiate it from other
deploy.wsdd files which may have been generated for other packages in the
project. All WSDD files in the src tree are collected in the Toolkit node for
convenience. Note however, that the Toolkit node does not correspond to
an actual physical location on disk. The deploy.wsdd file is saved in the
same directory as the generated stubs and skeletons.
Values in the deploy.wsdd file are derived from the information in the
WSDL file and from methods chosen in the Export Class As A Web
Service wizard. (Settings in the Import WSDL wizard do not change
values in the deployment descriptor.)
Note that the deploy.wsdd file is actually defined in the Axis toolkit. The
Import WSDL and Export Class As A Web Service wizards work
primarily through Axis, but the Borland Web Services Kit for Java has an
Axis to Apache SOAP cross-deployer that converts Axis deployment
information into Apache SOAP.
For a tutorial which uses the Import WSDL wizard to generate a web
service, then demonstrates how to find the WSDD file and examine it
more closely, see Chapter 9, “Tutorial: Generating Java classes from a
WSDL file.” For more information about SOAP, see Chapter 3, “Working
with SOAP servers.” For more information about WSDL, see Chapter 5,
“Working with WSDL.”

The WSDD file 6-1

6-2 Developer’s Guide
 Chapter

Developing EJBs as
Chapter7
7
web services
This is a feature of the The Borland Web Services Kit is designed to assist you in building
Borland Web Services Kit enterprise class web services applications on the J2EE platform. The
for Java. solutions are standards-based and are portable across application servers.
The Borland Web Services Kit has been tested with Borland Enterprise
Server (BES) and WebLogic in particular.
The J2EE platform has evolved over the years and is currently the
platform of choice for enterprise Java development. EJB containers, which
provide a solid platform for business logic and enterprise data, in
conjunction with web containers, such as servlets and JSPs, have extended
the functionality of applications by leveraging the penetration of browsers
and HTML.
Web services extend the functionality of the J2EE platform still further in
providing cross-platform and language-independent solutions. In
addition, the J2EE platform can itself leverage web services built outside
of its domain. Web services are not confined to a browser environment
and can be embedded just as easily in other applications and in
application servers.
Typically, as is the case with web containers, coarse-grained business
methods are the right candidate and appropriate design for exposing
functionality. The Borland Web Services Kit makes this effortless by
automatically exposing the appropriate methods in the stateless session beans
in the project. You can also override this default behavior and select only the
EJB modules, beans, and methods that you want to expose as web services.
Important For configuration issues with application servers, see “Release Notes” in
the JBuilder directory before completing these steps: <jbuilder>/
webservices_release_notes.html.

Developing EJBs as web services 7-1

Developing EJBs as web services

Briefly, these are the steps involved in creating an EJB-based web service:
1 Use the Soap Server wizard and create the axis WebApp as you
normally would while creating a stand-alone web services application.
This creates a run configuration based on the application server for the
project. See Chapter 3, “Working with SOAP servers” for more
information on the Soap Server wizard.
2 Create one or more EJB modules and populate them with session and
entity beans. Implement them as you would with any EJB application.
You may already have coarse-grained stateless session beans. If you
don’t, you need to create one, as only stateless session beans are
exposed as web services. The stateless session beans must have at least
one valid method in the remote interface. This model parallels the
access of beans from a web container, such as Servlet/JSPs. For more
information on EJBs, see the Enterprise JavaBeans Developer’s Guide.
3 Build the project.
Note The Axis toolkit combines each deployment file (deploy.wsdd) in your
project into a server-config.wsdd. Any manual edits to the deployment
files are overwritten by the toolkit. If you edit server-config.wsdd, turn
off the SOAP build option on the Build page of Project Properties or
server-config.wsdd will be overwritten by the toolkit when you build the
project. See “Setting build options” on page 3-5 for more information.
4 Run the application server and the SOAP server using the Web Services
Server run configuration created by the JBuilder wizards.

Now that you’ve built and published your application as a web service,
you’ll build a client to use the service you just published. In the next few

7-2 Developer’s Guide

 Developing EJBs as web services

steps, you’ll use the Web Services Explorer to browse all services available
on the server and to import the WSDL to build a client application.
1 Choose Tools|Web Services Explorer to open the Web Services
Explorer. See Chapter 8, “Browsing and publishing web services” for
information on the Web Services Explorer.
2 Expand the Axis node and select the Default Axis node in the tree.
3 Modify the URL field on the Details page with the WebApp context and
the server location of the web service. For example,
http://localhost:8080/axis/services or http://localhost:8080/axis/
servlet/AxisServlet, where http://localhost:8080 is the server location
and axis is the context.
4 Click the Display Services button on the Details page to display the
published EJB web services. Notice that beans are available in the list.
Note that the application server must be running before you can
display its services.

5 Pick the one of interest and click the Import WSDL toolbar button. For a
description of the files generated by the Import WSDL wizard, see
Chapter 5, “Working with WSDL.” For a tutorial, see Chapter 9,
“Tutorial: Generating Java classes from a WSDL file.”
6 Optional: Test the service as follows:
a Expand the new _generated package and notice the generated JUnit
test client, <BeanName>TestCase.
b Right-click <BeanName>TestCase in the _generated package and choose
Run Test. For a tutorial on how to run the <BeanName>TestCase file, see
“Step 5: Running and testing the web service” on page 11-4.
7 You can then publish the web service to a UDDI registry. See
“Publishing a web service from an Axis server” on page 8-22.
The previous steps complete the full cycle: building your typical EJB
application, publishing it as a web service, generating a client, and
consuming the web service.

Developing EJBs as web services 7-3

Customizing deployment

Customizing deployment
You can customize the deployment of your web services in the following
two ways:
• Modify the deployment node properties
• Edit the WSDD file

Modifying the deployment node properties

To change the deployment node properties on the Modules page of the
EJB-SOAP Properties dialog box:
1 Expand the Axis node, right-click the <EJB-SOAP: Axis Toolkit> node,
and choose Properties to choose the EJB modules and stateless session
beans to expose as web services. The stateless session beans must have
at least one valid method in the remote interface. The default behavior
is to expose all of these beans, which are selected on the Properties
page.

2 Uncheck any EJB modules and/or beans that you don’t want exposed
as a web service.

Editing the WSDD file

The deploy.wsdd under the <EJB-SOAP: Axis Toolkit> node. There will be
one deploy.wsdd for each EJB module, such as [<EJB module
name>]deploy.wsdd. The WSDD files are Web Services Deployment
Descriptors generated by JBuilder to represent the services that are being

7-4 Developer’s Guide

 Customizing deployment

exposed as a web service. You can customize the generated information.

In addition, you can deploy additional elements, such as custom handlers,
chains, and so on.
To edit the WSDD file,
1 Open the WSDD file you want to customize and look for and change
whatever is of interest. For example, you may choose to restrict the
methods exposed from <parameter name="allowedMethods"
value="getSample, setSample"/> to just allow get and no set method
<parameter name="allowedMethods" value="getSample"/>.
2 Edit the following entry in the <documentation> element of the
corresponding <Service> element, changing YES to NO:
<documentation>JBUILDER should auto generate this entry: YES(YES/NO)
</documentation>
Modifying this entry tells the web services toolkit that you don’t want
the WSDD file to be auto-generated and overwritten by JBuilder. Each
<Service> element contains this <documentation> element. You must
modify each <documentation> entry if you don’t want it overwritten.
3 Use the same mechanism to add requestFlow, typemappings, or any
other deployment elements to the WSDD file and JBuilder will deploy
them for you.

For more on WSDD files, see:

• Chapter 6, “The WSDD file”
• “Axis Web Services Deployment Descriptor (WSDD)” in the Axis
documentation in <jbuilder>/extras/xml-axis/java/wsdd/docs/
index.html
• “Custom Deployment - Introducing WSDD” in the Axis documentation
in <jbuilder>/extras/xml-axis/java/docs/user-guide.html

Developing EJBs as web services 7-5

7-6 Developer’s Guide
 Chapter

Browsing and publishing web

Chapter8
8
services
This is a feature of the Because web services can be created by anyone and consumed by anyone,
Borland Web Services Kit it’s important to have a mechanism for advertising and locating a service.
for Java. Currently, the UDDI (Universal Description, Discovery, and Integration)
framework can be used to register and find a service. In addition, you can
search for available web services using WSIL documents and for services
located on Axis servers. JBuilder provides the Web Services Explorer to
assist you in searching for and publishing web services.

Web Services Explorer overview

The Borland Web Services Kit for Java provides the Web Services
Explorer, available from the Tools menu, for searching available services
at sites and publishing web services to UDDI registries. Using the Web
Services Explorer, you can search for a business, a web service, or a
tModel, as well as add business and tModel entries. You can also monitor
message traffic to and from the UDDI sites in the UDDI Message Monitor.
For more information about UDDI, see “UDDI overview” on page 8-2.
Important The UDDI feature of the Web Services Explorer requires the use of Sun’s
JSSE extension. If you are using JDK 1.3 or earlier, you must install the
JSSE packages. This can be downloaded from Sun at http://
java.sun.com/products/jsse/index-102.html.
The Web Services Explorer also supports browsing network sites that run
Apache Axis-hosted web services. These sites provide overview
information, which describes the web services available at that site. Each
web service is described by a WSDL file. For more information about the

Browsing and publishing web services 8-1

UDDI overview

Axis features in the Web Services Explorer, see “Axis overview” on

page 8-5.

In addition, the Web Services Explorer supports browsing of Web Services

Inspection Language (WSIL) documents. WSIL documents are essentially
a collection of references to available web services on a web site that are
hosted by the web service provider. These references may point to other
WSIL documents, UDDI entries, or WSDL documents.
The Web Services Explorer also provides a link to the Import WSDL
wizard, which generates Java classes from a selected WSDL (Web Services
Description Language) file. Browse to any web service available on a
UDDI site, Axis site, or other web site listing services and select the node
that specifies the WSDL file. Then choose the Import WSDL button in the
Explorer to quickly generate Java classes. After creating a web service, you
can then use the publishing features of the Web Services Explorer to
publish your web service to UDDI registries.

See also
• “Adding and deleting nodes in the Explorer’s tree” on page 8-5
• “Web Services Explorer menus” in online help
• Chapter 5, “Working with WSDL”
• “Publishing a web service” on page 8-20
• Chapter 12, “Tutorial: Using the Web Services Explorer”

UDDI overview
The Universal Description, Discovery, and Integration (UDDI) framework
provides a mechanism for finding, describing, and registering web-based
services in a central business registry over the Internet. Through this
registry, industries can find business partners and dynamically connect to
their web services.
This XML-based framework uses Simple Object Access Protocol (SOAP)
and HTTP to discover a particular service in the registry using XML
messages to make remote procedure calls and send information to and

8-2 Developer’s Guide

 UDDI overview

from the registry. XML, HTTP, and SOAP provide the added advantage of
language independent, cross-platform programming.
A UDDI registry doesn’t contain the actual specifications about how
businesses do things electronically to share their products and services.
Instead, it contains pointers or references that link to this information.
Some of these pointers may be WSDL (Web Services Description
Language) files, which describe a web service.
UDDI registries can be private, public, or even local on your own
computer. Some registries, such as the UDDI Business Registry, are
updated and replicated with the same information by several UDDI
operator sites. Other registries are public but do not replicate their data
with other sites.
The UDDI Business Registry is a universal UDDI registry that is
maintained and operated as a distributed service by several operator sites.
These operator sites, such as Microsoft and IBM, replicate data with each
other to synchronize the instances of the registry. They also have UDDI
test sites where you can test your web services thoroughly before you
publish them.
UDDI accepts and organizes three types of business information:
• Publish—white pages containing business information, such as contact
and address information.
• Find—yellow pages containing business service information, organized
by industrial categories and geographic location.
• Bind—green pages containing technical information and specifications
about services, necessary for interfacing programmatically.

See also
• “Searching a UDDI registry” on page 8-7
• “Publishing web services in a UDDI registry” on page 8-20
• The UDDI project at http://www.uddi.org
• Microsoft’s UDDI site at http://uddi.microsoft.com
• IBM’s UDDI site at https://www-3.ibm.com/services/uddi/protect/
registry.html

UDDI terms and definitions

The Web Services Explorer uses many UDDI data types and terms that are
found in the UDDI specification. Listed below are a few of these terms and
their definitions. For complete information, see the UDDI specification at
http://uddi.org/specification.html.

Browsing and publishing web services 8-3

UDDI overview

Although this documentation assumes familiarity with the UDDI

specification, some key UDDI terms are defined here. For more
information on UDDI, visit http://www.uddi.org.

Table 8.1 UDDI terms

UDDI term Definition
accessPoint An entry point address for accessing a web service. This
could be a URL, email address, or phone number.
businessKey A unique identifier for a given business entity.
category Category information that is similar to an identifier but that
uses a predefined taxonomy, such as industry, product, or
geographic codes. It also uses name/value pairs. Examples
of these codes include: NAICS (North American Industry
Classification System), UNSPSC 3.1 (United Nations
Standard Products and Services Code System), and SIC
(Standard Industrial Classification) codes.
identifier A name/value pair that acts as an identifier for a business.
Examples include the D-U-N-S (Dun & Bradstreet’s Data
Universal Numbering System) ID and Thomas Register ID.
keyName Commentary that aids in readability but usually isn’t
required. For example, the D-U-N-S identifier for IBM has a
keyName of D-U-N-S, whereas the keyValue is the actual
nine-digit D-U-N-S number, 00-136-8083. However, the
keyName does have important meaning in the uddi-
org:misc-taxonomy category.
keyValue Specifies a business classification, such as the nine-digit D-
U-N-S number used for businesses worldwide.
operator site Each instance of a UDDI business registry. For example,
Microsoft and IBM maintain instances of the UDDI Business
Registry.
overview document A pointer to the location of the overview document
URL description.
serviceKey A unique key for a business service that is generated when
the service is registered.
tModel A reference to a technical specification of a service. TModels
are descriptions of web services that define service types.
Each TModel has a unique identifier and points to a
specification that describes the web service. tModels provide
a common point of reference that allow compatible services
to be easily identified.
tModelInstance A list of tModel information structures which acts as a
details fingerprint for the service. Includes such details as
description, tModel name, tModel key, and documentation.
tModelKey A unique identifier for a tModel that is assigned by UDDI
when a service is registered.

8-4 Developer’s Guide

 Axis overview

Axis overview
The Web Services Explorer allows you to browse network sites that run
Apache Axis-hosted web services. Searching these sites returns
information that describes the web services available in the form of a
WSDL file. JBuilder builds Axis servers with remote access disabled. To
browse services on Axis servers, remote access must first be enabled. See
“Accessing remote Axis servers” on page 8-16.

See also
• “Searching an Axis server for web services” on page 8-14
• “Publishing a web service from an Axis server” on page 8-22

WSIL overview
The Web Services Inspection Language (WSIL), like UDDI, provides a
method of service discovery for web services. Unlike UDDI, WSIL uses a
decentralized, distributed model, rather than a centralized model. WSIL
documents, which are essentially pointers to lists of services, allow
consumers of web services to browse available services on web sites
unlisted in the UDDI registries. The WSIL specification provides
standards for using XML-formatted documents to inspect a site for
services and a set of rules for how the information is made available. A
WSIL document gathers multiple references to pre-existing service
description documents in one document. The WSIL document is then
hosted by the provider of the service, so consumers can find out about
available services.

See also
• “Searching web services with WSIL documents” on page 8-17

Adding and deleting nodes in the Explorer’s tree

The Web Services Explorer has several nodes available in the tree view to
help you search for available web services at different locations:
• Axis Servers
• UDDI Sites
• WSIL Documents
Expand the Axis Servers node and see that it has a Default node, which
points to a common location for a test environment. The UDDI Sites node
has multiple UDDI nodes already available, such as Local, XMethods,

Browsing and publishing web services 8-5

Adding and deleting nodes in the Explorer’s tree

Microsoft, IBM, and UDDI test sites. The WSIL Documents node also
contains a Default node. You can add nodes to the existing nodes and
delete nodes in the Explorer’s tree.

The contents of these three nodes in the Explorer are read from XML files
delivered in the JBuilder defaults directory. Once you make a change to a
node, the changes are saved to your <home>/<.jbuilder> directory. The file
names are as follows:
• Axis Servers node: AxisServers.xml
• UDDI Sites node: UDDIOps.xml
• WSIL Documents node: WSILDocs.xml

To add a new node to the Axis Servers, UDDI Sites, and WSIL Documents
nodes,
1 Choose the node in the tree view. A page displays on the right: Axis
Servers page, UDDI Sites page, or WSIL Documents page.
2 Create a new node using one of the following methods:
• Click the New button on the page to the right.
• Choose File|New.
• Right-click the node and choose New.
3 Enter any name you like for the new node in the Input dialog box and
click OK.
4 Select the new node in the tree to display the detail information on the
right.
5 Enter the appropriate information, such as Publish and Inquiry URL for
UDDI sites or location URL for an Axis server or WSIL document.
6 Choose the Save button.

8-6 Developer’s Guide

 Searching a UDDI registry

To delete a node from the Explorer’s tree,

1 Choose the node you want to delete to display the Details page on the
right.
2 Click the Delete button on the Details page, choose File|Delete, or
right-click the node in the tree and choose Delete.
Note The top-level nodes can’t be deleted.

Searching a UDDI registry

There are several ways to search for web services in a UDDI registry with
the Web Services Explorer:
• Find a business
• Find a service
• Find a tModel
Important You can increase the timeout for the Web Services Explorer. Choose
UDDI|Connection Settings and enter the new timeout in the Timeout
field. Close the Explorer and reopen to apply the timeout value to any
connection. The server may also truncate your query results if it
determines that the results are too large.

Finding a business
You might want to find a particular business that you like to work with
and see what types of services they offer. Or you may want to find
businesses in a particular industry, such as software publishing. There are
several ways to search for a business using the Web Services Explorer:
• Search by business name
• Search by business category
• Search by business identifier
• Search by tModel

Searching by name
To search for a specific business by name in the Web Services Explorer,
complete the following steps:
1 Choose Tools|Web Services Explorer to open the Explorer.
2 Expand the UDDI Sites node in the tree on the left and double-click a
UDDI operator site node to expand it.

Browsing and publishing web services 8-7

Searching a UDDI registry

3 Select the Business List node to display the Query For Business page on
the right.

4 Enter the business name or the first few letters of the business name in
the Find By Name field on the Name tab. If you leave this field blank,
all the businesses at the site are found.
Note The Web Services Explorer supports the % symbol as a wildcard.
5 Execute the query with any of these methods:
• Choose Query|Execute.
• Click the Execute button on the toolbar.
• Click the Execute button on Query For Business page to the right of
the tree.
• Press Enter in the Find By Name field after entering the search name.
6 Expand the Business List node to see the query results and drill down
to find out more about a business and its services.

8-8 Developer’s Guide

 Searching a UDDI registry

Searching by category
Another method of searching for a business is to search by business
category. There are several business classifications you can search by:
• ntis-gov:naics:1997 (North American Industry Classification System)
• unspsc-org:unspsc:3-1 (United Nations Standard Products and Services
Code System)
• unspsc-org:unspsc (Universal Standard Products and Services
Classification)
• uddi-org:iso-ch:3166-1999 (codes for geographic location)
• ntis-gov:sic:1987 (Standard Industrial Classification)
• uddi-org:types
• uddi-org:misc-taxonomy
Note Other classification systems can also be used. If a scheme is not available
in the drop-down list, you can paste the key for the scheme into the
tModelKey field. You can also add and remove search criteria using the
Add and Remove buttons.
Each of these business classification systems has its own codes for the
various categories. Large businesses that do a wide variety of business
may be classified in several of these systems and under several
classifications in each system. For example, a company might sell
computer hardware and software. In NAICS, this business might be listed
with several classifications, such as computer training, data processing
services, and software publishers. This same business could also be
classified in UNSPSC as computer programmed instructions, database
software, and mainframe computers.
These business classifications are listed in the KeyName drop-down list
on the Category page of the Web Services Explorer. For further
classification, a KeyValue is used to give a more specific description of the
business. Each business classification also has a corresponding
tModelKey.

Browsing and publishing web services 8-9

Searching a UDDI registry

To search by business category,

1 Choose Tools|Web Services Explorer to open the Explorer.
2 Expand the UDDI Sites node in the tree on the left and double-click a
UDDI operator site node to expand it.
3 Select the Business List node to display the Query For Business page on
the right.
4 Choose the Category tab on the Query For Business page.
5 Click in the KeyName field to activate the drop-down list and choose
one of the business categories.
6 Enter an appropriate code for the selected business category in the
KeyValue column.
For example, if you want to search for all software publishers at a UDDI
site, you could choose Ntis-gov:naics:1997 from the KeyName drop-
down list, and enter the NAICS software publisher’s code in the
KeyValue field: 51121. Each business category type has its own set of
codes for classification.
7 Press Enter to commit the KeyValue.
8 Click the Execute button to execute the query.
9 Expand the Business List node to see the list of businesses registered as
the selected category.

8-10 Developer’s Guide

 Searching a UDDI registry

Searching by identifier
Another method of searching for a business is to search by business
identifier. There are several built-in identifier schemes you can search by:
• Thomasregister-com:supplierID
• Dnb-com:D-U-N-S (Dun & Bradstreet Number Identifier System)
These IDs are listed in the KeyName drop-down list on the Identifier page
of the Web Services Explorer. Each of these classifications has a
corresponding tModelKey.
To search by business identifier,
1 Choose Tools|Web Services Explorer to open the Explorer.
2 Expand the UDDI Sites node in the tree.
3 Expand a UDDI operator site node and select the Business List node to
display the Query For Business page on the right.
4 Choose the Identifier tab on the Query For Business page.
5 Choose one of these business identifiers from the KeyName drop-down
list:
• Thomasregister-com:supplierID
• Dnb-com:D-U-N-S
6 Enter an appropriate code for the selected business identifier in the
KeyValue column.
For example, if you want to search for a business with a D-U-N-S ID of
00-136-8083 at a UDDI site, you would choose Dnb-com:D-U-N-S from the
KeyName drop-down list, and enter the ID number in the KeyValue
field: 00-136-8083. This is IBM’s D-U-N-S ID.
7 Press Enter to commit the KeyValue.
8 Click the Execute button to execute the query.
9 Expand the Business List node to see the business registered with the
selected ID.

Finding a service
Querying by service can only be done within a particular business. You
must first search for a business name and select the business node in the
tree on the left before querying for a service.

Browsing and publishing web services 8-11

Searching a UDDI registry

To query for a service, complete the following steps:

1 Choose Tools|Web Services Explorer to open the Explorer.
2 Expand the UDDI Sites node in the tree on the left.
3 Expand a UDDI operator site node and execute a Query For Business
by name as explained in “Searching by name” on page 8-7.
4 Expand the Business List node to see the query results.
5 Select a business in the tree and choose the Query For Service tab on the
right.
6 Enter the name of the web service in the Find By Name field.
7 Click Execute to run the query and the web service appears as the only
node under the business node.
Note You can also search for a service by category or tModel.

Finding a tModel
You can also search for tModels in the Web Services Explorer. TModels
represent a technical specification for a web service. When searching for
tModels you can search by tModel name, category, and identifier.

Searching by name
To search for tModels by name,
1 Choose Tools|Web Services Explorer to open the Explorer.
2 Expand the UDDI Sites node in the tree on the left and double-click a
UDDI operator site node to expand it.
3 Choose the tModel List node in the tree to display the Query For
tModel page on the right.
4 Enter the tModel name in the Find By Name field.
For example, if you wanted to find all tModels beginning with the
uddi-org name, you would enter uddi-org.
5 Click the Execute button to execute the query.

8-12 Developer’s Guide

 Examining UDDI query results

6 Expand the tModel List node to see the results of the query.

Examining UDDI query results

Once you’ve executed a UDDI query, you can browse detailed information
about a web service in the Web Services Explorer. Each node in the Explorer’s
tree displays different information about a selected service. When you select a
node in the tree, the appropriate detail information displays to the right of the
tree. For example, when you select the business node in the tree, the Business
Details page is displayed on the right with overview information about the
business, as well as any contact information, identifiers, and categories. When
you expand the business node and select a business service, the Service
Details page displays, and so on.
There are several detail pages in the Web Services Explorer:
• Details
• Business Details
• Service Details
• Binding Details
• TModel Instance Details
• TModel Details

Detail pages in the Web Services Explorer

Queries for businesses and services return multiple nodes in the tree, such
as the business name, service name, binding information, tModel Instance,
and tModel details. Therefore, these queries can obtain information from
all five detail pages. Depending on the web service and how it’s
published, a service may not have all of these detail pages. Queries for
tModels return only tModel nodes in the tree and display the TModel

Browsing and publishing web services 8-13

Searching an Axis server for web services

Details page only. Some of the details on these pages are required while
others are optional, so some fields may be blank.

Details page
The Details page displays when a UDDI operator site node is selected.
This page displays operator site information, such as name, inquire URL,
and publish URL.

Business Details page

The Business Details page displays when the business node is selected.
This page displays company information, such as a company overview
with business name and description, contact information, identifiers, and
business categories.

Service Details page

The Service Details page displays when the web service node is selected in
the tree. This page displays overview information about the service, such
as the service name, description, and service key.

Binding Details page

The Binding Details page displays when the binding node is selected in
the tree. This page displays a description, the access point to the service,
and the URL type.

TModel Instance Details page

The TModel Instance Details page displays when the TModel Instance
Details node, which often defaults to <No Description>, is selected in the
tree. This page displays a description, tModel name, tModel key, an
overview document description, and an overview document URL.

TModel Details page

The TModel Details page displays when the fifth node in the Business List
is selected in the tree. It also displays when a tModel node in the TModel
List is selected. This page displays overview information, such as the
tModel name and description, and the tModel key, an overview document
description, an overview document URL, and any relevant identifiers and
categories.

Searching an Axis server for web services

Some web services are deployed to and available on network sites that run
Apache Axis-hosted web services. You can browse these with the Web
Services Explorer. If you’re searching a remote Axis server, remote access
on that server must be enabled. See “Accessing remote Axis servers” on

8-14 Developer’s Guide

 Searching an Axis server for web services

page 8-16. In addition, you can publish an Axis web service to a UDDI
registry. See “Publishing a web service from an Axis server” on page 8-22.
You can also create Axis web services locally and browse them as follows:
1 Create a web service as described in Chapter 11, “Tutorial: Publishing a
bean as a web service.”
2 Right-click the WebApp index.html file in the project pane and choose
Web Run to run the web server.
3 Choose Tools|Web Services Explorer to open the Explorer.
4 Display the web service as described in “Displaying services” on
page 8-15.

Displaying services
When web services are deployed to an Axis server, you can browse those
services in the Web Services Explorer.
To display available services on an Axis server,
1 Expand the Axis Servers node and create a new Axis node for the
server you want to browse.
2 Choose the new Axis node and enter the URL for the server in the URL
field, including the web context of the service. For example, http://
localhost:8080/MyWebContext/servlet/AxisServlet.
3 Click the Display Services button on the Details page.
4 Expand the node to view the available services.

You can also publish Axis web services to a UDDI site in the Web Services
Explorer. See “Publishing a web service from an Axis server” on page 8-22
Note Remote access must be enabled on remote Axis servers in order to browse
their services. See “Accessing remote Axis servers” on page 8-16.

Browsing and publishing web services 8-15

Searching an Axis server for web services

Accessing remote Axis servers

JBuilder builds Axis servers with remote access disabled. If you want to
change this default behavior, you’ll need to modify the server-config.wsdd
file as follows.
Warning Enabling remote administration may give unauthorized parties access to
your machine. Make sure to add security to your configuration.
To enable remote access:
1 Build the project.
2 Open the server-config.wsdd file located in the web application’s WEB-INF
directory on disk (this directory doesn’t display in the project) and edit
it as follows:
change the AdminService element that reads <parameter
name="enableRemoteAdmin" value="false"/> to <parameter
name="enableRemoteAdmin" value="true"/>.
3 Disable the regeneration of server-config.wsdd by changing the project’s
build SOAP option to not regenerate deployment at build time as
follows:
a Choose Project|Project Properties to open the Project Properties
dialog box.
b Choose the Build tab.
c Choose the SOAP tab on the Build page and uncheck the Regenerate
Deployment At Build Time option.

d Click OK to close the Project Properties dialog box.

8-16 Developer’s Guide

 Searching web services with WSIL documents

Searching web services with WSIL documents

Another method of searching available web services is to search with
WSIL documents. WSIL documents are collections of pointers to other
documents that list web services available on a web site. WSIL documents
can point to other WSIL documents, a UDDI business or service entry, and
WSDL documents. Usually web sites with available web services gather
their links into one WSIL document at a default location, such as http://
www.xmethods.net/inspection.wsil. Once you’ve found the service you
want at a site, you can import the WSDL document with the Import
WSDL wizard.
According to the Web Services Inspection Language specification, WSIL
documents must have at least one <service> element or one <link> element
and may have both. Services and links are displayed in the Web Services
Explorer as child nodes of a WSIL node.

Services node
The Services node displays the <service> elements in the WSIL document.
The <service> element specifies the WSDL file for the service or it can refer
to a UDDI entry that specifies the WSDL. Expand the Services node to
display the available services on the site. Expand a web service and select
the Description node beneath it to display the Details page. This page
provides such information as the location of the WSDL document,
whether the service is an endpoint, and binding information.

Browsing and publishing web services 8-17

Searching web services with WSIL documents

If the reference is to a UDDI entry, you can search for services by two
methods:
• Service key and Location URI
• Service key and Discovery URL
Choose an option and click the Fetch button to get the information. The
search results are displayed in a temporary node, WSIL Reference
Temporary, in the UDDI tree.

Links node
If any <link> elements are contained in the WSIL document, they display
as nodes under the Links node. Links can be addresses to another WSIL
document or to a UDDI business entry. Expand the Links node to see the
<link> elements in the WSIL document and select a link to display the
Details page.
If the link is a reference to a UDDI business entry, the Details page
displays UDDI information you can fetch from the UDDI registry. The
search results are displayed in a WSIL Reference Temporary node under
the UDDI node.

If the link refers to another WSIL document, you can click the Execute
button on the Details page to display the list of services in the WSIL.

8-18 Developer’s Guide

 Searching web services with WSIL documents

Executing a search
To search for available services at a web site,
1 Select the WSIL Documents node in the Explorer.
2 Click the New WSIL Location on the WSIL Documents page on the
right to create a new WSIL node.
Tip You can also right-click the node and choose New or choose File|New.
3 Enter a name for the node and click OK.
4 Enter the web site URL that you want to search. For example,
http://www.xmethods.net/inspection.wsil
5 Click Save to save the changes.
6 Expand the new node to see the available Services and Links nodes.
7 Do one of the following:
• Expand the Services node and choose a Description node under one
of the services to see the location of the WSDL document. You can
then use the Import WSDL wizard to import it and generate Java
classes to consume the service.
• Expand the Links node and choose a link to see what’s available on
the Details page.
If there’s a reference to a UDDI business entry, choose Fetch to
obtain the information. The results are displayed in a WSIL
Reference Temporary node under the UDDI node.
If the reference is to another WSIL document, you can also browse
those services and links. Choose the link with the WSIL reference
and click the Execute button on the Details page. Expand the link
node to display the services listed in the WSIL.

Browsing and publishing web services 8-19

Publishing web services in a UDDI registry

Publishing web services in a UDDI registry

The Web Services Explorer supports publishing of new web services and
their corresponding tModels. In some cases, UDDI sites require
registration before you can publish to them. Some UDDI sites have test
sites where you can publish and test new services before distributing them
on the official UDDI site. Most UDDI sites also require you to specify a
Publish URL before publishing your service. The Publish URL is available
on the site’s web site. For example, the Publish URL for the Microsoft
UDDI site is https://uddi.microsoft.com/publish

Publishing a web service

To publish a web service, you must first publish a business, if it doesn’t
exist, and then add information for the business, service, binding
template, and tModel.
First, add the new business as follows:
1 Choose Tools|Web Services Explorer to open the Explorer.
2 Choose a UDDI operator node, such as Microsoft, under the UDDI Sites
node in the tree. The operator site must have a Publish URL associated
with it. If the Publish URL field is blank, go to the operator’s web site to
find the Publish URL for that particular site. To enter the Publish URL
for an operator site, choose an operator node and enter the URL in the
Publish URL field on the Details page. Choose Save to save the entry.
3 Right-click the Business List node in the tree and choose New Business
or choose File|New Business.
4 Enter the name of the business in the dialog box and click OK.
5 Select the new business node and enter the appropriate information on
the Overview tab of the Business Details page on the right side. Some of
these details are filled in by the UDDI site, but the Explorer allows you
to edit these fields.
6 Choose the Contact tab and click Add. Enter the appropriate contact
information.
7 Continue to add information to this business by right-clicking the
business node and selecting New again to create the service node. Then

8-20 Developer’s Guide

 Publishing web services in a UDDI registry

right-click the service node and choose New to create the binding node,
and so on.

8 Choose the UDDI operator node, the Business List node, or the
business node and choose File|Save Changes. This saves all the
changes and posts them to the UDDI site. You can also right-click a
node and choose Save Changes or use the toolbar button. If the UDDI
site requires a login, you’ll be prompted for a user name and password.
Note The changes that are saved are dependent upon the node selected. You
can choose a child of a node and only save changes to that node and
nodes beneath it. You can also select the UDDI operator node or the
Business List node and save all the changes.

Publishing a tModel
To add and publish a new tModel,
1 Complete steps 1 and 2 in “Publishing a web service” on page 8-20.
2 Right-click the tModel List node in the tree and choose New tModel. A
new tModel node is added to the tree.
3 Select the New tModel node and enter the appropriate information on
the tModel Details page on the right side. If the UDDI site requires a
login, you’ll be prompted for a user name and password.
4 Select the tModel node and choose File|Save Changes to save the new
tModel and post it to the UDDI site.

Browsing and publishing web services 8-21

Publishing web services in a UDDI registry

Publishing a web service from an Axis server

If you have a locally-hosted Axis web service, you can also publish it to a
UDDI registry as follows. First, you need to set the default for publishing.
Then you need to run the Axis service locally on the web server and
publish it.
1 Create a local Axis web service as described in Chapter 11, “Tutorial:
Publishing a bean as a web service.”
2 Run the web server.
3 Choose Tools|Web Services Explorer to open the Explorer.
4 Expand the UDDI Sites node and expand the UDDI operator site where
you want to publish. Choose the Business List node and search for the
business where you want to publish the service. If the business doesn’t
exist yet, create a new business and choose File|Save Changes to save
the changes to the UDDI site.
5 Right-click the business node and choose Set As Publishing Default.
6 Create a new Axis node for the web service:
a Choose the Axis Servers node to display the Axis Server page on the
right.
b Click the New Axis Server button on the Axis Servers page.
c Enter a name for the new Axis node and click OK.
7 Modify the URL on the Axis Server Details page with the WebApp
context and the server location of the web service. For example, http://
localhost:8080/foo/servlet/AxisServlet
8 Click the Display Services button on the Details page to display the web
service in the Explorer’s tree.
9 Right-click the Axis service in the tree and choose Publish or choose
File|Publish. The service will be published to the business set as the
publishing default.

8-22 Developer’s Guide

 Monitoring UDDI messages

10 Click OK in the Publish Axis Service To UDDI dialog box to close it.
11 Log into the UDDI registry if it requires it. A dialog box appears
indicating that the service is published and the new nodes are created
for that service below the business node set as the publishing default.

Monitoring UDDI messages

The Web Services Explorer has a UDDI Message Monitor that allows you
to view the SOAP messages to and from the selected UDDI operator site.
To view these messages,
1 Expand the UDDI Sites node in the Explorer’s tree and choose a UDDI
node.
2 Choose UDDI|Cache UDDI Messages. This enables the UDDI Message
Monitor, which saves the requests to and responses from the UDDI
operator site.
3 Execute a search at the site.
4 Choose the UDDI operator node and choose UDDI|View Messages to
open the UDDI Message Monitor.
5 Select a response or request from the list and click View to view the
message. Here you can see the SOAP envelope and the XML messages
it contains in the Tree View on the left. The Source View on the right
displays the source code for the message sent or received.

Generating Java classes

The Web Services Explorer provides access to the Import WSDL wizard
for importing any WSDL documents that you browse to. The Import
WSDL wizard generates Java classes based on the WSDL document. The
Import WSDL wizard is available as a menu command, File|Import
WSDL, and as a button on the toolbar. The menu command and the
toolbar button are only active when a WSDL document is available. For

Browsing and publishing web services 8-23

Generating Java classes

example, if the tModel Details node is selected in the tree and a WSDL
document is in the Overview Document URL field, the Import WSDL
button is activated for you to select. The WSDL file name is automatically
entered in the wizard’s WSDL URL field.

See also
• Chapter 5, “Working with WSDL”
• Chapter 9, “Tutorial: Generating Java classes from a WSDL file”

8-24 Developer’s Guide

 Chapter

Tutorial: Generating Java

Chapter9
9
classes from a WSDL file
This is a feature of the This tutorial explains how to use the Import WSDL wizard to generate
Borland Web Services Kit Java classes. You’ll also write a Test class to retrieve a string from the
for Java. SOAP server and output it to the message pane.
The Import WSDL wizard generates some or all of the following Java
classes:

Table 9.1 Classes generated by the Import WSDL wizard

Class name Description
<type name>.java A class for each complexType in the WSDL.
<service name>Service.java A service interface which defines a get method
for each port listed in the service element of the
WSDL. This service interface defines a factory
class to get a stub instance.
<service name>ServiceLocator.java A locator class which is the implementation of
the service interface.
<service name>TestCase.java An optional JUnit test case for testing the web
service.
<WSDL file name>PortType.java An interface for each portType in the WSDL. You
will use the implementation of this interface to
call the remote methods.
<WSDL file An implementation class for the portType
name>SoapBindingImpl.java interface.
<WSDL file An optional skeleton class to encapsulate an
name>SoapBindingSkeleton.java implementation for the server.
<WSDL file A stub class which acts as a proxy for a remote
name>SoapBindingStub.java web service. This allows you to call the web
service as if it were a local object.

Tutorial: Generating Java classes from a WSDL file 9-1

Step 1: Creating a SOAP server

The wizard generates a package name based on the WSDL’s target

namespace or uses one that you specify, as well as adding any necessary
project libraries.
The following is a tutorial involving a modified version of
InteropTest.wsdl, a document created for interoperability testing of SOAP
servers. In this tutorial, you’ll use this WSDL and the Axis toolkit to create
client and server Java code, then connect to the service locally.
This tutorial assumes you are familiar with Java and the JBuilder IDE. For
more information on Java, see Getting Started with Java. For more
information on the JBuilder IDE, see “The JBuilder environment” in
Introducing JBuilder.

Step 1: Creating a SOAP server

First you’ll create a new project, then you’ll create a SOAP server with the
SOAP Server wizard.
1 Choose File|New Project to create a new project.
2 Enter WsdlInteropSample in the Name field and click Finish.
3 Choose File|New to open the object gallery.
4 Choose the Web Services tab and double-click the SOAP Server icon to
open the SOAP Server wizard. The Web Application wizard opens first,
because you need to create a WebApp to host the SOAP Server.
5 Enter axis in the Name field.
Note The name of the WebApp and the WebApp’s root directory are
important. They must match the root directory given for the SOAP
address in the WSDL file. The samples and documentation use axis as
the WebApp name.
6 Enter axis in the Directory field. An axis subdirectory will be created in
the next step when the WebApp is created.
7 Click OK to close the Web Application wizard and create the WebApp.
Now the SOAP Server wizard opens. The SOAP Server wizard creates a
web application that hosts a web server.
8 Accept axis in the WebApp field.
9 Leave the toolkit as Apache Axis.

9-2 Developer’s Guide

 Step 2: Generating the Java classes

10 Accept the default option, Copy Admin/Console To WebApp. The

SOAP Server wizard looks like this:

11 Click Finish to close the wizard. If you expand the Root directory of the
axis node in the project pane and open index.html, you’ll see the admin/
console copied over from the toolkit.

Step 2: Generating the Java classes

Next, you’ll add the WSDL file to the project and use the Import WSDL
wizard to generate the Java class files.
1 Choose the Add Files/Packages button on the project pane toolbar and
navigate to the samples/webservices/wsdl/ directory in the <jbuilder>
directory.
2 Select InteropTest.wsdl and click OK. The file is added to the project and
displayed in the project pane.
3 Right-click InteropTest.wsdl in the project pane and choose Import
WSDL from the context menu to activate the Import WSDL wizard.
Notice that InteropTest.wsdl is automatically inserted in the WSDL URL
field of the wizard. The Import WSDL wizard is also available on the

Tutorial: Generating Java classes from a WSDL file 9-3

Step 2: Generating the Java classes

Web Services page of the object gallery (File|New). The Import WSDL
wizard looks like this:

4 Accept the defaults in the wizard and click Finish. A package node
called org.soapinterop displays in the project pane. This package name
is based on the target namespace, http://soapinterop.org/. To see
where the package name came from, double-click InteropTest.wsdl in
the project pane to open it in the editor. Look for targetNamespace in the
structure pane and select it to highlight it in the editor:
targetNamespace="http://soapinterop.org/". This is what the wizard used
for the package name.
5 Open the package node to see the generated Java classes:
• InteropService.java—an abstract interface which defines a factory
class to get a stub instance.
• InteropServiceLocator.java—the implementation of the abstract
interface.
• InteropServiceTestCase.java—the JUnit test case for the service. For
more information about JUnit test cases, see “Unit Testing” in
Building Applications with JBuilder.
• InteropTestPortType.java—the service interface for each portType.
• InteropTestSoapBindingImpl.java—an implementation class for the
portType interface.

9-4 Developer’s Guide

 Step 3: Looking at the deployment descriptor

• InteropTestSoapBindingSkeleton.java—a skeleton class to encapsulate

an implementation for the server.
• InteropTestSoapBindingStub.java—a stub class which acts as a proxy
for a remote web service. This allows you to call the web service as if
it were a local object.
The project pane looks like this:

Step 3: Looking at the deployment descriptor

The Import WSDL wizard created a deploy.wsdd (web services deployment
descriptor) XML file. Values in the deploy.wsdd file are derived from the
information in the WSDL file. In this step, you’ll look at the deployment
descriptor in the editor.
1 Expand the axis node in the project pane, then expand the
<SOAP:Apache Axis toolkit> node.
2 Double-click [org.soapinterop] deploy.wsdd to open the file in the editor.
Note the following elements:

Element Description
service name The name of the published service, in this case
InteropPort.
parameter name="className" The name of the provider skeleton class that
encapsulates an implementation for the server.
The class generated by the wizard is called
org.soapinterop.InteropTestSoapBindingSkeleton.
parameter name ="allowedMethods" The published method(s).

Tutorial: Generating Java classes from a WSDL file 9-5

Step 4: Creating a test class

Step 4: Creating a test class

1 Choose File|New Class and create a new class called Test with the
following code:
package wsdlinteropsample;

import org.soapinterop.*;
import java.net.*;

public class Test {

public static void main(String[] args) {
try {
InteropTestPortType stub = new
InteropServiceLocator().getInteropPort();
System.err.println(stub.echoString("foo string"));
}
catch (Exception ex) {
ex.printStackTrace();
}
}
}
2 Open org.soapinterop.InteropTestSoapBindingImpl.java.
3 Replace the method body of echoString with:
return inputString.toUpperCase();
4 Right-click index.html in the Root directory of the axis WebApp node in
the project pane and choose Web Run Using “Webservices Server”
from the context menu to compile the classes and start up the web
server. Note that “Webservices Server” in the Web Run command of
the context menu refers to a runtime configuration that was
automatically created for you by the SOAP Server wizard. For more
information on runtime configurations, see “Setting runtime
configurations” in Building Applications with JBuilder.
5 Right-click Test.java and select Run Using Defaults.
InteropTestSoapBindingStub.java passes the call to the SOAP server and
the server responds by returning the passed string in uppercase. The
client prints FOO STRING to the message pane.
Congratulations! You’ve completed the tutorial and generated the Java
files for a basic web service from a WSDL file. For more information about
WSDL, see Chapter 5, “Working with WSDL.” For more information
about SOAP, see Chapter 3, “Working with SOAP servers.”

9-6 Developer’s Guide

 Chapter

Tutorial: Generating a web

Chapter10
10
service from a WSDL document
This is a feature of the This tutorial teaches you how to build a web service application starting
Borland Web Services Kit from an existing WSDL file. You will use the Import WSDL wizard to
for Java. generate Java classes from the WSDL file. Then you’ll complete the
remaining steps to access a web service which provides translation to and
from foreign languages using AltaVista’s BabelFish.
This tutorial assumes you are familiar with Java, JavaServer Pages (JSP)
and the JBuilder IDE. For more information on Java, see Getting Started
with Java. For more information on JavaServer Pages, see “Developing
JavaServer Pages” in the Web Application Developer’s Guide. For more
information on the JBuilder IDE, see “The JBuilder environment” in
Introducing JBuilder.

Step 1: Creating a new project

In this step, you will create a new project using the Project wizard.
1 Select File|New Project to display the Project wizard.
2 Enter a project name in the Name field, such as wsdltutorial.
3 Click Finish to close the Project wizard and create the project. You do
not need to make any changes to the defaults on Steps 2 and 3 of the
wizard.
A new project is created.

Tutorial: Generating a web service from a WSDL document 10-1

Step 2: Creating a new SOAP server

Step 2: Creating a new SOAP server

In this step you’ll create a SOAP server using the SOAP Server wizard.
1 Choose File|New.
2 Click the Web Services tab of the object gallery. Double-click the SOAP
Server icon. Since the new project does not yet contain a web
application, the Web Application wizard appears. A SOAP Server
requires a web application to host it.
3 Type axis for both the web application name and directory.
Note The name of the WebApp and the WebApp’s root directory are
important. They must match the root directory given for the SOAP
address in the WSDL file. The samples and documentation use axis as
the WebApp name.
4 Click OK to create the axis WebApp. The SOAP Server wizard displays.
5 Accept the defaults for the WebApp and the Apache Axis Toolkit. The
SOAP Server wizard looks like this:

6 Click Finish to close the SOAP Server wizard.

Step 3: Importing the WSDL file

In this step, you’ll add a WSDL file to the project, then generate Java
classes from the WSDL file using the Import WSDL wizard.
1 Click the Add Files/Packages button.

10-2 Developer’s Guide

 Step 3: Importing the WSDL file

2 Browse to BabelFishService.wsdl in <jbuilder>/samples/webservices/

BasicWebService. Select it and click OK. The file is added to your project.
This WSDL file will be used to generate Java classes which implement
the web service.
3 Right-click BabelFishService.wsdl in the project pane. Select Import
WSDL from the context menu. The Import WSDL wizard appears. The
Import WSDL wizard looks like this:

4 Accept all the defaults and click Finish. The following files are
generated in the net.xmethods.www package:
• BabelFishBindingImpl.java is the service implementation. You write
your code in this class. This class implements BabelFishPortType.java.
• BabelFishBindingSkeleton.java is the server-side implementation of
the service, which delegates to an implementation class.
• BabelFishBindingStub.java is the client stub that serializes the Java call
and parameters into SOAP.
• BabelFishPortType.java is an abstract interface for the service.
• BabelFishService.java is an abstract interface which defines a factory
class to get a stub instance.
• BabelFishServiceLocator.java is the implementation of the abstract
service interface.
• BabelFishServiceTestCase.java is the JUnit test case for the service. For
more information about JUnit test cases, see “Unit Testing” in
Building Applications with JBuilder.

Tutorial: Generating a web service from a WSDL document 10-3

Step 4: Implementing the service

Expand the net.xmethods.www package node in the project pane to see the
generated files. The project pane looks like this:

5 Choose Project|Make Project to compile the generated classes.

Step 4: Implementing the service

In this step, you’ll replace the generated code in BabelFishBindingImpl.java
with code that implements the web service.
1 Expand the net.xmethods.www package node in the project pane.
2 Double-click BabelFishBindingImpl in the project pane to open it in the
editor.
3 Remove the generated body of the BabelFishBindingImpl class and add
the code indicated in bold:
public class BabelFishBindingImpl implements
net.xmethods.www.BabelFishPortType {
private String translatedOutput = "Sorry, I don't speak ";
public java.lang.String babelFish(java.lang.String translationmode,
java.lang.String sourcedata) throws java.rmi.RemoteException {
if (translationmode == "en_fr")
translatedOutput = translatedOutput + " English";
else
translatedOutput = translatedOutput + " your language";
return translatedOutput;
}
}

Step 5: Creating the Public web application

In this step, you’ll create a WebApp to host the JSP you’ll create in the
following step.
1 Choose File|New.

10-4 Developer’s Guide

 Step 6: Creating a JSP that invokes the web service

2 Click the Web tab of the object gallery and select Web Application.
Click OK. The Web Application wizard appears.
3 Enter Public for both the web application name and directory.
4 Click OK.

Step 6: Creating a JSP that invokes the web service

In this step you’ll use the JSP wizard to create the skeleton of a JSP. Then
you’ll fill in the JSP code.
1 Choose File|New.
2 Click the Web tab of the object gallery and select JavaServer Page. Click
OK. The JSP wizard appears.
3 Make sure Public is selected as the WebApp.
4 Type index for the name of the JSP.
5 Uncheck Generate Submit Form.
6 Make sure Generate Sample Bean is checked. The JSP wizard looks like
this:

7 Click Next.
8 Enter com.borland.demo.web for the sample bean’s package name.

Tutorial: Generating a web service from a WSDL document 10-5

Step 6: Creating a JSP that invokes the web service

9 Make sure the name of the bean is indexBean. The JSP wizard looks like
this:

10 Click Finish.
11 Make sure index.jsp is open in the editor.
12 Replace the contents of the <body></body> tags with the following JSP
code:
<h1>A simple JSP using a Web Service</h1>
<form method="post">
<table>
<tr>
<td>Enter the text to translate</td>
<td><input name="inputParam" value="<jsp:getProperty name="indexBeanId"
property="inputParam" />"></td>
</tr>
<tr>
<td>Choose the language to translate text to</td>
<td><select name="inputOption">
<option value="en_fr">English to French
<option value="en_de">English to German
<option value="en_it">English to Italian
<option value="en_pt">English to Portuguese
<option value="en_es">English to Spanish
<option value="fr_en">French to English
<option value="de_en">German to English
<option value="it_en">Italian to English
<option value="pt_en">Portuguese to English
<option value="ru_en">Russian to English
<option value="es_en">Spanish to English
</select>
</td>
</tr>

10-6 Developer’s Guide

 Step 7: Implementing the bean

<tr>
<td>Select the server</td>
<td><select name="serverOption">
<option value="public">Publicly hosted service at XMethods
<option value="local">Locally hosted service you built
</select>
</td>
</tr>
</table>
<input type="submit" name="Submit" value="Submit"><input type="reset"
value="Reset"></br>
</form>

<br>I translated your text</br>

<br><b>"<jsp:getProperty name="indexBeanId" property="inputParam" />"</b>
</br>
<br>into your language as</br>
<br><b>"<jsp:getProperty name="indexBeanId" property="outputParam"/>"</b>
</br>

Step 7: Implementing the bean

In this step, you’ll write code to implement the indexBean class that was
created by the JSP wizard in the previous step.
1 Expand the com.borland.demo.web package node in the project pane.
2 Double-click indexBean in the project pane to open it in the editor.
3 Remove the body of the indexBean class and add the code shown in
bold:
package com.borland.demo.web;

import net.xmethods.www.*;
import java.net.URL;

public class indexBean {

public static void main(String[] args){
BabelFishPortType ws = null;
try {

ws = new BabelFishServiceLocator().getBabelFishPort
(new URL("http://localhost:9090/axis/services/BabelFishPort"));
System.out.println(ws.babelFish("en_fr", "Hello"));
}
catch (Exception ex) {
ex.printStackTrace();
}
}

Tutorial: Generating a web service from a WSDL document 10-7

Step 7: Implementing the bean

private BabelFishPortType ws;

private String outputParam;
private String inputParam = "Hello";
private String inputOption = "en_fr";
private String serverOption = "public";

public String getInputParam() {

return inputParam;
}
public String getInputOption() {
return inputOption;
}
public String getOutputParam() {
try {
if (serverOption.equals("public"))
ws = new BabelFishServiceLocator().getBabelFishPort();
else
ws = new BabelFishServiceLocator().getBabelFishPort
(new URL("http://localhost:9090/axis/services/BabelFishPort"));
outputParam = ws.babelFish(inputOption, inputParam);
}
catch (Exception ex) {
ex.printStackTrace();
}
return outputParam;
}
public void setInputParam(String newInput) {
if (newInput!=null) {
inputParam = newInput;
}
}
public void setInputOption(String newOption) {
if (newOption!=null) {
inputOption = newOption;
}
}

public String getServerOption() {

return serverOption;
}

public void setServerOption(String newOption) {

if (newOption!=null) {
serverOption = newOption;
}
}

10-8 Developer’s Guide

 Step 8: Invoking the web service

Step 8: Invoking the web service

1 Choose Project|Make Project to compile the project.
2 Right-click index.jsp in the Public/Root directory folder in the project
pane. Select Web Run Using “Webservices Server” from the context
menu. This starts both web applications: axis, which hosts the web
service, and Public, which contains the JSP that’s used to access the web
service. Note that “Webservices Server” in the Web Run command of
the context menu refers to a runtime configuration that was
automatically created for you by the SOAP Server wizard. For more
information on runtime configurations, see “Setting runtime
configurations” in Building Applications With JBuilder.
3 Enter text to translate and select a target language. Click Submit. The
text is translated if a translation is available.
Congratulations! You’ve completed the tutorial and created a web service
that provides translation of strings using AltaVista’s BabelFish. For more
information about WSDL, see Chapter 5, “Working with WSDL.” For
more information about SOAP, see Chapter 3, “Working with SOAP
servers.”

Tutorial: Generating a web service from a WSDL document 10-9

10-10 Developer’s Guide
 Chapter

Tutorial: Publishing a bean as a

Chapter11
11
web service
This is a feature of the This tutorial teaches you how to use the Export Class As A Web Service
Borland Web Services Kit wizard to export a JavaBean as a web service.
for Java.
This tutorial assumes you are familiar with Java, and the JBuilder IDE. For
more information on Java, see Getting Started with Java. For more
information on the JBuilder IDE, see “The JBuilder environment” in
Introducing JBuilder.

Step 1: Creating a new project

In this step, you will create a new project using the Project wizard.
1 Select File|New Project to display the Project wizard.
2 Enter a project name in the Name field, such as exportbean.
3 Click Finish to close the Project wizard and create the project. You do
not need to make any changes to the defaults on Steps 2 and 3 of the
wizard.
A new project is created.

Tutorial: Publishing a bean as a web service 11-1

Step 2: Creating a sample Java bean

Step 2: Creating a sample Java bean

In this step, you’ll use the JavaBean wizard to create a sample JavaBean
which can be exported as a web service.
1 Select File|New to display the object gallery.
2 Choose the General tab of the object gallery.
3 Select JavaBean and click OK to launch the JavaBean wizard.
4 Accept the default Class Information.
5 Check Generate Sample Property.
6 Click OK. A Bean1.java file is generated in the exportbean package.

Step 3: Exporting the sample bean as a web service

In this step, you’ll use the Export Class As A Web Service wizard to export
the bean as a web service.
1 Select Project|Make Project “exportbean”. Compiling the project makes
the sample bean available to the Export Class As A Web Service
wizard.
2 Right-click Bean1 in the project pane. Select Export Class As Web Service
from the context menu. The Export Class As A Web Service wizard
looks like this:

11-2 Developer’s Guide

 Step 4: Creating a new SOAP server

3 Accept all the defaults and click Finish. A WSDL file called
exportbean.wsdl file is generated. This file contains the WSDL
information which defines how to connect to the web service. The Java
files which make up the web service are also generated and placed in a
package called exportbean_generated. These include the following files:
• Bean1PortType.java is the interface for the service.
• Bean1Service.java is an abstract interface which defines a factory class
to get a stub instance.
• Bean1ServiceLocator.java is the implementation of the abstract
interface.
• Bean1ServiceTestCase.java is the JUnit test case for the service. For
more information about JUnit test cases, see “Unit Testing” in
Building Applications with JBuilder.
• Bean1ServicePortSoapBindingStub.java is the client stub that serializes
the Java call and parameters into SOAP.

Step 4: Creating a new SOAP server

In this step you’ll create a SOAP server using the SOAP Server wizard.
1 Choose File|New.
2 Click the Web Services tab of the object gallery. Double-click the SOAP
Server icon. Since the new project does not yet contain a web
application, the Web Application wizard appears. A SOAP Server
requires a web application to host it.
3 Type axis for both the web application name and directory.
Note The name of the WebApp and the WebApp’s root directory are
important. They must match the root directory given for the SOAP
address in the WSDL file. The samples and documentation use axis as
the WebApp name.

Tutorial: Publishing a bean as a web service 11-3

Step 5: Running and testing the web service

4 Click OK to create the axis WebApp. The SOAP Server wizard displays.
The SOAP Server wizard looks like this:

5 Accept the defaults for the WebApp and the Apache Axis Toolkit and
click Finish to close the SOAP Server wizard.

Step 5: Running and testing the web service

In this step, you will run the SOAP server. Then you’ll run the JUnit test
case which was generated by the Export Class As A Web Service wizard to
test the JavaBean running as a web service.
1 Expand the axis node in the project pane. Expand the Root directory of
the axis WebApp.
2 Right-click index.html. Select Web Run Using “Webservices Server”
from the context menu. The SOAP Server is started. Note that
“Webservices Server” in the Web Run command of the context menu
refers to a runtime configuration that was automatically created for you
by the SOAP Server wizard. For more information on runtime
configurations, see “Setting runtime configurations” in Building
Applications with JBuilder.
3 Expand the exportbean_generated package node in the project pane.
4 Right-click Bean1ServiceTestCase.java and select Run Test Using Defaults
from the context menu. This runs the generated JUnit test case in the

11-4 Developer’s Guide

 Step 5: Running and testing the web service

default test runner. Here is how JBTestRunner looks after running the
test case:

The test case accesses the public methods of the JavaBean running as a
web service in the SOAP Server. For more information on unit testing,
see “Unit Testing” in Building Applications with JBuilder.
Congratulations! You’ve completed the tutorial, published a JavaBean as a
web service, and tested it. For more information about WSDL, see
Chapter 5, “Working with WSDL.” For more information about SOAP, see
Chapter 3, “Working with SOAP servers.” For more information on unit
testing, see “Unit Testing” in Building Applications with JBuilder.

Tutorial: Publishing a bean as a web service 11-5

11-6 Developer’s Guide
 Chapter

Tutorial: Using the Web

Chapter12
12
Services Explorer
Overview
This is a feature of the JBuilder provides the Web Services Explorer for browsing and querying
Borland Web Services Kit UDDI registries. UDDI registries are databases used by businesses to
for Java. register their web services and to search for other available web services.
These registries are based on the Universal Description, Discovery, and
Integration (UDDI) framework. UDDI uses the Extensible Markup
Language (XML) and may also use the Web Services Description language
(WSDL) for describing a service.
The Web Services Explorer has additional features for browsing and
publishing services. For more information on these features, see
Chapter 8, “Browsing and publishing web services.”
Important The UDDI feature of the Web Services Explorer requires the use of Sun’s
JSSE extension. If you are using JDK 1.3 or earlier then you must install the
JSSE packages. This can be downloaded from Sun at http://
java.sun.com/products/jsse/index-102.html.

See also
• uddi.org at http://www.uddi.org

Tutorial: Using the Web Services Explorer 12-1

About this tutorial

About this tutorial

Using the Web Services Explorer, you can query a web service by name,
identifier, category, or tModel. The query type is defined by the currently
selected node in the Explorer’s tree. Select the Business List node for a
business query and the tModel node for a tModel query. Querying by
service can only be done within a particular business. Select a business in
the tree on the left before querying a service.
When the tree selection is on a particular business, service, binding, or
tModel, the right tab of the Explorer displays various details about that
node. Many entries are published without additional details, such as
identifiers and categories, so these tabs may be blank.
For definitions of any unfamiliar UDDI terms, see “UDDI terms and
definitions” on page 8-3.
In this tutorial, you’ll learn how to use the Web Services Explorer by
executing the following tasks:
• Browse all web services at the XMethods site.
• Browse tModels.
• Find software publishers at the Microsoft UDDI site.
• Generate Java classes.

Step 1: Browsing all web services at the XMethods site

In this step, you’ll use the Web Services Explorer to browse all the web
services available at XMethods, an organization that promotes the
development, deployment, and use of web services. For more information
about XMethods, visit http://www.xmethods.net/.
1 Choose Tools|Web Services Explorer to open the Web Services
Explorer.
2 Expand the UDDI Sites node in the tree on the left and expand the
XMethods operator site node.

12-2 Developer’s Guide

 Step 1: Browsing all web services at the XMethods site

3 Select the Business List node to display the Query For Business page on
the right.

4 Leave the Find By Name field blank to find all the businesses at the site
and choose the Execute button on the Query For Business page to
execute the query.
Tip You can also choose Query|Execute or use the Execute Query button
on the toolbar.
Important You can increase the timeout for the Web Services Explorer. Choose
UDDI|Connection Settings and enter the new timeout in the Timeout
field. Close the Explorer and reopen to apply the timeout value to any
connection. The server may also truncate your query results if it
determines that the results are too large.
5 Expand the XMethods Business List node to see all the services offered
by various companies at the XMethods site.
6 Search for the SQLData business as follows:
• Choose the Business List node again.
• Choose the Name tab on the Query For Business page.
• Enter SQLData in the Find By Name field.
• Press Enter or click the Execute button.
7 Select the SQLData node in the tree.
Notice that the Business Details page displays on the right with
overview information as well as contact, identifier, and category
information, if available. Also, the Query For Service tab displays on
the right. If you know the name of the service, you can narrow your

Tutorial: Using the Web Services Explorer 12-3

Step 1: Browsing all web services at the XMethods site

search even further by entering the name of the service in the Find By
Name field on the Query For Service page.

8 Expand the SQLData node and notice that there are several services
available.
9 Choose the SQLData Headline News node. Now the Service Details
page displays on the right with general information about the web
service, such as business name, description, and service key.
10 Expand the SQLData Headline News node and choose the next node
below it, SOAP Binding. The Binding Details page displays on the right
with a description of how to bind to the service, the access point to the
service, and the access point URL type. Some of these fields may be
blank if they aren’t required.
11 Expand the SOAP Binding node and choose the next node, <No
Description>. The TModel Instance Details page displays on the right
with details about the tModel, such as a description of the service,
tModel name and key, instance description, overview document
description and URL, and any instance parameters. Many of these
fields are blank because they are optional.
12 Navigate to the last SQLData node under the <No Description> node,
the tModel node. Examine the TModel details displayed to the right on
the Overview tab, such as name, description, TModel key, and
overview document description and URL. Some of the information is
the same as the TModel Instance Details page. The description field
describes what the web service does. The overview URL field contains
the URL that points to a WSDL file, which describes the specification
for the web service in the Web Services Description Language. The
WSDL file, written in XML, describes the service interface and the XML
messages that go in and out of the web service. By examining the
WSDL file, you can write programs that invoke and interact with the
web service.

12-4 Developer’s Guide

 Step 2: Browsing tModels

Note At this point you could use the Import WSDL button on the toolbar to
open the Import WSDL wizard. This wizard generates Java classes
from the WSDL. See “Step 4: Generating Java classes” on page 12-7.

Step 2: Browsing tModels

In this step, you’ll find all the tModels that begin with the uddi-org name.
TModels are references to a technical specification of a service. UDDI uses
tModels to point to the specification, instead of holding all the data within
the registry. Each tModel has a unique identifier called a Universal
Unique Identifier (UUID). UDDI assigns these identifiers when a web
service is first published. Applications and programmers who develop
them use this UUID to access information about the specification for a
web service.
1 Expand the Microsoft node in the UDDI Sites tree and choose the
tModel List node in the tree to display the Query For tModel page.
2 Enter uddi-org in the Find By Name field to find all tModels of this type
at the Microsoft site.
3 Click the Execute button to execute the query.
4 Expand the tModel List node and notice the different categories for
uddi-org, such as http, types, publication, ftp, fax, taxonomy, and so on.
5 Choose the second, not the first, uddi-org:http node at the bottom of the
list. You see from the description that this tModel describes a web
service that is invoked through a web browser and/or the http
protocol.

6 Click the Categories tab to see how this tModel is categorized. This
tModelType has a keyValue of transport.

Tutorial: Using the Web Services Explorer 12-5

Step 3: Finding software publishers at the Microsoft UDDI site

7 Choose uddi-org:publication node. Read the Overview Document

Description field on the Overview page for a description of the tModel:
“This tModel defines the publication API calls for interacting with the
UDDI registry.” Notice also that the overview document URL links to a
WSDL file. This WSDL file defines the publication API calls for
interacting with the UDDI Business Registry. If you cut and paste the
overview document URL into an XML-compliant web browser, such as
Internet Explorer, you’ll see the defined calls.
8 Click the Categories tab. This tModelType has four KeyValues and
points to four specifications: specification, xmlSpec, soapSpec, and
wsdlSpec.

Step 3: Finding software publishers at the Microsoft UDDI site

Next, you’ll use a category search to find all the software publishers at the
Microsoft UDDI site.
1 Select the Microsoft Business List node to display the Query For
Business page.
2 Choose the Category tab.
3 Choose ntis-gov:naics:1997 from the KeyName drop-down list. The
North American Industry Classification System (NAICS) is an
industrial classification system that has replaced the U.S. Standard
Industrial Classification (SIC) system. Notice that the TModelKey field
is filled out automatically.
4 Enter 51121 in the KeyValue field. This is the NAIC code for software
publishers.

5 Press Enter to commit the value.

6 Click the Execute button to execute the query.

12-6 Developer’s Guide

 Step 4: Generating Java classes

7 Expand the Business List node to see the results of the query.
8 Select a business in the list and choose the Categories tab. One of the
categories should be software publisher with a KeyValue of 51121.
Notice that businesses often have multiple categories.
9 Expand the IBM Corporation node and select Buy From IBM.
10 Choose the Categories tab on the Business Details page to see how IBM
is categorized. Because IBM is such a large company with a wide range
of products, it’s registered under several categories called KeyNames.
Notice that many of the KeyNames begin with NAICS and UNSPSC
(Universal Standard Products and Services Classification), which are
different classification systems. Each KeyName has a corresponding
unique tModelKey and KeyValue.

Step 4: Generating Java classes

JBuilder provides the Import WSDL wizard to quickly generate Java files
from an existing WSDL file. A WSDL file, Web Services Description
Language, describes a web service interface and the XML messages that
go in and out of the web service. TModels may point to a WSDL
description, which is written in XML.
In this step, you’ll create a project, search for a web service with the Web
Services Explorer, and use the Import WSDL wizard to generate Java
classes from the WSDL file for the web service.
1 Choose File|New Project to open the Project wizard and create a new
project.
2 Enter WsdlToJava in the Name field and click Finish.
3 Choose Tools|Web Services Explorer to open the Web Services
Explorer, if it’s not already open.
4 Return to the XMethods node in the tree and expand the XMethods
Business List node.
5 Expand the XMethods node under the Business List node.
6 Choose the web service, eBay Price Watcher.
7 Continue navigating down the eBay Price Watcher node and select the
last node, the tModel node. If the tModel node is selected, the WSDL
field in the Import WSDL wizard is automatically filled out with the
correct WSDL file for that service. The tModel node must be selected to
use the Import WSDL wizard, since it has the WSDL file listed in the
Overview Document URL field.
8 Click the Import WSDL button on the toolbar to open the Import WSDL
wizard or choose File|Import WSDL. Notice that the correct WSDL file

Tutorial: Using the Web Services Explorer 12-7

Step 4: Generating Java classes

is automatically entered in the WSDL URL field. The wizard inserts this
WSDL found in the Overview Document URL field in the tModel
details.

9 Choose the options you want and click Next.

10 Accept the default package name, which is based on the
targetNameSpace, and click Finish.
Java classes are generated in a package node in the project pane. The
Import WSDL wizard generates Java classes from the WSDL. It
generates a package name based on the WSDL’s target namespace or
one that you specify. It also adds the necessary libraries to the project.
11 Return to the Web Services Explorer and highlight the URL for the
WSDL file in the Overview Document URL field.
12 Copy and paste the URL into an XML-compliant browser, such as
Internet Explorer, to open the WSDL file. Here you’ll see the methods
used to access the web service.

See also
• Chapter 5, “Working with WSDL”
• Chapter 10, “Tutorial: Generating a web service from a WSDL
document”
• Chapter 9, “Tutorial: Generating Java classes from a WSDL file”
Congratulations! You’ve completed the tutorial.

12-8 Developer’s Guide

 Step 4: Generating Java classes

The Web Services Explorer also includes these additional features:

• Publishing web services
• Browsing Axis servers for web services
• Browsing web services with WSIL documents
• Monitoring UDDI messages
To learn more about the Web Services Explorer and its additional features,
see Chapter 8, “Browsing and publishing web services.”

Tutorial: Using the Web Services Explorer 12-9

12-10 Developer’s Guide
 Index
A Details page 8-14
developer support 1-4
accessPoint 8-4 documentation conventions 1-2
Apache Axis 3-3 Macintosh-specific 1-4
deploying to 6-1 platform conventions 1-3
Apache SOAP 3-3 D-U-N-S ID 8-11
deploying to 6-1
architecture 2-1 E
Axis servers
disabling and enabling remote access 8-16 EJB
publishing services 8-22 exporting as web service 7-1
searching for web services 8-14 web services 7-1
web services 8-5 Envelope element 3-1
Axis, Apache 3-3 Export Class As A Web Service wizard 5-2, 5-3

B F
BabelFish web service 10-1 fonts
Binding Details page 8-14 documentation conventions 1-2
Borland
contacting 1-4 I
Borland Online 1-5
identifier 8-4, 8-11
Borland Web Services Kit for Java 2-4
Import WSDL wizard 5-2
See also web services
Web Services Explorer 8-23
Build page, Project Properties
SOAP tab 3-5
Business Details page 8-14 J
businessKey 8-4 J2EE
web services 7-1
C Java classes
generating from WSDL 5-2, 9-1, 10-1
category 8-4, 8-9
publishing as web service 5-2, 5-3, 11-1
class file
JavaBean
publishing as web service 5-2, 5-3
publishing as web service 11-1
contacting Borland 1-4
JSEE
newsgroups 1-5
Web Services Explorer 8-1
World Wide Web 1-5
Copy Admin/Console To WebApp option 3-3
creating K
BabelFish web service 10-1 keyName 8-4
SOAP server 9-1, 10-1 keyValue 8-4

D M
deploy.wsdd file 5-2, 6-1 Macintosh
regenerating 3-5 support 1-4
deploying monitoring
to a SOAP server 6-1 SOAP messages 4-1
web service 6-1 UDDI SOAP messages 8-23
detail pages
Web Services Explorer 8-13

Index I-1
N T
newsgroups 1-5 TCP Monitor 4-1
Borland 1-5 technical support 1-4
Thomas Register 8-11
O TModel Details page 8-14
TModel Instance Details page 8-14
online resources 1-5 tModelInstance details 8-4
operator sites 8-4 tModelKey 8-4
overview document URL 8-4 tModels 8-4
publishing 8-21
P searching 8-12
toolkit node, SOAP 3-1
publishing
tutorials
Java class as web service 5-2, 5-3
creating BabelFish web services 10-1
services from Axis servers 8-22
creating web service 9-1, 10-1
tModels 8-21
export class as web service 11-1
web services 8-20
import WSDL 9-1, 10-1
publishing bean as web service 11-1
Q Web Services Explorer 12-1
queries
Web Services Explorer 8-13 U
UDDI 2-4
R JSEE 8-1
Regenerate Deployment At Build Time option 3-5 monitoring messages 8-23
runtime configurations operator sites 8-3, 8-4
for a SOAP server 3-4 overview 8-2
terms and definitions 8-3
S UDDI Business Registry 8-3
UDDI Message Monitor 8-23
server-config.wsdd file 3-5 UDDI registries 8-2
Service Details page 8-14 publishing from Axis servers 8-22
serviceKey 8-4 publishing services 8-20
Simple Object Access Protocol (SOAP) 2-2, 3-1 publishing tModels 8-21
See also SOAP searching with Web Services Explorer 8-7
SOAP 3-1 Universal Description, Discovery and Integration
Apache toolkit 3-3 (UDDI) 2-4
build option in Project Properties 3-5 See also UDDI
monitoring messages 4-1 Usenet newsgroups 1-5
monitoring UDDI messages 8-23
selecting a toolkit 3-3 W
server-config.wsdd file 3-5
toolkit node 3-1 web services 2-1
SOAP (Simple Object Access Protocol) 2-2 Borland Web Services Kit for Java 2-4
See also web services business categories 8-9
SOAP server 3-1 business identifiers 8-11
creating 9-1, 10-1 creating 9-1, 10-1
deploying to 6-1 deployment descriptor 5-2, 6-1
relationship to webapp 3-1 EJBs 7-1
runtime configuration 3-4 generating from WSDL 5-2, 9-1, 10-1
starting 3-4 J2EE 7-1
SOAP Server wizard 3-1, 3-2 overview 2-1
SOAP toolkit publishing 8-1, 8-20
selecting 3-3 publishing Java class as 5-2, 5-3
publishing tModels 8-21

I-2 Developer’s Guide

 registering 8-1 searching for businesses 8-7
searching 8-1, 8-12 searching for services 8-7, 8-11
SOAP (Simple Object Access Protocol) 2-2 searching for tModels 8-12
technologies 2-2 searching WSIL 8-17
UDDI 2-4, 8-2 tutorial 12-1
Web Services Explorer 8-1 UDDI query results 8-13
WSDL 5-1 WSIL 8-5
WSDL (Web Services Description Web Services Inspection Language (WSIL) 2-4, 8-5
Language) 2-3 See also WSIL
WSIL 2-4, 8-5 WebApp
Web Services Description Language (WSDL) 2-3, hosting SOAP server 3-1
5-1 wizards
See also WSDL Export Class As A Web Service 5-2, 5-3
Web Services Explorer 8-1 Import WSDL 5-2
adding nodes 8-5 Import WSDL wizard 8-23
Axis servers 8-5 SOAP Server 3-1
browsing services 8-1 WSDD file 5-2, 6-1
deleting nodes 8-5 regenerating 3-5
detail pages 8-13 WSDL 5-1
Import WSDL wizard 8-23 generating from a Java class 5-2, 5-3
JSEE 8-1 importing 5-2
publishing from Axis servers 8-22 WSDL (Web Services Description Language) 2-3
publishing tModels 8-21 See also web services
publishing web services 8-20 WSDL file
registering services 8-1 importing 9-1, 10-1
searching Axis servers 8-14 WSIL 2-4
searching by business name 8-7 searching for web services 8-17
searching by category 8-9 WSIL (Web Services Inspection Language) 8-5
searching by identifier 8-11

Index I-3