src/site/xdoc/usersguide.xml - juddi - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Copyright 2001-2009 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * 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.
  *
  */ -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
 <document>
   <properties>
     <title>jUDDI User's Guide</title>
   </properties>
   <body>

     <anchor id="requirements"/>
     <section name="Requirements">
       <p>jUDDI is a pure Java web application and as such can be deployed to
         any application server or servlet engine that supports version 2.1 or
         later of the servlet API. If you need an application server, we
         recommend <link href="http://jakarta.apache.org/tomcat/">Jakarta
         Tomcat</link>.  Note also that jUDDI requires Java 1.3 or later. As
         with any Java web application, deployment to your application server
         or servlet engine will vary on a product-by-product basis.
       </p>
       <p>Instructions for deploying jUDDI to several application servers have
         been donated and are available in the <link href="http://wiki.apache.org/ws/jUDDI">HOW-TO</link>
         section of the jUDDI wiki.
       </p>
       <p>jUDDI also requires an external datastore in which to persist the
         registry data it manages.  Typically this is a relational database
         management system such as MySQL, Oracle or DB2. Support for several
         open source and commercial database products are included. See the
         section below titled <link href="#datastore">Persistence</link> for
         more information.
       </p>
     </section>

     <anchor id="config"/>
     <section name="Configuration">
       <p>To properly configure and deploy jUDDI it will be helpful to understand
         a bit about it's architecture. jUDDI consist of a core request processor
         that unmarshalls incoming UDDI requests, invoking the appropriate UDDI
         function and marshalling UDDI responses (marshalling and unmarshalling
         is the process of converting XML data to/from Java objects).
       </p>
       <p>To invoke a UDDI function jUDDI employs the services of three
         configurable sub-components or modules that handle persistence (the
         DataStore), authentication (the Authenticator) and the generation of
         UUID's (the UUIDGen). jUDDI is bundled and pre-configured to use
         default implementations of each of these modules to help your registry
         up and running quickly. These sub-components and a description of
         the default implementations are described below.
       </p>
       <p>Several public Java interfaces for creating your own DataStore,
         Authenticator and UUIDGen module implementations are available. Please
         see the <link href="#moddev">module development</link> section of this
         guide for more information regarding jUDDI module development.
       </p>
     </section>

     <anchor id="datastore"/>
     <section name="Persistence (jUDDI DataStore)">
       <p>jUDDI needs a place to store it's registry data so it should come as
         no surprise that jUDDI is pre-configured to use JDBC and any one of
         several different DBMSs to do this.
       </p>
       <p>The process of setting this up is straight forward. Start by creating
         a new jUDDI database using the instructions for your preferred DBMS
         which you will find in the 'sql' directory of your jUDDI distribution.
         At the time of this writing instructions for the following products
         were available:
       </p>
       <p>
         <ul>
           <li>MySQL</li>
           <li>DB2</li>
           <li>HSQLdb (HypersonicSQL)</li>
           <li>Sybase</li>
           <li>PostreSQL</li>
           <li>Oracle</li>
           <li>TotalXML</li>
           <li>JDataStore (Borland)</li>
         </ul>
       </p>
       <p>If support for your DBMS is not listed you might try posting a message
         to the juddi-user list to see if someone has already developed support
         for it.  You can also try to create the scripts yourself by using the
         instructions for a supported DBMS as a guide. Please consider
         contributing your work back to the project so the next person won't
         have the same issue.
       </p>
       <p>To complete the DataStore set up you'll need to configure a JNDI
         Datasource with a name of <b>'jdbc/juddiDB'</b> in the application
         server or servlet engine that you're deploying to. Datasource setup
         varies on an product-by-product basis so review documentation for
         your application server. If you're deploying to Jakarta Tomcat,  take a
         look at Tomcat's <link  href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html">JNDI
         Datasource HOW-TO</link> for assistance.
       </p>
     </section>

     <anchor id="authenticator"/>
     <section name="Authentication (jUDDI Authenticator)">
       <p>Authenticating a jUDDI publisher is a two-step process. The first step
         confirms that the ID/password combination provided by the user in a
         get_authToken request is valid. The default Authenticator implementation
         simply approves any authentication attempt. It is expected that a
         typical jUDDI deployment will use an external authentication
         mechanism.  It is our hope that additional jUDDI authentication
         implementations will be developed by jUDDI users as they determine how
         they would like authentication to take place in their particular
         environment. See the jUDDI Developers Guide for more information on
         developing a custom jUDDI authentication module for your environment.
       </p>
       <p>The second step confirms that the publisher has been defined to
         jUDDI. A publisher is said to be defined when a row identifying the
         publisher exists in the PUBLISHER table of the jUDDI datastore. At the
         moment the only way to do this is via SQL. An example of defining a
         new publisher named John Doe would look like this:
       </p>
       <p>
         <b>
         <pre>
           INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,ADMIN,ENABLED)
           VALUES ('jdoe','John Doe','false','true');
         </pre>
         </b>
       </p>
       <p>The PUBLISHER table consists of several columns but only four of them
         are required and they are defined as follows:
       </p>
       <p>
         <table>
          <tr><th>Column Name</th><th>Description</th></tr>
          <tr><td>PUBLISHER_ID</td><td>The user ID the publisher uses when authenticating. IMPORTANT: This should be the same value used to authenticate with the external authentication service.</td></tr>
          <tr><td>PUBLISHER_NAME</td><td>The publisher's name (or in UDDI speak the Authorized Name).</td></tr>
          <tr><td>ADMIN</td><td>Indicate if the publisher has administrative privileges. Valid values for this column are 'true' or 'false'. The ADMIN value is currently not used.</td></tr>
          <tr><td>ENABLED</td><td>Indicate if the publishers account is enabled and eligible for use.</td></tr>
         </table>
       </p>
       <p>The jUDDI web application will (eventually) be extended to facilitate
         the Publisher creation process. The value of the ADMIN column in the
         PUBLISHER table above will be used to determine who has the privilege
         to create new jUDDI publishers.
       </p>
     </section>

     <anchor id="uuidgen"/>
     <section name="UUID Generation (jUDDI UUIDGen)">
       <p>There's nothing for you to do here but I thought I'd offer a little
         information about how, why and where jUDDI makes use of UUID generation.
       </p>
       <p>The UDDI specification indicates that each Business, Service, Binding
         and TModel (Technical Model) is to be uniquely identified by a
         Universally Unique ID (UUID). Additionally, jUDDI also uses the UUID
         generator to create AuthTokens.
       </p>
       <p>Generation of a UUID typically requires access to hardware level
         information that (unfortunately) is not easily accessible from Java.
         Fortunately, the UUID specification offers an alternative method for
         generating these ID's when this hardware information is not present.
         By default the jUDDI implements this alternative method.
       </p>
     </section>

     <anchor id="logging"/>
     <section name="Logging">
       <p>When deploying jUDDI you may wish to make changes to the
        juddi.properties and log4j.properties files. These files are located in
        the juddi webapp's WEB-INF/classes directory. They're here because
        they need to be in the classpath for jUDDI to locate and load them at
        runtime. One Log4j property value that you'll most likely want to set
        is log4j.appender.LOGFILE.File which specifies the name and location of
        the jUDDI log file.
       </p>
     </section>

     <anchor id="moddev"/>
     <section name="Module Development">
       <p>Coming Soon.
       </p>
     </section>

   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	* Copyright 2001-2009 The Apache Software Foundation.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* 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.
	*
	*/ -->
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
	<document>
	<properties>
	<title>jUDDI User's Guide</title>
	</properties>
	<body>

	<anchor id="requirements"/>
	<section name="Requirements">
	<p>jUDDI is a pure Java web application and as such can be deployed to
	any application server or servlet engine that supports version 2.1 or
	later of the servlet API. If you need an application server, we
	recommend <link href="http://jakarta.apache.org/tomcat/">Jakarta
	Tomcat</link>. Note also that jUDDI requires Java 1.3 or later. As
	with any Java web application, deployment to your application server
	or servlet engine will vary on a product-by-product basis.
	</p>
	<p>Instructions for deploying jUDDI to several application servers have
	been donated and are available in the <link href="http://wiki.apache.org/ws/jUDDI">HOW-TO</link>
	section of the jUDDI wiki.
	</p>
	<p>jUDDI also requires an external datastore in which to persist the
	registry data it manages. Typically this is a relational database
	management system such as MySQL, Oracle or DB2. Support for several
	open source and commercial database products are included. See the
	section below titled <link href="#datastore">Persistence</link> for
	more information.
	</p>
	</section>

	<anchor id="config"/>
	<section name="Configuration">
	<p>To properly configure and deploy jUDDI it will be helpful to understand
	a bit about it's architecture. jUDDI consist of a core request processor
	that unmarshalls incoming UDDI requests, invoking the appropriate UDDI
	function and marshalling UDDI responses (marshalling and unmarshalling
	is the process of converting XML data to/from Java objects).
	</p>
	<p>To invoke a UDDI function jUDDI employs the services of three
	configurable sub-components or modules that handle persistence (the
	DataStore), authentication (the Authenticator) and the generation of
	UUID's (the UUIDGen). jUDDI is bundled and pre-configured to use
	default implementations of each of these modules to help your registry
	up and running quickly. These sub-components and a description of
	the default implementations are described below.
	</p>
	<p>Several public Java interfaces for creating your own DataStore,
	Authenticator and UUIDGen module implementations are available. Please
	see the <link href="#moddev">module development</link> section of this
	guide for more information regarding jUDDI module development.
	</p>
	</section>

	<anchor id="datastore"/>
	<section name="Persistence (jUDDI DataStore)">
	<p>jUDDI needs a place to store it's registry data so it should come as
	no surprise that jUDDI is pre-configured to use JDBC and any one of
	several different DBMSs to do this.
	</p>
	<p>The process of setting this up is straight forward. Start by creating
	a new jUDDI database using the instructions for your preferred DBMS
	which you will find in the 'sql' directory of your jUDDI distribution.
	At the time of this writing instructions for the following products
	were available:
	</p>
	<p>
	<ul>
	<li>MySQL</li>
	<li>DB2</li>
	<li>HSQLdb (HypersonicSQL)</li>
	<li>Sybase</li>
	<li>PostreSQL</li>
	<li>Oracle</li>
	<li>TotalXML</li>
	<li>JDataStore (Borland)</li>
	</ul>
	</p>
	<p>If support for your DBMS is not listed you might try posting a message
	to the juddi-user list to see if someone has already developed support
	for it. You can also try to create the scripts yourself by using the
	instructions for a supported DBMS as a guide. Please consider
	contributing your work back to the project so the next person won't
	have the same issue.
	</p>
	<p>To complete the DataStore set up you'll need to configure a JNDI
	Datasource with a name of <b>'jdbc/juddiDB'</b> in the application
	server or servlet engine that you're deploying to. Datasource setup
	varies on an product-by-product basis so review documentation for
	your application server. If you're deploying to Jakarta Tomcat, take a
	look at Tomcat's <link href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html">JNDI
	Datasource HOW-TO</link> for assistance.
	</p>
	</section>

	<anchor id="authenticator"/>
	<section name="Authentication (jUDDI Authenticator)">
	<p>Authenticating a jUDDI publisher is a two-step process. The first step
	confirms that the ID/password combination provided by the user in a
	get_authToken request is valid. The default Authenticator implementation
	simply approves any authentication attempt. It is expected that a
	typical jUDDI deployment will use an external authentication
	mechanism. It is our hope that additional jUDDI authentication
	implementations will be developed by jUDDI users as they determine how
	they would like authentication to take place in their particular
	environment. See the jUDDI Developers Guide for more information on
	developing a custom jUDDI authentication module for your environment.
	</p>
	<p>The second step confirms that the publisher has been defined to
	jUDDI. A publisher is said to be defined when a row identifying the
	publisher exists in the PUBLISHER table of the jUDDI datastore. At the
	moment the only way to do this is via SQL. An example of defining a
	new publisher named John Doe would look like this:
	</p>
	<p>
	<b>
	<pre>
	INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,ADMIN,ENABLED)
	VALUES ('jdoe','John Doe','false','true');
	</pre>
	</b>
	</p>
	<p>The PUBLISHER table consists of several columns but only four of them
	are required and they are defined as follows:
	</p>
	<p>
	<table>
	<tr><th>Column Name</th><th>Description</th></tr>
	<tr><td>PUBLISHER_ID</td><td>The user ID the publisher uses when authenticating. IMPORTANT: This should be the same value used to authenticate with the external authentication service.</td></tr>
	<tr><td>PUBLISHER_NAME</td><td>The publisher's name (or in UDDI speak the Authorized Name).</td></tr>
	<tr><td>ADMIN</td><td>Indicate if the publisher has administrative privileges. Valid values for this column are 'true' or 'false'. The ADMIN value is currently not used.</td></tr>
	<tr><td>ENABLED</td><td>Indicate if the publishers account is enabled and eligible for use.</td></tr>
	</table>
	</p>
	<p>The jUDDI web application will (eventually) be extended to facilitate
	the Publisher creation process. The value of the ADMIN column in the
	PUBLISHER table above will be used to determine who has the privilege
	to create new jUDDI publishers.
	</p>
	</section>

	<anchor id="uuidgen"/>
	<section name="UUID Generation (jUDDI UUIDGen)">
	<p>There's nothing for you to do here but I thought I'd offer a little
	information about how, why and where jUDDI makes use of UUID generation.
	</p>
	<p>The UDDI specification indicates that each Business, Service, Binding
	and TModel (Technical Model) is to be uniquely identified by a
	Universally Unique ID (UUID). Additionally, jUDDI also uses the UUID
	generator to create AuthTokens.
	</p>
	<p>Generation of a UUID typically requires access to hardware level
	information that (unfortunately) is not easily accessible from Java.
	Fortunately, the UUID specification offers an alternative method for
	generating these ID's when this hardware information is not present.
	By default the jUDDI implements this alternative method.
	</p>
	</section>

	<anchor id="logging"/>
	<section name="Logging">
	<p>When deploying jUDDI you may wish to make changes to the
	juddi.properties and log4j.properties files. These files are located in
	the juddi webapp's WEB-INF/classes directory. They're here because
	they need to be in the classpath for jUDDI to locate and load them at
	runtime. One Log4j property value that you'll most likely want to set
	is log4j.appender.LOGFILE.File which specifies the name and location of
	the jUDDI log file.
	</p>
	</section>

	<anchor id="moddev"/>
	<section name="Module Development">
	<p>Coming Soon.
	</p>
	</section>

	</body>
	</document>