resin 4.0 documentation

Overview

Resin is a high-performance, scalable Java/PHP application server. We release two versions of Resin: an open source version under the GPL, and a professional version with enhanced performance, clustering, and reliability features.

Quick Start

You can start using Resin by simply expanding the archive, and starting Resin with a Java command line.

Installation

Resin Web Server

Apache

IIS

Plugin Dispatch

Linux Boot

Command-Line

While most configuration options have been made available in resin.xml, this section describes some common command-line options.

Configuration

Resin is a powerful, customizable application server. This section discusses how to configure Resin.

<cluster> - clustering, caching, load-balancing, and distributed sessions

<database> - connection pool and database driver configuration

<host> - virtual hosts

Ports - HTTP, SSL, addresses and ports

<resin> - top-level configuration container

Resource tags - database, classloader, jms, bean, and IoC

Rewrite - URL rewriting, dispatching, and load-balancing

<server> - threading, keepalive, timeout, and jvm arguments

session - servlet sessions

variables - configuration variables

<web-app> - servlet and filter configuration

Index - alphabetical list of tags

Relax Schema

Environment

Resin J2EE

Resin web.xml

resin.conf

J2EE Common

J2EE web.xml

Guide: Admin

Overview and introduction to Resin from an administration perspective.

Admin

The /resin-admin web-app provides an administration overview of a Resin server. Resin-Pro users can obtain information across the entire cluster, profile a running Resin instance, and obtain thread dumps and heap dumps.

All Resin users should familiarize themselves with the thread dump, profile, and heap capabilities.

Amber

Amber is Resin's implementation of the JPA 1.0 persistence specification, focusing on simplicity and quality.

BAM

BAM (Brokered Agent Messaging) is a simplified messaging API designed around federated, addressable services, model-based messages, and supports both message and rpc-style communication. As an abstraction of the Jabber protocol, it supports instant messaging, queued (SEDA) services, publish/subscribe, interactive games, and event notification applications. BAM supports multiple protocols including local messaging, Hessian protocol and XMPP (Jabber).

Caching

Server caching can speed dynamic pages to near-static speeds. When pages created by database queries only change every 15 minutes, e.g. CNN or Wikipedia or Slashdot, Resin can cache the results and serve them like static pages. Because Resin's caching only depends on HTTP headers, it will work for any JSPs, servlet or PHP page.response.

Resin's caching operates like a proxy cache, looking at HTTP headers to compare hash codes or digests or simply caching for a static amount of time. Since the proxy cache follows the HTTP standards, applications like Mediawiki will automatically see dramatic performance improvement with no extra work. You can even cache REST-style GET requests.

Because the cache supports advanced headers like "Vary", it can cache different versions of the page depending on the browser's capabilities. Gzip-enabled browsers will get the cached compressed page while more primitive browsers will see the plan page. With "Vary: Cookie", you can return a cached page for anonymous users, and still return a custom page for logged-in users.

Clustering

As traffic increases beyond a single server, Resin's clustering lets you add new machines to handle the load and simultaneously improves uptime and reliability by failing over requests from a downed or maintenance server to a backup transparently.

Database

Resin provides a robust and tested connection pool that is used to obtain connections to databases.

Deployment

Resin provides a wide variety of custom packaging and deployment options.

EJB 3.0

Resin's EJB support is integrated with Resin IoC. This integration means plain Java beans can use EJB annotations and interception, EJBs can use Resin IoC annotations, and both kinds of beans can be configured directly from the resin-web.xml or discovered by classpath scanning.

Embedding

Resin's embedding API lets developers embed Resin as the web interface for an existing application, simplifies unit testing, and improves IDE integration capabilities. The ResinEmbed JavaDoc gives more details.

Filters

Hessian

Hessian and Burlap are compact binary and XML protocols for applications needing performance without protocol complexity. Hessian is a small binary protocol. Burlap is a matching XML protocol. Providing a web service is as simple as creating a servlet. Using a service is as simple as a JDK Proxy interface.

Hessian

Hessian 1.0 spec

Hessian 2.0 draft spec

Java Binding

Burlap

IoC

Resin is designed around the Java Dependency Injection specification (JSR-299), an inversion-of-control framework used for all configuration and resources including servlets, EJBs, messaging, remoting, and databases. Applications can take advantage of Java Injection using standard annotations and interfaces.

Since Resin-IoC is used for servlets, WebBeans and EJBs, any application bean can use EJB annotations like @TransactionAttribute or WebBeans @InterceptionTypes or event @Observes capabilities, in addition to the dependency injection and IoC configuration.

The dependency injection framework is type-safe, meaning the registry is organized around Java types, not a flat namespace, which gives more power and flexibility for component assembly. Since injection is annotation-based, most components can avoid XML configuration, while XML is still available for components.

JSF

As of Resin version 3.1.6 Resin supports JSF 1.2. JSF specification defines a base set components for capturing user input and displaying output. Resin implements the spec from the ground up to take advantage of Resin's unique, high performance features. The two most notable features that make Resin's JSF fast are use of serialization mechanism implemented in Hessian protocol for JSF state handling and a fast-jsf mode of JSP generation.

Along with the features orientated at performance advantage Resin's JSF offers integration with Web Beans (JSR 299). If you are using JSF's managed bean facility you can go straight to minimizing the amount of XML configuration by using Web Beans defined ways instead (will be shown below).

JSP

JSP creates output (such as HTML) from template text and scripting actions. Template text is returned verbatim to the requesting client, and actions are used to fill in dynamic values and do things conditionallly.

Introduction

Compilation

EL

JSTL

Directives

Variables

Actions

Applications

Schema for JSP-2.0 .tld files

Velocity syntax

JSP Templates

Logging

Resin can perform access logging, specify where JDK logging interface messages go, and redirect the stderr and stdout for your applications.

Messaging

Configuration for Resin's JMS provider implementation. The JDBC Queues and Topics provide a persistent messaging store. The Memory Queues and Topics provide a low-overhead memory-based store.

Performance

Benchmarks

JVM Tuning

Performance FAQ

Performance Scrapbook

Tuning

Quercus/PHP

Quercus is Caucho Technology's fast, open-source, 100% Java implementation of the PHP language. Performance is 4x mod_php and is comparable with PHP accelerator performance. Quercus uses Resin-IoC/WebBeans to integrate with Resin services.

Security - Quercus gains security advantages from the JVM platform

Module Status

Remoting

Resin's remoting lets applications write services as plain Java objects and export them with a choice of protocols, including Hessian, Burlap, CXF (SOAP), XFire. Because Resin activates the service as an IoC singleton, the service can use any of Resin's IoC capabilities, including dependency injection, AOP interception, EJB transactions, and event handling.

For applications which need to use a custom protocol, making a new driver for a protocol is also straightforward.

Scheduled Tasks

Resin's <resin:ScheduledTask> capability lets you schedule events using a flexible cron-style trigger. The task can be any Runnable bean, a method specified by EL, or a URL.

Security

Resin's <resin:ScheduledTask> capability lets you schedule events using a flexible cron-style trigger. The task can be any Runnable bean, a method specified by EL, or a URL.

Server Push

Resin's server-push (Comet) servlet API enables streaming communication such as reverse AJAX dynamic updates for browser/JavaScript applications. The API encapsulates of the threading and communications issues between the request threads and the rest of the application.

Servlets

Servlets are Java classes which service HTTP requests. The only requirement for writing a servlet is that it implements the javax.servlet.Servlet interface.

Servlets are loaded from the classpath like all Java classes. Normally, users put servlets in WEB-INF/classes so Resin will automatically reload them when they change.

JSP pages are implemented as Servlets, and tend to be more efficient for pages with lots of text.

Third-party

Resin's support for third-party libraries and packages is primarily documented at http://wiki.caucho.com. This section includes links to the most popular packages.

Troubleshooting

A list of symptoms and their possible resolution.

Virtual Hosting

A Resin server can serve many virtual hosts, each with its own servlets and documents. The configuration is flexible, allowing dynamic host deployment in a hosts directory or using explicit <host> tags for additional control and security, and compatibility with existing Apache sites, enabling easy upgrades and evaluation for PHP servers to Quercus.

Watchdog

For reliability and security, Resin servers are started and monitored by a separate Resin watchdog process. The watchdog continually checks the health of the Resin server and restarts the Resin instance if is becomes unresponsive.

In most cases, the watchdog reads the resin.xml and configures itself automatically, so no extra configuration is required. Certain specialized configurations like ISPs can configure the watchdog to isolate JVMs for protection and security.

WebApp

A web application is a self-contained subtree of the web site. It uses Servlets, Filters, JSP, and the functionality provided by Resin and any other java code to provide a response to a client that makes an HTTP request.

XML and XSLT

Introduction

JAXP

XML Path Language (XPath)

XSLT Filter

XSLT

XPath Functions