The Java Web Services Developer Pack

The Web services approach greatly simplifies B2B collaboration and provides a new model for the way businesses share their data and systems. In the Web services model, the Internet is leveraged to present a wide array of services, that is, self-contained modules of business function, that can be discovered and used on demand. As the following figure shows:

1. After creating and deploying one or more of its services ...
2. A business registers those services in a registry on the Internet. The registry contains information about the service and points to additional information.
3. Another business, through an application program, can then discover a needed service by searching the registry. The Web services model supports standard registries such as business registries that conform to UDDI or ebXML.
4. Using the information it discovers in a UDDI registry, a business application locates the appropriate server that runs the Web service. The application also locates a service definition that describes, among other things, how to make requests to the service. Using an ebXML registry involves the exchange of business profile information between the Web service provider and the Web service requester. After the exchange, the two parties agree on a business arrangement. The requester then locates and uses the Web service according to the business arrangement.

Here are some important things to consider about this approach:

It's based on standards

The entire Web services approach is based on a set of standard protocols and technologies, so that all participating components understand how to communicate. For example, service discovery in a UDDI registry uses a standard messaging protocol called SOAP. Service definitions follow a Web service description standard called WSDL. And the transactions that involve the exchange of business profiles follow ebXML Messaging standards. The bottom line is that companies no longer have to work out special, proprietary agreements regarding how to communicate requests between their systems, and what the communicated information means.

It offers advantages to service providers and clients

In the big picture, the Web services model offers advantages to Web service providers and the clients that use the services. Web service providers can use the Internet to market their services to a potentially huge set of possible clients. For clients, it can mean quicker and more flexible application development. Instead of creating large applications that include all necessary logic and data, developers can create smaller applications that access needed functions through Web services. For example, instead of including credit card transaction processing functions in an online retail application, an application can access a Web service that provides those functions. Clients can search for registered services that meet their requirements, select the best one, and use it. It doesn't matter where the Web service is located on the Internet -- as long as the Web service is registered, it's available to clients. In other words, the entire World Wide Web is potentially available to satisfy the service requirements of a client.

In addition, a Web service can locate and use other Web services. For example, the credit card transaction Web service can access a Web service that tracks credit history.

Java technologies and tools for Web service providers and clients are available

Recently, Sun Microsystems made available through its Early Access Release Program the Java Web Services Developer Pack (WSDP), Early Access Release 1, a package of technologies and tools for building and testing Web services using the Java programming language, and for building and testing Java applications that access Web services.

This article is the first in a series that describes the Java WSDP. The series highlights the technologies and tools included in the Java WSDP, and shows how you can use those technologies and tools to build Web services and applications that access Web services. This first article focuses on registration, in particular, the Java API for XML Registries (JAXR) API, an API in the Java WSDP that you can use to register a Web service. Later articles in the series will focus on other components of the Java WSDP. However before describing JAXR, let's look at some fundamental technologies that drive the Web services model -- especially those that are specifically pertinent to registration. The Java technologies in the Java WSDP support these fundamental Web services technologies. For example, the JAXR API can be used to access standard registries such as those that conform to UDDI or ebXML. A business can use the JAXR API in a Java program to register its Web services in a standard registry, or search for Web services that are registered in standard registries.

If you're familiar with XML and the XML-based technologies that are fundamental to the Web services model, skip to Java Technologies and Tools for Web Services. Otherwise see Web Services Technologies to learn about XML and the XML-based technologies for Web services.

Web Services Technologies

One of the things that makes the Web services model so attractive is that it's built on standard technologies, especially Extensible Markup Language (XML) technologies, that have wide industry acceptance. These technologies make for an "open" environment, ensuring that a Web service can be located and used, no matter where it is, what platform it runs on, or who developed it.

This section describes XML and the following XML technologies that are pertinent to registration and the JAXR API:

• Universal Description, Discovery, and Integration (UDDI)
• Simple Object Access Protocol (SOAP)
• Electronic Business XML (ebXML)

Future articles in this series will cover other important XML-based technologies that are part of the Web services model, such as the Web Services Description Language (WSDL).

XML

XML is emerging as the standard for exchanging data on the Internet. There are a number of reasons for this, some of which are:

XML is relatively easy to learn, especially for people who know HTML

In fact, XML and Hypertext Markup Language (HTML) have the same ancestry: Standard Generalized Markup Language (SGML). SGML is an international standard for defining the structure of electronic documents. These include Web-based and non-Web-based documents. SGML is functionally rich but complex. HTML is a small, simple application of SGML that defines the structure of the type of document you typically see on the Web -- that is, one with paragraphs, lists, tables, graphics and so on. XML is a more ambitious application of SGML. It allows you to define your own type of documents (to learn more about that, see XML is extensible).

For people who know HTML, a language whose use is pervasive across the Web, learning XML tends not to be a major obstacle. Like HTML, XML involves the use of tags that "mark up" the contents of a text file, (notice that the "M" in HTML, XML, and SGML stands for Markup) however the objective of the markup differs. HTML tags are designed for presentation. They instruct an application that can interpret the tags, such as a Web browser, how to display information. For example, the following HTML markup instructs the interpreting application to:

• Display the first line as a heading.
• Put the next few lines in a paragraph.
• Put the last three lines in a numbered list.

<h4>This is a heading</h4>
<p>This is a paragraph.
Here's the second line of the paragraph.
Here's the end of the paragraph.
</p>
<ol>

<li>The first item</li>
<li>The second item</li>
<li>The last item</li>
</ol>

And here's the displayed result. (Note that the box around the output is simply to set it off from the text in this article. The previous HTML tags do not create the box, although you can display a box like this using HTML tags.)

XML describes the content of a document

An XML tag identifies information in a document, and also identifies the structure of the information. Applications capable of interpreting these tags can then process the information according to the meaning of the information and its organization.

For example, the following XML markup identifies some information. The information is identified as bookshelf. The XML markup also describes the structure of bookshelf. The bookshelf structure includes two subordinate items identified as book. Each book has three subordinate items identified as title, author, and price.

<bookshelf>
   <book>
      <title>My Life and Times</title>
      <author>Felix Harrison</author>
      <price>39.95</price>
   </book>

   <book>
      <title>Travel Tips for the Frugal</title>
      <author>Juan Arellaga</author>
      <price>25.00</price>
   </book>
</bookshelf>

Although tags such as <book> and <title> might appear to inherently give meaning to the information they identify, they really don't. Information tagged with XML tags has meaning only if people associate a particular meaning with a particular tag. If people (1) agree on a meaning, say that the <book> tag is used to identify a book, and that <title>,<author>, and <price> tags identify the title, author, and price of the book, respectively, and (2) use those tags consistently, it gives people a way to exchange data. Their applications can send XML documents to each other, and process the information in those documents, relying on the commonly understood meanings associated with the XML tags.

XML documents have a well-formed structure

Notice that in the previous example, each XML tag has an ending tag. For example, <bookshelf>...</bookshelf>. This is a requirement in XML. Another requirement is that a tag that begins within another tag must end before the end of the other tag, and must be completely nested within that other tag. So that </title>, </author>, and </price> all come before </book>, and in that relative order. XML does allow for empty tags, that is, tags that have nothing between the opening and closing of the tag. For these tags, you can use a shorthand notation. For example, instead of coding an empty tag like this:

<emptytag></emptytag>

You can code it like this:

<emptytag/>

These requirements are part of set of requirements that must be met to make an XML document "well-formed". To be valid, an XML document must be well-formed. Because valid XML documents must be well-formed, it makes it easier to create programs that process XML documents.

The structure within an XML tag is consistent

An important requirement for effective data interchange, that is, in addition to having a consistently understood meaning associated with an XML tag, is the consistent structure of an XML document. Structural consistency can mean that an XML document is well-formed. However, it can also mean that the structure inside of an XML tag is consistent. For example, it might mean that an application can rely on the fact that any time a <book> tag is specified, <title>, <author>, and <price> tags are specified within the <book> tag. XML provides for this latter type of structural consistency through schema specifications.

XML is extensible

A schema specifies the "grammar" for an XML document. In other words, it specifies what tags are allowed in the document, the structure of those tags, and other rules about the tags, such as what type of data is expected in a tag (or no data if it's an empty tag). A schema is typically specified in a Document Type Definition (DTD). A DTD however is optional. There are other mechanisms to specify a schema. Additionally, you don't have to specify any grammar at all. In that case, the XML document is relatively unconstrained. It can include any tags -- you can even define your own tags. In this way, XML (unlike HTML) allows you to define your own type of document. However, whatever type of document you define, it still needs to be well-formed. This ability to define your own tags means that XML is extensible (remember that the X in XML stands for extensible).

A DTD specification for the bookshelf tag would look something like this:

<!ELEMENT bookshelf(book)+>
<!ELEMENT book(title, author, price)>
<!ELEMENT title(#PCDATA)+>
<!ELEMENT author(#PCDATA)+>
<!ELEMENT price(#PCDATA)+>

The specification says that there is an "element" named bookshelf. (Formally, each unit in an XML document is an element.) The bookshelf element contain at least one book element (the + means that there can be more than one). Each book element contains a title, author, and price element. The #PCDATA specification means that the data supplied with the title, author, and price elements is character data that must be parsed.

If people agree to use the same schemas in addition to agreeing on consistent meanings for XML tags, it makes the use of XML an effective way to exchange data. And, in fact, many areas of business are agreeing to agree. For example, there already are DTDs available for many business areas, and businesses within these areas are starting to converge on the use of those DTDs for data interchange.

UDDI

XML is an effective way to exchange data, but how is it used specifically in Web services? One way is to identify a Web service in a registry so that a program looking for a Web service can easily find it and understand what it does. A large consortium representing a wide variety of industries has developed specifications for Web service registration. This cross-industry effort is called the Universal Description, Discovery, and Integration (UDDI) project. The UDDI specifications are becoming one of the generally adopted standards for Web services. The consortium has also implemented the UDDI specifications in a UDDI Business Registry, and it makes the Business registry available to the public for businesses to register their Web services. (UDDI is not the only standard that is commonly used for Web services registration. Another approach that is generally adopted for Web services is ebXML.)

Think of a UDDI registry as a "Yellow Pages" for Web services. Like the Yellow Pages directory for phone numbers, a UDDI registry provides simple information about:

• Who it is. A registration includes the name of the Web service provider, and can include additional identifiers such as a North American Industry Classification System (NAICS) code or a Dun & Bradstreet D-U-N-S number.
• What it is. A registration includes the name of a Web service and, typically, a brief description.
• Where it is. A registration contains "binding templates" that point to an address where the service can be accessed.
• How to request it. A registration contains "tModels" that describe the interface for the Web service.

Each registry that conforms to UDDI is operated at its own site (the UDDI specifications refer to this as the "operator" site). The operator site contains the master copy of its registry. However, the collection of UDDI registries is replicated. If a business searches for a Web service in a registry at one operator site, the search is done across the information in the master copy, including the information replicated from the other UDDI registries.

The UDDI specifications define how to publish and discover information about Web services in a UDDI-conforming registry. More specifically, the specifications define a UDDI schema and a UDDI API. The schema identifies the types of XML data structures that comprise an entry in the registry for a Web service. The API describes the SOAP messages that are used to publish an entry in a registry, or discover an entry in a registry.

UDDI Schema

The UDDI schema identifies the types of XML data structures that comprise an entry in the registry for a Web service. The following figure illustrates the schema. It shows the five types of XML data structures that comprise a registration.

Click image to enlarge

businessEntity. This structure represents all known information about a business or entity and the services that it offers. (The reference to "entity" means that an entry in a UDDI registry does not necessarily have to be for a business. It could be for other types of enterprises such as schools or research institutions.) From an XML standpoint, a businessEntity is the top-level data structure that holds descriptive information about a business or entity. A businessEntity element contains attributes that:

• Uniquely identify the businessEntity (businessKey). The key is a Universal Unique Identifier (UUID) that is generated by the registry. The mechanism that produces UUIDs guarantees uniqueness through a combination of hardware addresses, timestamps and random numbers.
• Name the individual who published the businessEntity data (authorizedName)
• Specify the UDDI registry site that manages the master copy of the businessEntity data (operator)

Other elements within the structure identify the name recorded for the business or entity (name), and optionally specify additional information about the business or entity, such as its:

• Description (description)
• List of contacts (contacts)
• List of services offered (businessServices)
• List of identifiers that can be used in a search (identifierBag)
• One or more category designations, such as an industry designation or a geographic designation (categoryBag).

Here is an example that shows part of a complete BusinessEntity structure for a hypothetical company named BooksToGo. The company provides various Web services, including an online book ordering service.

<businessEntity businessKey="35AF7F00-1419-11D6-A0DC-000C0E00ACDD"
authorizedName="0100002CAL" 
  operator="www-3.ibm.com/services/uddi">
<name>BooksToGo</name>
<description xml:lang="en">
   The source for all professional books
</description>
<contacts>
<contact>

<personName>Ramesh Mandava</personName>
<phone>
  (877)1111111
</phone>
</contact>
</contacts>

businessService. This structure identifies a service provided by the business or entity that is represented by the parent businessEntity. A business or entity can provide multiple services, so there can be multiple businessService elements within a businessEntity. The set (or "family") of businessService elements are specified in a businessServices structure.

Here is an example that shows part of a complete businessService structure for an online book ordering service offered by BooksToGo. Notice especially the categoryBag element, which is used to specify a classification scheme (formally this is known as a "taxonomy"). In this example, the taxonomy is NAICS.

<businessServices>
<businessService serviceKey="
  2AB346C0-2282-43B0-756B-0003CC35CC1D">

<name>Online Book Ordering</name>
<description xml:lang="en">
  Ordering books online
</description>
<categoryBag>
  ntis-gov:naic
<catgeoryBag>  

bindingTemplate and tModel. A bindingTemplate in tandem with a tModel provides two important pieces of information about a Web service: its technical specification and its accessPoint. A technical specification (also called a "technical fingerprint") typically provides details about things such as protocols and interchange formats used in communicating with the service. The accessPoint is an address, such as a URL or email address, at which the service can be called. Contained within a bindingTemplate structure is a tModelInstanceInfo element that references a tModel by its key. The referenced tModel provides the technical specification.

There can be multiple bindingTemplate elements for the family of services identified in a businessServices structure. As you might guess, the multiple bindingTemplate elements are specified in a bindingTemplates structure.

Here is an example that shows part of a complete bindingTemplate structure for the online book ordering service offered by BooksToGo. Notice the reference to the tModelKey in the tModelInstanceInfo element.

<bindingTemplates>
<bindingTemplate bindingKey="
  4BC7C340-2398-12E6-887C-0005AC33CC2D"
<description>
  JAXRPC (SOAP/HTTP ) based binding
</description>  
<accessPoint>
  http://www.BooksToGo.com:8080/books/

</accessPoint>

<tModelInstanceDetails>
<tModelInstanceInfo tModelKey="UUID:
  36E13526-4553-3265-B5F7-C4B522E75A05" />
</tModelInstanceDetails>

publisherAssertion. This structure is used as a way of asserting a relationship between one businessEntity and another. For example, the structure can be used to show that two business are subsidiaries of the same company. To assert the relationship, each of the two businessEntity structures specifies its own publishAssertion structure. However the information in each structure needs to be exactly the same.

Continuing with the BooksToGo example, let's assume that it has no relationship that it needs to assert.

UDDI API

The UDDI API describes the Simple Object Access Protocol (SOAP) messages that are used to publish an entry in a registry (the "Publish" API), and those that are used to discover an entry in a registry (the "Inquiry" API).

Publish API. There are a variety of messages defined in the Publish API. What they have in common is that they perform some action related to one of the types of structures that comprise the UDDI schema. For example, the Publish API message save_business is used to save or update one or more complete businessEntity structures in a registry. Similar messages are available to save or update one or more complete businessService structures (the message is save_service), bindingTemplate structures (save_binding), and tModel structures (save_tModel). A slight variation is the set_publisherAssertions message, which is used to manage all of the assertions associated with an individual publisher.

Here, for example, is a message that saves the businessService structure (named Online Book Ordering) that you saw previously in the description of the UDDI schema. Notice the authinfo element. It is used to specify an authentication token. This is a value that is a standard part of UDDI's authentication mechanism and needs to be specified in all Publisher API calls. You obtain the authentication token by issuing a call to get_authToken.

<save_service generic="2.0" xmlns=um:uddi-org:api-v2">
<authinfo>authentication token goes here ...</authinfo>
<businessServices>
<businessService serviceKey="
  2AB346C0-2282-43B0-756B-0003CC35CC1D">
<name>Online Book Ordering</name>
<description xml:lang="en">

  Use this service to purchase books over the Web
</description>

In addition to messages that save or update UDDI structures in a registry, the Publish API also defines messages that delete these structures. For example, the delete_service message deletes a businessService structure.

Inquiry API. The Inquiry API contains two types of messages: "find" messages that search UDDI registries for entries that meet specified search criteria, and "get" messages that retrieve detailed information about a specified registration. For example, you use the Inquiry API message find_business to search for all registered business entities that meet search criteria specified in the call. Here, for example, is a find_business message that searches for all business entities whose registered name begins with the characters "Books":

<find_business generic="2.0" xmlns=um:uddi-org:api-v2">
<name>Books%</name>
</find_business>

The call returns a businessList structure that contains information about each matching business, and summaries of the businessService elements exposed by those businesses. Similar messages exist to search for services within a registered businessEntity (find_service), bindings within a registered businessService (find_binding), and tModels (find_tModel). You can also search for businessEntity registrations that are related to a specific business entity (find_relatedBusinesses).

The "get" messages include those that return detailed information about one or more business entities (get_businessDetail and get_businessDetailExt), business services (get_serviceDetail), bindingTemplates get_bindingDetail), and tModels get_tModelDetail.

Here, for example, is a get_serviceDetail message that returns detailed information about the Online Book Ordering service. Notice how the serviceKey value is used to identify the service.

<get_serviceDetail generic="2.0" xmlns=um:uddi-org:api-v2">
<serviceKey>"2AB346C0-2282-43B0-756B-0003CC35CC1D"</name>
</get_serviceDetail>

SOAP

Though agreeing on the meaning and structure of XML tags makes the use of XML an effective way to exchange data, it's not sufficient for data interchange over the Web. For instance, you still need some agreed-upon protocol for sending XML documents across the Web so that the receiver understands what it's getting, and what to do in response. That's where Simple Object Access Protocol (SOAP) comes in. SOAP is a XML-based protocol for exchanging information in a distributed environment. It's a major underpinning of the communication mechanism for Web services. For example, you register a Web service in a UDDI registry using the SOAP protocol. You also use the SOAP protocol to look for a Web service in a UDDI registry, and once you find the service, you use the SOAP protocol to request it.

Like UDDI, SOAP is XML based. Also, like UDDI, SOAP is a generally accepted standard for Web services. The reason for SOAP's widespread adoption is its simplicity. SOAP is "lightweight," that is, it involves a relatively small amount of code, and it's fairly easy to understand. The basic item of transmission in SOAP is the SOAP message, which consists of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body.

Here is an example of a SOAP message, designed to retrieve the current price of a stock. Specifically, the SOAP message makes a request to GetLastTradePrice, passing it a symbol DEF. GetLastTradePrice is an operation performed by a Web service, and DEF is the symbol for a specific stock. Clearly, for the request to be satisfied, GetLastTradePrice needs to be described, and its description needs to specify that the operation takes a stock symbol as input and returns a stock price as output. This is not done in SOAP. Instead it's done through Web Services Description Language (WSDL), an XML-based language for describing a Web service. A WSDL description for a Web service is contained in a WSDL document for the service. For the purposes of this example, assume that a WSDL document exists for a Web service, and in that document, the GetLastTradePrice operation is appropriately defined. Later articles in this series will cover WSDL in more depth.

<SOAP-ENV: Envelope
  xmlns:SOAP-ENV=
    "http://schemas.xmlsoap.org/soap/envelope/"
  SOAP-ENV: 
    encodingStyle=
      "http://schemas.xmlsoap.org/soap/encoding/">
        <SOAP-ENV:Header>
           <t:Transaction xmlns:t="some-URI">
              SOAP-ENV:mustUnderstand="1"> 
                  5
           </t:Transaction>

        </SOAP-ENV:Header>
        <SOAP-ENV:Body>
           <m:GetLastTradePrice xmlns:m="some-URI">
              <symbol>DEF</Symbol>
           </m: GetLastTradePrice>

        </SOAP-ENV:Body>
</SOAP-Envelope>

Envelope. The Envelope element is the top element of the envelope. In this example, the Envelope element specifies two things: an XML namespace and an encoding style. An XML namespace is a collection of names that can be used in XML element types and attribute names, in other words, it's an XML schema. The example points to the URI http://schemas.xmlsoap.org/soap/envelope. This URI defines the XML schema for SOAP messages.

The encodingStyle attribute identifies the encoding style. An encoding style identifies the data types recognized by SOAP messages, and specifies rules for how these data types are serialized (that is transformed into a stream of bytes) for transport across the Web. The example points to the URI http://schemas.xmlsoap.org/soap/encoding/. This URI specifies the encoding style for "Section 5" encodings, the ones described in Section 5 of the SOAP specification.

Header. As mentioned earlier, the header is optional. However, if it's included in a SOAP message it must be the first child of the Envelope element. The Header element, through attributes, extends the SOAP message in a modular way. It's important to understand that a SOAP message travels from an originator (a client application) to a final destination, potentially passing through a set of intermediate nodes along the message path. Each node is an application that can receive and forward SOAP messages. The SOAP header can be used to indicate some additional processing at a node, that is, processing independent of the processing done at the final destination. In the example, the Header element indicates that this is a transaction (a URI specifies the namespace for the transaction). The header could just as easily have specified attributes for another type of process, such as authorization checking. The attribute value mustUnderstand=1 means that the initial node in the SOAP message path must process the header. The value 5 is passed to the initial node as input.

Body. You can think of the SOAP body as containing the main part of the SOAP message. In particular, the Body element contains information for the final recipient of the SOAP message. In the example, the Body element contains two items of information: GetLastTradePrice (with its namespace) and DEF. This information is passed to the final destination. The application at that destination needs to understand the request and take the appropriate action. As mentioned earlier, for the purposes of this example, assume that a WSDL document exists for a Web service, and in that document, the GetLastTradePrice operation is appropriately defined. Based on the information in the WSDL document, assume that the application calls the GetLastTradePrice operation, passing it the DEF ticker symbol as input. The WSDL document also indicates that the output returned by the GetLastTradePrice operation is a price. The returned price information is also passed in a SOAP message. The body of the response looks like this:

<SOAP-ENV:Body>
   <m:GetLastTradePriceOutput xmlns:m="some-URI">
           <price>42.50</price>
   </m: GetLastTradePriceOutput>
</SOAP-ENV:Body>

The ebXML framework is being developed by the ebXML initiative. This initiative is a joint project of the United Nations Centre for Trade Facilitation and Electronic Business (UN/CEFACT) and the Organization for the Advancement of Structured Information Standards (OASIS), and includes representation from an extremely wide set of businesses and other entities around the world (including standards bodies). The framework consists of a set of ebXML specifications, all of them XML based. A fundamental concept in ebXML is expressed in the following extract taken from one of the ebXML specifications (the Collaboration-Protocol Profile and Agreement Specification):

The exchange of information between two Parties requires each Party to know the other Party's supported Business Collaborations, the other Party's role in the Business Collaboration, and the technology details about how the other Party sends and receives Messages.

The way each Party can exchange information, in the context of a Business Collaboration, can be described by a Collaboration-Protocol Profile (CPP). The agreement between the parties can be expressed as a Collaboration-Protocol Agreement (CPA).

The CPP and CPA are typically stored in an ebXML registry. Let's examine each of these ebXML components:

Collaboration-Protocol Profile (CPP). The CPP is an XML document that contains information about a business (in ebXML terms, a business is referred to as a "Party") and the way it exchanges information with another Party. This can include information about who the Party is (for example, its name and contact information), the services it offers (ebXML calls these "business transactions"), its role in a business collaboration (for example, a "buyer" or "seller"), and details about the message transport it uses, and its security constraints. This information about a business's ebXML capabilities and constraints is also known as a "business profile". The CPP also points to a document called a "Business-Process Specification" that defines the interactions supported by the Party, in other words, the specifics of a collaboration that a Party is capable of.

Collaboration-Protocol Agreement (CPA). The CPA is an XML document that describes the specific capabilities that two Parties have agreed to use in a business collaboration. One way to look at a CPA is as an intersection of the CPPs for the two Parties that collaborate. A CPA contains the same type of information as a CPP, but for the two parties involved. This also includes the appropriate reference to Business-Process Specification. Essentially, a CPA is a contract between the two Parties in a collaboration. It describes the valid, enforceable interactions that can take place between the two parties as part of the collaboration.

ebXML Registry. An ebXML registry stores CPPs, CPA, and other information relevant to business collaboration. As is the case for UDDI, ebXML offers services to register and discover information about a business. However unlike a UDDI registry (which points to a WSDL document for a description of a Web service), an ebXML Registry actually contains the description of a business's service within its CPP and associated Business-Process Specification.

A high-level view of how these components are used for Web services is as follows:

1. Parties register their CPPs in an ebXML registry.
2. A Party (let's call it Party 1) searches the ebXML registry for a needed Web service. It finds that the needed service is provided by Party 2. The information is in Party 2's CPP in the ebXML registry.
3. Party 2 creates a CPA for a business collaboration with Party 1 and sends the CPA to Party 1.
4. Party 1 and Party 2 negotiate an agreement. Each stores a copy of the CPA in its server.
5. Party 1 finds and uses the Web service provided by Party 2 as part of the collaboration defined by the CPA.

One other thing to note about ebXML is that two Parties exchange information using the ebXML messaging standard. This standard is based on the SOAP standard. However it extends SOAP in important areas such as security (for example, it adds support for creating and verifying a digital signature) and reliable message handling. The ebXML messaging standard also conforms with the SOAP Messages with Attachments specification, itself an extension of SOAP that enables a user to send attachments with a SOAP message.

Java Technologies and Tools for Web Services

The content of a Web service, that is, its business logic, can be coded in any programming language. However, for reasons such as portability that make it ideal for application development, the Java programming language is also ideal for building Web services and developing applications that use Web services.

The Java WSDP provides a set of Java APIs and tools to help simplify building and using Web services in the Java programming language. These APIs and tools enable a Web service provider to use the Java language to do things such as register a Web service in a standard registry, and describe the interface to the service. For Web service requesters, the APIs enable Web service discovery and use from the Java platform. Both Web service providers and requesters can take advantage of tools in the Java WSDP package for testing. In addition, the Java WSDP provides components and tools for building Web applications (which can, if desired, request Web services).

The Java WSDP EA1 release includes the following Web service development-related APIs and tools. The APIs are also available separately (that is, without the Java WSDP tools) in the Java XML Pack. The APIs (in either package) are updated quarterly.

• APIs
  • Java API for XML Registries (JAXR) 1.0 EA 1. Use this API to publish a Web service in a registry such as a UDDI or ebXML registry, or search a registry for a Web service.
  • Java API for XML Messaging (JAXM) 1.0 EA 1. Use this API to construct and send messages that conform to XML-based messaging standards such as SOAP or ebXML messaging. APIs such as JAXR send messages using JAXM.
  • Java API for XML-based RPC (JAX-RPC) 1.0 EA 1. Use this API to make XML-based remote procedure calls (RPC calls) to invoke Web service-provided operations.
  • Java API for XML Processing (JAXP) 1.2 EA 1 (with XML Schema support). Use this API to process XML documents, for instance, XML documents returned as output by Web services.
• Tools
  • Java WSDP Registry Server 1.0 EA 1. This is an implementation of a UDDI registry that you can use as a test registry.
  • Tomcat Java Servlet & JavaServer Pages container 4.1-dev. This tool provides an environment for managing and executing servlets and JSP pages. It's provided in the Java WSDP to help you build and test services or Web applications that use these technologies.
  • JavaServer Pages (JSP) Standard Tag Library ("JSTL") 1.0 EA 3. This library provides a set of tags that you can use to perform commonly requested JSP operations, such as iterating over lists or specifying conditional actions. You can use these standard tags in various JSP containers, including the Tomcat Java Servlet & JavaServer Pages container.
  • Java Secure Socket Extension (JSSE) 1.0.2. This is a set of Java packages that enable secure Internet communications. It implements a Java version of SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols and includes functions for data encryption, server authentication, message integrity, and optional client authentication. JSSE 1.0.2 is included in Java WSDP to allow you to develop secure applications that use protocols such as SSL and TSL.
  • Ant Build Tool 1.4.1. Ant is a tool that you can use to to build a Java-based project. Ant is perfectly suited for building XML-based projects such as Web services applications. In fact, using Ant, you define project build operations in an XML file.

Let's focus on one of the Java APIs provided in Java WSDP -- the JAXR API.

JAXR

JAXR is a Java API that you can use to access standard registries such as those that conform to UDDI or ebXML.

JAXR is a Java API that you can use to access standard registries such as those that conform to UDDI or ebXML. However the intent is wider than that -- the JAXR specifications make it clear that the design goal of JAXR is to support other future registry standards. The JAXR API in the EA1 release of Java WSDP supports UDDI registries only. Support for ebXML Registries using the JAXR API is being developed in an open source project, see the OASIS ebXML Registry Reference Implementation Project (ebxmlrr) for details.

Clients and Providers

There are three roles that take part in issuing and handling requests made through the JAXR API: JAXR clients, JAXR providers, and registry providers. The JAXR API provides interfaces and classes for use by JAXR clients and providers. A JAXR provider implements the JAXR API. For example, the reference implementation of the JAXR API provided with the Java WSDP is a JAXR provider. A registry provider is an implementation of a registry specification, for instance, an actual UDDI or ebXML registry.

Here's how the roles interact:

Click image to enlarge

1. A JAXR client uses JAXR interfaces and classes to request access to a registry. The client sends the request to a JAXR provider.

2. When a JAXR provider receives a request from a JAXR client, it transforms the request into an equivalent request that is based on the specifications of the target registry. The JAXR provider then passes this transformed request to a registry provider.

3. The registry provider receives a request from a JAXR provider and processes it. The process is then reversed ...

4. The registry provider returns a response to the JAXR provider, which transforms it to an equivalent JAXR response.

5. The JAXR provider sends the JAXR response to the JAXR client.

JAXR Packages

The JAXR API comprises a number of packages. Two of the more important packages are javax.xml.registry.infomodel and javax.xml.registry.

• javax.xml.registry.infomodel. This package contains the interfaces that define the JAXR information model. The information model describes what types of objects reside in a registry and how the types of objects relate to each another. Some of the important interfaces in the package are:

  RegistryObject	This is the base class for the information model. It provides basic information about an object in a registry. It also provides methods for accessing related objects (such as Organization and Service objects).
  Organization	This is a RegistryObject that provides information about a business or other entity.
  Service	This is a RegistryObject that provides information about a Web service that is offered by a business or other entity identified by an Organization object. A number of different Service objects can be associated with a single Organization object.
  ServiceBinding	This is a RegistryObject that provides information about how to access a specific interface provided by a Service object. For example, a ServiceBinding might indicate that a specific operation offered by a Web service is accessed through SOAP over an HTTP connection. There can be multiple ServiceBinding objects defined for the same Service object.

  Notice the evident mapping between the interfaces in the JAXR information model and registry objects such as the data structures in the UDDI schema. For example, the JAXR interface Organization clearly maps to the UDDI businessEntity data structure. Similarly the Service interface maps to the businessService data structure, and ServiceBinding to bindingTemplate.

• javax.xml.registry. This package contains the interfaces and classes for access to a registry through a JAXR provider.

  ConnectionFactory	This is an abstract base class for factory classes that create a JAXR connection. Two important methods in ConnectionFactory are setProperties which is used to set the properties of a connection, and createConnection, which creates a connection.
  Connection	This class represents a connection between a JAXR client and a JAXR provider.
  RegistryService	This is the principal interface implemented by a JAXR provider. A registry client can get this interface through a Connection object. The RegistryService provides the methods that a JAXR client uses to discover various capability-specific interfaces implemented by the JAXR provider, such as the BusinessLifeCycleManager and BusinessQueryManager interfaces.
  LifeCycleManager	This interface provides methods to perform "life cycle" operations on information in the registry, as modeled by objects in the information model. For example, the method createOrganization creates a new Organization object, and the method createService creates a new Service object.
  BusinessLifeCycleManager	This is a subinterface of the LifeCycleManager interface. It provides a way to request life cycle management operations that mimic the UDDI interface. For example, the method saveOrganizations saves a collection of Organization objects in the registry, and the method deleteServices removes a collection of Service objects from a registry.
  BusinessQueryManager	This interface provides methods to query the registry. For example, the method findOrganizations searches the registry for all organizations that match criteria specified in the method call.

  The classes and interfaces in the javax.xml.registry package provide methods that map to registry messages, such as those defined in the UDDI API. For example, the saveOrganizations method in the LifeCycleManager interface maps to the UDDI Publish API message save_business, and the findOrganizations method in the BusinessQueryManager interface maps to the UDDI Inquiry API message find_business.

Let's look at these interfaces and classes in use, by examining a JAXR example.

A JAXR Example

In this example, a company named BooksToGo uses JAXR to register a Web service, and another company, BoomingBusiness.com, uses JAXR to discover the service. The example uses the IBM UDDI Business Test Registry, and the JAXR 1.0 EA 1 Reference Implementation.

BooksToGo operates a number of retail stores that sell books. Supplementing its store sales, BooksToGo also has a web site through which customers can order books online. Recently, BooksToGo decided to make available its online book ordering service as a Web service, that is, it decided to publicize the service in a business registry. BooksToGo uses the Java platform for a lot of its systems and applications, including its online book ordering application. As a result, the company sees the Java APIs in the Java WSDP as a natural choice to assist in implementing the Web service, especially for tasks such as registering the Web service. BooksToGo decides to use the Java WSDP for its online book ordering service.

BoomingBusiness.com is a company that provides a Web site to its employees. The Web site is a portal to a variety of employee services. For example, the site links to human resources-related information such as a list of H.R. contacts, employee tools such as a vacation planner, and other company-related material. BoomingBusiness.com would like to extend the portal to other types of services that employees have requested, for example, an online service for ordering books. The company decides to implement this extension as a Web services-based solution. In particular, BoomingBusiness.com plans to extend the portal so that when an employee requests a type of service, an underlying application program dynamically searches a business registry for services of that type. With this approach, the application can discover a variety of service offerings for any given type, and so employees can select from a wide variety of available services offerings. BoomingBusiness.com's IT staff further requires that the solution be platform independent, and not tied to a proprietary protocol. Based on the requirements, BoomingBusiness.com decides to implement the solution using the Java programming language and XML. It also decides to use Java WSDP to aid in building the solution.

BooksToGo Registers Its Online Book Ordering Web Service

BooksToGo uses the JAXR API in the Java WSDP package to register its online book ordering service as a Web service. It chooses to register the service in a UDDI registry. Here is how BooksToGo registers its online book ordering web service.

Step 1: Obtain authorization for updates to the registry

Registry providers typically require a user to have proper authorization in order to update the contents of a registry. This means that a user typically needs to obtain a user ID and password from the registry provider, and then supply this authorization information before attempting to do things like register a service. (Note that the Java WSDP Registry Server, which is an implementation of a UDDI registry, does not require a user ID and password for access.)

BooksToGo decides to initially register its services in a UDDI registry provided by IBM, the IBM UDDI Business Test Registry. So, BooksToGo initially gets the necessary user ID and password from the IBM UDDI Account Registration site.

Step 2: Connect to the registry provider

The BooksToGo application development staff begins working on a Java program that will be used for accessing and updating a registry. The first thing the progammers consider for the program is connecting to the registry.

Establish a Connection: To access a registry, a JAXR client needs to establish a connection with a registry provider. To do that, the client uses the createConnection method of the provider's ConnectionFactory class. Each registry provider can make available one or more ConnectionFactory classes that are configured in a specific way. If a registry provider does make a configured ConnectionFactory class available, it also needs to register it with a naming service such as one that is based on the Java Naming and Directory Interface (JNDI) interface. So a good way for a JAXR client to find a configured ConnectionFactory class is through JNDI.

The JAXR 1.0 EA 1 Reference Implementation provides a ConnectionFactory class. If a JAXR client uses the Reference Implementation to connect to a registry, the client needs to use the newInstance method in the ConnectionFactory class to create an instance of the object, for example:

ConnectionFactory factory = 
     ConnectionFactory.newInstance();

Set Properties for the Connection: A JAXR client can also specify properties for the connectionFactory object. Some of these properties are standard to JAXR, others can be defined by a JAXR provider. The standard properties are:

javax.xml.registry.queryManagerURL	This is a string that specifies the URL for the query manager service of the registry provider. This is the URL of the API for querying the registry.
javax.xml.registry.lifeCycleManagerURL	This is a string that specifies the URL for the life cycle manager service of the registry provider. This is the URL of the API for updating the registry.
javax.xml.registry.factoryClass	This is a string that is the fully-qualified class name for the ConnectionFactory class of a registry-specific JAXR provider. A registry-specific JAXR provider is a JAXR provider that implements the JAXR API in a registry-specific way, and plugs into a JAXR pluggable provider that implements features of the JAXR API in a registry-independent way.

To specify the properties, a JAXR client supplies them as parameters to the setProperties method of the ConnectionFactory:

Properties props = new Properties(); props.setProperty( "javax.xml.registry.queryManagerURL", "..."); props.setProperty( "javax.xml.registry.lifeCycleManagerURL", "..."); props.setProperty( "javax.xml.registry.factoryClass", "..."); factory.setProperties(props);

BooksToGo Connects: BooksToGo creates a ConnectionFactory object and specifies properties for it as follows. (Note that the URL strings for the property specifications are broken into multiple lines for presentation purposes. In a real program, you should not break these URL strings.)

import javax.xml.registry.*; ... String queryURL = "http://www-3.ibm.com/services/uddi/ testregistry/inquiryapi"; String publishURL = "https://www-3.ibm.com/services/ uddi/testregistry/protect/publishapi"; ... ConnectionFactory factory = ConnectionFactory.newInstance(); Properties props = new Properties(); props.setProperty( "javax.xml.registry.queryManagerURL", queryURL); props.setProperty( "javax.xml.registry.lifeCycleManagerURL", publishURL); props.setProperty( "javax.xml.registry.factoryClass", "com.sun.xml.registry.uddi. ConnectionFactoryImpl"); factory.setProperties(props); connection = factory.createConnection();

Step 3: Provide Authorization Information

As mentioned earlier, registry providers typically require a user to have proper authorization, in the form of a valid user ID and password, to update the contents of a registry. In particular, registry specifications such as UDDI require authentication for certain requests. For example, the UDDI specification requires that a UDDI registry authenticate requests that use UDDI's Publish API. In JAXR terms, this means that a UDDI registry provider needs to authenticate a request from an JAXR provider to do things like publish a Web service to the registry or remove a Web service registration.

Specify Credentials: JAXR provides a way to pass authentication information to a JAXR provider, and subsequently on to a registry provider. In JAXR, authentication information is passed as a set of credentials. The credential concept is the same as that used in the Java Authentication and Authorization Service (JAAS) that is part of the Java 2 Platform, Standard Edition (J2SE). To hold the credentials for registry access, a JAXR client needs to first create a PasswordAuthentication object. The PasswordAuthentication is in the java.net package in the Java 2 Platform. When the client creates the PasswordAuthentication object, it specifies the user name (as a string), and the password (as a character array):

import java.util.*; String userName = "..."; String password = "..."; PasswordAuthentication passwdAuth = new PasswordAuthentication( userName, password.toCharArray());

To set the credentials, a JAXR client uses the setCredentials method in the Connection object. The credentials are specified as a hashed set:

Set credentials = new HashSet();
  credentials.add(passwdAuth);
  connection.setCredentials(credentials);

BooksToGo Provides Credentials: BooksToGo provides its credentials as follows:

import java.util.*; ... String userName = "btguser"; String password = "btgpwd"; ... // Constructing Authorization Token PasswordAuthentication passwdAuth = new PasswordAuthentication(userName, password.toCharArray()); Set credentials = new HashSet(); credentials.add(passwdAuth); connection.setCredentials(credentials);

Step 4: Register the service

To register a service, a JAXR client needs to:

• Get the registryService.
• Use the registryService to get a LifeCycleManager.
• Use the LifeCycleManager to create objects for inclusion in the registry.

Get the registryService: In JAXR, all operational requests, such as publishing to a registry or querying a registry, are made using the registryService interface. What this means is that after it gets a connection, a JAXR client needs to get the registryService interface that is associated with that connection.

A client uses the getRegistryService method to get the registryService interface:

RegistryService rs = connection.getRegistryService(); 

Get the LifeCycleManager: After a JAXR client gets the getRegistryService interface, it uses it to make a specific registry request. In JAXR, the term "Life Cycle management" describes activities such as registering a business or updating a Web service registration, in other words, activities that typically require authentication. A JAXR provider implements an interface, LifeCycleManager that a JAXR client uses to request life cycle management activities such as creating new objects for inclusion in a registry. The LifeCycleManager interface presents a generic API. A LifeCycleManager subinterface, called the BusinessLifeCycleManager, provides a more business-oriented API. To get the interfaces, JAXR provides the getLifeCycleManager and getBusinessLifeCycleManager methods:

LifeCycleManager lifeCycleManager = rs.getLifeCycleManager(); BusinessLifeCycleManager businessLifeCycleManager= rs.getBusinessLifeCycleManager();

Create Objects for Inclusion in the Registry: The LifeCycleManager interface includes various factory methods, that create new objects for inclusion in a registry. These methods have the name createInterface, where Interface is the name of an interface in the JAXR information model. Some of these methods are:

• createOrganization
• createService
• createUser
• createPersonName
• createTelephoneNumber
• createEmailAddress
• createClassification

As mentioned previously, an Organization maps to a businessEntity data structure in a UDDI registry. Like a businessEntity, an Organization is associated with other information such as service offerings, contacts, and business classifications. This related information is contained in objects in the information model. The createInterface methods are used to create these objects. For example, the following code creates an Organization, and adds a description to it. Notice the method createInternationalString. This method creates a string that is internationalized to several Locales.

BusinessLifeCycleManager lifeCycleManager = null; ... Organization org = lifeCycleManager.createOrganization("MyBusiness"); InternationalString orgDesc = lifeCycleManager.createInternationalString( "An excellent business"); org.setDescription(orgDesc);

BooksToGo Registers: BooksToGo wants to register the following information for its business and its Online Book Ordering service:

Business Name	BooksToGo
Contact Information	Primary Contact: Ramesh Mandava Phone number: (877)1111111 Email Address: ramesh.mandava@BooksToGo.com
Classification Scheme (classification, code)	NAICS (Book Stores", 451211)
Service	Online Book Ordering
Service Binding	Description: JAXRPC (SOAP/HTTP) based binding Access Point: http://www.BooksToGo.com:8080/books/

To see how BooksToGo creates the Organization object and its related objects, look here.

Notice that before the classification is created, there's an extra step. BooksToGo first queries the registry to find the pertinent classification scheme (formally, this is known as a taxonomy) that it wants to use. (See Identifying a Taxonomy for more details.) In this case, the taxonomy is the North American Industry Classification System (NAICS). JAXR supplies a QueryManager interface and a subinterface, BusinessQueryManager, to query a registry. The BusinessQueryManager method findClassificationSchemeByName finds classification schemes in a registry based on a pattern supplied as a parameter to the call. BooksToGo is interested in the NAICS pattern: ntis-gov:naics.

Registration Program

Here is a sample application program that uses the JAXR API to publish the BooksToGo organization and its Online Book Ordering service in a UDDI registry. You can run this program, see Build and Run the Sample Programs.

Notice that the program also can be used to delete an organization from the registry. The delete request must include the organization's key. The program creates a Key object to hold the key and then passes it as part of a collection to the BusinessLifeCycleManager method deleteOrganizations:

javax.xml.registry.infomodel.Key key = lifeCycleManager.createKey( keyString); ... Collection keys = new ArrayList(); keys.add(key); BulkResponse response = lifeCycleManager.deleteOrganizations(keys);

BoomingBusiness.com Discovers the Book Ordering Web Service

BoomingBusiness.com creates an application that searches a registry for online book ordering services. It uses the JAXR API in the Java WSDP package to search a UDDI registry. Here is how BoomingBusiness.com does the search.

Step 1: Connect to the registry provider

BoomingBusiness.com's application program connects to the UDDI registry in the same way that BooksToGo does in its application program (see Step 2: Connect to the registry provider in the section BooksToGo Registers Its Online Book Ordering Web Service). The registry that BoomingBusiness.com searches does not require authorization for searches, so unlike BooksToGo, BoomingBusiness.com does not need a user ID and password for access to the registry.

BoomingBusiness.com creates a ConnectionFactory object and specifies properties for it. (Note that the URL strings for the property specifications are broken into multiple lines for presentation purposes. In a real program, you should not break these URL strings.)

import javax.xml.registry.*; ... String queryURL = "http://www-3.ibm.com/services/uddi/ testregistry/inquiryapi"; ... ConnectionFactory factory = ConnectionFactory.newInstance(); Properties props = new Properties(); props.setProperty( "javax.xml.registry.queryManagerURL", queryURL); props.setProperty( "javax.xml.registry.factoryClass", "com.sun.xml.registry.uddi. ConnectionFactoryImpl"); factory.setProperties(props); connection = factory.createConnection();

Step 2: Search the registry

To search a registry for a service, a JAXR client needs to:

• Get the registryService.
• Use the registryService to get a QueryManager.
• Use the QueryManager to issue search requests.

Get the registryService: Just as BooksToGo does for publishing its Web service, BoomingBusiness.com needs to get the registryService interface before it can request operations on the registry (see Step 4: Register the service in the section BooksToGo Registers Their Online Book Ordering Web Service).

RegistryService rs = connection.getRegistryService(); 

Get the QueryManager: Recall that BooksToGo uses the LifeCycleManager interface and the BusinessLifeCycleManager subinterface to make its registry requests. But searching a registry is not a Life Cycle management activity. Instead, it's an activity that is part of what JAXR terms "Query Management". JAXR provides a QueryManager interface for Query Management, and defines two subinterfaces: BusinessQueryManager and DeclarativeQueryManager. The BusinessQueryManager interface provides methods for searching a registry based on criteria such as classification. The DeclarativeQueryManager provides methods for issuing an ad-hoc query, that is a query whose format is based on immediate need. A JAXR provider implements these interfaces. To get the interfaces, JAXR provides the getQueryManager, getBusinessQueryManager, and getDeclarativeQueryManager methods:

QueryManager queryManager = rs.getQueryManager(); BusinessQueryManager businessQueryManager = rs.getBusinessQueryManager(); DeclarativeQueryManager declarativeQueryManager = rs.getDeclarativeQueryManager();

Issue Search Requests: BoomingBusiness.com uses the BusinessQueryManager interface to make search requests. The BusinessQueryManager provides various "find" methods, that search for specific types of objects in the JAXR information model. Recall that each of these object types provides information about specific kinds of items in the registry, for example, an Organization object provides information about a registered business or other registered entity. These methods in the BusinessQueryManager interface have the name findInterface, where Interface is the name of an interface in the JAXR information model. Some of these methods are:

• FindClassificationSchemes
• FindOrganizations
• FindServices
• FindServiceBindings

Notice that the names of these methods suggest that they find multiple objects, and in fact, that's true for most of the BusinessQueryManager methods. Methods such as FindOrganizations return a BulkResponse that includes a collection of Organization objects.

Search Criteria: The searching done by methods such as FindOrganizations is based on criteria that is specified as arguments in the method call. The arguments are:

. .

findQualifier	Identifies find qualifiers, each of which provides various constants that identify search control options. For example, the constant EXACT_NAME_MATCH specifies that the search should return objects that exactly match a name supplied in the search criteria.
namePatterns	A collection of strings that are used for pattern matching in the search. This can include wildcards. So, for instance, a wildcard pattern specification such as %trans can be used to search for objects whose name begins with the characters trans.
classifications	Identifies classifications to be used in the search. They limit the objects returned to those that have the specified classifications.
specifications	Identifies technical specifications (these correspond to UDDI tModel elements) to be used in the search. This is analogous to the tModelBag in UDDI. They limit the objects returned to those that have the identified technical specifications.
externalIdentifiers	Specify external identifiers using identifications schemes such as NAICS or DUNS. They limit the objects returned to those that correspond to the external identifiers.
externalLinks	Identifies links outside the registry. They limit the objects returned to those that have the specified external links.

Calls to most of the BusinessQueryManager methods require that a JAXR client specify values for all the arguments listed above. Some require fewer arguments. Here, for example, is a call to the FindOrganizations method that searches for Organization objects whose names begin with the string Trans. Notice that the call includes values for all of the arguments listed above, however most of them are null values. The only non-null value is for the findQualifier. That value, SORT_BY_NAME_DESC, asks for search results to be returned in alphabetical order. If a JAXR client wanted the results returned in reverse alphabetical order, the client would specify a findQualifier value of SORT_BY_NAME_ASC.

BusinessQueryManager queryManager; Collection findQualifiers = new ArrayList(); findQualifiers.add(FindQualifier.SORT_BY_NAME_DESC); Collection namePatterns = new ArrayList(); namePatterns.add("%Trans"); BulkResponse response = queryManager.findOrganizations(findQualifiers, null, null, null, null, null);

Identifying a Taxonomy: Say a JAXR client wanted to do a search by classification. The client might, for example, want to find all Organization objects in a UDDI registry that are classified as "Payroll Services" according to the NAICS classification scheme. In this case, the client uses the FindOrganizations method, specifying the classification value of interest as an argument in the call. However before doing that, the client needs to identify a classification scheme, that is, its taxonomy. The BusinessQueryManager provides a method, findClassificationSchemeByName to identify a classification scheme:

BusinessQueryManager queryManager ClassificationScheme classificationScheme = queryManager.findClassificationSchemeByName( "ntis-gov:naics");

But that's not enough. A JAXR client also needs to specify the value of the classification, that is, the taxonomy element, stored in the registry. To do this, the client uses the LifeCycleManager method createClassification:

BusinessLifeCycleManager lifeCycleManager; Classification classification = lifeCycleManager.createClassification( classificationScheme, "Payroll Services", " 541214" );

The client then adds the classification to classifications list and makes the call to findOrganizations:

Collection classifications = new ArrayList(); classifications.add ( classification ); BulkResponse response = queryManager.findOrganizations(findQualifiers, null, classifications, null, null, null);

Retrieving Results: Recall that most of the BusinessQueryManager methods, such as FindOrganizations, return a collection of objects in a BulkResponse. To retrieve the objects, a JAXR client uses the BulkResponse method getCollection:

BulkResponse response;
Collection orgs = response.getCollection();

The client can then iterate through the collection of objects and retrieve information using get methods provided by those objects. For example, a client can retrieve the name and description of an object by calling the getName and getDescription method provided by the RegistryObject interface. Similarly, if a JAXR client wanted to retrieve the Service and ServiceBinding objects for an Organization, it uses the getServices and getServiceBindings methods of the Organization interface.

Iterator orgIter = orgs.iterator(); while (orgIter.hasNext()) { Organization org = (Organization) orgIter.next(); InternationalString name = getName(org); InternationalString name = getDescription(org); } Collection services = org.getServices(); Iterator svcIter = services.iterator(); while (svcIter.hasNext()) { ... Collection serviceBindings = svc.getServiceBindings(); Iterator sbIter = serviceBindings.iterator(); while (sbIter.hasNext()) { ... { }

BoomingBusiness.com Does the Search: BoomingBusiness.com wants to search the registry for online book ordering services. To see how it does the search and retrieves information from the returned objects look here.

Search Program

Here is a sample application program that uses the JAXR API to search a UDDI registry for and return information about entries classified as "Book Stores," that is, entries having the NAICS code 451211. You can run this program, see Build and Run the Sample Programs.

Build and Run the Sample Programs

You can build and run the sample programs that are highlighted in the JAXR Example. The two programs are:

• ProviderController.java. This program publishes the BooksToGo organization and its Online Book Ordering service in a UDDI registry. You can also use the program to delete an organization from the registry, based on an organization key that you supply in the delete request.
• ClientQuery.java. This program search a UDDI registry for information about entries classified as "Book Stores," that is, entries having the NAICS code 451211.

To build and run the programs:

1. Copy the following files to a directory:

   • ProviderController.java
   • ClientQuery.java
   • article.props
   • build.xml

   Copy the following file to your home directory: .jaxr.properties.

   You will need to replace the user-name and user-password strings in the article.props file with your own user name and password. You will also need to replace the http-proxyhost, http-proxyport, https-proxyhost, and http-proxyport values in the .jaxr.properties file with your own http and https proxies and port numbers

2. Ensure that the Java WSDP EA1 release is installed. You can find the download on the Java Technology & XML Downloads & Specifications page.

3. Start the Tomcat container that is packaged with the Java WSDP. A script named catalina.sh is in the bin subdirectory of your Java WSDP installation. Include that subdirectory in your path. Then make that subdirectory the current directory and enter the command:

   catalina.sh run
   

4. Update the properties, as appropriate, in the article.props file. You will need to update the userName and password strings with your own user name and password.

5. Use the Ant Build Tool that is packaged in the Java WSDP to build and run the sample programs. The build.xml file defines project build operations.

   A script named ant.sh is in the bin subdirectory of your Java WSDP installation. Include that subdirectory in your path. Then make that subdirectory the current directory and enter one of the following commands:

   ant publish
   

   This builds and runs the ProviderController.java program to publish the BooksToGo organization and its Online Book Ordering service in a UDDI registry.

   ant -DDELETE_KEY=org_key delete
   

   This builds and runs the ProviderController.java program to delete an organization from the registry. Replace org_key with the key of the organization key that you want to delete from the registry.

   ant query
   
   

   This builds and runs the ClientQuery.java program to search a UDDI registry for information about entries classified as "Book Stores," that is, entries having the NAICS code 451211.

Summary

This article focused on one of the Java APIs in the Java Web Services Developer Pack: JAXR. This API enables you to request Web service registration operations in the Java platform. The article showed how you can use the JAXR API to register a Web service in a standard business registry such as a UDDI registry. It also showed how you can use the API to search a registry for Web services. Later articles in the series will focus on other components in the Java WSDP, and illustrate how you can use them to access and use Web services in the Java platform.

For More Information

Java Web Services Developer Pack

Java Web Services Tutorial

Java Technology & Web Services

Web Services Made Easier

Dot Com Builder: Web Services

Web Services Technical Articles on the JDC

Java Technology & XML Downloads

uddi.org Home Page

ebXML Home Page

Simple Object Access Protocol (SOAP) 1.1

Web Services Description Language (WSDL) 1.1

North American Industry Classification System (NAICS) Codes and Titles

D&B DUNS Number

Sun ONE for Developers

Also, take advantage of the numerous sessions on Web services being offered at the 2002 JavaOne Conference. For example, in the Birds of a Feather session Developing and Deploying Web Services Using the Java Web Services Developer Pack speakers Nandkumar Kesavan, Ramesh Mandava, and Bhakti Mehta discuss how to build, deploy, and dynamically access Web services with the Java WSDP, and also cover choices available in developing Web services. For a list of sessions, see Web Services Today and Tomorrow.

Finally, the JAXR developer forum is a good place to get answers to questions about JAXR and to contribute to technical discussions about JAXR.

About the Author

Ed Ort is a staff member of the Java Developer Connection. He has written extensively about relational database technology and programming languages.

Ramesh Mandava is a staff engineer at Sun Microsystems. Currently, Ramesh leads the Web Services SQE team, which ensures that Web services deliverables from Sun meet customer quality expectations and needs.

Have a question about programming? Use Java Online Support.