<?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.sar/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 class that implements the <emphasis>org.jboss.soa.bpel.runtime.engine.ode.UDDIRegistration</emphasis> interface.
       				</entry>
       			</row>
       			<row>
       				<entry>bpel.uddi.clerk.config</entry>
       				<entry>String (not used by default)</entry>
	       			<entry>
	       			Defines the path to the <filename>bpel.uddi.client.xml</filename> config file. This can be left commented out if
	       			you want to use the <filename>jbossesb.sar/esb.uddi.client.xml</filename>. However in that case a
	       			<filename>bpel.uddi.clerk.manager</filename> 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 <emphasis>bpel.uddi.clerk.config</emphasis> is left commented out.
	       		    This value should correspond to the name of the manager
	       			in the <filename>esb.juddi.client.xml</filename>. Note that if the <emphasis>bpel.uddi.clerk.config</emphasis> is defined, the
	       			setting of the <emphasis>bpel.uddi.clerk.manager</emphasis> 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 <filename>esb.juddi.client.xml</filename>. 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 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 SOA-P-5.0.0 (or JBossESB 4.8 or higher) UDDI integration is
       		turned on and the <emphasis>bpel.uddi.client.impl</emphasis> is set to
       		<emphasis>org.jboss.soa.bpel.uddi.UDDIRegistrationImpl</emphasis>.
       		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>
       		
       	</section>
       		
</chapter>
