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:
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.
$JETTY_HOME/extra/plus
.
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).
Jetty-X.X.X-all.tar.gz
bundle which contains standard Jetty, along with all the extra extensions (including JettyPlus).
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.
java -DSTART=extra/etc/start-plus.config -jar start.jar config.xml
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
.
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
.
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
To use the mail service, you need to:
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>
<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);
<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>
InitialContext context = new InitialContext();
String starwars = (String)context.lookup("java:comp/env/someEnv");
"/"
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/
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:
<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>
java -Dlog4j.configuration=log4j.properties -jar start.jar config.xml
The Jetty JAAS classes are 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:
<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.
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>
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> =?
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.
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:
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 . . . }