resources: class loaders, environment and ioc

Environment tags configure class-loaders, logging, authentication
and resources like databases, JMS queues, EJB servers, and web service
clients. Many of the resources are stored in JNDI or in EL variables
for later assembly.

Any environment resource can appear in any
of Resin environments: <resin>, <cluster>, <host> and <web-app>.
Resources configured at parent levels are shared among all children,
so a database can share connection pools for all web-apps or an
authenticator can provide single-signon.

<authenticator>

child of <resin>,<cluster>,<host>,<web-app>,<login-config>

<authenticator> configures an authentication resource
for the current environment context. The authenticator is used for
login and also for the getUserPrincipal
and isUserInRole methods of the
HttpServletRequest object.

The authenticators are scoped to their containing environment.
An authenticator defined in
WEB-INF/resin-web.xml applies only to the web-app, while an
authenticator defined in the <cluster> section of the resin.conf
applies to the entire cluster. The <management> configuration provides an authenticator which is available
to all applications.

Resin's servlet authentication uses an authentication resource to
validate user login and to provide single-signon capability.
The authenticator is configured in the environment context
where it is shared. An authenticator configured in the web-app
only applies to the web-app, but an authenticator configured in
the host will apply to all hosts.

The authenticator class is selected with the uri or
class attribute. The class can be any custom class
extending com.caucho.server.security.AbstractAuthenticator.
The uri is a symbolic name for the authenticator class.
More details on the predefined authenticators are in the
Resin security documentation.

properties: Java properties-style authentication.

jaas: JAAS authentication.

jdbc: JDBC password-based authentication.

xml: XML JDBC password-based authentication.

Configuration of the authenticator uses bean-style configuration in the
<init> tag.

<bean>

<bean> configures a custom singleton bean and stores in the
WebBeans registry. <bean> is a primary configuration tag
for Resin's IoC capabilities.
The bean can also be optional registered in JNDI.

Custom configuration of the bean is in the <init> section.
Field values may use JSP-EL expressions as well as constant strings
or even complex sub-beans. More details for configuring singleton
beans are in Resin IoC.

<case-insensitive>

Because some operating systems are case-insensitive, it is important
for security reasons for Resin to behave differently for case-sensitive
and case-insensitive directories. For example, when case-insensitive
is true, url-patterns will match in a case-insensitive manner, so TEST.JSP
will work like test.jsp.

<case-insensitive> schema

r_case-insensitive = element case-insensitive {
r_boolean-Type
}

<character-encoding>

child of <resin>,<cluster>,<host>,<web-app>

default The default value is ISO-8859-1.

<character-encoding> specifies the default character
encoding for the environment.

<class-loader>

child of <resin>,<cluster>,<host>,<web-app>

<class-loader> configures a dynamic classloader
for the current environment.

Each environment (<cluster>, <host>, <web-app>) etc,
can add dynamic classloaders. The environment will inherit the parent
classloaders. Each <class-loader> is comprised of several implementing
loader items: library-loader for WEB-INF/lib, compiling-loader for
WEB-INF/classes.

For web-apps, the classloaders generally belong in a <prologue>
section, which ensures that Resin evaluates them first. The evaluation
order is particularly important in cases like resin-web.xml vs web.xml,
because the resin-web.xml is evaluated after the web.xml.

classloader types

ELEMENT

DESCRIPTION

<compiling-loader>

Automatically compiles sources code to
classes. It its the default loader for WEB-INF/classes.

<library-loader>

Loads jar files from a directory. It is the default loader
for WEB-INF/lib.

<simple-loader>

Loads classes from a directory, but does not compile them
automatically.

<component>

child of <resin>,<cluster>,<host>,<web-app>

<component> configures a component bean template and stores in the
WebBeans registry. Injection of a <component> will generally create a
new bean instance in constrast to the singleton <bean>.
<component> is a primary configuration tag
for Resin's IoC capabilities.
The bean can also be optionally registered in JNDI.

Custom configuration of the component is in the <init> section.
Field values may use JSP-EL expressions as well as constant strings
or even complex sub-beans. More details for configuring singleton
beans are in Resin IoC.

<dependency-check-interval>

child of <resin>,<cluster>,<host>,<web-app>

default 2s

<dependency-check-interval> Configures how often the environment context
should be checked for changes. The default value is set low for
development purposes, deployments should use something larger like
5m or 1h.

Resin automatically checks each environment for updates, generally
class or configuration updates. Because these checks can take a considerable
amount of time, deployment servers should use high values like 60s or more while development machines will want low values like 2s.

The interval defaults to the parent's interval. So the web-app will
default to the host's value.

<ejb-message-bean>

child of <resin>,<cluster>,<host>,<web-app>

<ejb-message-bean> configures a bean as a message listener.
The listener can be a simple bean that just implements the
javax.jms.MessageListener interface. No other packaging
or complications are necessary. Resin will retrieve messages from a
configured queue and pass them to the listener as they arrive. The
listeners are typically pooled.

The bean has full access to Resin-IoC capabilities, including
dependency injection, transaction attributes, and aspect interception.

The message bean can plug into custom messaging systems. The
application will need to define a ResourceAdapter and
an ActivationSpec. More details are available in the
Resin Messaging section.

<ejb-stateful-bean>

<ejb-stateful-bean> configures an EJB @Stateful bean. The
@Stateful bean is a single-threaded component bean suitable for
transaction processing. See Resin EJB
for more details.

The stateful-bean is registered in the Resin-IoC/WebBeans context and
optionally with JNDI.

Since @Stateful beans are components, they are created at the request
of the application and destroyed by the application. @Stateful beans are
never singletons. For singleton-style beans, either use a <bean> or
a @Stateless session bean.

<ejb-stateless-bean>

<ejb-stateless-bean> configures an EJB @Stateless bean. The
@Statelesss bean is a pooled, proxied, singleton component bean suitable.
See Resin EJB for more details.

The stateless-bean is registered in the Resin-IoC/WebBeans context and
optionally with JNDI.

@Stateless beans are similar to <bean> singletons, but pool instances.
Each instance executes a single thread at a time, unlike <bean>
singletons which are multithreaded like servlets. Both styles can
use the same aspect capabilities like dependency injection, transactions,
and interceptors. Because @Stateless beans are singletons, they
do not have a scope attribute.

<ejb-stateless-bean> Attributes

ATTRIBUTE

DESCRIPTION

DEFAULT

class

the classname of the bean implementation

required

init

IoC initialization for each bean instance

jndi-name

A JNDI name to store the bean as.

name

The Resin-IoC/WebBeans @Named registration

The classname

<ejb-stateless-bean> schema

element ejb-stateless-bean {
class
& init?
& jndi-name?
& name?
}

<env-entry>

Some application beans prefer to retrieve configuration data from JNDI,
including String, Integer, and Double constants. env-entry configures
that data in the current context. As with other Resin configuration, the
value can use JSP-EL expressions.

The example configuration stores a string in java:comp/env/greeting.
Following the J2EE spec, the env-entry-name is relative to
java:comp/env. If the env-entry is in the <host> context, it will
be visible to all web-apps in the host.

<fileset>

<fileset> provides the ability to match a set of files. It is
modelled after the ant tag by the same name. The fileset matches
files from a base directory defined by 'dir'. Files can be included
by patterns defined by <include> tags or excluded by patterns defined in
<exclude> tags.

<fileset> Attributes

ATTRIBUTE

DESCRIPTION

DEFAULT

dir

the starting directory

required

include

an include pattern

do not include all files

exclude

an exclude pattern

do not exclude any files

<fileset> schema

element fileset {
dir
& exclude*
& include*

fileset patterns

A pattern can contain two special characters: '*' and '**'. '*' matches any
part of path, but does not match the path separator. '**' matches any part of
a path, including the path separator.

The following example matches .jar files in WEB-INF/lib. Since it does
not search the lib directory recursively, WEB-INF/lib/foo/bar.jar will not
match.

The internal compiler requires tools.jar from the JDK installation, so a JDK
must be used (not a JRE). Sometimes the internal compiler causes errors,
creating exceptions or simply hanging and taking up a thread. The solution is
to change the compiler to use an external compiler.

The javac compiler is included with the JDK. It executes that same as the
internal compiler, however it is executed as an external process and is less
prone to the problems described for the internal compiler. In resin.conf with
the javac configuration option:

<jndi-link>

child of <resin>,<cluster>,<host>,<web-app>

<jndi-link> creates a symbolic link from one jndi name to another, or links to a foreign JNDI context.

Resin's JNDI can link to foreign JNDI contexts. For example, third-party
EJB servers will often expose their EJB beans through a JNDI context.
jndi-link will create the appropriate InitialContextFactory, configure it,
and lookup the foreign JNDI objects.

<jndi-link> Attributes

ATTRIBUTE

DESCRIPTION

DEFAULT

factory

Class name of the JNDI InitialContextFactory. Since Resin 1.2

optional

foreign-name

The target name of the symbolic link, or the sub-context of the foreign JNDI context. Since Resin 1.2

none

init-param

Configuration parameters for the JNDI environment passed to InitialContextFactory. Since Resin 1.2

<mail>

child of <resin>,<cluster>,<host>,<web-app>

<mail> configures a javax.mail.Session object and makes
it available in Resin-IoC/WebBeans. Mail properties can be
configured using the properties attribute. Some of the most common
properties can be configured directly on the <mail> tag.

<reference>

child of <resin>,<cluster>,<host>,<web-app>

<reference> configures a JNDI ObjectFactory. Some legacy
resources are configured using an ObjectFactory syntax. The <reference>
tag provides a compatible way to configure those objects. More modern
resources should use <bean> or <component> for IoC configuration.

JNDI ObjectFactories are used to create objects from JNDI references.
The <reference> tag configures the ObjectFactory and stores it in JNDI.

<resin:otherwise>

<resin:otherwise> is the catch-all configuration for a <resin:choose>
block when none of the <resin:when> items match.

<resin:otherwise> schema

element resin:otherwise {
context-dependent content
}

<resin:if>

resin:if executes part of the configuration file conditionally. resin:if
can be particularly useful in combination with Java command-line properties
like -Dfoo=bar to enable development mode or testing configuration.

<resin:if> Attributes

ATTRIBUTE

DESCRIPTION

DEFAULT

test

the test to perform

required

The resin:if schema is context-dependent. For example, resin:if in
a <web-app> will have web-app content while resin:if in a <host>
will have host content.

<resin:import>

<resin:import> reads configuration from another file or set of
files. For example, the WEB-INF/web.xml and WEB-INF/resin-web.xml files
are implemented as <resin:import> in the app-default.xml.

The target file is validated by the schema of the including context.
So a resin:import in <web-app-default> will have a target with a
top-level of <web-app>, and a resin:import in <cluster> will have
a top-level tag of <cluster>.

The following example shows how Resin implements the WEB-INF/web.xml
and WEB-INF/resin-web.xml files. Both are simply resin:import in a
web-app-default. When Resin configures the web-app, it will process
the web-app-default program, and call resin:import for the web.xml file.

Some applications may want to split their configuration into multiple
files using the fileset. For example, a Resin-IoC
application might want to define beans in WEB-INF/beans/*.xml and give
the web-app flexibility in which bean files to create.

<scheduled-task>

<scheduled-task> schedules a job to be executed at specific times
or after specific delays. The times can be specified by a cron syntax or
by a simple delay parameter. The job can be either a Runnable
bean, a method specified by an EL expression, or a URL.

When specified as an IoC bean, the bean task has full IoC capabilities,
including injection, @TransactionAttribute aspects, interception and
@Observes.

bean-style job configuration

The most common and flexible job configuration uses standard IoC
bean-style configuration. The bean must implement Runnable.
Like the <bean> tag, the class attribute specifies the
Runnable class, and any init section configures
the bean using Resin IoC configuration.

task reference job configuration

The task bean can also be passed to the <scheduled-task> using
a Resin-IoC EL reference. The name of the task bean would be defined
previously, either in a <bean> or <component> or picked up by classpath
scanning. Like the bean-style job configuration, the reference bean must
implement Runnable.

method reference job configuration

<scheduled-task> can execute a method on a defined bean as the
scheduler's task. The method is specified using EL reference syntax.
At each trigger time, <scheduled-task> will invoke the EL method
expression.

In the following example, the task invokes myMethod()
on the myBean singleton every 1 hour.

url job configuration

In a <web-app>, the <scheduled-task> can invoke a servlet URL
at the trigger times. The task uses the servlet RequestDispatcher
and forwards to the specified URL. The URL is relative to the <web-app>
which contains the <scheduled-task.

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.