You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by fh...@apache.org on 2006/09/11 20:38:37 UTC
svn commit: r442283 - in /tomcat/tc6.0.x/trunk: ./ webapps/docs/tribes/
Author: fhanik
Date: Mon Sep 11 11:38:36 2006
New Revision: 442283
URL: http://svn.apache.org/viewvc?view=rev&rev=442283
Log:
documentation for the groupcom module
Added:
tomcat/tc6.0.x/trunk/webapps/docs/tribes/
tomcat/tc6.0.x/trunk/webapps/docs/tribes/faq.xml
tomcat/tc6.0.x/trunk/webapps/docs/tribes/introduction.xml
tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.dia (with props)
tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.jpg (with props)
tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.dia (with props)
tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.jpg (with props)
tomcat/tc6.0.x/trunk/webapps/docs/tribes/project.xml
tomcat/tc6.0.x/trunk/webapps/docs/tribes/setup.xml
tomcat/tc6.0.x/trunk/webapps/docs/tribes/tomcat-docs.xsl
Modified:
tomcat/tc6.0.x/trunk/build.xml
Modified: tomcat/tc6.0.x/trunk/build.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/build.xml?view=diff&rev=442283&r1=442282&r2=442283
==============================================================================
--- tomcat/tc6.0.x/trunk/build.xml (original)
+++ tomcat/tc6.0.x/trunk/build.xml Mon Sep 11 11:38:36 2006
@@ -346,6 +346,15 @@
includes="*.xml">
<param name="relative-path" expression=".."/>
</style>
+
+ <style basedir="webapps/docs/tribes"
+ destdir="${tomcat.build}/webapps/docs/tribes"
+ extension=".html"
+ style="webapps/docs/tomcat-docs.xsl"
+ excludes="project.xml"
+ includes="*.xml">
+ <param name="relative-path" expression=".."/>
+ </style>
<!-- Print friendly version -->
<mkdir dir="${tomcat.build}/webapps/docs/printer" />
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/faq.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/faq.xml?view=auto&rev=442283
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/tribes/faq.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/tribes/faq.xml Mon Sep 11 11:38:36 2006
@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="introduction.html">
+
+ &project;
+
+ <properties>
+ <author email="fhanik@apache.org">Filip Hanik</author>
+ <title>Apache Tribes - Frequently Asked Questions</title>
+ </properties>
+
+<body>
+
+
+<section name="Frequently Asked Questions">
+</section>
+</body>
+
+</document>
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/introduction.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/introduction.xml?view=auto&rev=442283
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/tribes/introduction.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/tribes/introduction.xml Mon Sep 11 11:38:36 2006
@@ -0,0 +1,330 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="introduction.html">
+
+ &project;
+
+ <properties>
+ <author email="fhanik@apache.org">Filip Hanik</author>
+ <title>Apache Tribes - Introduction</title>
+ </properties>
+
+<body>
+
+
+<section name="Quick Start">
+
+ <p>Apache Tribes is a group or peer-to-peer communcation framework that enables you to easily connect
+ your remote objects to communicate with each other.
+ </p>
+ <ul>
+ <li>Import: <code>org.apache.catalina.tribes.Channel</code></li>
+ <li>Import: <code>org.apache.catalina.tribes.Member</code></li>
+ <li>Import: <code>org.apache.catalina.tribes.MembershipListener</code></li>
+ <li>Import: <code>org.apache.catalina.tribes.ChannelListener</code></li>
+ <li>Import: <code>org.apache.catalina.tribes.group.GroupChannel</code></li>
+ <li>Create a class that implements: <code>org.apache.catalina.tribes.ChannelListener</code></li>
+ <li>Create a class that implements: <code>org.apache.catalina.tribes.MembershipListener</code></li>
+ <li>Simple class to demonstrate how to send a message:
+ <source>
+ //create a channel
+ Channel myChannel = new GroupChannel();
+
+ //create my listeners
+ ChannelListener msgListener = new MyMessageListener();
+ MembershipListener mbrListener = new MyMemberListener();
+
+ //attach the listeners to the channel
+ myChannel.addMembershipListener(mbrListener);
+ myChannel.addChannelListener(msgListener);
+
+ //start the channel
+ myChannel.start(Channel.DEFAULT);
+
+ //create a message to be sent, message must implement java.io.Serializable
+ //for performance reasons you probably want them to implement java.io.Externalizable
+ Serializable myMsg = new MyMessage();
+
+ //retrieve my current members
+ Member[] group = myChannel.getMembers();
+
+ //send the message
+ channel.send(group,myMsg,Channel.SEND_OPTIONS_DEFAULT);
+ </source>
+ </li>
+ </ul>
+ <p>
+ Simple yeah? There is a lot more to Tribes than we have shown, hopefully the docs will be able
+ to explain more to you. Remember, that we are always interested in suggestions, improvements, bug fixes
+ and anything that you think would help this project.
+ </p>
+ <p>
+ Note: Tribes is currently built for JDK1.5, you can run on JDK1.4 by a small modifications to locks used from the <code>java.util.concurrent</code> package.
+ </p>
+</section>
+
+
+<section name="What is Tribes">
+ <p>
+ Tribes is a messaging framework with group communication abilities. Tribes allows you to send and receive
+ messages over a network, it also allows for dynamic discovery of other nodes in the network.<br/>
+ And that is the short story, it really is as simple as that. What makes Tribes useful and unique will be
+ described in the section below.<br/>
+ </p>
+ <p>
+ The Tribes module was started early 2006 and a small part of the code base comes from the clustering module
+ that has been existing since 2003 or 2004.
+ The current cluster implementation has several short comings and many work arounds were created due
+ to the complexity in group communication. Long story short, what should have been two modules a long time
+ ago, will be now. Tribes takes out the complexity of messaging from the replication module and becomes
+ a fully independent and highly flexible group communication module.<br/>
+ </p>
+ <p>
+ In Tomcat the old <code>modules/cluster</code> has now become <code>modules/groupcom</code>(Tribes) and
+ <code>modules/ha</code> (replication). This will allow development to proceed and let the developers
+ focus on the issues they are actually working on rather than getting boggled down in details of a module
+ they are not interested in. The understanding is that both communication and replication are complex enough,
+ and when trying to develop them in the same module, well you know, it becomes a cluster :)<br/>
+ </p>
+ <p>
+ Tribes allows for guaranteed messaging, and can be customized in many ways. Why is this important?<br/>
+ Well, you as a developer want to know that the messages you are sending are reaching their destination.
+ More than that, if a message doesn't reach its destination, the application on top of Tribes will be notified
+ that the message was never sent, and what node it failed.
+ </p>
+
+</section>
+
+<section name="Why another messaging framework">
+ <p>
+ I am a big fan of reusing code and would never dream of developing something if someone else has already
+ done it and it was available to me and the community I try to serve.<br/>
+ When I did my research to improve the clustering module I was constantly faced with a few obstacles:<br/>
+ 1. The framework wasn't flexible enough<br/>
+ 2. The framework was licensed in a way that neither I nor the community could use it<br/>
+ 3. Several features that I needed were missing<br/>
+ 4. Messaging was guaranteed, but no feedback was reported to me<br/>
+ 5. The semantics of my message delivery had to be configured before runtime<br/>
+ And the list continues...
+ </p>
+ <p>
+ So I came up with Tribes, to address these issues and other issues that came along.
+ When designing Tribes I wanted to make sure I didn't lose any of the flexibility and
+ delivery semantics that the existing frameworks already delivered. The goal was to create a framework
+ that could do everything that the others already did, but to provide more flexibility for the application
+ developer. In the next section will give you the high level overview of what features tribes offers or will offer.
+ </p>
+</section>
+
+<section name="Feature Overview">
+ <p>
+ To give you an idea of the feature set I will list it out here.
+ Some of the features are not yet completed, if that is the case they are marked accordingly.
+ </p>
+ <p>
+ <b>Pluggable modules</b><br/>
+ Tribes is built using interfaces. Any of the modules or components that are part of Tribes can be swapped out
+ to customize your own Tribes implementation.
+ </p>
+ <p>
+ <b>Guaranteed Messaging</b><br/>
+ In the default implementation of Tribes uses TCP for messaging. TCP already has guaranteed message delivery
+ and flow control built in. I believe that the performance of Java TCP, will outperform an implementation of
+ Java/UDP/flow-control/message guarantee since the logic happens further down the stack.<br/>
+ Tribes supports both non-blocking and blocking IO operations. The recommended setting is to use non blocking
+ as it promotes better parallelism when sending and receiving messages. The blocking implementation is available
+ for those platforms where NIO is still a trouble child.
+ </p>
+ <p>
+ <b>Different Guarantee Levels</b><br/>
+ There are three different levels of delivery guarantee when a message is sent.<br/>
+ <ol>
+ <li>IO Based send guarantee. - fastest, least reliable<br/>
+ This means that Tribes considers the message transfer to be successful
+ if the message was sent to the socket send buffer and accepted.<br/>
+ On blocking IO, this would be <code>socket.getOutputStream().write(msg)</code><br/>
+ On non blocking IO, this would be <code>socketChannel.write()</code>, and the buffer byte buffer gets emptied
+ followed by a <code>socketChannel.read()</code> to ensure the channel still open.
+ The <code>read()</code> has been added since <code>write()</code> will succeed if the connection has been "closed"
+ when using NIO.
+ </li>
+ <li>ACK based. - recommended, guaranteed delivery<br/>
+ When the message has been received on a remote node, an ACK is sent back to the sender,
+ indicating that the message was received successfully.
+ </li>
+ <li>SYNC_ACK based. - guaranteed delivery, guaranteed processed, slowest<br/>
+ When the message has been received on a remote node, the node will process
+ the message and if the message was processed successfully, an ACK is sent back to the sender
+ indicating that the message was received and processed successfully.
+ If the message was received, but processing it failed, an ACK_FAIL will be sent back
+ to the sender. This is a unique feature that adds an incredible amount value to the application
+ developer. Most frameworks here will tell you that the message was delivered, and the application
+ developer has to build in logic on whether the message was actually processed properly by the application
+ on the remote node. If configured, Tribes will throw an exception when it receives an ACK_FAIL
+ and associate that exception with the member that didn't process the message.
+ </li>
+ </ol>
+ You can of course write even more sophisticated guarantee levels, and some of them will be mentioned later on
+ in the documentation. One mentionable level would be a 2-Phase-Commit, where the remote applications don't receive
+ the message until all nodes have received the message. Sort of like a all-or-nothing protocol.
+ </p>
+ <p>
+ <b>Per Message Delivery Attributes</b><br/>
+ Perhaps the feature that makes Tribes stand out from the crowd of group communication frameworks.
+ Tribes enables you to send to decide what delivery semantics a message transfer should have on a per
+ message basis. Meaning, that your messages are not delivered based on some static configuration
+ that remains fixed after the message framework has been started.<br/>
+ To give you an example of how powerful this feature is, I'll try to illustrate it with a simple example.
+ Imagine you need to send 10 different messsages, you could send the the following way:
+ <source>
+ Message_1 - asynchronous and fast, no guarantee required, fire and forget
+ Message_2 - all-or-nothing, either all receivers get it, or none.
+ Message_3 - encrypted and SYNC_ACK based
+ Message_4 - asynchronous, SYNC_ACK and call back when the message is processed on the remote nodes
+ Message_5 - totally ordered, this message should be received in the same order on all nodes that have been
+ send totally ordered
+ Message_6 - asynchronous and totally ordered
+ Message_7 - RPC message, send a message, wait for all remote nodes to reply before returning
+ Message_8 - RPC message, wait for the first reply
+ Message_9 - RPC message, asynchronous, don't wait for a reply, collect them via a callback
+ Message_10- sent to a member that is not part of this group
+ </source>
+ As you can imagine by now, these are just examples. The number of different semantics you can apply on a
+ per-message-basis is almost limitless. Tribes allows you to set up to 28 different on a message
+ and then configure Tribes to what flag results in what action on the message.<br/>
+ Imagine a shared transactional cache, probably >90% are reads, and the dirty reads should be completely
+ unordered and delivered as fast as possible. But transactional writes on the other hand, have to
+ be ordered so that no cache gets corrupted. With tribes you would send the write messages totally ordered,
+ while the read messages you simple fire to achieve highest throughput.<br/>
+ There are probably better examples on how this powerful feature can be used, so use your imagination and
+ your experience to think of how this could benefit you in your application.
+ </p>
+ <p>
+ <b>Interceptor based message processing</b><br/>
+ Tribes uses a customizable interceptor stack to process messages that are sent and received.<br/>
+ <i>So what, all frameworks have this!</i><br/>
+ Yes, but in Tribes interceptors can react to a message based on the per-message-attributes
+ that are sent runtime. Meaning, that if you add a encryption interceptor that encrypts message
+ you can decide if this interceptor will encrypt all messages, or only certain messages that are decided
+ by the applications running on top of Tribes.<br/>
+ This is how Tribes is able to send some messages totally ordered and others fire and forget style
+ like the example above.<br/>
+ The number of interceptors that are available will keep growing, and we would appreciate any contributions
+ that you might have.
+ </p>
+ <p>
+ <b>Threadless Interceptor stack</b>
+ The interceptor don't require any separate threads to perform their message manipulation.<br/>
+ Messages that are sent will piggy back on the thread that is sending them all the way through transmission.
+ The exception is the <code>MessageDispatchInterceptor</code> that will queue up the message
+ and send it on a separate thread for asynchronous message delivery.
+ Messages received are controlled by a thread pool in the <code>receiver</code> component.<br/>
+ The channel object can send a <code>heartbeat()</code> through the interceptor stack to allow
+ for timeouts, cleanup and other events.<br/>
+ The <code>MessageDispatchInterceptor</code> is the only interceptor that is configured by default.
+ </p>
+ <p>
+ <b>Parallel Delivery</b><br/>
+ Tribes support parallel delivery of messages. Meaning that node_A could send three messages to node_B in
+ parallel. This feature becomes useful when sending messages with different delivery semantics.
+ Otherwise if Message_1 was sent totally ordered, Message_2 would have to wait for that message to complete.<br/>
+ Through NIO, Tribes is also able to send a message to several receivers at the same time on the same thread.
+ </p>
+ <p>
+ <b>Silent Member Messaging</b><br/>
+ With Tribes you are able to send messages to members that are not in your group.
+ So by default, you can already send messages over a wide area network, even though the dynamic discover
+ module today is limited to local area networks by using multicast for dynamic node discovery.
+ Of course, the membership component will be expanded to support WAN memberships in the future.
+ But this is very useful, when you want to hide members from the rest of the group and only communicate with them
+ </p>
+</section>
+
+<section name="Where can I get Tribes">
+ <p>
+ I hope you have enjoyed this short introduction to Tribes. You can download <a href="../apache-tribes.jar">Tribes here</a>
+ or you can download Tribes <a href="../tribes-all.zip">including javadoc and this doc</a>
+ </p>
+
+
+</section>
+
+<!--
+<section name="Cluster Configuration for ReplicationTransmitter">
+<p>
+List of Attributes<br/>
+<table border="1" cellpadding="5">
+
+ <tr>
+ <th align="center" bgcolor="aqua">Attribute</th>
+ <th align="center" bgcolor="aqua">Description</th>
+ <th align="center" bgcolor="aqua">Default value</th>
+ </tr>
+
+ <tr>
+ <td>replicationMode</td>
+ <td>replication mode (<em>synchronous</em>, <em>pooled</em>, <em>asynchronous</em> or <em>fastasyncqueue</em>)
+ </td>
+ <td><code>pooled</code></td>
+ </tr>
+
+ <tr>
+ <td>processSenderFrequency</td>
+ <td>Control the sender keepalive status and drop sender socket connection after timeout is reached.
+ Check every processSenderFrequency value engine background ticks.
+ </td>
+ <td><code>2</code></td>
+ </tr>
+
+ <tr>
+ <td>compress</td>
+ <td>compress bytes before sending (consume memory, but reduce network traffic - GZIP)</td>
+ <td><code>false</code></td>
+ </tr>
+
+ <tr>
+ <td>ackTimeout</td>
+ <td>acknowledge timeout and only usefull it waitForAck is true</td>
+ <td><code>15000</code></td>
+ </tr>
+
+ <tr>
+ <td>waitForAck</td>
+ <td>Wait for ack after data send</td>
+ <td><code>false</code></td>
+ </tr>
+
+ <tr>
+ <td>autoConnect</td>
+ <td>is sender disabled, fork a new socket</td>
+ <td><code>false</code></td>
+ </tr>
+
+ <tr>
+ <td>doTransmitterProcessingStats</td>
+ <td>create processing time stats</td>
+ <td><code>false</code></td>
+ </tr>
+</table>
+</p>
+<p>
+Example to get statistic information, wait for ack at every message send and transfer at compressed mode<br/>
+<source>
+ <Sender
+ className="org.apache.catalina.cluster.tcp.ReplicationTransmitter"
+ replicationMode="fastasyncqueue"
+ compress="true"
+ doTransmitterProcessingStats="true"
+ ackTimeout="15000"
+ waitForAck="true"
+ autoConnect="false"/>
+</source>
+</p>
+</section>
+
+-->
+</body>
+
+</document>
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.dia
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.dia?view=auto&rev=442283
==============================================================================
Binary file - no diff available.
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.dia
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.jpg
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.jpg?view=auto&rev=442283
==============================================================================
Binary file - no diff available.
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-initiate-election.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.dia
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.dia?view=auto&rev=442283
==============================================================================
Binary file - no diff available.
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.dia
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.jpg
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.jpg?view=auto&rev=442283
==============================================================================
Binary file - no diff available.
Propchange: tomcat/tc6.0.x/trunk/webapps/docs/tribes/leader-election-message-arrives.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/project.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/project.xml?view=auto&rev=442283
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/tribes/project.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/tribes/project.xml Mon Sep 11 11:38:36 2006
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="Apache Tribes Documentation - Top Level Directory"
+ href="http://tomcat.apache.org/">
+
+ <title>Apache Tribes - The Tomcat Cluster Communication Module</title>
+
+ <logo href="/images/tomcat.gif">Apache Tomcat</logo>
+
+
+ <body>
+
+ <menu name="Links">
+ <item name="Docs Home" href="../index.html"/>
+ <item name="FAQ" href="http://tomcat.apache.org/faq" />
+ </menu>
+
+ <menu name="User Guide">
+ <item name="1) Introduction" href="introduction.html"/>
+ <item name="2) Setup" href="setup.html"/>
+ <item name="3) FAQ" href="faq.html"/>
+ </menu>
+
+ <menu name="Reference">
+ <item name="Release Notes" href="RELEASE-NOTES.txt"/>
+ <item name="JavaDoc" href="/api/index.html"/>
+ </menu>
+
+ <menu name="Apache Tribes Development">
+ <item name="Membership" href="membership.html"/>
+ <item name="Transport" href="transport.html"/>
+ <item name="Interceptors" href="interceptors.html"/>
+ <item name="Status" href="status.html"/>
+ <item name="Developers" href="developers.html"/>
+ </menu>
+
+ </body>
+
+</project>
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/setup.xml
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/setup.xml?view=auto&rev=442283
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/tribes/setup.xml (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/tribes/setup.xml Mon Sep 11 11:38:36 2006
@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document url="introduction.html">
+
+ &project;
+
+ <properties>
+ <author email="fhanik@apache.org">Filip Hanik</author>
+ <title>Apache Tribes - Configuration</title>
+ </properties>
+
+<body>
+
+
+<section name="Configuration Overview">
+</section>
+</body>
+
+</document>
Added: tomcat/tc6.0.x/trunk/webapps/docs/tribes/tomcat-docs.xsl
URL: http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/tribes/tomcat-docs.xsl?view=auto&rev=442283
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/tribes/tomcat-docs.xsl (added)
+++ tomcat/tc6.0.x/trunk/webapps/docs/tribes/tomcat-docs.xsl Mon Sep 11 11:38:36 2006
@@ -0,0 +1,436 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!-- Content Stylesheet for "tomcat-docs" Documentation -->
+
+<!-- $Id: tomcat-docs.xsl 377243 2006-02-12 21:26:03Z markt $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+
+ <!-- Output method -->
+ <xsl:output method="html"
+ encoding="iso-8859-1"
+ indent="no"/>
+
+
+ <!-- Defined parameters (overrideable) -->
+ <xsl:param name="home-name" select="'The Tomcat Project'"/>
+ <xsl:param name="home-href" select="'http://tomcat.apache.org/'"/>
+ <xsl:param name="home-logo" select="'/images/tomcat.gif'"/>
+ <xsl:param name="printer-logo" select="'/images/printer.gif'"/>
+ <xsl:param name="apache-logo" select="'/images/asf-logo.gif'"/>
+ <xsl:param name="relative-path" select="'.'"/>
+ <xsl:param name="void-image" select="'/images/void.gif'"/>
+ <xsl:param name="project-menu" select="'menu'"/>
+ <xsl:param name="standalone" select="''"/>
+ <xsl:param name="buglink" select="'http://issues.apache.org/bugzilla/show_bug.cgi?id='"/>
+
+ <!-- Defined variables (non-overrideable) -->
+ <xsl:variable name="body-bg" select="'#ffffff'"/>
+ <xsl:variable name="body-fg" select="'#000000'"/>
+ <xsl:variable name="body-link" select="'#525D76'"/>
+ <xsl:variable name="banner-bg" select="'#525D76'"/>
+ <xsl:variable name="banner-fg" select="'#ffffff'"/>
+ <xsl:variable name="sub-banner-bg" select="'#828DA6'"/>
+ <xsl:variable name="sub-banner-fg" select="'#ffffff'"/>
+ <xsl:variable name="source-color" select="'#023264'"/>
+ <xsl:variable name="attributes-color" select="'#023264'"/>
+ <xsl:variable name="table-th-bg" select="'#039acc'"/>
+ <xsl:variable name="table-td-bg" select="'#a0ddf0'"/>
+
+ <!-- Process an entire document into an HTML page -->
+ <xsl:template match="document">
+ <xsl:variable name="project"
+ select="document('project.xml')/project"/>
+ <html>
+ <head>
+ <title><xsl:value-of select="project/title"/> - <xsl:value-of select="properties/title"/></title>
+ <xsl:for-each select="properties/author">
+ <xsl:variable name="name">
+ <xsl:value-of select="."/>
+ </xsl:variable>
+ <xsl:variable name="email">
+ <xsl:value-of select="@email"/>
+ </xsl:variable>
+ <meta name="author" value="{$name}"/>
+ <meta name="email" value="{$email}"/>
+ </xsl:for-each>
+ </head>
+
+ <body bgcolor="{$body-bg}" text="{$body-fg}" link="{$body-link}"
+ alink="{$body-link}" vlink="{$body-link}">
+
+ <table border="0" width="100%" cellspacing="0">
+
+ <xsl:comment>PAGE HEADER</xsl:comment>
+ <tr>
+ <td>
+ <xsl:if test="project/logo">
+ <xsl:variable name="alt">
+ <xsl:value-of select="project/logo"/>
+ </xsl:variable>
+ <xsl:variable name="home">
+ <xsl:value-of select="project/@href"/>
+ </xsl:variable>
+ <xsl:variable name="src">
+ <!--<xsl:value-of select="$relative-path"/>--><xsl:value-of select="project/logo/@href"/>
+ </xsl:variable>
+
+ <xsl:comment>PROJECT LOGO</xsl:comment>
+ <a href="{$home}">
+ <img src="{$src}" align="right" alt="{$alt}" border="0"/>
+ </a>
+ </xsl:if>
+ </td>
+ <td>
+ <font face="arial,helvetica,sanserif">
+ <h1><xsl:value-of select="$project/title"/></h1>
+ </font>
+ </td>
+ <td>
+ <xsl:comment>APACHE LOGO</xsl:comment>
+ <xsl:variable name="src">
+ <xsl:value-of select="$relative-path"/><xsl:value-of select="$apache-logo"/>
+ </xsl:variable>
+ <a href="http://www.apache.org/">
+ <img src="http://tomcat.apache.org/tomcat-5.5-doc/images/asf-logo.gif" align="right" alt="Apache Logo" border="0"/>
+ </a>
+ </td>
+ </tr>
+ </table>
+
+ <table border="0" width="100%" cellspacing="4">
+
+ <xsl:comment>HEADER SEPARATOR</xsl:comment>
+ <tr>
+ <td colspan="2">
+ <hr noshade="noshade" size="1"/>
+ </td>
+ </tr>
+
+ <tr>
+
+ <!-- Don't generate a menu if styling printer friendly docs -->
+ <xsl:if test="$project-menu = 'menu'">
+ <xsl:comment>LEFT SIDE NAVIGATION</xsl:comment>
+ <td width="20%" valign="top" nowrap="true">
+ <xsl:apply-templates select="project/body/menu"/>
+ </td>
+ </xsl:if>
+
+ <xsl:comment>RIGHT SIDE MAIN BODY</xsl:comment>
+ <td width="80%" valign="top" align="left">
+ <table border="0" width="100%" cellspacing="4">
+ <tr>
+ <td align="left" valign="top">
+ <h1><xsl:value-of select="project/title"/></h1>
+ <h2><xsl:value-of select="properties/title"/></h2>
+ </td>
+ <td align="right" valign="top" nowrap="true">
+ <!-- Add the printer friendly link for docs with a menu -->
+ <xsl:if test="$project-menu = 'menu'">
+ <xsl:variable name="src">
+ <xsl:value-of select="$relative-path"/><xsl:value-of select="$printer-logo"/>
+ </xsl:variable>
+ <xsl:variable name="url">
+ <xsl:value-of select="/document/@url"/>
+ </xsl:variable>
+ <small>
+ <a href="printer/{$url}">
+ <img src="{$src}" border="0" alt="Printer Friendly Version"/>
+ <br />print-friendly<br />version
+ </a>
+ </small>
+ </xsl:if>
+ <xsl:if test="$project-menu != 'menu'">
+ <xsl:variable name="void">
+ <xsl:value-of select="$relative-path"/><xsl:value-of select="$void-image"/>
+ </xsl:variable>
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </xsl:if>
+ </td>
+ </tr>
+ </table>
+ <xsl:apply-templates select="body/section"/>
+ </td>
+
+ </tr>
+
+ <xsl:comment>FOOTER SEPARATOR</xsl:comment>
+ <tr>
+ <td colspan="2">
+ <hr noshade="noshade" size="1"/>
+ </td>
+ </tr>
+
+ <xsl:comment>PAGE FOOTER</xsl:comment>
+ <tr><td colspan="2">
+ <div align="center"><font color="{$body-link}" size="-1"><em>
+ Copyright © 1999-2006, Apache Software Foundation
+ </em></font></div>
+ </td></tr>
+
+ </table>
+ </body>
+ </html>
+
+ </xsl:template>
+
+
+ <!-- Process a menu for the navigation bar -->
+ <xsl:template match="menu">
+ <p><strong><xsl:value-of select="@name"/></strong></p>
+ <ul>
+ <xsl:apply-templates select="item"/>
+ </ul>
+ </xsl:template>
+
+
+ <!-- Process a menu item for the navigation bar -->
+ <xsl:template match="item">
+ <xsl:variable name="href">
+ <xsl:value-of select="@href"/>
+ </xsl:variable>
+ <li><a href="{$href}"><xsl:value-of select="@name"/></a></li>
+ </xsl:template>
+
+
+ <!-- Process a documentation section -->
+ <xsl:template match="section">
+ <xsl:variable name="name">
+ <xsl:value-of select="@name"/>
+ </xsl:variable>
+ <table border="0" cellspacing="0" cellpadding="2">
+ <!-- Section heading -->
+ <tr><td bgcolor="{$banner-bg}">
+ <font color="{$banner-fg}" face="arial,helvetica.sanserif">
+ <a name="{$name}">
+ <strong><xsl:value-of select="@name"/></strong></a></font>
+ </td></tr>
+ <!-- Section body -->
+ <tr><td><blockquote>
+ <xsl:apply-templates/>
+ </blockquote></td></tr>
+ </table>
+ </xsl:template>
+
+
+ <!-- Process a documentation subsection -->
+ <xsl:template match="subsection">
+ <xsl:variable name="name">
+ <xsl:value-of select="@name"/>
+ </xsl:variable>
+ <table border="0" cellspacing="0" cellpadding="2">
+ <!-- Subsection heading -->
+ <tr><td bgcolor="{$sub-banner-bg}">
+ <font color="{$sub-banner-fg}" face="arial,helvetica.sanserif">
+ <a name="{$name}">
+ <strong><xsl:value-of select="@name"/></strong></a></font>
+ </td></tr>
+ <!-- Subsection body -->
+ <tr><td><blockquote>
+ <xsl:apply-templates/>
+ </blockquote></td></tr>
+ </table>
+ </xsl:template>
+
+
+ <!-- Process a source code example -->
+ <xsl:template match="source">
+ <xsl:variable name="void">
+ <xsl:value-of select="$relative-path"/><xsl:value-of select="$void-image"/>
+ </xsl:variable>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="{$source-color}" width="1" height="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ <td bgcolor="{$source-color}" height="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ <td bgcolor="{$source-color}" width="1" height="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ </tr>
+ <tr>
+ <td bgcolor="{$source-color}" width="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ <td bgcolor="#ffffff" height="1"><pre>
+ <xsl:value-of select="."/>
+ </pre></td>
+ <td bgcolor="{$source-color}" width="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ </tr>
+ <tr>
+ <td bgcolor="{$source-color}" width="1" height="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ <td bgcolor="{$source-color}" height="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ <td bgcolor="{$source-color}" width="1" height="1">
+ <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </xsl:template>
+
+
+ <!-- Process an attributes list with nested attribute elements -->
+ <xsl:template match="attributes">
+ <table border="1" cellpadding="5">
+ <tr>
+ <th width="15%" bgcolor="{$attributes-color}">
+ <font color="#ffffff">Attribute</font>
+ </th>
+ <th width="85%" bgcolor="{$attributes-color}">
+ <font color="#ffffff">Description</font>
+ </th>
+ </tr>
+ <xsl:for-each select="attribute">
+ <tr>
+ <td align="left" valign="center">
+ <xsl:if test="@required = 'true'">
+ <strong><code><xsl:value-of select="@name"/></code></strong>
+ </xsl:if>
+ <xsl:if test="@required != 'true'">
+ <code><xsl:value-of select="@name"/></code>
+ </xsl:if>
+ </td>
+ <td align="left" valign="center">
+ <xsl:apply-templates/>
+ </td>
+ </tr>
+ </xsl:for-each>
+ </table>
+ </xsl:template>
+
+ <!-- Fix relative links in printer friendly versions of the docs -->
+ <xsl:template match="a">
+ <xsl:variable name="href" select="@href"/>
+ <xsl:choose>
+ <xsl:when test="$standalone = 'standalone'">
+ <xsl:apply-templates/>
+ </xsl:when>
+ <xsl:when test="$project-menu != 'menu' and starts-with(@href,'../')">
+ <a href="../{$href}"><xsl:apply-templates/></a>
+ </xsl:when>
+ <xsl:when test="$project-menu != 'menu' and starts-with(@href,'./') and contains(substring(@href,3),'/')">
+ <a href=".{$href}"><xsl:apply-templates/></a>
+ </xsl:when>
+ <xsl:when test="$project-menu != 'menu' and not(contains(@href,'//')) and not(starts-with(@href,'/')) and not(starts-with(@href,'#')) and contains(@href,'/')">
+ <a href="../{$href}"><xsl:apply-templates/></a>
+ </xsl:when>
+ <xsl:when test="$href != ''">
+ <a href="{$href}"><xsl:apply-templates/></a>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:variable name="name" select="@name"/>
+ <a name="{$name}"><xsl:apply-templates/></a>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Changelog related tags -->
+ <xsl:template match="changelog">
+ <table border="0" cellpadding="2" cellspacing="2">
+ <xsl:apply-templates/>
+ </table>
+ </xsl:template>
+
+ <xsl:template match="changelog/add">
+ <tr>
+ <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/add.gif</xsl:variable>
+ <td><img alt="add" class="icon" src="{$src}"/></td>
+ <td><xsl:apply-templates/></td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="changelog/update">
+ <tr>
+ <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/update.gif</xsl:variable>
+ <td><img alt="update" class="icon" src="{$src}"/></td>
+ <td><xsl:apply-templates/></td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="changelog/design">
+ <tr>
+ <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/design.gif</xsl:variable>
+ <td><img alt="design" class="icon" src="{$src}"/></td>
+ <td><xsl:apply-templates/></td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="changelog/docs">
+ <tr>
+ <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/docs.gif</xsl:variable>
+ <td><img alt="docs" class="icon" src="{$src}"/></td>
+ <td><xsl:apply-templates/></td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="changelog/fix">
+ <tr>
+ <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/fix.gif</xsl:variable>
+ <td><img alt="fix" class="icon" src="{$src}"/></td>
+ <td><xsl:apply-templates/></td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="changelog/scode">
+ <tr>
+ <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/code.gif</xsl:variable>
+ <td><img alt="code" class="icon" src="{$src}"/></td>
+ <td><xsl:apply-templates/></td>
+ </tr>
+ </xsl:template>
+
+ <!-- Process an attributes list with nested attribute elements -->
+ <xsl:template match="status">
+ <table border="1" cellpadding="5">
+ <tr>
+ <th width="15%" bgcolor="{$attributes-color}">
+ <font color="#ffffff">Priority</font>
+ </th>
+ <th width="50%" bgcolor="{$attributes-color}">
+ <font color="#ffffff">Action Item</font>
+ </th>
+ <th width="25%" bgcolor="{$attributes-color}">
+ <font color="#ffffff">Volunteers</font>
+ </th>
+ <xsl:for-each select="item">
+ <tr>
+ <td align="left" valign="center">
+ <xsl:value-of select="@priority"/>
+ </td>
+ <td align="left" valign="center">
+ <xsl:apply-templates/>
+ </td>
+ <td align="left" valign="center">
+ <xsl:value-of select="@owner"/>
+ </td>
+ </tr>
+ </xsl:for-each>
+ </tr>
+ </table>
+ </xsl:template>
+
+ <!-- Link to a bug report -->
+ <xsl:template match="bug">
+ <xsl:variable name="link"><xsl:value-of select="$buglink"/><xsl:value-of select="text()"/></xsl:variable>
+ <a href="{$link}"><xsl:apply-templates/></a>
+ </xsl:template>
+
+ <!-- Process everything else by just passing it through -->
+ <xsl:template match="*|@*">
+ <xsl:copy>
+ <xsl:apply-templates select="@*|*|text()"/>
+ </xsl:copy>
+ </xsl:template>
+
+</xsl:stylesheet>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org