You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juddi.apache.org by sv...@apache.org on 2005/01/07 05:18:47 UTC
cvs commit: ws-juddi/site/src/documentation/content/xdocs usersguide.xml
sviens 2005/01/06 20:18:47
Modified: site/src/documentation/content/xdocs usersguide.xml
Log:
Moved installation instructions into the User's Guide
Revision Changes Path
1.6 +166 -1 ws-juddi/site/src/documentation/content/xdocs/usersguide.xml
Index: usersguide.xml
===================================================================
RCS file: /home/cvs/ws-juddi/site/src/documentation/content/xdocs/usersguide.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- usersguide.xml 24 Aug 2004 18:44:17 -0000 1.5
+++ usersguide.xml 7 Jan 2005 04:18:47 -0000 1.6
@@ -5,10 +5,175 @@
<title>jUDDI User's Guide</title>
</header>
<body>
+
+ <anchor id="requirements"/>
<section>
- <title>User's Guide</title>
+ <title>Requirements</title>
+ <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_20HOW_2dTOs">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>
+ <title>Configuration</title>
+ <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="/devguide.html">jUDDI Developer's Guide</link> for
+ more information regarding jUDDI module development.
+ </p>
+ </section>
+
+ <anchor id="datastore"/>
+ <section>
+ <title>Persistence (jUDDI DataStore)</title>
+ <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>
+ <title>Authentication (jUDDI Authenticator)</title>
+ <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>
+ <title>UUID Generation (jUDDI UUIDGen)</title>
+ <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>
+ <title>Logging</title>
+ <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>
+
</body>
</document>