<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="uddi">
  <title>UDDI Integration</title>   
       
       <section>
       		<title>Overview</title>

       		<para>
       		The integration of a UDDI client into the RiftSaw runtime codebase allows for the auto-registration
       		of BPEL services to an UDDI registry upon deployment of the service. The registration
       		process uses the jUDDI-3 client libraries which are capable of communicating to any
       		UDDI v3 complaint registry. 
       		</para>
       		
       		<para>Upon deployment both the Service and its BindingTemplate (EndPoint information) are registered, and a
       		partnerLinkChannel is created for each partnerLink. UDDI lookup will obtain the WSDL Endpoint from the
       		UDDI and access this URL to obtain the WSDL straight from the Service. Upon undeployment the 
       		BindingTemplate is removed from the UDDI Registry.
       		</para>
       		
       </section>
  
       <section>
       		<title>UDDI config properties</title>

			<para>
			By default RiftSaw uses the jUDDI client libraries of JBossESB/SOA-P, and the client
			configuration is found in the deploy/jbossesb.saw/esb.juddi.client.xml. Both the
			name of the ClerkManager and the Clerk itself are specified in the
			<emphasis>bpel.properties</emphasis> file.
			</para>
       		
       		<table>
       			<title>The UDDI related properties in the bpel.properties</title>
       			<tgroup cols="3" >
       			<colspec colnum="1" colname="col1" />
				<colspec colnum="2" colname="col2" />
				<colspec colnum="3" colname="col3" />
				<thead>
				<row>
				 	<entry>attribute</entry><entry>type (default)</entry><entry>description</entry>
				</row>
			    </thead>
			    <tbody>
				<row>
	       			<entry>bpel.uddi.registration</entry>
	       			<entry>boolean (true)</entry>
	       			<entry>
	       			If set to 'false', the UDDI integration is turned off. The RiftSaw installation process
	       			sets this value to 'true' only if the jbossesb-registry.sar is detected containing a jUDDI v3
	       			registry. In all other case it is defaulted to false.
	       			</entry>
       			</row>
       			<row>
       				<entry>bpel.webservice.secure</entry>
       				<entry>boolean (false)</entry>
       				<entry>
	       			The UDDI Registration process registers an WSDL AccessPoint in the BindingTemplate for the
	       			BPEL Service it is registering. The BPEL server exposes the service WSDL Endpoint on the
	       			WS stack (Currently we support JBossWS and CXF), if your WS stack is configured to a use
	       			a secure (https) protocol, then you need to switch this setting to 'true'. Note that this
	       			setting is used during the registration process only.
       				</entry>
       			</row>
       			<row>
       				<entry>bpel.uddi.client.impl</entry>
	       			<entry>String (org.jboss.soa.bpel.uddi.UDDIRegistrationImpl)</entry>
       			    <entry>
	       			Name of the a class that implements the org.jboss.soa.bpel.runtime.engine.ode.UDDIRegistration interface.
	       			The RiftSaw installation process set this value to org.jboss.soa.bpel.uddi300.UDDI300RegistrationImpl 
	       			if JBossESB-4.7 is detected. JBossESB-4.7 uses
	       			the jUDDI-3.0.0 client libary, while SOA-P-5.0.0 and future version of JBossESB will use jUDDI-3.0.1 or higher and
	       			for those it is set to org.jboss.soa.bpel.uddi.UDDIRegistrationImpl.
       				</entry>
       			</row>
       			<row>
       				<entry>bpel.uddi.clerk.config</entry>
       				<entry>String (not used by default)</entry>
	       			<entry>
	       			Defines the path to the bpel.uddi.client.xml config file. This can be left commented out if
	       			you want to use the jbossesb.sar/esb.uddi.client.xml. However in that case a bpel.uddi.clerk.manager
	       			needs to be defined.
       				</entry>
       			</row>
       			<row>
       				<entry>bpel.uddi.clerk.manager</entry>
	       			<entry>String (esb-registry)</entry>
	       			<entry>
	       			Defines the ClerkManager name that will be used if the bpel.uddi.clerk.config is left commented out.
	       		    This value should correspond to the name of the manager
	       			in the esb.juddi.client.xml. For JBossESB-4.7 this is 'test-manager', while for SOA-P-5.0.0 
	       			and newer version of JBossESB it is 'esb-registry'. Note that if the bpel.uddi.clerk.config is defined, the
	       			setting of the bpel.uddi.clerk.manager is ignored.
       				</entry>
       			</row>
       			<row>
       				<entry>bpel.uddi.clerk</entry>
       				<entry>String (BPEL_clerk)</entry>
	       			<entry>
	       			Defines the Clerk name that will be used. This value should correspond to the name of the clerk
	       			in the esb.juddi.client.xml. By default this is set to 'BPEL_clerk'.
       				</entry>
       			</row>
       			<row>
       				<entry>bpel.uddi.lookup</entry>
       				<entry>boolean (true)</entry>
       				<entry>
	       			If set to true, the creating process of the partner channel will do a lookup by serviceName in the
	       			UDDI, and a WSDL Endpoint is retrieved. This WSDL Endpoint is then used to obtain the WSDL. This
	       			process makes it easier to move Endpoints around within your deployment, without having to update
	       			the partnerlink WSDL files in your bpel deployments. Note that an it is still a requirement to
	       			deploy the initial partnerlink WSDL file for each partnerLink.
       				</entry>
       			</row>
       			
       			</tbody>
        		</tgroup>
        	</table>
        </section>
        
        <section>
       		<title>Default configurations</title>
       		<para>When RiftSaw is deployed to a JBossAS-5.1.0, jUDDI v3 is not installed, and therefore
       		the UDDI integration is turned off (bpel.uddi.registration=false).</para>
       		
       		<para>When RiftSaw is deployed to JBossAS-5.1.0 + JBossESB-4.7, the UDDI integration is
       		turned on. By default we use the jUDDI client library which ships with the JBossESB, which
       		is configured in the <filename>jbossesb.sar/esb.uddi.client.xml</filename>,
       		with manager name 'test-manager'. The <emphasis>bpel.uddi.client.impl</emphasis> is set 
       		to <emphasis>org.jboss.soa.bpel.uddi300.UDDI300RegistrationImpl</emphasis>.
       		</para>
       		
       		<para>When RiftSaw is deployed to SOA-P-5.0.0 (or JBossESB > 4.7) UDDI integration is
       		turned on and the <emphasis>bpel.uddi.client.impl</emphasis> is set to
       		<emphasis>org.jboss.soa.bpel.uddi.UDDIRegistrationImpl</emphasis>.
       		Again the <filename>jbossesb.sar/esb.uddi.client.xml</filename> is used, with manager name 'esb.registry'.
       		</para>
       	</section>
       	
       	<section>
       		<title>Other UDDI v3 Registries</title>
       		
       		<para>Other UDDI v3 compliant registries can be used, however the UDDIv3 spec only requires
       		communication using the UDDI WebServices. To set up SOAP based communication specify the JAXWS-Transport.
       		At this point it makes sense to no longer use the the esb.uddi.client.xml, but rather use your
       		own <emphasis>bpel.uddi.client.xml</emphasis>. For more details please see the jUDDI v3 documentation.
       		</para>
       	</section>
       	
       	<section>
       		<title>UDDI Registry Entities and UDDI Seed Data</title>
       		
       		<para>In the <filename>esb.uddi.client.xml</filename> a few properties are defined that are used by the Clerk at 
       		registration time. These settings of these values can be customized, however they must
       		correspond to the UDDI seed data specified for the jbossesb publisher, in the 
       		<filename>jbossesb-registry.sar/juddi_custom_install_data</filename>. So you will need to change it there as well.
       		</para>
       		
       		<para>The clerk is configured to use the jbossesb publisher and the <emphasis>keyDomain
       		</emphasis> is set to "esb.jboss.org".
       		</para>
       		
       		<para>The <emphasis>businessKey</emphasis> is set to "redhat-jboss".</para>
       		
            <para>The <emphasis>serviceDescription</emphasis> is set to "BPEL Service deployed by Riftsaw".</para>
            
            <para>The <emphasis>bindingDescription</emphasis> is set to "BPEL Endpoint deployed by Riftsaw".</para>
       		
       		<para>Note that in SOA-P-5 the <filename>jbossesb-registry.sar/esb.uddi.xml</filename> contains a property 
       		<emphasis>juddi.seed.always</emphasis> which is set to "true". This means that that it
       		is always trying to load the root seed data on startup of the server. It is recommended
       		to turn this value to "false" once you are content with the UDDI Seed Data. 
       		</para>
       		
       		
       		<warning><para>When running on JBossESB-4.7, the root seed data will only be installed if the UDDI tables are
       		still empty. This means that you need to make sure that the jUDDI Root Seed Data install process
       		did not run before installing RiftSaw. In other words, do not start JBossESB-4.7 before installing
       		RiftSaw.</para></warning>
       		
       	</section>
       		
</chapter>
