http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/ssl-howto.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/ssl-howto.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/ssl-howto.html new file mode 100644 index 0000000..c4c1b19 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/ssl-howto.html @@ -0,0 +1,512 @@ +Apache Tomcat 6.0 - SSL Configuration HOW-TO

+      The Apache Tomcat Servlet/JSP Container
+

Apache Tomcat 6.0

Apache Logo

Links

User Guide

Reference

Apache Tomcat Development

Apache Tomcat 6.0

SSL Configuration HOW-TO

Table of Contents
+ +
Quick Start
+ +
+

The description below uses the variable name $CATALINA_BASE to refer the + base directory against which most relative paths are resolved. If you have + not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE + directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, + the directory into which you have installed Tomcat 6.

+
+ +

To install and configure SSL support on Tomcat 6, you need to follow +these simple steps. For more information, read the rest of this HOW-TO.

+
    +
  1. Create a certificate keystore by executing the following command: +

    Windows:

    +
    +%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
    +
    +

    Unix:

    +
    +$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
    +
    +

    + and specify a password value of "changeit".


  2. +
  3. Uncomment the "SSL HTTP/1.1 Connector" entry in + $CATALINA_BASE/conf/server.xml and modify as described in + the Configuration section below.
  4. +

    +
+ + +
Introduction to SSL
+ +

SSL, or Secure Socket Layer, is a technology which allows web browsers and +web servers to communicate over a secured connection. This means that the data +being sent is encrypted by one side, transmitted, then decrypted by the other +side before processing. This is a two-way process, meaning that both the +server AND the browser encrypt all traffic before sending out data.

+ +

Another important aspect of the SSL protocol is Authentication. This means +that during your initial attempt to communicate with a web server over a secure +connection, that server will present your web browser with a set of +credentials, in the form of a "Certificate", as proof the site is who and what +it claims to be. In certain cases, the server may also request a Certificate +from your web browser, asking for proof that you are who you claim +to be. This is known as "Client Authentication," although in practice this is +used more for business-to-business (B2B) transactions than with individual +users. Most SSL-enabled web servers do not request Client Authentication.

+ +
SSL and Tomcat
+ +

It is important to note that configuring Tomcat to take advantage of +secure sockets is usually only necessary when running it as a stand-alone +web server. When running Tomcat primarily as a Servlet/JSP container behind +another web server, such as Apache or Microsoft IIS, it is usually necessary +to configure the primary web server to handle the SSL connections from users. +Typically, this server will negotiate all SSL-related functionality, then +pass on any requests destined for the Tomcat container only after decrypting +those requests. Likewise, Tomcat will return cleartext responses, that will +be encrypted before being returned to the user's browser. In this environment, +Tomcat knows that communications between the primary web server and the +client are taking place over a secure connection (because your application +needs to be able to ask about this), but it does not participate in the +encryption or decryption itself.

+ +
Certificates
+ +

In order to implement SSL, a web server must have an associated Certificate +for each external interface (IP address) that accepts secure connections. +The theory behind this design is that a server should provide some kind of +reasonable assurance that its owner is who you think it is, particularly +before receiving any sensitive information. While a broader explanation of +Certificates is beyond the scope of this document, think of a Certificate +as a "digital driver's license" for an Internet address. It states what +company the site is associated with, along with some basic contact +information about the site owner or administrator.

+ +

This "driver's license" is cryptographically signed by its owner, and is +therefore extremely difficult for anyone else to forge. For sites involved +in e-commerce, or any other business transaction in which authentication of +identity is important, a Certificate is typically purchased from a well-known +Certificate Authority (CA) such as VeriSign or Thawte. Such +certificates can be electronically verified -- in effect, the Certificate +Authority will vouch for the authenticity of the certificates that it grants, +so you can believe that that Certificate is valid if you trust the Certificate +Authority that granted it.

+ +

In many cases, however, authentication is not really a concern. An +administrator may simply want to ensure that the data being transmitted and +received by the server is private and cannot be snooped by anyone who may be +eavesdropping on the connection. Fortunately, Java provides a relatively +simple command-line tool, called keytool, which can easily create +a "self-signed" Certificate. Self-signed Certificates are simply user +generated Certificates which have not been officially registered with any +well-known CA, and are therefore not really guaranteed to be authentic at all. +Again, this may or may not even be important, depending on your needs.

+ +
General Tips on Running SSL
+ +

The first time a user attempts to access a secured page on your site, +he or she is typically presented with a dialog containing the details of +the certificate (such as the company and contact name), and asked if he or she +wishes to accept the Certificate as valid and continue with the transaction. +Some browsers will provide an option for permanently accepting a given +Certificate as valid, in which case the user will not be bothered with a +prompt each time they visit your site. Other browsers do not provide this +option. Once approved by the user, a Certificate will be considered valid +for at least the entire browser session.

+ +

Also, while the SSL protocol was designed to be as efficient as securely +possible, encryption/decryption is a computationally expensive process from +a performance standpoint. It is not strictly necessary to run an entire +web application over SSL, and indeed a developer can pick and choose which +pages require a secure connection and which do not. For a reasonably busy +site, it is customary to only run certain pages under SSL, namely those +pages where sensitive information could possibly be exchanged. This would +include things like login pages, personal information pages, and shopping +cart checkouts, where credit card information could possibly be transmitted. +Any page within an application can be requested over a secure socket by +simply prefixing the address with https: instead of +http:. Any pages which absolutely require +a secure connection should check the protocol type associated with the +page request and take the appropriate action if https is not +specified.

+ +

Finally, using name-based virtual hosts on a secured connection can be +problematic. This is a design limitation of the SSL protocol itself. The SSL +handshake, where the client browser accepts the server certificate, must occur +before the HTTP request is accessed. As a result, the request information +containing the virtual host name cannot be determined prior to authentication, +and it is therefore not possible to assign multiple certificates to a single +IP address. If all virtual hosts on a single IP address need to authenticate +against the same certificate, the addition of multiple virtual hosts should not +interfere with normal SSL operations on the server. Be aware, however, that +most client browsers will compare the server's domain name against the domain +name listed in the certificate, if any (applicable primarily to official, +CA-signed certificates). If the domain names do not match, these browsers will +display a warning to the client user. In general, only address-based virtual +hosts are commonly used with SSL in a production environment.

+ +
Configuration
+ +
Prepare the Certificate Keystore
+ +

Tomcat currently operates only on JKS, PKCS11 or +PKCS12 format keystores. The JKS format +is Java's standard "Java KeyStore" format, and is the format created by the +keytool command-line utility. This tool is included in the JDK. +The PKCS12 format is an internet standard, and can be manipulated +via (among other things) OpenSSL and Microsoft's Key-Manager. +

+ +

Each entry in a keystore is identified by an alias string. Whilst many +keystore implementations treat aliases in a case insensitive manner, case +sensitive implementations are available. The PKCS11 specification, +for example, requires that aliases are case sensitive. To avoid issues related +to the case sensitivity of aliases, it is not recommended to use aliases that +differ only in case. +

+ +

To import an existing certificate into a JKS keystore, please read the +documentation (in your JDK documentation package) about keytool. +Note that OpenSSL often adds readable comments before the key, +keytooldoes not support that, so remove the OpenSSL comments if +they exist before importing the key using keytool. +

+

To import an existing certificate signed by your own CA into a PKCS12 +keystore using OpenSSL you would execute a command like: +

openssl pkcs12 -export -in mycert.crt -inkey mykey.key \
+                        -out mycert.p12 -name tomcat -CAfile myCA.crt \
+                        -caname root -chain
+
+For more advanced cases, consult the OpenSSL +documentation. +

+

To create a new keystore from scratch, containing a single self-signed +Certificate, execute the following from a terminal command line:

+

Windows:

+
+%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
+
+

Unix:

+
+$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
+
+ +

(The RSA algorithm should be preferred as a secure algorithm, and this +also ensures general compatibility with other servers and components.)

+ +

This command will create a new file, in the home directory of the user +under which you run it, named ".keystore". To specify a +different location or filename, add the -keystore parameter, +followed by the complete pathname to your keystore file, +to the keytool command shown above. You will also need to +reflect this new location in the server.xml configuration file, +as described later. For example:

+

Windows:

+
+%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
+  -keystore \path\to\my\keystore
+
+

Unix:

+
+$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
+  -keystore /path/to/my/keystore
+
+ +

After executing this command, you will first be prompted for the keystore +password. The default password used by Tomcat is "changeit" +(all lower case), although you can specify a custom password if you like. +You will also need to specify the custom password in the +server.xml configuration file, as described later.

+ +

Next, you will be prompted for general information about this Certificate, +such as company, contact name, and so on. This information will be displayed +to users who attempt to access a secure page in your application, so make +sure that the information provided here matches what they will expect.

+ +

Finally, you will be prompted for the key password, which is the +password specifically for this Certificate (as opposed to any other +Certificates stored in the same keystore file). You MUST +use the same password here as was used for the keystore password itself. +This is a restriction of the Tomcat implementation. +(Currently, the keytool prompt will tell you that pressing the +ENTER key does this for you automatically.)

+ +

If everything was successful, you now have a keystore file with a +Certificate that can be used by your server.

+ +

Note: your private key password and keystore password +should be the same. If they differ, you will get an error along the lines +of java.io.IOException: Cannot recover key, as documented in +Bugzilla issue 38217, +which contains further references for this issue.

+ +
+ +
Edit the Tomcat Configuration File
+

+Tomcat can use two different implementations of SSL: +

    +
  • the JSSE implementation provided as part of the Java runtime (since 1.4)
  • +
  • the APR implementation, which uses the OpenSSL engine by default.
  • +
+The exact configuration details depend on which implementation is being used. +The implementation used by Tomcat is chosen automatically unless it is overriden as described below. +If the installation uses APR +- i.e. you have installed the Tomcat native library - +then it will use the APR SSL implementation, otherwise it will use the Java JSSE implementation. +

+ +

+ To avoid auto configuration you can define which implementation to use by specifying a classname + in the protocol attribute of the Connector.
+ To define a Java (JSSE) connector, regardless of whether the APR library is loaded or not do: +

+<-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11Protocol"
+           port="8443" .../>
+
+<-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
+           port="8443" .../>
+
+Alternatively, to specify an APR connector (the APR library must be available) use: +
+<-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
+           port="8443" .../>
+
+ +

+ +

If you are using APR, you have the option of configuring an alternative engine to OpenSSL. +

+<Listener className="org.apache.catalina.core.AprLifecycleListener"
+          SSLEngine="someengine" SSLRandomSeed="somedevice" />
+
+The default value is +
+<Listener className="org.apache.catalina.core.AprLifecycleListener"
+          SSLEngine="on" SSLRandomSeed="builtin" />
+
+So to use SSL under APR, make sure the SSLEngine attribute is set to something other than off. +The default value is on and if you specify another value, it has to be a valid engine name. +
+If you haven't compiled in SSL support into your Tomcat Native library, then you can turn this initialization off +
+<Listener className="org.apache.catalina.core.AprLifecycleListener"
+          SSLEngine="off" />
+
+SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy +but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy +sources like "/dev/urandom" that will allow quicker starts of Tomcat. + +

+ +

The final step is to configure the Connector in the +$CATALINA_BASE/conf/server.xml file, where +$CATALINA_BASE represents the base directory for the +Tomcat 6 instance. An example <Connector> element +for an SSL connector is included in the default server.xml +file installed with Tomcat. For JSSE, it should look something like this:

+
+<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<!--
+<Connector 
+           port="8443" maxThreads="200"
+           scheme="https" secure="true" SSLEnabled="true"
+           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
+           clientAuth="false" sslProtocol="TLS"/>
+-->
+
+

+ The example above will throw an error if you have the APR and the Tomcat Native libraries in your path, + as Tomcat will try to use the APR connector. The APR connector uses different attributes for + SSL keys and certificates. An example of an APR configuration is: +

+<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<!--
+<Connector 
+           port="8443" maxThreads="200"
+           scheme="https" secure="true" SSLEnabled="true"
+           SSLCertificateFile="/usr/local/ssl/server.crt" 
+           SSLCertificateKeyFile="/usr/local/ssl/server.pem"
+           clientAuth="optional" SSLProtocol="TLSv1"/>
+-->
+
+

+ +

You will note that the Connector element itself is commented out by default, +so you will need to remove the comment tags around it. Then, you can +customize the specified attributes as necessary. For detailed information +about the various options, consult the +Server Configuration Reference. The +following discussion covers only those attributes of most interest when +setting up SSL communication.

+ +

The port attribute (default value is 8443) is the TCP/IP +port number on which Tomcat will listen for secure connections. You can +change this to any port number you wish (such as to the default port for +https communications, which is 443). However, special setup +(outside the scope of this document) is necessary to run Tomcat on port +numbers lower than 1024 on many operating systems.

+ +
+

If you change the port number here, you should also change the + value specified for the redirectPort attribute on the + non-SSL connector. This allows Tomcat to automatically redirect + users who attempt to access a page with a security constraint specifying + that SSL is required, as required by the Servlet Specification.

+
+ +

There are additional options used to configure the SSL protocol. You may +need to add or change some attributes, depending on how you configured your +keystore earlier. If you are using a Java JSSE based SSL connector then +configuration options are documented in the +Java HTTP connector configuration +reference. If you are using the APR/native connector then refer to the +APR connector configuration guide for details of the +available configuration options.

+ +

After completing these configuration changes, you must restart Tomcat as +you normally do, and you should be in business. You should be able to access +any web application supported by Tomcat via SSL. For example, try:

+
+https://localhost:8443
+
+ +

and you should see the usual Tomcat splash page (unless you have modified +the ROOT web application). If this does not work, the following section +contains some troubleshooting tips.

+ +
+ +
Installing a Certificate from a Certificate Authority
+

To obtain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com +or trustcenter.de), read the previous section and then follow these instructions:

+ +
Create a local Certificate Signing Request (CSR)
+

In order to obtain a Certificate from the Certificate Authority of your choice +you have to create a so called Certificate Signing Request (CSR). That CSR will be used +by the Certificate Authority to create a Certificate that will identify your website +as "secure". To create a CSR follow these steps:

+
    +
  • Create a local Certificate (as described in the previous section): +
    keytool -genkey -alias tomcat -keyalg RSA \
    +    -keystore <your_keystore_filename>
    + Note: In some cases you will have to enter the domain of your website (i.e. www.myside.org) + in the field "first- and lastname" in order to create a working Certificate. +
  • +
  • The CSR is then created with: +
    keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr \
    +    -keystore <your_keystore_filename>
    +
  • +
+

Now you have a file called certreq.csr that you can submit to the Certificate Authority (look at the +documentation of the Certificate Authority website on how to do this). In return you get a Certificate.

+
+ +
Importing the Certificate
+

Now that you have your Certificate you can import it into you local keystore. +First of all you have to import a so called Chain Certificate or Root Certificate into your keystore. +After that you can proceed with importing your Certificate.

+ +
    +
  • Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.
    + For Verisign.com commercial certificates go to: + http://www.verisign.com/support/install/intermediate.html
    + For Verisign.com trial certificates go to: + http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html
    + For Trustcenter.de go to: + http://www.trustcenter.de/certservices/cacerts/en/en.htm#server
    + For Thawte.com go to: + http://www.thawte.com/certs/trustmap.html
    +
  • +
  • Import the Chain Certificate into your keystore +
    keytool -import -alias root -keystore <your_keystore_filename> \
    +    -trustcacerts -file <filename_of_the_chain_certificate>
    +
  • +
  • And finally import your new Certificate +
    keytool -import -alias tomcat -keystore <your_keystore_filename> \
    +    -file <your_certificate_filename>
    +
  • +
+
+
Troubleshooting
+ +

Here is a list of common problems that you may encounter when setting up +SSL communications, and what to do about them.

+ +
    + +
  • I get "java.security.NoSuchAlgorithmException" errors in my + log files. +
    +

    The JVM cannot find the JSSE JAR files. Follow all of the directions to + download and install JSSE.

    +
  • + +
  • When Tomcat starts up, I get an exception like + "java.io.FileNotFoundException: {some-directory}/{some-file} not found". +
    +

    A likely explanation is that Tomcat cannot find the keystore file + where it is looking. By default, Tomcat expects the keystore file to + be named .keystore in the user home directory under which + Tomcat is running (which may or may not be the same as yours :-). If + the keystore file is anywhere else, you will need to add a + keystoreFile attribute to the <Factory> + element in the Tomcat + configuration file.

    +
  • + +
  • When Tomcat starts up, I get an exception like + "java.io.FileNotFoundException: Keystore was tampered with, or + password was incorrect". +
    +

    Assuming that someone has not actually tampered with + your keystore file, the most likely cause is that Tomcat is using + a different password than the one you used when you created the + keystore file. To fix this, you can either go back and + recreate the keystore + file, or you can add or update the keystorePass + attribute on the <Connector> element in the + Tomcat configuration + file. REMINDER - Passwords are case sensitive!

    +
  • + +
  • When Tomcat starts up, I get an exception like + "java.net.SocketException: SSL handshake errorjavax.net.ssl.SSLException: No + available certificate or key corresponds to the SSL cipher suites which are + enabled." +
    +

    A likely explanation is that Tomcat cannot find the alias for the server + key withinthe specified keystore. Check that the correct + keystoreFile and keyAlias are specified in the + <Connector> element in the + Tomcat configuration file. + REMINDER - keyAlias values may be case + sensitive!

    +
  • + +
+ +

If you are still having problems, a good source of information is the +TOMCAT-USER mailing list. You can find pointers to archives +of previous messages on this list, as well as subscription and unsubscription +information, at +http://tomcat.apache.org/lists.html.

+ +
Miscellaneous Tips and Bits
+ +

To access the SSL session ID from the request, use:
+ + + String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session"); + +
+For additional discussion on this area, please see +Bugzilla. +

+ +

+ Copyright © 1999-2010, Apache Software Foundation +
\ No newline at end of file http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/faq.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/faq.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/faq.html new file mode 100644 index 0000000..5af7d14 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/faq.html @@ -0,0 +1,7 @@ +Apache Tribes - The Tomcat Cluster Communication Module - Apache Tribes - Frequently Asked Questions
Apache Tomcat

Apache Tomcat 6.0

Apache Logo

Links

User Guide

Reference

Apache Tribes Development

Apache Tribes - The Tomcat Cluster Communication Module

Apache Tribes - Frequently Asked Questions

Frequently Asked Questions
+

+ Copyright © 1999-2010, Apache Software Foundation +
\ No newline at end of file http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/introduction.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/introduction.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/introduction.html new file mode 100644 index 0000000..0c5f5f9 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/introduction.html @@ -0,0 +1,233 @@ +Apache Tribes - The Tomcat Cluster Communication Module - Apache Tribes - Introduction
Apache Tomcat

Apache Tomcat 6.0

Apache Logo

Links

User Guide

Reference

Apache Tribes Development

Apache Tribes - The Tomcat Cluster Communication Module

Apache Tribes - Introduction

Table of Contents
+ +
Quick Start
+ +

Apache Tribes is a group or peer-to-peer communication framework that enables you to easily connect + your remote objects to communicate with each other. +

+
    +
  • Import: org.apache.catalina.tribes.Channel
  • +
  • Import: org.apache.catalina.tribes.Member
  • +
  • Import: org.apache.catalina.tribes.MembershipListener
  • +
  • Import: org.apache.catalina.tribes.ChannelListener
  • +
  • Import: org.apache.catalina.tribes.group.GroupChannel
  • +
  • Create a class that implements: org.apache.catalina.tribes.ChannelListener
  • +
  • Create a class that implements: org.apache.catalina.tribes.MembershipListener
  • +
  • Simple class to demonstrate how to send a message: +
    +        //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);
    +      
    +
  • +
+

+ 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. +

+

+ Note: Tribes is currently built for JDK1.5, you can run on JDK1.4 by a small modifications to locks used from the java.util.concurrent package. +

+
What is Tribes
+

+ 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.
+ 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.
+

+

+ 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 workarounds 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.
+

+

+ In Tomcat the old modules/cluster has now become modules/groupcom(Tribes) and + modules/ha (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 :)
+

+

+ Tribes allows for guaranteed messaging, and can be customized in many ways. Why is this important?
+ 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. +

+ +
Why another messaging framework
+

+ 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.
+ When I did my research to improve the clustering module I was constantly faced with a few obstacles:
+ 1. The framework wasn't flexible enough
+ 2. The framework was licensed in a way that neither I nor the community could use it
+ 3. Several features that I needed were missing
+ 4. Messaging was guaranteed, but no feedback was reported to me
+ 5. The semantics of my message delivery had to be configured before runtime
+ And the list continues... +

+

+ 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. +

+
Feature Overview
+

+ 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. +

+

+ Pluggable modules
+ 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. +

+

+ Guaranteed Messaging
+ 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.
+ 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. +

+

+ Different Guarantee Levels
+ There are three different levels of delivery guarantee when a message is sent.
+

    +
  1. IO Based send guarantee. - fastest, least reliable
    + This means that Tribes considers the message transfer to be successful + if the message was sent to the socket send buffer and accepted.
    + On blocking IO, this would be socket.getOutputStream().write(msg)
    + On non blocking IO, this would be socketChannel.write(), and the buffer byte buffer gets emptied + followed by a socketChannel.read() to ensure the channel still open. + The read() has been added since write() will succeed if the connection has been "closed" + when using NIO. +
  2. +
  3. ACK based. - recommended, guaranteed delivery
    + 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. +
  4. +
  5. SYNC_ACK based. - guaranteed delivery, guaranteed processed, slowest
    + 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. +
  6. +
+ 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. +

+

+ Per Message Delivery Attributes
+ 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.
+ 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 messages, you could send the the following way: +

+      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
+    
+ 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.
+ 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.
+ 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. +

+

+ Interceptor based message processing
+ Tribes uses a customizable interceptor stack to process messages that are sent and received.
+ So what, all frameworks have this!
+ 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.
+ This is how Tribes is able to send some messages totally ordered and others fire and forget style + like the example above.
+ The number of interceptors that are available will keep growing, and we would appreciate any contributions + that you might have. +

+

+ Threadless Interceptor stack + The interceptor don't require any separate threads to perform their message manipulation.
+ Messages that are sent will piggy back on the thread that is sending them all the way through transmission. + The exception is the MessageDispatchInterceptor 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 receiver component.
+ The channel object can send a heartbeat() through the interceptor stack to allow + for timeouts, cleanup and other events.
+ The MessageDispatchInterceptor is the only interceptor that is configured by default. +

+

+ Parallel Delivery
+ 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.
+ Through NIO, Tribes is also able to send a message to several receivers at the same time on the same thread. +

+

+ Silent Member Messaging
+ 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 +

+
Where can I get Tribes
+

+ Tribes ships as a module with Tomcat, and is released as part of the Apache Tomcat release. +

+ + +

+ Copyright © 1999-2010, Apache Software Foundation +
\ No newline at end of file http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/setup.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/setup.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/setup.html new file mode 100644 index 0000000..e80f4be --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/tribes/setup.html @@ -0,0 +1,7 @@ +Apache Tribes - The Tomcat Cluster Communication Module - Apache Tribes - Configuration
Apache Tomcat

Apache Tomcat 6.0

Apache Logo

Links

User Guide

Reference

Apache Tribes Development

Apache Tribes - The Tomcat Cluster Communication Module

Apache Tribes - Configuration

Configuration Overview
+

+ Copyright © 1999-2010, Apache Software Foundation +
\ No newline at end of file