You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juddi.apache.org by jf...@apache.org on 2010/03/01 18:57:26 UTC
svn commit: r917612 - in /webservices/juddi/trunk/docs:
devguide/en-US/Author_Group.xml userguide/en-US/Author_Group.xml
userguide/en-US/SimplePublish.xml
userguide/en-US/images/uddi_core_datastructures.gif
userguide/en-US/jUDDI_User_Guide.xml
Author: jfaath
Date: Mon Mar 1 17:57:26 2010
New Revision: 917612
URL: http://svn.apache.org/viewvc?rev=917612&view=rev
Log:
updating user guide with simple publish article
Added:
webservices/juddi/trunk/docs/userguide/en-US/SimplePublish.xml (with props)
webservices/juddi/trunk/docs/userguide/en-US/images/uddi_core_datastructures.gif (with props)
Modified:
webservices/juddi/trunk/docs/devguide/en-US/Author_Group.xml
webservices/juddi/trunk/docs/userguide/en-US/Author_Group.xml
webservices/juddi/trunk/docs/userguide/en-US/jUDDI_User_Guide.xml
Modified: webservices/juddi/trunk/docs/devguide/en-US/Author_Group.xml
URL: http://svn.apache.org/viewvc/webservices/juddi/trunk/docs/devguide/en-US/Author_Group.xml?rev=917612&r1=917611&r2=917612&view=diff
==============================================================================
--- webservices/juddi/trunk/docs/devguide/en-US/Author_Group.xml (original)
+++ webservices/juddi/trunk/docs/devguide/en-US/Author_Group.xml Mon Mar 1 17:57:26 2010
@@ -18,6 +18,12 @@
<email>kstam@apache.org</email>
</author>
+ <author>
+ <firstname>Jeff</firstname>
+ <surname>Faath</surname>
+ <email>jfaath@apache.org</email>
+ </author>
+
<author>
<firstname>The jUDDI Community</firstname>
<surname></surname>
Modified: webservices/juddi/trunk/docs/userguide/en-US/Author_Group.xml
URL: http://svn.apache.org/viewvc/webservices/juddi/trunk/docs/userguide/en-US/Author_Group.xml?rev=917612&r1=917611&r2=917612&view=diff
==============================================================================
--- webservices/juddi/trunk/docs/userguide/en-US/Author_Group.xml (original)
+++ webservices/juddi/trunk/docs/userguide/en-US/Author_Group.xml Mon Mar 1 17:57:26 2010
@@ -26,6 +26,12 @@
<email></email>
</author>
+ <author>
+ <firstname>Jeff</firstname>
+ <surname>Faath</surname>
+ <email>jfaath@apache.org</email>
+ </author>
+
<author>
<firstname>The jUDDI Community</firstname>
<surname></surname>
Added: webservices/juddi/trunk/docs/userguide/en-US/SimplePublish.xml
URL: http://svn.apache.org/viewvc/webservices/juddi/trunk/docs/userguide/en-US/SimplePublish.xml?rev=917612&view=auto
==============================================================================
--- webservices/juddi/trunk/docs/userguide/en-US/SimplePublish.xml (added)
+++ webservices/juddi/trunk/docs/userguide/en-US/SimplePublish.xml Mon Mar 1 17:57:26 2010
@@ -0,0 +1,298 @@
+<?xml version='1.0'?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "jUDDI_User_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-SimplePublish">
+ <title>Simple Publishing Using the jUDDI API</title>
+ <para>
+ One of the most common requests we get on the message board is âHow do I publish a service using jUDDI?â This question holds a wide berth, as it can result anywhere from not understanding the UDDI data model, to confusion around how jUDDI is set up, to the
+ order of steps required to publish artifacts in the registry, to general use of the API â and everything in between. This article will attempt to answer this âloadedâ question and, while not going into too much detail, will hopefully clear some of the
+ confusion about publishing into the jUDDI registry.
+ </para>
+ <section>
+ <title>UDDI Data Model</title>
+ <para>
+ Before you begin publishing artifacts, you need to know exactly how to break down your data into the UDDI model. This topic is covered extensively in the specification, particularly in section 3, so I only want to gloss over some for details. Readers
+ interested in more extensive coverage should most definitely take a look at the UDDI specification.
+ </para>
+ <para>
+ Below is a great diagram of the UDDI data model (taken directly from the specification):
+ </para>
+ <figure id="fig-UDDI-coredatastructures">
+ <title>UDDI Core Data Structures</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/uddi_core_datastructures.gif" scalefit="1" />
+ </imageobject>
+ <textobject>
+ <phrase>UDDI core data structures</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ As you can see, data is organized into a hierarchical pattern. Business Entities are at the top of the pyramid, they contain Business Services and those services in turn contain Binding Templates. TModels (or technical models) are a catch-all structure
+ that can do anything from categorize one of the main entities, describe the technical details of a binding (ex. protocols, transports, etc), to registering a key partition. TModels wonât be covered too much in this article as I want to focus on the
+ three main UDDI entities.
+ </para>
+ <para>
+ The hierarchy defined in the diagram is self-explanatory. You must first have a Business Entity before you can publish any services. And you must have a Business Service before you can publish a Binding Template. There is no getting around this structure;
+ this is the way UDDI works.
+ </para>
+ <para>
+ Business Entities describe the organizational unit responsible for the services it publishes. It generally consist of a description and contact information. How one chooses to use the Business Entity is really dependent on the particular case. If youâre one
+ small company, you will likely just have one Business Entity. If you are a larger company with multiple departments, you may want to have a Business Entity per department. (The question may arise if you can have one uber-Business Entity and multiple
+ child Business Entities representing the departments. The answer is yes, you can relate Business Entities using Publisher Assertions, but that is beyond the scope of this article.)
+ </para>
+ <para>
+ Business Services are the cogs of the SOA landscape. They represent units of functionality that are consumed by clients. In UDDI, thereâs not much to a service structure; mainly descriptive information like name, description and categories. The meat of the
+ technical details about the service is contained in its child Binding Templates.
+ </para>
+ <para>
+ Binding Templates, as mentioned above, give the details about the technical specification of the service. This can be as simple as just providing the serviceâs access point, to providing the location of the service WSDL to more complicated scenarios to
+ breaking down the technical details of the WSDL (when used in concert with tModels). Once again, getting into these scenarios is beyond the scope of this article but may be the subject of future articles.
+ </para>
+ </section>
+ <section>
+ <title>jUDDI Additions to the Model</title>
+ <para>
+ Out of the box, jUDDI provides some additional structure to the data model described in the specification. Primarily, this is the concept of the Publisher.
+ </para>
+ <para>
+ The UDDI specification talks about ownership of the entities that are published within the registry, but makes no mention about how ownership should be handled. Basically, it is left up to the particular implementation to decide how to handle âusersâ that
+ have publishing rights in the registry.
+ </para>
+ <para>
+ Enter the jUDDI Publisher. The Publisher is essentially an out-of-the-box implementation of an identity management system. Per the specification, before assets can be published into the registry, a âpublisherâ must authenticate with the registry by
+ retrieving an authorization token. This authorization token is then attached to future publish calls to assign ownership to the published entities.
+ </para>
+ <para>
+ jUDDIâs Publisher concept is really quite simple, particularly when using the default authentication. You can save a Publisher to the registry using jUDDIâs custom API and then use that Publisher to publish your assets into the registry. jUDDI allows for
+ integration into your own identity management system, circumventing the Publisher entirely if desired. This is discussed in more detail in the documentation, but for purposes of this article, we will be using the simple out-of-the-box Publisher
+ solution.
+ </para>
+ <para>
+ One quick note: ownership is essentially assigned to a given registry entity by using its âauthorizedNameâ field. The âauthorizedNameâ field is defined in the specification in the operationalInfo structure which keeps track of operational info for each
+ entity.
+ </para>
+ </section>
+ <section>
+ <title>UDDI and jUDDI API</title>
+ <para>
+ Knowing the UDDI data model is all well and good. But to truly interact with the registry, you need to know how the UDDI API is structured and how jUDDI implements this API. The UDDI API is covered in great detail in chapter 5 of the specification but will be
+ summarized here.
+ </para>
+ <para>
+ UDDI divides their API into several âsetsâ â each representing a specific area of functionality. The API sets are listed below:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Inquiry â deals with querying the registry to return details on entities within
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Publication â handles publishing entities into the registry
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Security â open-ended specification that handles authentication
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Custody and Ownership Transfer â deals with transferring ownership and custody of entities
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Subscription â allows clients to retrieve information on entities in a timely manner using a subscription format
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Subscription Listener â client API that accepts subscription results
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Value Set (Validation and Caching)â validates keyed reference values (not implemented by jUDDI)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Replication â deals with federation of data between registry nodes (not implemented by jUDDI)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The most commonly used APIs are the Inquiry, Publication and Security APIs. These APIs provide the standard functions for interacting with the registry.
+ </para>
+ <para>
+ The jUDDI server implements each of these API sets as a JAX-WS compliant web service and each method defined in the API set is simply a method in the corresponding web service. The client module provided by jUDDI uses a âtransportâ class that defines how
+ the call is to be made. The default transport uses JAX-WS but there are several alternative ways to make calls to the API. Please refer to the documentation for more information.
+ </para>
+ <para>
+ One final note, jUDDI defines its own API set. This API set contains methods that deal with handling Publishers as well as other useful maintenance functions (mostly related to jUDDIâs subscription model). This API set is obviously proprietary to jUDDI and
+ therefore doesnât conform to the UDDI specification.
+ </para>
+ </section>
+ <section>
+ <title>Getting Started</title>
+ <para>
+ Now that weâve covered the basics of the data model and API sets, itâs time to get started with the publishing sample. The first thing that must happen is to get the jUDDI server up and running. Please refer to this
+ <ulink url="http://apachejuddi.blogspot.com/2010/02/getting-started-with-juddi-v3.html">article</ulink>
+ that explains how to start the jUDDI server.
+ </para>
+ <section>
+ <title>Simple Publishing Example</title>
+ <para>
+ We will now go over the âsimple-publishâ example found in the documentation. This sample expands upon the HelloWorld example in that after retrieving an authentication token, a Publisher, BusinessEntity and BusinessService are published to the registry.
+ </para>
+ <para>
+ The sample consists of only one class: SimplePublish. Letâs start by taking a look at the constructor:
+ </para>
+ <programlisting language="Java" role="JAVA">
+ public SimplePublish() {
+ try {
+ String clazz = UDDIClientContainer.getUDDIClerkManager(null).
+ getClientConfig().getUDDINode("default").getProxyTransport();
+ Class<?> transportClass = ClassUtil.forName(clazz, Transport.class);
+ if (transportClass!=null) {
+ Transport transport = (Transport) transportClass.
+ getConstructor(String.class).newInstance("default");
+
+ security = transport.getUDDISecurityService();
+ juddiApi = transport.getJUDDIApiService();
+ publish = transport.getUDDIPublishService();
+ }
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+ </programlisting>
+ <para>
+ The constructor uses the jUDDI client API to retrieve the transport from the default node. You can refer to the documentation if youâre confused about how clerks and nodes work. Suffice it to say, we are simply retrieving the default client transport class which
+ is designed to make UDDI calls out using JAX-WS web services.
+ </para>
+ <para>
+ Once the transport is instantiated, we grab the three API sets we need for this demo: 1) the Security API set so we can get authorization tokens, 2) the proprietary jUDDI API set so we can save a Publisher and 3) the Publication API set so we can actually publish
+ entities to the registry.
+ </para>
+ <para>
+ All the magic happens in the publish method. We will look at that next.
+ </para>
+ <para>
+ Here are the first few lines of the publish method:
+ </para>
+ <programlisting language="Java" role="JAVA">
+ // Setting up the values to get an authentication token for the 'root' user ('root' user
+ // has admin privileges and can save other publishers).
+ GetAuthToken getAuthTokenRoot = new GetAuthToken();
+ getAuthTokenRoot.setUserID("root");
+ getAuthTokenRoot.setCred("");
+
+ // Making API call that retrieves the authentication token for the 'root' user.
+ AuthToken rootAuthToken = security.getAuthToken(getAuthTokenRoot);
+ System.out.println ("root AUTHTOKEN = " + rootAuthToken.getAuthInfo());
+ </programlisting>
+ <para>
+ This code simply gets the authorization token for the ârootâ user. The ârootâ user (or publisher) is automatically installed in every jUDDI instance and acts as the âadministratorâ for jUDDI API calls. Additionally, the ârootâ user is the owning
+ publisher for all the initial services installed with jUDDI. You may be wondering what those âinitial servicesâ are. Well, since the UDDI API sets are all implemented as web services by jUDDI, every jUDDI node actually registers those services inside
+ itself. This is done per the specification.
+ </para>
+ <para>
+ Letâs get back to the code. Now that we have root authorization, we can add a publisher:
+ </para>
+ <programlisting language="Java" role="JAVA">
+ // Creating a new publisher that we will use to publish our entities to.
+ Publisher p = new Publisher();
+ p.setAuthorizedName("my-publisher");
+ p.setPublisherName("My Publisher");
+
+ // Adding the publisher to the "save" structure, using the 'root' user authentication info and
+ // saving away.
+ SavePublisher sp = new SavePublisher();
+ sp.getPublisher().add(p);
+ sp.setAuthInfo(rootAuthToken.getAuthInfo());
+ juddiApi.savePublisher(sp);
+ </programlisting>
+ <para>
+ Here weâve simply used the jUDDI API to save a publisher with authorized name âmy-publisherâ. Notice how the authorization token for the ârootâ user is used. Next, we need to get the authorization token for this new publisher:
+ </para>
+ <programlisting language="Java" role="JAVA">
+ // Our publisher is now saved, so now we want to retrieve its authentication token
+ GetAuthToken getAuthTokenMyPub = new GetAuthToken();
+ getAuthTokenMyPub.setUserID("my-publisher");
+ getAuthTokenMyPub.setCred("");
+ AuthToken myPubAuthToken = security.getAuthToken(getAuthTokenMyPub);
+ System.out.println ("myPub AUTHTOKEN = " + myPubAuthToken.getAuthInfo());
+ </programlisting>
+ <para>
+ This is pretty straightforward. Youâll note that no credentials have been set on both authorization calls. This is because weâre using the default authenticator which doesnât require credentials. We have our authorization token for our new
+ publisher, now we can simply publish away:
+ </para>
+ <programlisting language="Java" role="JAVA">
+ // Creating the parent business entity that will contain our service.
+ BusinessEntity myBusEntity = new BusinessEntity();
+ Name myBusName = new Name();
+ myBusName.setValue("My Business");
+ myBusEntity.getName().add(myBusName);
+
+ // Adding the business entity to the "save" structure, using our publisher's authentication info
+ // and saving away.
+ SaveBusiness sb = new SaveBusiness();
+ sb.getBusinessEntity().add(myBusEntity);
+ sb.setAuthInfo(myPubAuthToken.getAuthInfo());
+ BusinessDetail bd = publish.saveBusiness(sb);
+ String myBusKey = bd.getBusinessEntity().get(0).getBusinessKey();
+ System.out.println("myBusiness key: " + myBusKey);
+
+ // Creating a service to save. Only adding the minimum data: the parent business key retrieved
+ //from saving the business above and a single name.
+ BusinessService myService = new BusinessService();
+ myService.setBusinessKey(myBusKey);
+ Name myServName = new Name();
+ myServName.setValue("My Service");
+ myService.getName().add(myServName);
+ // Add binding templates, etc...
+
+ // Adding the service to the "save" structure, using our publisher's authentication info and
+ // saving away.
+ SaveService ss = new SaveService();
+ ss.getBusinessService().add(myService);
+ ss.setAuthInfo(myPubAuthToken.getAuthInfo());
+ ServiceDetail sd = publish.saveService(ss);
+ String myServKey = sd.getBusinessService().get(0).getServiceKey();
+ System.out.println("myService key: " + myServKey);
+ </programlisting>
+ <para>
+ To summarize, here we have created and saved a BusinessEntity and then created and saved a BusinessService. Weâve just added the bare minimum data to each entity (and in fact, have not added any BindingTemplates to the service). Obviously, you
+ would want to fill out each structure with greater information, particularly with services. However, this is beyond the scope of this article, which aims to simply show you how to programmatically publish entities.
+ </para>
+ <para>
+ There are a couple important notes regarding the use of entity keys. Version 3 of the specification allows for publishers to create their own keys but also instructs implementers to have a default method. Here we have gone with the default
+ implementation by leaving each entityâs âkeyâ field blank in the save call. jUDDIâs default key generator simply takes the nodeâs partition and appends a GUID. In a default installation, it will look something like this:
+ </para>
+ <blockquote>
+ <para>
+ uddi:juddi.apache.org:<GUID>
+ </para>
+ </blockquote>
+ <para>
+ You can, of course, customize all of this, but that is left for another article. The second important point is that when the BusinessService is saved, Iâve had to explicitly set its parent business key (retrieved from previous call saving the
+ business). This is a necessary step when the service is saved in an independent call like this. Otherwise you would get an error because jUDDI wonât know where to find the parent entity. I could have added this service to the BusinessEntityâs service
+ collection and saved it with the call to saveBusiness. In that scenario I would not have to set the parent business key.
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Conclusion</title>
+ <para>
+ That does it for this article. Hopefully I managed to clear some of the confusion around the open-ended question, âHow do I publish a service using jUDDI?â.
+ </para>
+ </section>
+</chapter>
+
Propchange: webservices/juddi/trunk/docs/userguide/en-US/SimplePublish.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: webservices/juddi/trunk/docs/userguide/en-US/images/uddi_core_datastructures.gif
URL: http://svn.apache.org/viewvc/webservices/juddi/trunk/docs/userguide/en-US/images/uddi_core_datastructures.gif?rev=917612&view=auto
==============================================================================
Binary file - no diff available.
Propchange: webservices/juddi/trunk/docs/userguide/en-US/images/uddi_core_datastructures.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: webservices/juddi/trunk/docs/userguide/en-US/jUDDI_User_Guide.xml
URL: http://svn.apache.org/viewvc/webservices/juddi/trunk/docs/userguide/en-US/jUDDI_User_Guide.xml?rev=917612&r1=917611&r2=917612&view=diff
==============================================================================
--- webservices/juddi/trunk/docs/userguide/en-US/jUDDI_User_Guide.xml (original)
+++ webservices/juddi/trunk/docs/userguide/en-US/jUDDI_User_Guide.xml Mon Mar 1 17:57:26 2010
@@ -17,6 +17,8 @@
<xi:include href="jUDDI_configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Using_jUDDI-Client.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="UDDI_Annotations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="SimplePublish.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Subscription.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
---------------------------------------------------------------------
To unsubscribe, e-mail: juddi-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: juddi-cvs-help@ws.apache.org