1. [13-Mar-2005] JettyPlus updated to JOTM 2.0.5and XAPool 1.4.2
2. [03-Mar-2005] JAAS enhancement to retrieve extra fields from login forms
3. [22-Aug-2004] JettyPlus now updated to XAPool 1.3.3
4. [22-Aug-2004] JettyPlus supports pluggable DataSources
5. [13-Jun-2004] JettyPlus now supports JMX
6. [07-Apr-2004] JettyPlus now updated to JOTM 1.4.3
7. [07-Apr-2004] new start configuration for JettyPlus start.jar

# JettyPlus://

## About these instructions

The instructions in these pages served from http://jetty.mortbay.org refer to the most recent release (or the CVS `HEAD` version, whichever is most recent) of JettyPlus. The JettyPlus downloads contain instructions matching the downloaded version, and can be accessed on your local machine by running the Jetty demo webapp:

`java -jar start.jar etc/demo.xml`

and surfing to the `URL http://localhost:8080/jetty/plus`

## What it is, where to get it and how to run it

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 JettyJBoss and JettyJOnAS).

The feature set currently contains:

- Java Transaction API (JTA) and Resource references, eg DataSources
- Java Naming and Directory Interface API (JNDI)
- Log4J
- Java Authentication and Authorization Service (JAAS)
- Java Mail

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.

### Downloading

JettyPlus is part of the Jetty SourceForge project. To obtain JettyPlus you can:

- check out Jetty from CVS (see CVS instructions). The JettyPlus source is in `$JETTY_HOME/extra/plus`.
- download a release of the `Jetty-X.X.X-extra.tar.gz` 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).
- download a release of the `Jetty-X.X.X-all.tar.gz` bundle which contains standard Jetty, along with all the extra extensions (including JettyPlus).

### Configuration

To use JettyPlus, you must configure the `org.mortbay.jetty.plus.Server` class in your xml configuration file rather than the standard `org.mortbay.jetty.Server` class, eg:
`

      <Configure class="org.mortbay.jetty.plus.Server">

`

You may also need to provide configuration for JettyPlus features that you want to use.

### Starting JettyPlus

To start JettyPlus:
`

       java -DSTART=extra/etc/start-plus.config -jar start.jar config.xml

`

### JettyPlus with JMX

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 `extra/etc/jettyplus-jmx.xml`

To start JettyPlus with JMX support:
``

     java -Dmain.class=org.mortbay.xml.XmlConfiguration -jar start.jar extra/etc/jettyplus-jmx.xml

If you have copied the example mlet file setup, the JMX http adaptor can be found on port `8082`.

### More information ...

If you use the convenient `start.jar` method of running Jetty as described above (highly recommended!), all necessary jar and property files will be automatically be placed on the JVM classpath for you.

Otherwise, you need to set up the the classpath yourself. JettyPlus consists of `org.mortbay.jetty.plus.jar`, `org.mortbay.jaas.jar` as well as a number of libraries found in `extra/ext` and property files found in `extra/resources`.

- all property files in extra/resources
- org.mortbay.jetty.plus.jar
- org.mortbay.jetty.jaas.jar (if you want to use JAAS)
- activation.jar
- mail.jar
- carol.jar
- commons-cli.jar
- commons-logging.jar
- hsqldb.jar (only for running the demo webapps)
- jonas_timer.jar
- jotm.jar
- jotm_iiop_stubs.jar
- jotm_jrmp_stubs.jar
- jta-spec1_0_1.jar
- jts1_0.jar
- log4j.jar
- objectweb-datasource.jar
- xapool.jar

The `extra/plus/README.TXT` file in the source distribution contains more information on the JettyPlus package, including instructions on how to run the JettyPlus demonstration webapps.

## Features

### Transactions and XADataSources

Click here for information on distributed transactions and XA resources.

### Non-XA DataSources

Click here for information on DataSource resources

### Mail Service

A mail service is provided with JettyPlus. This means that you can send email programmatically from servlets, JSPs etc.

To use the mail service, you need to:

- Step 1: reference the Mail Service in your `web.xml` descriptor as a resource. Eg. `

        <resource-env-ref>
          <description>
            Mail Service
          </description>
          <resource-env-ref-name>
            mail/Session <!-- must be same as JNDI name in xml config file (see step 2) -->
          </resource-env-ref-name>
          <resource-env-ref-type>
            javax.mail.Session
          </resource-env-ref-type>
        </resource-env-ref>

  `
- Step 2: set up the Mail Service in your JettyPlus xml configuration file. Eg: `

        <Call name="addService">
          <Arg>
            <New class="org.mortbay.jetty.plus.MailService">
              <Set name="Name">MailService</Set>
              <Set name="JNDI">mail/Session</Set>
              <!-- set up the id of the smtp user                 -->
              <Set name="User">XXX</Set>
              <!-- set up the password of the smtp user           -->
              <Set name="Password">XXX</Set>
               <!-- set up the hostname/ip addr of the smtp server -->
              <Put name="mail.smtp.host">XXX</Put>
               <!-- setup any javax.mail.smtp provider variables   -->
              <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>

  `
- Step 3: access it in your code. Eg: `

        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);

  `

### JNDI

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:

- Step 1: enter some env entries in your webapp web.xml file, eg: `

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

  `
- Step 2: obtain a javax.naming.InitialContext object and call the lookup method, eg: `

       InitialContext context = new InitialContext();
       String starwars = (String)context.lookup("java:comp/env/someEnv");

  `

New: JettyPlus JNDI service is now lenient on leading and trailing `"/"` elements of JNDI names. This avoids a lot of errors caused by mis-typings. For example, the following are all now equivalent:

> `

>     java:comp/env/mything (strictly the correct form according to the spec)
>     java:/comp/env/mything
>     java:/comp/env/mything/

> `

### Log4J

The JettyPlus package provides a Jetty `org.mortbay.util.LogSink` to enable Jetty log messages to appear in Log4J style logs. The `extra/resources` directory is added to the classpath by `extra/etc/start.config` and contains a `log4j.properties` configuration file which may be modified as needed.

To use Log4J:

- Step 1: configure the LogSink in your Jetty xml configuration file, eg: `

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

  `
- Step 2: enable it on the command line: `

        java -Dlog4j.configuration=log4j.properties -jar start.jar config.xml

  `

### JAAS

JAAS provides a pluggable framework for authenticating and authorising users. JettyPlus JAAS integrates this with the declarative security model of the Java Servlet Specification.

The Jetty JAAS classes are not included in the main JettyPlus jar (`org.mortbay.jetty.plus.jar`). Instead, it is built as `org.mortbay.jaas.jar` to enable it to be used either with standard Jetty, or with JettyPlus.

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 (`org.mortbay.jaas.spi.JDBCLoginModule`), interacting with a database to store user names, passwords and roles, is included with the release to illustrate what to implement.

Some important classes are:

org.mortbay.jaas.JAASUserRealm
  This bridges Jetty's realm concept to JAAS. This class must be configured as the realm for your webapp.
org.mortbay.jaas.JAASPrincipal
  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.
org.mortbay.jaas.JAASRole
  This is a Principal that represents a role possessed by a user.
org.mortbay.jaas.JAASGroup
  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".
org.mortbay.jaas.spi.JDBCLoginModule
  An example implementation of a LoginModule that uses a database to store user names, passwords and roles. All database-related information is configurable, including:
  - the names and columns of the user table and role table
  - the database connection driver, URL, username and password.

#### Using JAAS

- Step 1: Configure the realm for your webapp context in the Jetty xml configuration file: `

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

  ` Note that it is only actually necessary to specify the `RoleCheckPolicy` or `CallbackHandlerClass` if you have provided custom implementations of them.
- Step 2: Configure some security constraints and a login method in your `web.xml` file, eg: `

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

  `
- Step 3: Create a login module configuration file. This one is from the Jetty JAAS demo (in `extra/etc/login.conf`): `

            // 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";
            };

  ` Note that the name of the module ("jdbc") must be the same as that specified as the `LoginModuleName` in the Jetty xml config file in Step 1.

  There is no particular schema required for the database tables storing the authentication and role information. The properties `userTable, userField, credentialField, userRoleTable, userRoleUserField, userRoleRoleField` configure the names of the tables and the columns within them that are used to format the following queries: ``

        select <credentialField> from <userTable> where <userField> =?
        select <userRoleRoleField> from <userRoleTable> where <userRoleUserField> =?

- Step 4: Specify the location of the login configuration file on the Jetty run line by setting the `java.security.auth.login.config` property: `

          -Djava.security.auth.login.config=mylogin.conf

  `

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 `extra/plus` as instructed in the `extra/plus/README.TXT` file in the source distribution.

#### Extension for extra fields with FORM login

As all servlet containers intercept and process a form submission with action `j_security_check`, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass `j_username` and `j_password`. 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 org.mortbay.jaas.callback.RequestParameterCallback. This callback handler gives you access to all parameters that were passed in the form submission. To use it:

- Create a custom JAAS login module. Use the org.mortbay.jaas.spi.JDBCLoginModule as an example.
- In the `login()` method of your custom login module, add the `RequestParameterCallback` 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:

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