You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juddi.apache.org by ks...@apache.org on 2014/02/03 20:34:37 UTC
svn commit: r1564021 [1/5] - in /juddi/docs/trunk: ./ ClientGuide/
ClientGuide/en-US/ Guide/ Guide/Guide/ Guide/en-US/ images/ images/community/
Author: kstam
Date: Mon Feb 3 19:34:34 2014
New Revision: 1564021
URL: http://svn.apache.org/r1564021
Log:
adding Guide and ClientGuide
Added:
juddi/docs/trunk/ClientGuide/
juddi/docs/trunk/ClientGuide/en-US/
juddi/docs/trunk/ClientGuide/en-US/ClientGuide-docinfo.xml
juddi/docs/trunk/ClientGuide/en-US/ClientGuide.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideKeyFormatTemplates.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideMappingWADLandWSDLtoUDDI.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideSimplePublishingUsingthejUDDIAPI.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideTCKRunner.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIMigrationTool.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIv2Services.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingUDDIAnnotationstoAutomateRegistration.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingjUDDIRestServices.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingthejUDDIGUI.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuidejUDDIClientConfigurationGuide.asciidoc
juddi/docs/trunk/ClientGuide/en-US/ClientGuidejUDDIClientforNET.asciidoc
juddi/docs/trunk/ClientGuide/en-US/Guardfile (with props)
juddi/docs/trunk/ClientGuide/en-US/_Sidebar.asciidoc
juddi/docs/trunk/ClientGuide/en-US/asciidoctor.css
juddi/docs/trunk/ClientGuide/pom.xml
juddi/docs/trunk/Guide/
juddi/docs/trunk/Guide/Guide/
juddi/docs/trunk/Guide/en-US/
juddi/docs/trunk/Guide/en-US/Guardfile (with props)
juddi/docs/trunk/Guide/en-US/Guide-docinfo.xml
juddi/docs/trunk/Guide/en-US/Guide.asciidoc
juddi/docs/trunk/Guide/en-US/GuideAdministration.asciidoc
juddi/docs/trunk/Guide/en-US/GuideArchitecture.asciidoc
juddi/docs/trunk/Guide/en-US/GuideConfigurationServer.asciidoc
juddi/docs/trunk/Guide/en-US/GuideContributingtojUDDI.asciidoc
juddi/docs/trunk/Guide/en-US/GuideExtendingUDDI.asciidoc
juddi/docs/trunk/Guide/en-US/GuideGettingStarted.asciidoc
juddi/docs/trunk/Guide/en-US/GuideHowToDeployjUDDITo.asciidoc
juddi/docs/trunk/Guide/en-US/GuideRootSeedData.asciidoc
juddi/docs/trunk/Guide/en-US/GuideTroubleshootingjUDDI.asciidoc
juddi/docs/trunk/Guide/en-US/GuideUDDIRegistryIntroduction.asciidoc
juddi/docs/trunk/Guide/en-US/GuideUDDISubscriptions.asciidoc
juddi/docs/trunk/Guide/en-US/GuideUsingDigitalSignaturesinUDDI.asciidoc
juddi/docs/trunk/Guide/en-US/_Sidebar.asciidoc
juddi/docs/trunk/Guide/en-US/asciidoctor.css
juddi/docs/trunk/Guide/pom.xml
juddi/docs/trunk/Home.asciidoc
juddi/docs/trunk/Readme.asciidoc
juddi/docs/trunk/images/
juddi/docs/trunk/images/GettingStarted-add_publisher.png (with props)
juddi/docs/trunk/images/GettingStarted-authToken_SoapUI.png (with props)
juddi/docs/trunk/images/GettingStarted-create_business.png (with props)
juddi/docs/trunk/images/GettingStarted-create_keygenerator.png (with props)
juddi/docs/trunk/images/GettingStarted-form_login.png (with props)
juddi/docs/trunk/images/GettingStarted-happy_juddi.png (with props)
juddi/docs/trunk/images/GettingStarted-jUDDI_admin.png (with props)
juddi/docs/trunk/images/GettingStarted-jUDDI_welcome.png (with props)
juddi/docs/trunk/images/GettingStarted-juddi_services.png (with props)
juddi/docs/trunk/images/UDDI_Registry_invocation_pattern.png (with props)
juddi/docs/trunk/images/UDDI_services_overview.png (with props)
juddi/docs/trunk/images/a_bothup_b_sales_down.png (with props)
juddi/docs/trunk/images/community/
juddi/docs/trunk/images/community/community_doc.png (with props)
juddi/docs/trunk/images/community/jbossorglogo.png (with props)
juddi/docs/trunk/images/community/title_hdr.png (with props)
juddi/docs/trunk/images/create_new_subscription.png (with props)
juddi/docs/trunk/images/icon.svg (with props)
juddi/docs/trunk/images/jUDDIArchitecture_Gui.png (with props)
juddi/docs/trunk/images/jUDDIArchitecture_clientAndGui.png (with props)
juddi/docs/trunk/images/jUDDIArchitecture_server.png (with props)
juddi/docs/trunk/images/juddi-admin-configure.png (with props)
juddi/docs/trunk/images/juddi-admin-home.png (with props)
juddi/docs/trunk/images/juddi-admin-juddiapi.png (with props)
juddi/docs/trunk/images/juddi-admin-mbeans.png (with props)
juddi/docs/trunk/images/juddi-admin-stats.png (with props)
juddi/docs/trunk/images/juddi-admin-status.png (with props)
juddi/docs/trunk/images/juddi-gui-browse-business.png (with props)
juddi/docs/trunk/images/juddi-gui-browse-business2.png (with props)
juddi/docs/trunk/images/juddi-gui-browse-options.png (with props)
juddi/docs/trunk/images/juddi-gui-browse-services.png (with props)
juddi/docs/trunk/images/juddi-gui-browse-tmodel.png (with props)
juddi/docs/trunk/images/juddi-gui-create-business.png (with props)
juddi/docs/trunk/images/juddi-gui-create-business2.png (with props)
juddi/docs/trunk/images/juddi-gui-create-business3.png (with props)
juddi/docs/trunk/images/juddi-gui-fullbootstrap-menu.png (with props)
juddi/docs/trunk/images/juddi-gui-import-wsdl.png (with props)
juddi/docs/trunk/images/juddi-gui-login-warning.png (with props)
juddi/docs/trunk/images/juddi-gui-menu.png (with props)
juddi/docs/trunk/images/juddi-gui-mybuz.png (with props)
juddi/docs/trunk/images/juddi-gui-nodeswitcher.png (with props)
juddi/docs/trunk/images/juddi-gui-publisherassertion.png (with props)
juddi/docs/trunk/images/juddi-gui-publisherassertion2.png (with props)
juddi/docs/trunk/images/juddi-gui-publisherassertion3.png (with props)
juddi/docs/trunk/images/juddi-gui-search.png (with props)
juddi/docs/trunk/images/juddi-gui-service-add1.png (with props)
juddi/docs/trunk/images/juddi-gui-service-add2.png (with props)
juddi/docs/trunk/images/juddi-gui-sign1.png (with props)
juddi/docs/trunk/images/juddi-gui-sign2.png (with props)
juddi/docs/trunk/images/juddi-gui-signed-invalid.png (with props)
juddi/docs/trunk/images/juddi-gui-signed-valid.png (with props)
juddi/docs/trunk/images/juddi-gui-signerpanel1.png (with props)
juddi/docs/trunk/images/juddi-gui-signerpanel2.png (with props)
juddi/docs/trunk/images/juddi-gui-signerpanel3.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription-view.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription1.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription2.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription2a.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription3.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription4.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription5.png (with props)
juddi/docs/trunk/images/juddi-gui-subscription6.png (with props)
juddi/docs/trunk/images/juddi-gui-tabletbootstrap-menu.png (with props)
juddi/docs/trunk/images/juddi-gui-tmodel-keygen.png (with props)
juddi/docs/trunk/images/juddi-gui-transfer.png (with props)
juddi/docs/trunk/images/juddi-gui-welcome.png (with props)
juddi/docs/trunk/images/marketing_node_installation.png (with props)
juddi/docs/trunk/images/marketing_services.png (with props)
juddi/docs/trunk/images/newly_saved_subscription.png (with props)
juddi/docs/trunk/images/raw_XML_response_synchronous_subscription_request.png (with props)
juddi/docs/trunk/images/registration_by_annotation.png (with props)
juddi/docs/trunk/images/registry_info_helloworld.png (with props)
juddi/docs/trunk/images/sales_node_installation.png (with props)
juddi/docs/trunk/images/sales_services.png (with props)
juddi/docs/trunk/images/set_coverage_period.png (with props)
juddi/docs/trunk/images/subscriptions_portal.png (with props)
juddi/docs/trunk/images/uddi_core_datastructures.gif (with props)
juddi/docs/trunk/pom.xml
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuide-docinfo.xml
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuide-docinfo.xml?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuide-docinfo.xml (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuide-docinfo.xml Mon Feb 3 19:34:34 2014
@@ -0,0 +1,56 @@
+ <authorgroup>
+
+Â <author>
+Â Â <firstname>Kurt</firstname>
+Â Â <surname>Stam</surname>
+ <othername role='mi'>T</othername>
+ <affiliation>
+ <shortaffil>RedHat</shortaffil>
+ <jobtitle>Enterprise Integration Magician (EIM)</jobtitle>
+ <orgname>Red Hat, Inc.</orgname>
+ <orgdiv><ulink url="http://www.jboss.org/overlord">SOA Governance</ulink></orgdiv>
+ <authorblurb>
+ <para>
+ Open Source, written by domain experts.
+ </para>
+ </authorblurb>
+
+ </affiliation>
+
+Â </author>
+
+ <author>
+ Â Â <firstname>Alex</firstname>
+ Â Â <surname>O'Ree</surname>
+ <affiliation>
+ <shortaffil>Apache Software Foundation (ASF)</shortaffil>
+ <orgname>Apache Software Foundation (ASF), http://juddi.apache.org</orgname>
+ </affiliation>
+ Â </author>
+
+ </authorgroup>
+
+ <copyright>
+ Â <year>2003-2014</year>
+ <holder>The Apache Software Foundation</holder>
+ </copyright>
+
+ <legalnotice>
+ <simpara>
+Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+</simpara>
+<simpara>
+ You may obtain a copy of the License at
+
+ <ulink url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>
+</simpara>
+<simpara>
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ </simpara>
+</legalnotice>
+
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuide.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuide.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuide.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuide.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,95 @@
+Apache jUDDI Client and GUI Guide
+=================================
+:doctype: book
+:backend: docbook5
+:docinfo:
+
+[dedication]
+Dedication
+----------
+We'd like to dedicate this guide to Steve Viens and Andy Cutright who started this project back in 2003.
+
+[preface]
+Preface
+-------
+The jUDDI client framework facilitates interaction with any UDDI v3 compliant registry. In addition to providing a client framework for both Java and .NET, it also provides a self proclaimed Technical Compatilibity Test (TCK) Suite. The jUDDI community encourages collabration of other vendors on the TCK or on the client framework in general.
+
+include::ClientGuideSimplePublishingUsingthejUDDIAPI.asciidoc[]
+
+include::ClientGuidejUDDIClientConfigurationGuide.asciidoc[]
+
+include::ClientGuideKeyFormatTemplates.asciidoc[]
+
+include::ClientGuideUsingthejUDDIGUI.asciidoc[]
+
+include::ClientGuideMappingWADLandWSDLtoUDDI.asciidoc[]
+
+include::ClientGuideUsingUDDIAnnotationstoAutomateRegistration.asciidoc[]
+
+include::ClientGuideUDDIv2Services.asciidoc[]
+
+include::ClientGuideUDDIMigrationTool.asciidoc[]
+
+include::ClientGuideUsingjUDDIRestServices.asciidoc[]
+
+include::ClientGuidejUDDIClientforNET.asciidoc[]
+
+include::ClientGuideTCKRunner.asciidoc[]
+
+:numbered!:
+
+////
+/* commented out till we start using it */
+[appendix]
+Example Appendix
+----------------
+One or more optional appendixes go here at section level 1.
+
+Appendix Sub-section
+~~~~~~~~~~~~~~~~~~~
+Sub-section body.
+
+
+[bibliography]
+Example Bibliography
+--------------------
+The bibliography list is a style of AsciiDoc bulleted list.
+
+[bibliography]
+.Books
+- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
+'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999.
+ISBN 1-56592-580-7.
+
+[bibliography]
+.Articles
+- [[[abc2003]]] Gall Anonim. 'An article', Whatever. 2003.
+
+[glossary]
+Example Glossary
+----------------
+Glossaries are optional. Glossaries entries are an example of a style
+of AsciiDoc labeled lists.
+
+[glossary]
+A glossary term::
+The corresponding (indented) definition.
+
+A second glossary term::
+The corresponding (indented) definition.
+
+
+[colophon]
+Example Colophon
+----------------
+Text at the end of a book describing facts about its production.
+////
+
+
+[index]
+Index
+-----
+////////////////////////////////////////////////////////////////
+The index is normally left completely empty, it's contents being
+generated automatically by the DocBook toolchain.
+////////////////////////////////////////////////////////////////
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideKeyFormatTemplates.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideKeyFormatTemplates.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideKeyFormatTemplates.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideKeyFormatTemplates.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,65 @@
+[[chapter-KeyFormatTemplates]]
+== Key Format Templates
+
+=== UDDIv3 key format
+The UDDI v3 keys are formatted such that they are human readable. The short story is that UDDI v3 keys are formatted like: _uddi:<domain>:name_. For example, if you wanted a tModel defined as "uddi:www.mycompany.com:serviceauthenticationmethod", you would first have to create a tModel key generator with value "uddi:www.mycompany.com:keygenerator".
+
+
+=== jUDDI key format templates
+
+The jUDDI client has taken the key format approach one step further so the name part of the key actually helps you understand what the key is for, or even better in the case of a binding template what server registered the key.
+
+==== Advantages of using a template
+
+Using a binding Key with format `uddi:${keyDomain}:binding_${serverName}_${serviceName}_${portName}_${serverPort}` contains valuable information for two reasons
+- you can tell from the bindingKey what server registered it. This is helpful information if you want to debug connectivity issues between a client and the UDDI server.
+- if a server goes to register a bindingTemplate it registered before it won't create a second bindingTemplate, so it won't leave behind dead or duplicate bindingTemplates.
+
+==== Default UDDIKeyConvention Key Templates
+
+The default templates setup by the jUDDI client are:
+....
+uddi:${keyDomain}:business_${businessName}
+uddi:${keyDomain}:service_${serviceName}
+uddi:${keyDomain}:service_cache_${serverName}
+uddi:${keyDomain}:binding_${serverName}_${serviceName}_${portName}_${serverPort}
+....
+where tokens are expressed using `${}`. The templates are defined in the UDDIKeyConvention class.
+
+==== How to use the templates?
+At runtime a serviceKey can be obtained using
+....
+String serviceKey = UDDIKeyConvention.getServiceKey(properties, serviceName);
+....
+The serviceName can be specified in as a property in the first argument, or it can explicitly passed as the second argument. Using the second argument overrides what's specified in the properties. By default it will use the service template `uddi:${keyDomain}:service_${serviceName}`, but if you wish to use a different template you can simple specify that as a property, for example
+....
+String myCustomServiceFormat = "uddi:${keyDomain}:s_${serviceName}";
+properties.add(Property.SERVICE_KEY_FORMAT, myCustomServiceFormat);
+String myCustomFormattedServiceKey = UDDIKeyConvention.getServiceKey(properties, serviceName);
+....
+
+==== Where to define to properties?
+You can define the properties in your code, or you can obtain and pass in the properties defined in your `uddi.xml`. For an exmaple of this you can check out the `META-INF/wsdl2uddi-uddi.xml` of the `wsdl2uddi` example where for the `default` node we set
+....
+ ...
+ <nodes>
+ <node>
+ <name>default</name>
+ <properties>
+ <property name="serverName" value="localhost"/>
+ <property name="serverPort" value="8080"/>
+ <property name="keyDomain" value="uddi.joepublisher.com"/>
+ <property name="businessName" value="WSDL-Business"/>
+ </properties>
+ ...
+ </node>
+ ...
+ </nodes>
+ ...
+....
+and you can obtain the properties like
+....
+UDDIClient uddiClient = new UDDIClient("META-INF/wsdl2uddi-uddi.xml");
+Properties properties = uddiClient.getClientConfig().getUDDINode("default").getProperties();
+....
+This is exactly what the WSDL2UDDI implementation does, and it the reason the class requires the properties in the constructor.
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideMappingWADLandWSDLtoUDDI.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideMappingWADLandWSDLtoUDDI.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideMappingWADLandWSDLtoUDDI.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideMappingWADLandWSDLtoUDDI.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,77 @@
+== Mapping WSDL and WSDL to UDDI
+
+=== Introduction
+
+OASIS published a technical article which describes the recommended way to map the entries from a WSDL (Web Service Description Language) document into UDDI (https://www.oasis-open.org/committees/uddi-spec/doc/tn/uddi-spec-tc-tn-wsdl-v202-20040631.htm). The jUDDI-client provides a convenient mechanism for this mapping. In addition, the jUDDI team provides a similar API for mapping a WADL (Web Application Description Language) document to UDDI. This guide will help you use the APIs to register a WSDL or WADL document that describes a service within a UDDI registry.
+
+=== Use Case - WSDL
+
+The most basic use case is that we have one or more SOAP/WSDL based services from a 3rd party that was just stood up on our network and we wish to now advertise to our user base that this service exists. We could manually punch in the information, but what fun is that? Let's import it using some code! This can be expanded to import services in bulk.
+
+==== Sample Code
+
+----
+URL url = new URL("http://someURLtoYourWSDL");
+ReadWSDL rw = new ReadWSDL();
+Definition wsdlDefinition = rw.readWSDL(url);
+Properties properties = new Properties();
+properties.put("keyDomain", domain);
+properties.put("businessName", domain);
+properties.put("serverName", url.getHost());
+properties.put("serverPort", url.getPort());
+wsdlURL = wsdlDefinition.getDocumentBaseURI();
+WSDL2UDDI wsdl2UDDI = new WSDL2UDDI(null, new URLLocalizerDefaultImpl(), properties);
+//This creates a the services from WSDL
+BusinessServices businessServices = wsdl2UDDI.createBusinessServices(wsdlDefinition);
+//This creates the tModels from WSDL
+Map<QName, PortType> portTypes = (Map<QName, PortType>) wsdlDefinition.getAllPortTypes();
+//This creates more tModels from WSDL
+Set<TModel> portTypeTModels = wsdl2UDDI.createWSDLPortTypeTModels(wsdlURL, portTypes);
+Map allBindings = wsdlDefinition.getAllBindings();
+//This creates even more tModels from WSDL
+Set<TModel> createWSDLBindingTModels = wsdl2UDDI.createWSDLBindingTModels(wsdlURL, allBindin
+
+//Now just save the tModels, then add the services to a new or existing business
+----
+
+==== Links to sample project
+
+.SVN Links to sample projects
+* http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/
+* http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/wsdl2uddi/
+* http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/uddi-samples/
+
+The examples are also available in both jUDDI distributions.
+
+=== Use Case - WADL
+
+The most basic use case is that we have one or more REST/WADL based services from a 3rd party that was just stood up on our network and we wish to now advertise to our user base that this service exists. We could manually punch in the information, but what fun is that? Let's import it using some code! This can be expanded to import services in bulk.
+
+==== Sample Code
+----
+Application app = WADL2UDDI.ParseWadl(new URL("URL to WADL file"));
+List<URL> urls = WADL2UDDI.GetBaseAddresses(app);
+URL url = urls.get(0);
+String domain = url.getHost();
+Properties properties = new Properties();
+properties.put("keyDomain", domain);
+properties.put("businessName", domain);
+properties.put("serverName", url.getHost());
+properties.put("serverPort", url.getPort());
+WADL2UDDI wadl2UDDI = new WADL2UDDI(null, new URLLocalizerDefaultImpl(), properties);
+
+//creates the services
+BusinessService businessServices = wadl2UDDI.createBusinessService(new QName("MyWasdl.namespace", "Servicename"), app);
+//creates tModels (if any)
+Set<TModel> portTypeTModels = wadl2UDDI.createWADLPortTypeTModels(wsdlURL, app);
+//Now just save the tModels, then add the services to a new or existing business
+----
+
+
+==== Links to sample project
+
+.SVN Links to sample projects
+* http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/
+* http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/uddi-samples/
+
+The examples are also available in both jUDDI distributions.
\ No newline at end of file
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideSimplePublishingUsingthejUDDIAPI.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideSimplePublishingUsingthejUDDIAPI.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideSimplePublishingUsingthejUDDIAPI.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideSimplePublishingUsingthejUDDIAPI.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,249 @@
+== Simple Publishing Using the jUDDI API
+
+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.
+
+=== UDDI Data Model
+
+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.
+
+Below is a great diagram of the UDDI data model (taken directly from the specification):
+http://juddi.apache.org/docs/3.x/userguide/html/images/uddi_core_datastructures.gif
+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.
+
+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.
+
+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.)
+
+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.
+
+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.
+
+=== jUDDI Additions to the Model
+
+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.
+
+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.
+
+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.
+
+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.
+
+TIP: In UDDI, 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. In jUDDI, the authorizedName field translates to the person's username, also know as the publisher id,
+
+
+=== UDDI and jUDDI API
+
+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.
+
+UDDI divides their API into several "sets" - each representing a specific area of functionality. The API sets are listed below:
+
+* Inquiry - deals with querying the registry to return details on entities within
+* Publication - handles publishing entities into the registry
+* Security - open-ended specification that handles authentication
+* Custody and Ownership Transfer - deals with transferring ownership and custody of entities
+* Subscription - allows clients to retrieve information on entities in a timely manner using a subscription format
+* Subscription Listener - client API that accepts subscription results
+* Value Set (Validation and Caching)- validates keyed reference values (not implemented by jUDDI)
+* Replication - deals with federation of data between registry nodes (not implemented by jUDDI)
+The most commonly used APIs are the Inquiry, Publication and Security APIs. These APIs provide the standard functions for interacting with the registry.
+
+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.
+
+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.
+
+=== Getting Started
+
+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 http://apachejuddi.blogspot.com/2010/02/getting-started-with-juddi-v3.html article that explains how to start the jUDDI server.
+
+==== Simple Publishing Example
+
+We will now go over the "simple-publish" examples. These examples expand upon the HelloWorld example in that after retrieving an authentication token, a BusinessEntity and BusinessService are published to the registry. There are two examples:
+
+ - simple-publish-portal - This is how to perform the publish operations in a way that's portable, meaning that the code logic should apply to any UDDIv3 client application library.
+ - simple-publish-clerk - This shows you how to perform the same actions using the helper functions in jUDDI's Client library, which greatly reduces the code required and makes things simple. This uses the UDDIClerk's functions.
+
+===== Simple Publishing using Portable Code
+
+The complete source for this example can be found here:
+ - Portable http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/simple-publish-portable/
+
+----
+ public SimplePublishPortable() {
+ try {
+ // create a client and read the config in the archive;
+ // you can use your config file name
+ UDDIClient uddiClient = new UDDIClient("META-INF/uddi.xml");
+ // a UddiClient can be a client to multiple UDDI nodes, so
+ // supply the nodeName (defined in your uddi.xml.
+ // The transport can be WS, inVM, RMI etc which is defined in the uddi.xml
+ Transport transport = uddiClient.getTransport("default");
+ // Now you create a reference to the UDDI API
+ security = transport.getUDDISecurityService();
+ publish = transport.getUDDIPublishService();
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+----
+
+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.
+
+Once the transport is instantiated, we grab the two API sets we need for this demo: 1) the Security API set so we can get authorization tokens and 2) the Publication API set so we can actually publish entities to the registry.
+
+All the magic happens in the publish method. We will look at that next.
+
+Here are the first few lines of the publish method:
+----
+ // Login aka retrieve its authentication token
+ GetAuthToken getAuthTokenMyPub = new GetAuthToken();
+ getAuthTokenMyPub.setUserID("bob"); //your username
+ getAuthTokenMyPub.setCred("bob"); //your password
+ AuthToken myPubAuthToken = security.getAuthToken(getAuthTokenMyPub);
+ System.out.println(getAuthTokenMyPub.getUserID() + "'s AUTHTOKEN = " + "******* never log auth tokens!");
+----
+
+IMPORTANT: Don't log authentication tokens. In addition, whenever you're done with it, it should be 'discarded'. Think of it as a logout function.
+
+This code simply gets the authorization token for the 'bob' user.
+
+TIP: jUDDI includes two reserved usernames, 'uddi' and 'root'. Root 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. The user 'uddi' owns the remaining preinstalled data.
+
+Now that we have Bob's authorization, we can start publishing.
+
+TIP: You'll note that no credentials have been set on both authorization calls. This is because we're using the default authenticator (which is for testing purposes doesn't require credentials). Most UDDI servers will require authentication.
+
+----
+ // 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...
+ // <snip> We removed some stuff here to make the example shorter, check out the source for more info</snip>
+
+ // 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);
+
+ //and we're done, don't forget to logout!
+ security.discardAuthToken(new DiscardAuthToken(myPubAuthToken.getAuthInfo()));
+----
+
+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. 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.
+
+===== Simple Publishing using Clerks
+
+The complete source for this example can be found here:
+ - Clerk http://svn.apache.org/repos/asf/juddi/trunk/juddi-examples/simple-publish-clerk/
+
+The sample consists of only one class: SimplePublishPortable. Let's start by taking a look at the constructor:
+
+
+----
+ public SimplePublishClerk() {
+ try {
+ // create a client and read the config in the archive;
+ // you can use your config file name
+ UDDIClient uddiClient = new UDDIClient("META-INF/uddi.xml");
+ //get the clerk
+ clerk = uddiClient.getClerk("default");
+ if (clerk==null)
+ throw new Exception("the clerk wasn't found, check the config file!");
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+----
+
+Notice that this is already much more streamlined than the previous example. In this scenario, all configuration settings and credentials are stored in "META-INF/uddi.xml".
+
+TIP: The configuration file used by clients can be overridden via the system property "uddi.client.xml". E.g. java -Duddi.client.xml=/usr/local/uddi.xml -jar MyCoolProgram.jar
+
+UDDIClient's job is to read the configuration file and initialize the data structures for working with 1 or more UDDI nodes (or servers). It also handles automatic registration of endpoints using WSDL documents or using class annotations. UDDIClerk's job is to manage credentials and to perform a number of common tasks. Feel free to use them in your programs and help you simplify things.
+
+The UDDIClerk also handle credentials and authentication to UDDI for you. If you didn't want to store credentials (it can be encrypted) then you can specify them at runtime very easily.
+
+Moving on, the next function is Publish. Here's the short short version.
+
+----
+public void publish() {
+ try {
+ // 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);
+ //<snip>we removed a bunch of useful stuff here, see the full example for the rest of it</snip>
+
+ //register the business, if the return value is null, something went wrong!
+ BusinessEntity register = clerk.register(myBusEntity);
+ //don't forget to log out!
+ clerk.discardAuthToken();
+ if (register == null) {
+ System.out.println("Save failed!");
+ System.exit(1);
+ }
+ // Now you have a business and service via
+ // the jUDDI API!
+ System.out.println("Success!");
+
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+
+----
+
+The UDDIClerk has a register and unregister function for nearly everything for UDDI. Between the UDDIClient and UDDIClerk, there's enough helper functions to significantly reduce the amount of code needed to work with UDDI. Here's a quick list of things they can do for you:
+
+ * Create a tModel Partition, also know as a Key Generator
+ * Resolve endpoints from WSDLs, Hosting directors, and other binding template references from Access Points http://uddi.org/pubs/uddi-v3.0.2-20041019.htm#_Toc85908385
+ * Get Bindings by Version
+ * Add REST or SOAP tModels to a binding template
+ * Setup asynchronous callbacks for subscriptions
+ * Compare the values of a tModel Instance Info, such as Quality of Service Metrics
+ * Create and register services using a WADL or WSDL document
+ * And more...
+
+We're also looking for the next thing to add to the client library. Have an idea? Please open a ticket on jUDDI's Issue Tracker at https://issues.apache.org/jira/browse/JUDDI.
+
+==== About UDDI Entity Keys
+
+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:
+
+uddi:juddi.apache.org:(generated GUID/UUID)
+
+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, we have 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 we would not have to set the parent business key.
+
+
+=== A few tips on adding Binding Templates
+
+Arguably, the most useful useful part of UDDI is advertising your services similar to a phone book or directory. The important part really isn't that Bob's Business exists (BusinessEntity), it's that Bob provides a service (BusinessService) and it's located at this address. This is where the Binding Template comes it. It identifies an instance of a service, its location and any other metadata associated with the endpoint that someone may want to know.
+
+This article skips the binding Template data because it can be lengthy, but the full source for these examples shows you exactly how to build and add binding templates.
+
+=== Conclusion
+
+Hopefully this added clarity to the question, "How do I publish a service using jUDDI?".
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideTCKRunner.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideTCKRunner.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideTCKRunner.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideTCKRunner.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,65 @@
+== Using the UDDI Technology Compatibility Kit
+
+Since UDDI is a specification with many complex rules in it, we (the jUDDI team) have had to write test cases to exercise each of the rules and restrictions in UDDI. Knowing that there are a number of open source and commercial UDDI v3 implementations, the jUDDI team took this as an opportunity to create a reusable benchmark for testing the compatibility of UDDI v3 implementations.
+
+IMPORTANT: Although the TCK covers a large number of test cases, the UDDI specification is long and complex. It's more than possible that we missed a few scenarios or test cases. If you run across any, please let us know.
+
+=== Using the TCK Runner
+
+The TCK Runner requires a few files to operate:
+
+ . juddi-tck-runner-version.jar - This is the executable
+ . uddi.xml - This file sets the location of the UDDI services
+ . tck.properties - This file controls what tests are ran.
+ . truststore and keystore.jks - These files are for digital signature tests
+
+==== Configuration
+
+ - Edit the uddi.xml file and update all of the UDDI endpoint locations for all supported endpoints of UDDI server being tested. Ignore all credentials and other settings
+ - Edit tck.properties and update the usernames and passwords of the test users. Enable or disable tests based on the whether or not the UDDI server supports the optional listed capabilities.
+
+TIP: Do not use usernames and passwords that already have data associated with it.
+
+A few of the test cases, such as RMI transport, are not identified by the UDDI specification, therefore the results may be skewed if unsupported tests are attempted. In addition, the UDDI specification identifies a number of APIs and features that are considered optional.
+
+Although it is possible to run the TCK against a UDDIv2 registry using the UDDIv2 transport adapters, this is not supported. The TCK's test cases and rules apply to the business rules defined in UDDIv3. Unsupported and unmapped functions defined in UDDIv3 that are not supported in UDDIv2 fail ultimately fail.
+
+===== tck.properties
+
+The TCK properties file contains settings for all of the TCK tests.
+
+ . Credentials - You'll need credentials for a number of user accounts
+ . jUDDI optional tests - If you're running the tests against jUDDI, there's a number of additional tests ran to exercise things like user accounts.
+ . Load testing - These settings enable you to tweak or disable the load testing.
+ . Key stores - These are needed to run the digital signature tests
+ . Supported transports - jUDDI supports a number of transports, such as RMI and HTTP (for UDDI service interaction) and SMTP and HTTP for subscription callbacks. RMI is actually not in the spec and SMTP is considered optional, so you'll want to adjusted these based on the available documentation from the vendor.
+
+===== uddi.xml
+
+The only parts used from uddi.xml are the following
+
+ . The endpoints of the UDDI services
+ . The client subscription callback settings
+
+==== Running the TCK Runner
+
+Executing the TCK runner is simple.
+
+----
+java (options) -Duddi.client.xml=uddi.xml -jar juddi-tck-runner-{VERSION}-SNAPSHOT-jar-with-dependencies.jar
+----
+
+Optional parameters
+
+ * -Ddebug=true - this turns up the logging output, typically including the XML payloads of each message.
+ * -Duddi.client.xml=uddi.xml - Use this file as the jUDDI Client config file. This specifies where all of the UDDI endpoints are.
+ * -Dtck.properties=file.properties - Use this to use an alternate tck properties file.
+
+=== Analyzing the Results
+
+There are two ways to identify the result of the tests.
+
+ * Analyze the console output
+ * Review the test results in uddi-tck-results-[DateTime].txt
+
+The results are summarized in the uddi-tck-results file along with the specific error conditions and stack traces that will enable you to find out the root cause of the failure. It may be necessary to obtain UDDI server logs to help with root cause identification.
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIMigrationTool.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIMigrationTool.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIMigrationTool.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIMigrationTool.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,92 @@
+== UDDI Migration and Backup Tool
+
+The UDDI Migration and Backup Tool can be used to perform a number of administrative tasks such as
+
+ - Backup the contents of a UDDI server (business, services, binding templates and tModels)
+ - Import contents into a UDDI server (business, services, binding templates and tModels)
+
+In addition, the migration tool has a few features that serve as job aids.
+
+ - Ability to remove digital signatures on Import or Export
+ - Ability to maintain ownership properties of UDDI entries
+ - Ability to export and import Publishers (jUDDI only)
+ - Automatically skip an item on import if the entity key already exists
+
+The UDDI Migration and Backup Tool is Command Line Interface program and has a number of use cases such as:
+
+* Copying data from one registry to another
+* Migrating from one vendor to another
+* Periodic backups
+* Upgrades to jUDDI
+
+TIP: The migration tool will not overwrite data when importing.
+
+
+=== Using the tool
+
+There are many configuration options and settings for the migration tool. This tool is distributed with the uddi client distribution package.
+
+==== Get help
+
+----
+>java -jar juddi-migration-tool-3.2.0-SNAPSHOT-jar-with-dependencies.jar
+This tool is used to export and import UDDI data from a UDDI v3 registry
+Random TIP: Without the preserveOwnership flag, all imported data will be owned by the username that imported it.
+
+usage: java -jar juddi-migration-tool-(VERSION)-jar-with-dependencies.jar
+ -business <arg> Im/Export option, file to store the business data,
+ default is 'business-export.xml'
+ -config <arg> Use an alternate config file default is 'uddi.xml'
+ -credFile <arg> Import option with -preserveOwnership, this is a
+ properties file mapping with user=pass
+ -export Exports data into a UDDIv3 registry
+ -import Imports data into a UDDIv3 registry
+ -isJuddi Is this a jUDDI registry? If so we can in/export
+ more stuff
+ -mappings <arg> Im/Export option, file that maps keys to owners,
+ default is 'entityusermappings.properties'
+ -myItemsOnly Export option, Only export items owned by yourself
+ -node <arg> The node 'name' in the config, default is 'default'
+ -pass <arg> Password, if not defined, those is uddi.xml will be
+ used
+ -preserveOwnership Im/Export option, saves owership data to the
+ 'mappings' file
+ -publishers <arg> jUDDI only - In/Export option, file to store
+ publishers, default is 'publishers-export.xml'
+ -stripSignatures Im/Export option, removes digital signatures from
+ all signed items, default is false
+ -tmodel <arg> Im/Export for tmodels, file to store tmodel data,
+ default is 'tmodel-export.xml'
+ -user <arg> Username, if not defined, those is uddi.xml will be
+ used
+----
+
+==== Use case: basic import and export
+
+To export everything without preserving ownership information:
+
+----
+java -jar juddi-migration-tool-(VERSION)-jar-with-dependencies.jar -export
+----
+
+To import everything without preserving ownership information:
+
+----
+java -jar juddi-migration-tool-(VERSION)-jar-with-dependencies.jar -import
+----
+
+==== Use case: Import and Export while preserving ownership information
+
+To export everything with preserving ownership information:
+
+----
+java -jar juddi-migration-tool-(VERSION)-jar-with-dependencies.jar -export -preserveOwnership
+----
+
+To import everything with preserving ownership information, first edit the mappings file which is entityusermappings.properties by default. Once every user has a password, run the following command
+
+----
+java -jar juddi-migration-tool-(VERSION)-jar-with-dependencies.jar -import -preserveOwnership
+----
+
+TIP: When preserving ownership information, upon import, you'll need every UDDI entity owner's password. If you don't have this and you're using jUDDI, you can temporarily switch jUDDI to the 'DefaultAuthenticator' which doesn't validate passwords (just put anything in the mappings file for each user). Once the import is complete, you can then switch back to whatever authenticator you were using before.
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIv2Services.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIv2Services.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIv2Services.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideUDDIv2Services.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,48 @@
+== Using the UDDI v2 Services and Adapters
+
+=== Introduction
+
+Starting with jUDDI version 3.2, a number of adapters are provided to help you use or access UDDI version 2 based services. There are a multitude of options and will be discussed in the following sections.
+
+=== Accessing UDDI v2 services using the jUDDI v3 Client
+
+Accessing UDDI v2 services via the jUDDI v3 client is quite simple. All that's required is modification of the uddi.xml client configuration file. Simply set the transport to:
+
+----
+org.apache.juddi.v3.client.transport.JAXWSv2TranslationTransport
+----
+
+...and adjust the 'inquiryUrl' and 'publishUrl' URL endpoints.
+
+TIP: When accessing UDDI v2, Custody Transfer, Subscription, Replication and Value Set APIs will not be available and may generate unexpected behavior. The UDDIv3 Inquiry getOperationalInfo method is only partially mapped.
+
+That's it. No code changes are required other than to avoid Custody Transfer, Subscription, Replication and Value Set APIs. In addition, digital signatures are not mapped.
+
+=== Accessing UDDI v2 services using UDDI v2 APIs
+
+The jUDDI v3 client now contains the UDDI 2 web service clients. Although, there isn't currently a configuration/transport/client/clerk wrapper for it, you can still get access to web service clients with the following code:
+----
+org.apache.juddi.v3.client.UDDIServiceV2 svc = new UDDIServiceV2();
+Inquire port = svc.getInquire();
+((BindingProvider) port).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/juddiv3/services/inquiryv2");
+Publish pub= svc.getPublish();
+((BindingProvider) pub).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/juddiv3/services/publishv2");
+----
+
+All you need to reference the following projects/jars from jUDDI:
+
+* juddi-client
+* uddi-ws
+
+=== Accessing jUDDI v3 services from an existing UDDI v2 based client, plugin or tool
+
+When UDDI v2 was release, many application developers jumped on board to support it. As such, there are many UDDI v2 tools that exist, such as IDE plugins like Eclipse's Web Services Explorer. To support legacy tools, jUDDI now offers UDDI v2 endpoints. Simple point your tool at the following URLs. You'll have to alter them to match your environment.
+
+----
+http://localhost:8080/juddiv3/services/inquiryv2
+http://localhost:8080/juddiv3/services/publishv2
+----
+
+=== Additional Information
+
+The UDDI v2 adapters provide basic mappings from to and from UDDI v3. The juddi-client has several mapping functions that are used both client and service side to convert from UDDI v2 to UDDI v3. In addition, the client has as several interface adapters to help with a seamless transition.
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingUDDIAnnotationstoAutomateRegistration.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingUDDIAnnotationstoAutomateRegistration.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingUDDIAnnotationstoAutomateRegistration.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingUDDIAnnotationstoAutomateRegistration.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,152 @@
+== Using UDDI Annotations
+Conventionally Services (BusinessService) and their EndPoints (BindingTemplates) are registered to a UDDI Registry using a GUI, where an admin user manually adds the necessary info. This process tends to make the data in the Registry rather static and the data can grow stale over time. To make the data in the UDDI more dynamic it makes sense to register and EndPoint (BindingTemplate) when it comes online, which is when it gets deployed. The UDDI annotations are designed to just that: register a Service when it get deployed to an Application Server. There are two annotations: UDDIService, and UDDIServiceBinding. You need to use both annotations to register an EndPoint. Upon undeployment of the Service, the EndPoint will be de-registered from the UDDI. The Service information stays in the UDDI. It makes sense to leave the Service level information in the Registry since this reflects that the Service is there, however there is no EndPoint at the moment ("Check back later"). It is a man
ual process to remove the Service information. The annotations use the juddi-client library which means that they can be used to register to any UDDIv3 registry.
+
+=== UDDI Service Annotation
+The UDDIService annotation is used to register a service under an already existing business in the Registry. The annotation should be added at the class level of the java class.
+
+.UDDIService attributes
+[options="header"]
+|======================================
+|attribute| description| required
+|serviceName| The name of the service, by default the clerk will use the one name specified in the WebService annotation| no
+|description| Human readable description of the service| yes
+|serviceKey| UDDI v3 Key of the Service| yes
+|businessKey| UDDI v3 Key of the Business that should own this Service. The business should exist in the registry at time of registration| yes
+|lang| Language locale which will be used for the name and description, defaults to "en" if omitted| no
+|categoryBag| Definition of a CategoryBag, see below for details| no
+|======================================
+
+
+
+=== UDDIServiceBinding Annotation
+The UDDIServiceBinding annotation is used to register a BindingTemplate to the UDDI registry. This annotation cannot be used by itself. It needs to go along side a UDDIService annotation.
+
+.UDDIServiceBinding attributes
+[options="header"]
+|======================================
+|attribute| description| required
+|bindingKey| UDDI v3 Key of the ServiceBinding| yes
+|description| Human readable description of the service| yes
+||accessPointType UDDI v3 AccessPointType, defaults to wsdlDeployment if omitted| no
+|accessPoint| Endpoint reference| yes
+|lang| Language locale which will be used for the name and description, defaults to "en" if omitted| no
+|tModelKeys| Comma-separated list of tModelKeys key references| no
+|categoryBag| Definition of a CategoryBag, see below for further details| no
+|======================================
+
+==== Java Web Service Example
+The annotations can be used on any class that defines a service. Here they are added to a WebService, a POJO with a JAX-WS 'WebService' annotation.
+----
+package org.apache.juddi.samples;
+
+import javax.jws.WebService;
+import org.apache.juddi.v3.annotations.UDDIService;
+import org.apache.juddi.v3.annotations.UDDIServiceBinding;
+
+@UDDIService(
+ businessKey="uddi:myBusinessKey",
+ serviceKey="uddi:myServiceKey",
+ description = "Hello World test service")
+@UDDIServiceBinding(
+ bindingKey="uddi:myServiceBindingKey",
+ description="WSDL endpoint for the helloWorld Service. This service is used for "
+ + "testing the jUDDI annotation functionality",
+ accessPointType="wsdlDeployment",
+ accessPoint="http://localhost:8080/juddiv3-samples/services/helloworld?wsdl")
+@WebService(
+ endpointInterface = "org.apache.juddi.samples.HelloWorld",
+ serviceName = "HelloWorld")
+
+public class HelloWorldImpl implements HelloWorld {
+ public String sayHi(String text) {
+ System.out.println("sayHi called");
+ return "Hello " + text;
+ }
+}
+----
+On deployment of this WebService, the juddi-client code will scan this class for UDDI annotations and take care of the registration process. The configuration file uddi.xml of the juddi-client is described in the chapter, Using the jUDDI-Client. In the clerk section you need to reference the Service class 'org.apache.juddi.samples.HelloWorldImpl':
+----
+<clerk name="BobCratchit" node="default" publisher="sales" password="sales">
+ <class>org.apache.juddi.samples.HelloWorldImpl</class>
+</clerk>
+----
+which means that Bob is using the node connection setting of the node with name "default", and that he will be using the "sales" publisher, for which the password it "sales". There is some analogy here as to how datasources are defined.
+
+==== Wiring it all together
+
+The mechanism that triggers the automated registration is the UDDIClient. For each class you annotation, the class needs to be listed in the jUDDI Client Configuration file. When the client reads in the configuration, it will read the uddi.xml config file for the following location:
+----
+client/clerks/clerk[].class
+----
+In addition, the following flag must be set to true.
+----
+client/clerks@registerOnStartup="true"
+----
+Here's a full example
+----
+<clerks registerOnStartup="false" >
+ <clerk name="default" node="default" publisher="userjoe" password="******" cryptoProvider="" isPasswordEncrypted="false">
+ <class>com.mybiz.services.Service1</class>
+ </clerk>
+</clerks>
+----
+
+The next step is to automate the "starting" and "stopping" of UDDIClient. In Java, anything that runs in a servlet container and use the following servlet class:
+----
+org.apache.juddi.v3.client.config.UDDIClerkServlet
+----
+It will automatically handle registration on start up and it will remove binding Templates on shutdown (this ensuring clients that discover the endpoint won't find a dead link).
+
+Clients that run elsewhere simply need to "start" the UDDIClient.
+----
+//start up
+UDDIClient clerkManager = new UDDIClient("META-INF/uddi.xml");
+// register the clerkManager with the client side container
+UDDIClientContainer.addClient(clerkManager);
+clerkManager.start(); //will create business/services/bindings as necessary
+
+//shutdown down
+clerkManager.stop(); //will unregister binding templates
+----
+
+
+=== .NET Web Service Example
+
+In .NET, the procedure is almost identical to Java. Annotate your web service classes, append the classnames to your uddi.xml client config file. .NET annotations work with any WCF, ASP.NET or any other class.
+
+==== Wiring it all together
+
+In .NET, there's a few options, each with pro's and con's for automating registration.
+
+===== Use UDDIClient in your service's constructor
+Pro: It's simple
+Con: Services often get multiple instances depending on the number of worker threads in the server and thus can cause some concurrency issues.
+
+===== Use UDDIClient in Global.asa Application_Start
+Pro: It's simple
+Con: You need .NET 4.0 and ASP.NET enabled in order to utilize this function
+
+More information about this can be found here: http://weblogs.asp.net/scottgu/archive/2009/09/15/auto-start-asp-net-applications-vs-2010-and-net-4-0-series.aspx
+
+
+=== CategoryBag Attribute
+The CategoryBag attribute allows you to reference tModels. For example the following categoryBag
+----
+<categoryBag>
+ <keyedReference tModelKey="uddi:uddi.org:categorization:types"
+ keyName="uddi-org:types:wsdl" keyValue="wsdlDeployment" />
+ <keyedReference tModelKey="uddi:uddi.org:categorization:types"
+ keyName="uddi-org:types:wsdl2" keyValue="wsdlDeployment2" />
+</categoryBag>
+----
+can be put in like
+----
+categoryBag="keyedReference=keyName=uddi-org:types:wsdl;keyValue=wsdlDeployment;" +
+ "tModelKey=uddi:uddi.org:categorization:types," +
+ "keyedReference=keyName=uddi-org:types:wsdl2;keyValue=wsdlDeployment2;" +
+ "tModelKey=uddi:uddi.org:categorization:types2",
+----
+
+=== Considerations for clustered or load balanced web servers and automated registration
+
+Most production environments have primary and failover web servers and/or an intelligent load balancer that routers traffic to whichever server is online. When using automated registration with the jUDDI client, care must be taken when enabling automated registration.
Added: juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingjUDDIRestServices.asciidoc
URL: http://svn.apache.org/viewvc/juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingjUDDIRestServices.asciidoc?rev=1564021&view=auto
==============================================================================
--- juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingjUDDIRestServices.asciidoc (added)
+++ juddi/docs/trunk/ClientGuide/en-US/ClientGuideUsingjUDDIRestServices.asciidoc Mon Feb 3 19:34:34 2014
@@ -0,0 +1,210 @@
+== Using the jUDDI REST Services
+
+jUDDI includes a Inquiry API adapter that exposes some of the basic functionality of UDDI via REST. Data can be retrieved in both XML and JSON encoding for all methods.
+
+=== URL Patterns and methods
+
+. All jUDDI Inquiry REST service are accessible via HTTP GET.
+. Authentication is not yet supported. This also implies that the Inquiry API must be configured for anonymous access (i.e. do not turn on Inquiry Authentication Required).
+. The jUDDI Inquiry REST service is not currently portable as an adapter to other UDDI instances (but it could be adapted to it in the future)
+
+==== Endpoints
+
+All endpoints must be prefixed with http(s)://server:port/juddicontext/ where 'juddicontext' is typically 'juddiv3'.
+
+WADL Document: http://localhost:8080/juddiv3/services/inquiryRest?_wadl
+
+TIP: All of the examples in this document reference JSON encoded messages. To switch to XML messages, just replace the 'JSON' with 'XML' in the URL. That's it!
+
+==== Methods
+
+Each method is accessible using the following pattern:
+
+----
+http://localhost:8080/juddiv3/services/inquiryRest/{encoding}/{method}/{parameters}
+//or
+http://localhost:8080/juddiv3/services/inquiryRest/{encoding}/{method}?{name=value}
+----
+Notes
+
+* Encoding - Can be 'XML' or 'JSON'
+* Methods - See below
+* Parameters - usually a unique UDDI key
+
+===== xxxList
+
+Returns up to 100 items within a KeyBag object, containing a list of all keys for the given object type.
+
+. serviceList - http://localhost:8080/juddiv3/services/inquiryRest/JSON/serviceList
+. businessList - http://localhost:8080/juddiv3/services/inquiryRest/JSON/businessList
+. tModelList - http://localhost:8080/juddiv3/services/inquiryRest/JSON/tModelList
+
+===== endpointsByService/key
+
+Returns all executable endpoints for a given service key, including all binding Templates. This also resolves hosting redirector and a number of other accessPoint useType specifics.
+
+Example:
+
+----
+http://localhost:8080/juddiv3/services/inquiryRest/JSON/endpointsByService/uddi:juddi.apache.org:services-custodytransfer
+----
+
+===== getDetail
+
+Return the details of a specific item using query parameters. This implements the UDDI recommendation for HTTP GET services for UDDI. See http://uddi.org/pubs/uddi-v3.0.2-20041019.htm#_Toc85908158 for further information.
+
+Example:
+----
+http://localhost:8080/juddiv3/services/inquiryRest/XML/getDetail?businessKey=uddi:juddi.apache.org:businesses-asf
+----
+
+The following query parameters are supported. Only one can be specified at a time
+
+. businessKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/getDetail?businessKey=uddi:juddi.apache.org:businesses-asf
+. tModelKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/getDetail?tModelKey=uddi:uddi.org:categorization:types
+. bindingKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/getDetail?bindingKey=uddi:juddi.apache.org:servicebindings-inquiry-ws
+. serviceKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/getDetail?serviceKey=uddi:juddi.apache.org:services-inquiry
+
+===== xxxKey
+
+Return the details of a specific item. This is similar to getDetail except that it is not based on query parameters. The underlying code of this function is the same as getDetail.
+
+Example:
+
+. businessKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/businessKey/uddi:juddi.apache.org:businesses-asf
+. tModelKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/tModelKey/uddi:uddi.org:categorization:types
+. bindingKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/bindingKey/uddi:juddi.apache.org:servicebindings-inquiry-ws
+. serviceKey/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/serviceKey/uddi:juddi.apache.org:services-inquiry
+. opInfo/(key) - http://localhost:8080/juddiv3/services/inquiryRest/JSON/opInfo/uddi:juddi.apache.org:businesses-asf
+
+===== xxxSearch
+
+Returns the search results for registered entities in XML or JSON using a number of query parameters.
+
+Supported entities:
+ . searchService
+ . searchBusiness
+ . searchTModel
+
+Supported query parameters
+ . name - Filters by the name element. If not specified, the wildcard symbol is used '%'.
+ . lang - Filters by language. If not specified, null is used.
+ . findQualifiers - Adds sorting or additional find parameters. comma delimited. If not specified, 'approximateMatch' is used
+ . maxrows - Maximum rows returned. If not specified, 100 is used.
+ . offset - Offset for paging operations. If not specified, 0 is used.
+
+=== Example Output
+
+
+==== XML
+
+The output of all XML encoded messages is identical to the UDDI schema specifications. There should be no surprises.
+
+==== JSON
+
+The output of JSON encoded messages is obviously different than XML. The following is an example of what it looks like.
+----
+{
+ "businessEntity": {
+ "@businessKey": "uddi:juddi.apache.org:businesses-asf",
+ "discoveryURLs": {
+ "discoveryURL": {
+ "@useType": "homepage",
+ "$": "http://localhost:8080/juddiv3"
+ }
+ },
+ "name": {
+ "@xml.lang": "en",
+ "$": "An Apache jUDDI Node"
+ },
+ "description": {
+ "@xml.lang": "en",
+ "$": "This is a UDDI v3 registry node as implemented by Apache jUDDI."
+ },
+ "businessServices": {
+ "businessService": [
+ {
+ "@serviceKey": "uddi:juddi.apache.org:services-custodytransfer",
+ "@businessKey": "uddi:juddi.apache.org:businesses-asf",
+ "name": {
+ "@xml.lang": "en",
+ "$": "UDDI Custody and Ownership Transfer Service"
+ },
+ "description": {
+ "@xml.lang": "en",
+ "$": "Web Service supporting UDDI Custody and Ownership Transfer API"
+ },
+ "bindingTemplates": {
+ "bindingTemplate": [
+ {
+ "@bindingKey": "uddi:juddi.apache.org:servicebindings-custodytransfer-ws",
+ "@serviceKey": "uddi:juddi.apache.org:services-custodytransfer",
+ "description": "UDDI Custody and Ownership Transfer API V3",
+ "accessPoint": {
+ "@useType": "wsdlDeployment",
+ "$": "http://localhost:8080/juddiv3/services/custody-transfer?wsdl"
+ },
+ "tModelInstanceDetails": {
+ "tModelInstanceInfo": {
+ "@tModelKey": "uddi:uddi.org:v3_ownership_transfer",
+ "instanceDetails": {
+ "instanceParms": "\n \n <?xml version=\"1.0\" encoding=\"utf-8\" ?>\n <UDDIinstanceParmsContainer\n xmlns=\"urn:uddi-org:policy_v3_instanceParms\">\n <authInfoUse>required</authInfoUse>\n </UDDIinstanceParmsContainer>\n \n "
+ }
+ }
+ },
+ "categoryBag": {
+ "keyedReference": {
+ "@tModelKey": "uddi:uddi.org:categorization:types",
+ "@keyName": "uddi-org:types:wsdl",
+ "@keyValue": "wsdlDeployment"
+ }
+ }
+ },
+ {
+ "@bindingKey": "uddi:juddi.apache.org:servicebindings-custodytransfer-ws-ssl",
+ "@serviceKey": "uddi:juddi.apache.org:services-custodytransfer",
+ "description": "UDDI Custody and Ownership Transfer API V3 SSL",
+ "accessPoint": {
+ "@useType": "wsdlDeployment",
+ "$": "https://localhost:8443/juddiv3/services/custody-transfer?wsdl"
+ },
+ "tModelInstanceDetails": {
+ "tModelInstanceInfo": [
+ {
+ "@tModelKey": "uddi:uddi.org:v3_ownership_transfer",
+ "instanceDetails": {
+ "instanceParms": "\n \n <?xml version=\"1.0\" encoding=\"utf-8\" ?>\n <UDDIinstanceParmsContainer\n xmlns=\"urn:uddi-org:policy_v3_instanceParms\">\n <authInfoUse>required</authInfoUse>\n </UDDIinstanceParmsContainer>\n \n "
+ }
+ },
+ {
+ "@tModelKey": "uddi:uddi.org:protocol:serverauthenticatedssl3"
+ }
+ ]
+ },
+ "categoryBag": {
+ "keyedReference": {
+ "@tModelKey": "uddi:uddi.org:categorization:types",
+ "@keyName": "uddi-org:types:wsdl",
+ "@keyValue": "wsdlDeployment"
+ }
+ }
+ }
+ ]
+ }
+ }
+ ]
+ },
+ "categoryBag": {
+ "keyedReference": {
+ "@tModelKey": "uddi:uddi.org:categorization:nodes",
+ "@keyName": "",
+ "@keyValue": "node"
+ }
+ }
+ }
+}
+
+----
+=== More information
+
+For more information, please check out the source code: http://svn.apache.org/repos/asf/juddi/trunk/juddi-rest-cxf/
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@juddi.apache.org
For additional commands, e-mail: commits-help@juddi.apache.org