<P>
<div class="whatsnew">
<img src="/jetty/images/whatsnew.gif"/>
<div>
<ol>
<li>[13-Mar-2005] JettyPlus updated to <a href="http://jotm.objectweb.org">JOTM 2.0.5</a>and <a href="http://xapool.experlog.com">XAPool 1.4.2</a></li>
<li>[03-Mar-2005] <a href="#loginextra">JAAS enhancement</a> to retrieve extra fields from login forms</li>
<li>[22-Aug-2004] JettyPlus now updated to <a href="http://xapool.experlog.com">XAPool 1.3.3</a></li>
<li>[22-Aug-2004] JettyPlus supports <A href="#datasource">pluggable DataSources</A></li>
<li>[13-Jun-2004] JettyPlus now <A href="#jmx">supports JMX</a></li>
<li>[07-Apr-2004] JettyPlus now updated to <a href="http://jotm.objectweb.org">JOTM 1.4.3 </a></li>
<li>[07-Apr-2004] new <A href="#start.config">start configuration</a> for JettyPlus start.jar</li>
</ol>
</div>
</div>
<H1>JettyPlus://</H1>
<h2>About these instructions</h2>
The instructions in these pages served from <a href="http://jetty.mortbay.org">http://jetty.mortbay.org</a> refer to the most recent release (or the CVS <code>HEAD</code> version, whichever is most recent) of JettyPlus. The JettyPlus <a href="#download">downloads</a> contain instructions matching the downloaded version, and can be accessed on your local machine by running the Jetty demo webapp:
<p>
<code>java -jar start.jar etc/demo.xml</code>
<p>
and surfing to the <code>URL http://localhost:8080/jetty/plus</code>
<A name="start.config">
<h2> What it is, where to get it and how to run it</h2>
</a>
The purpose of this project is to enrich Jetty by
selectively incorporating useful J2EE and non-J2EE features. The result is
JettyPlus, an environment offering additional facilities to
core web and servlet services, but which does not entail a full-blown
application server (such as <A HREF="/jetty/jboss/index.html">JettyJBoss</A> and <A HREF="/jetty/jonas/index.html">JettyJOnAS</A>).
<P>
The feature set currently contains:
<ul>
<li> <A HREF="http://java.sun.com/j2ee/transactions.html">Java
Transaction API (JTA)</A> and Resource references, eg <A HREF="http://java.sun.com/j2se/1.4.1/docs/api/javax/sql/package-summary.html">DataSources</A>
<li> <A HREF="http://java.sun.com/products/jndi/">Java Naming and Directory Interface API (JNDI)</A>
<li> <A HREF="http://jakarta.apache.org/log4j/docs/">Log4J</A>
<li> <A HREF="http://java.sun.com/products/jaas/">Java Authentication and Authorization Service (JAAS)</A>
<li> <A HREF="http://java.sun.com/products/javamail/">Java Mail</A>
</ul>
<P>
These features have been implemented as a pluggable, Service-based architecture. This means that it is possible to develop and use alternative services to those provided.
</P>
<a name="download">
<h3>Downloading</h3>
</a>
JettyPlus is part of the <a href="http://sourceforge.net/projects/jetty/">Jetty SourceForge</a> project. To obtain JettyPlus you can:
<ul>
<li>check out Jetty from CVS (see <a href="http://sourceforge.net/cvs/?group_id=7322">CVS instructions</a>). The JettyPlus source is in <code>$JETTY_HOME/extra/plus</code>.
</li>
<li><a href="/jetty/download.html">download</a> a release of the <code>Jetty-X.X.X-extra.tar.gz</code> bundle which contains a number of extensions to Jetty, including JettyPlus. (Note: as this bundle does NOT include standard Jetty, you will need to install it separately before you can run JettyPlus).
</li>
<li><a href="/jetty/download.html">download</a> a release of the <code>Jetty-X.X.X-all.tar.gz</code> bundle which contains standard Jetty, along with all the extra extensions (including JettyPlus).
</li>
</ul>
<h3>Configuration</h3>
To use JettyPlus, you must configure the <code>org.mortbay.jetty.plus.Server</code>
class in your xml configuration file rather than the standard
<code>org.mortbay.jetty.Server</code> class, eg:
<BR>
<code><pre> <Configure class="org.mortbay.jetty.plus.Server"></code></pre>
<P>
You may also need to provide configuration for JettyPlus <a href="#feature-config">features</a> that you want to use.
<h3>Starting JettyPlus</h3>
To start JettyPlus:
<BR>
<code><pre> java -DSTART=extra/etc/start-plus.config -jar start.jar config.xml</code></pre>
<BR>
<a name="jmx">
<h3>JettyPlus with JMX</h3>
</a>
JettyPlus supports JMX for management. As with standard Jetty, to enable the JMX support, you must start JettyPlus with an jmx config file. This boot
file must contain one mbean entry for each Server instance you wish to run, and usually also an entry for a JMX http adaptor. An example is in
<code><b>extra/etc/jettyplus-jmx.xml</b></code>
<P>
To start JettyPlus with JMX support:
<BR>
<code><pre> java -Dmain.class=org.mortbay.xml.XmlConfiguration -jar start.jar extra/etc/jettyplus-jmx.xml</pre></code>
<BR>
If you have copied the example mlet file setup, the JMX http adaptor can be found on port <code><b>8082</b></code>.
<h3>More information ...</h3>
If you use the convenient <code>start.jar</code> method of running Jetty as described above (<i>highly recommended!</i>), all necessary jar and property files will be <i>automatically</i> be placed on the JVM classpath for you.
<p>
<i>Otherwise</i>, you need to set up the the classpath yourself. JettyPlus consists of <code><b>org.mortbay.jetty.plus.jar</b></code>, <code><b>org.mortbay.jaas.jar</b></code> as well
as a number of libraries found in <code><b>extra/ext</b></code> and property files found in <code><b>extra/resources</b></code>.
<ul>
<li>all property files in extra/resources</li>
<li>org.mortbay.jetty.plus.jar
<li>org.mortbay.jetty.jaas.jar (if you want to use JAAS)
<li>activation.jar
<li>mail.jar
<li>carol.jar
<li>commons-cli.jar
<li>commons-logging.jar
<li>hsqldb.jar (only for running the demo webapps)
<li>jonas_timer.jar
<li>jotm.jar
<li>jotm_iiop_stubs.jar
<li>jotm_jrmp_stubs.jar
<li>jta-spec1_0_1.jar
<li>jts1_0.jar
<li>log4j.jar
<li>objectweb-datasource.jar
<li>xapool.jar
</ul>
<P>
The <code>extra/plus/README.TXT</code> file in the source distribution
contains more information on the JettyPlus package, including
instructions on how to run the JettyPlus demonstration webapps.
<P>
<A name="feature-config"><h2>Features</H2></a>
<A href="xadatasources.html"><H3>Transactions and XADataSources</H3></a>
Click here for <a href="xadatasources.html">information on distributed transactions and XA resources</a>.
<A href="datasources.html"><H3>Non-XA DataSources</H3></a>
Click here for <a href="datasources.html">information on DataSource resources</a>
<H3>Mail Service </H3>
A mail service is provided with JettyPlus. This means that you can send email programmatically from servlets, JSPs etc.
<P>
To use the mail service, you need to:
<P>
<ul>
<li><B>Step 1:</B> reference the Mail Service in your <code>web.xml</code>
descriptor as a resource. Eg.
<code><pre>
<resource-env-ref>
<description>
Mail Service
</description>
<resource-env-ref-name>
mail/Session <font color=silver><!-- must be same as JNDI name in xml config file (see step 2) --></font>
</resource-env-ref-name>
<resource-env-ref-type>
javax.mail.Session
</resource-env-ref-type>
</resource-env-ref>
</pre></code>
</li>
<li><B>Step 2:</B> set up the Mail Service in your JettyPlus xml
configuration file. Eg:
<code><pre>
<Call name="addService">
<Arg>
<New class="org.mortbay.jetty.plus.MailService">
<Set name="Name">MailService</Set>
<Set name="JNDI">mail/Session</Set>
<font color="silver"><!-- set up the id of the smtp user --></font>
<Set name="User">XXX</Set>
<font color="silver"><!-- set up the password of the smtp user --></font>
<Set name="Password">XXX</Set>
<font color="silver"> <!-- set up the hostname/ip addr of the smtp server --></font>
<Put name="mail.smtp.host">XXX</Put>
<font color="silver"> <!-- setup any javax.mail.smtp provider variables --></font>
<Put name="mail.pop3.user">zzz</Put>
<Put name="mail.pop3.host">vvv</Put>
<Put name="mail.from">me@me</Put>
<Put name="mail.debug">false</Put>
</New>
</Arg>
</Call>
<li><B>Step 3:</B> access it in your code. Eg:
<code><pre>
javax.mail.Session session =
(javax.mail.Session)context.lookup("java:comp/env/mail/Session");
Message msg = new MimeMessage(session);
msg.setFrom(new InternetAddress("me@me.com"));
msg.addRecipient(new InternetAddress("you@you.com"));
msg.setContent("Hi");
Transport.send(msg);
</code></pre>
</li>
</ul>
<H3>JNDI </H3>
JettyPlus supports JNDI, including ENC lookups of <env-entry> tags in the
web.xml descriptor. All you need to do to effect JNDI env lookups in your code is to:
<ul>
<li><B>Step 1:</B> enter some env entries in your webapp
web.xml file, eg:
<code><pre>
<env-entry>
<env-entry-name>
someEnv
</env-entry-name>
<env-entry-value>
A long time ago in a galaxy far far away
</env-entry-value>
<env-entry-type>
java.lang.String
</env-entry-type>
</env-entry>
</code></pre>
</li>
<li><B>Step 2:</B> obtain a javax.naming.InitialContext object and call the lookup
method, eg:
<code><pre>
InitialContext context = new InitialContext();
String starwars = (String)context.lookup("java:comp/env/someEnv");
</code></pre>
</li>
</ul>
<font color=red><i>New:</i></font> JettyPlus JNDI service is now lenient on leading and trailing <code>"/"</code> elements of JNDI names. This avoids a lot of errors caused by mis-typings. For example, the following are all now equivalent:
<blockquote>
<code>
<pre>
java:comp/env/mything (strictly the correct form according to the spec)
java:/comp/env/mything
java:/comp/env/mything/
</pre>
</code>
</blockquote>
<P>
<H3> Log4J </H3>
The JettyPlus package provides a Jetty <code>org.mortbay.util.LogSink</code> to
enable Jetty log messages to appear in Log4J style logs. The
<code>extra/resources</code> directory is added to the classpath by
<code>extra/etc/start.config</code> and contains a
<code>log4j.properties</code> configuration file which may be modified
as needed.
<P>
To use Log4J:
<ul>
<li><b>Step 1:</b> configure the LogSink in your Jetty xml
configuration file, eg:
<code><pre>
<Call name="instance" class="org.mortbay.util.Log">
<Call name="disableLog"/>
<Call name="add">
<Arg>
<New class="org.mortbay.util.log4j.Log4jSink">
<Call name="start"/>
</New>
</Arg>
</Call>
</Call>
</pre></code>
</li>
<li><b>Step 2:</b> enable it on the command line:
<code><pre>
java -Dlog4j.configuration=log4j.properties -jar start.jar config.xml
</pre></code>
</ul>
<H3>JAAS</H3>
JAAS provides a pluggable framework for authenticating and
authorising users. JettyPlus JAAS integrates this with the declarative
security model of the Java Servlet Specification.
<P>
The Jetty JAAS classes are <emph>not</emph> included in the main
JettyPlus jar (<code>org.mortbay.jetty.plus.jar</code>). Instead, it is built
as <code>org.mortbay.jaas.jar</code> to enable it to be used
either with standard Jetty, or with JettyPlus.
<P>
As JAAS is a pluggable framework, the Jetty JAAS integration
aims to dictate as little as possible whilst providing
a sufficiently flexible infrastructure to allow users to drop in
their own custom LoginModules. An example LoginModule (<code>org.mortbay.jaas.spi.JDBCLoginModule</code>),
interacting with a database to store user names, passwords and
roles, is included with the release to illustrate what to
implement.
<P>
Some important classes are:
<dl>
<dt><b>org.mortbay.jaas.JAASUserRealm</b></dt>
<dd> This bridges Jetty's realm concept to JAAS. This class must be
configured as the realm for your webapp.</dd>
<dt><b>org.mortbay.jaas.JAASPrincipal</b></dt>
<dd> Implements the java.security.Principal interface. This class is
used by the sample JDBCLoginModule, but the Jetty JAAS infrastructure
is Principal agnostic, meaning you can use your own
implementation of this class for your LoginModules if you wish.</dd>
<dt><b>org.mortbay.jaas.JAASRole</b></dt>
<dd>This is a Principal that represents a role possessed by a
user.</dd>
<dt><b>org.mortbay.jaas.JAASGroup</b></dt>
<dd>An implementation of the java.security.acl.Group interface. It is
used only by the sample JDBCLoginModule to group all roles
possessed by a user under a single Principal called "roles".</dd>
<dt><b>org.mortbay.jaas.spi.JDBCLoginModule</b></dt>
<dd>An example implementation of a LoginModule that uses a database to store
user names, passwords and roles. All database-related information
is configurable, including:
<ul>
<li>the names and columns of the user table and role table
<li>the database connection driver, URL, username and password.
</ul>
</dd>
</dl>
<P>
<H4>Using JAAS</H4>
<ul>
<li><b>Step 1:</b> Configure the realm for your webapp
context in the Jetty xml configuration file:
<code><pre>
<Call name="addWebApplication">
<Arg>/jaas/*</Arg>
<Arg><SystemProperty name="jetty.home"/>/extra/plus/demo/webapps/jaas</Arg>
<Set name="Realm">
<New class="org.mortbay.jaas.JAASUserRealm">
<Set name="Name">Test JAAS Realm</Set>
<Set name="LoginModuleName">jdbc</Set>
<Set name="RoleCheckPolicy">
<New class="org.mortbay.jaas.StrictRoleCheckPolicy"/>
</Set>
<Set name="CallbackHandlerClass">
org.mortbay.jaas.callback.DefaultCallbackHandler
</Set>
</New>
</Set>
</Call>
</pre></code>
Note that it is only actually necessary to specify the
<code>RoleCheckPolicy</code> or
<code>CallbackHandlerClass</code> if you have provided custom
implementations of them.
</li>
<BR>
<li><b>Step 2:</b> Configure some security constraints and a
login method in your
<code>web.xml</code> file, eg:
<code><pre>
<security-constraint>
<web-resource-collection>
<web-resource-name>JAAS Role</web-resource-name>
<url-pattern>/doit/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>roleA</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<realm-name>Test JAAS Realm</realm-name>
<form-login-config>
<form-login-page>/login.html </form-login-page>
<form-error-page>/error401.html </form-error-page>
</form-login-config>
</login-config>
</pre></code>
</li>
<li><b>Step 3:</b> Create a login module configuration
file. This one is from the Jetty JAAS demo (in <code>extra/etc/login.conf</code>):
<code><pre>
// sample login config file for the Jetty JDBCLoginModule
// if you change the database and need to specify a password, set the property dbPassword
jdbc {
org.mortbay.jaas.spi.JDBCLoginModule required
debug="true"
dbUrl="jdbc:hsqldb:."
dbUserName="sa"
dbDriver="org.hsqldb.jdbcDriver"
userTable="myusers"
userField="myuser"
credentialField="mypassword"
userRoleTable="myuserroles"
userRoleUserField="myuser"
userRoleRoleField="myrole";
};
</pre></code>
Note that the name of the module ("jdbc") must be the same as
that specified as the <code>LoginModuleName</code> in the Jetty
xml config file in Step 1.
<P>There is no particular schema required for the database tables storing the authentication and role information. The properties <code>userTable, userField, credentialField, userRoleTable, userRoleUserField, userRoleRoleField</code> configure the names of the tables and the columns within them that are used to format the following queries:
<code><pre>
select <credentialField> from <userTable> where <userField> =?
select <userRoleRoleField> from <userRoleTable> where <userRoleUserField> =?
</pre></code>
</li>
<BR>
<li><b>Step 4:</b> Specify the location of the login
configuration file on the Jetty run line by setting the
<code>java.security.auth.login.config</code> property:
<code><pre>
-Djava.security.auth.login.config=mylogin.conf
</pre></code>
</li>
</ul>
<P>
The above describes how to use the Jetty JAAS integration to
authenticate web users and authorize them against webapp security
constraints. It can also be used for authorization with a Java
security manager and permission policy file. For information on
how to accomplish this, build and run the JAAS demo in <code>extra/plus</code>
as instructed in the <code>extra/plus/README.TXT</code> file in the source distribution.
</P>
<a name="loginextra">
<H4>Extension for extra fields with FORM login</H4>
</a>
As all servlet containers intercept and process a form submission with action <code>j_security_check</code>, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass <code>j_username</code> and <code>j_password</code>. For those rare occasions when this is not good enough, and you require more information from the user in order to authenticate them, you can use the (new) JAAS callback handler <a href="/javadoc/org/mortbay/jaas/callback/RequestParameterCallback">org.mortbay.jaas.callback.RequestParameterCallback</a>. This callback handler gives you access to all parameters that were passed in the form submission. To use it:
<ul>
<li> Create a custom JAAS login module. Use the <a href="/javadoc/org/mortbay/jaas/spi/JDBCLoginModule">org.mortbay.jaas.spi.JDBCLoginModule</a> as an example.</li>
<li> In the <code>login()</code> method of your custom login module, add the <code>RequestParameterCallback</code> to the list of callback handlers the login module uses, tell it which params you are interested in, and then get the value of the parameter back:
<pre>
public boolean login()
throws LoginException
{
.
.
.
Callback[] callbacks = new Callback[3];
callbacks[0] = new NameCallback();
callbacks[1] = new ObjectCallback();
//as an example, look for a param named "extrainfo" in the request
//use one RequestParameterCallback() instance for each param you want to access
callbacks[2] = new RequestParameterCallback ();
((RequestParameterCallback)callbacks[2]).setParameterName ("extrainfo");
.
.
.
callbackHandler.handle(callbacks);
String userName = ((NameCallback)callbacks[0]).getName();
Object pwd = ((ObjectCallback)callbacks[1]).getObject();
List paramValues = ((RequestParameterCallback)callbacks[2]).getParameterValues();
//use the userName, pwd and the value(s) of the parameter named "extrainfo" to
//authenticate the user
.
.
.
}
</pre>
</li>
</ul>
