The example use PHP as the CGI executable, but they can be easily adapted to any CGI script.

Of course Resin includes Quercus, a 100% pure Java PHP interpreter. These examples demonstrate how to execute the native PHP interpreter without the need for Apache.

I also included instruction on setting up WordPress with CGI and FastCGI.

wiki: Resin Application Server: Custom Rewrite Rules

Resin’s URL rewriting is similar to Apache’s mod_rewrite, using regexp matching and the CDI XML syntax for built-in rules like resin:Redirect, resin:MovedPermanently and resin:Dispatch. In addition to the build-in rules, you can create your own custom rules for more sophisticated
URL management. This wiki cookbook gives a quick example of one of those rules.

wiki4: Resin Application Server: Parameterized Web Server Cluster

The cookbook will be interesting if you want to see a relatively-complicated Resin CDI configuration which includes JNDI for the purpose of Spring integration, and also showing how custom facades can be combined with a standard JMS Topic configuration.

wiki4: Resin Messaging: WebSockets with Hessian

Note, that this is a binary websocket protocol, so it would be used with a custom websocket client, not a browser. Since the browsers currently prefer speaking text websockets, the equivalent would be a JSON server.

Wiki: Resin Web Server: URL Rewrite Forbidding non-SSL Requests

The example is pretty simple, since it just needs the as the action rule, and a single predicate, to test the request. Because it’s simple, it’s a good introductory example of Resin’s URL rewriting for people who haven’t looked into it yet.

http://wiki4.caucho.com/Resin_Java_Cache_using_CDI_Inject

See http://wiki4.caucho.com/Hessian_Performance_OutputStream for a short cookbook example.

Command start-all

The command simply starts all Resin servers that bind to machine’s interfaces. Before explaining in detail what this command does I have to delve into explaining new feature of Resin Pro 4.0.24. Starting version 4.0.24 Resin introduces a new configuration tag that allows to configure multiple servers at once. The tag works with resin.properties that allows specifying the list of addresses that the new servers will bind to. Using resin.properties allows to localize the changes to a single short file and makes editing configuration a bit easier compared to XML based files. The new server-multi tag will look as below:

<cluster id="app_tier">

    <!-- define the servers in the cluster -->
    <server-multi id-prefix="app-" address-list="${app_tier}" port="6800"/>

Property app_tier is imported from resin.properties:

app_tier      : 192.168.1.16;192.168.1.17

Command start-all will examine the IPs and if they are assigned to any of the local interfaces will start appropriate server. The server names are assigned dynamically by adding an index to id-prefix of the server-multi tag. The index is derived from position of a particular IP in address-list. Such, for the two IPs defined in the example above app-0 and app-1 will be started.

bin/resin.sh help start-all
starts all servers listening to the machine's IP interfaces
where options include:
   -conf <file>            : select a configuration file
   -data-directory <dir>   : select a resin-data directory
   -join-cluster <cluster> : join a cluster as a dynamic server
   -log-directory <dir>    : select a logging directory
   -resin-home <dir>       : select a resin home directory
   -root-directory <dir>   : select a root directory
   -server <id>            : select a <server> to run
   -watchdog-port <port>   : override the watchdog-port
   -verbose                : print verbose starting information
   -preview                : run as a preview server
   -debug-port <port>      : configure a debug port
   -jmx-port <port>        : configure an unauthenticated jmx port

Once the servers are started you can shut them down with a resin shutdown command (bin/resin.sh shutdown). Don’t forget about status command to check on status of the servers.

Commands enable, disable and disable-soft

When a need arises to take a server out of rotation with the load-balancer or bring the server back into rotation commands disable(-soft) or enable come into play. Resin’s Load-Balancer (configured in resin.xml with web-tier attributes) integrates with the app-tier’s dynamic capabilities. Web-tier and app-tier’s knowing of each other allow for Resin’s Cloud Elasticity (growing or shrinking). Taking a server out is can be done with either disable or disable-soft commands. Disable-soft allows server to finish sessions that it’s serving. Once the disable-soft command is issued web-tier will no longer distribute any new client’s requests to a that server. The commands take the exact same list of arguments at the moment, available with bin/resin.sh help enable|disable|disable-soft

bin/resin.sh help enable
bin/resin.sh help enable
usage: bin/resin.sh [-conf <file>] -server <triad-server> enable -address <address> -port <port> -user <user> \
-password <password> <server>

description:
   enables specified in <server> argument server

options:
   -server <triad-server> : one of the servers in the triad
   -address <address>     : ip or host name of the server
   -port <port>           : server http port
   -user <user>           : user name used for authentication to the server
   -password <password>   : password used for authentication to the server

Command jmx-dump, jmx-list, jmx-set and jmx-call

The set of Jmx commands helps query and execute actions on objects that are published via JMX. The easiest of the set is jmx-dump command. It only accepts the standart arguments and prints all registered MBeans with attributes and values. After executing the command you will see output similar to below:

resin $bin/resin.sh jmx-dump
{"create_time": "Fri Dec 02 10:24:48 PST 2011"
, "jmx": {
"JMImplementation:type=MBeanServerDelegate" : {
  "ImplementationName": "Resin-JMX",
  "ImplementationVendor": "Caucho Technology",
  "ImplementationVersion": "Resin-4.0.s111202",
  "MBeanServerId": "Resin-JMX",
  "SpecificationName": "Java Management Extensions",
  "SpecificationVendor": "Sun Microsystems",
  "SpecificationVersion": "1.4"
},
...

If you’d like to query for a specific MBean or a set of MBeans you might want to use command jmx-list. This command accepts a pattern that queries only the MBeans that match the pattern. On the other hand, jmx-list command with *:* argument can be quite helpful when you don’t really know what you are looking for. Piping the output to grep makes combing through a vast amount of data a breeze. The jmx-list command can also print MBeans attributes and values, and, operatons. e.g.

bin/resin.sh  jmx-list *:*
JMImplementation:type=MBeanServerDelegate
com.sun.management:type=HotSpotDiagnostic
java.lang:type=ClassLoading
java.lang:type=Compilation
java.lang:type=GarbageCollector,name=ConcurrentMarkSweep
java.lang:type=GarbageCollector,name=ParNew
java.lang:type=Memory
java.lang:type=MemoryManager,name=CodeCacheManager
java.lang:type=MemoryPool,name=CMS Old Gen
java.lang:type=MemoryPool,name=CMS Perm Gen
java.lang:type=MemoryPool,name=Code Cache
java.lang:type=MemoryPool,name=Par Eden Space
java.lang:type=MemoryPool,name=Par Survivor Space
java.lang:type=OperatingSystem
java.lang:type=Runtime
java.lang:type=Threading
java.util.logging:type=Logging
resin:type=AccessLog,Host=default
resin:type=BlockManager
resin:type=CacheStore
resin:type=Cluster,name=app_tier
resin:type=Cluster,name=cache_tier
resin:type=Cluster,name=web_tier
resin:type=ClusterServer,name=app-0
resin:type=ClusterServer,name=app-1
resin:type=ClusterServer,name=web-0

Command’s distinct options include the following:

bin/resin.sh help jmx-list
usage: resinctl [--options] jmx-list [<pattern>]

  lists the JMX MBeans in a Resin server (Resin Pro)
 ... [common-remote-command-options]
  --all                  : when <pattern> not specified sets the wildcard pattern (*:*)
  --attributes           : prints MBean's attributes
  --operations           : prints operations
  --platform             : when <pattern> not specified sets the pattern to (java.lang:*)
  --values               : prints attribute values

Command jmx-set allows to change a value of a MBean attribute at run time. So the command options will include pattern, attribute and value. If the pattern matches multiple beans it will not perform updating of an attribute.

bin/resin.sh help jmx-set
usage: resinctl [--options] jmx-set value

  sets a JMX value for a server MBean (Resin Pro)

where options include:
 ... [common-remote-command-options]
  --attribute  : name of the attribute
  --pattern    : pattern to match MBean, adheres to the rules defined for javax.managment.ObjectName e.g. qa:type=Foo

The command will perform necessary conversions converting attribute from String to type of the attribute. Command jmx-call invokes MBean’s operation. Similarly to jmx-set, the command accepts a pattern that must uniquely identify MBean, operation name and a list of values that will be passed to the operation as parameters.

bin/resin.sh help jmx-call
usage: resinctl [--options] jmx-call value...

  calls a JMX operation on a server MBean (Resin Pro)

where options include:
 ... [common-remote-command-options]
  --operation <operation> : operation to invoke
  --pattern <pattern>     : pattern to match MBean

Example of using jmx-call command to obtain a heap-dump

bin/resin.sh jmx-call -pattern com.sun.management:type=HotSpotDiagnostic -operation dumpHeap /tmp/heap.hprof true
method `dumpHeap(java.lang.String, boolean)' called on `com.sun.management:type=HotSpotDiagnostic' returned `null'.

After the method completes you can view the heap dump with jvisualvm

jvisualvm --openfile /tmp/heap.hprof

Command pdf-report

This command can be very instrumental in collecting various information from JVM and Resin into one document. I’ve uploaded a sample file for you to download and examine. The report is truly more then one can cover in one blog post, but here is a short list of info that it provides.

The command writes the pdf report into Resin’s log directory.

bin/resin.sh help pdf-report
usage: resinctl [--options] pdf-report

  creates a PDF report of a Resin server (Resin Pro)

where options include:
  --address <ip>          : IP address or host name of (triad) server
  --conf <file>           : alternate resin.xml file
  --logdir <dir>          : PDF output directory (default to resin log)
  --password <password>   : admin password for authentication
  --path <file>           : path to a PDF-generating .php file
  --period <time>         : specifies look-back period of time (default 7D)
  --port <port>           : IP port of (triad) server
  --profile-sample <time> : specifies profiling sampling frequency (100ms)
  --profile-time <time>   : turns code profiling on for a time before generating report
  --report <value>        : specifies the report-type key (default Snapshot)
  --resin-home <dir>      : alternate resin home
  --server <id>           : id of a server in the config file
  --snapshot              : saves heap-dump, thread-dump, jmx-dump before generating report
  --user <user>           : admin user name for authentication

You can take a look at the report produced with the following command:

bin/resin.sh -server app-0 pdf-report -snapshot -report blog-sample -profile-time 30s -period 30m

You can open the report for viewing by clicking on a link: Resin PDF Report.

Command generate-password

This command allows to quickly generate password for inserting into a resin.properties file or admin-users.xml file.

bin/resin.sh generate-password -user admin -password secret
admin_user : admin
admin_password : {SSHA}EsmhniwTx1zi5oSAn5etMsq7sFROhSmV

Command license-add

This command deploys a license to resin server and restarts the server if -restart option is specified.

bin/resin.sh help license-add
usage: bin/resin.sh [-conf <file>] license-add -license <license file> [-to <filename>] [-overwrite] [-restart]

description:
   copies a license file to the appropriate license directory

options:
    ... [common-remote-command-options]
   -license <license file> : path to license file to add (required)
   -to <filename>          : file name license will be written to (defaults to name of license file)
   -overwrite              : overwrite existing license file if exists
   -restart                : restart Resin after license is added

Command log-level

Command log-level is used to change the logging level at runtime. The logging level can be set to return to previous value automatically, after specified period of time.

bin/resin.sh help log-level
usage: resinctl [--options] log-level loggers...

  sets the java.util.logging level for debugging (Resin Pro)

where options include:
  --active-time <time>   : specifies temporary level active time (default permanent). e.g. 5s
  --address <ip>         : IP address or host name of (triad) server
  --all                  : all logs (rare to use)
  --conf <file>          : alternate resin.xml file
  --config               : configuration debugging logs
  --fine                 : finer debugging logs (admin/user-level)
  --finer                : finer debugging logs (developer-level)
  --finest               : finest debugging log
  --info                 : default logging level
  --off                  : disable logging
  --password <password>  : admin password for authentication
  --port <port>          : IP port of (triad) server
  --resin-home <dir>     : alternate resin home
  --server <id>          : id of a server in the config file
  --severe               : severe, typically fatal warnings
  --user <user>          : admin user name for authentication
  --warning              : non-fatal warnings

e.g.
bin/resin.sh log-level -finer com.caucho.server.session
Logger 'com.caucho.server.session' level is set to 'FINER'

Be cautious setting a log level to finer logging permanently, as it may cause the logs to fill up the disk space very quickly! Especially on servers under load. Set -active-time option to make sure you don’t forget to reset logging level.

Commands user-add, user-list and user-remove

The commands help with Resin administration. The users managed by these commands are Resin administrators. This is not a facility that you can use to add users to your particular application.

bin/resin.sh help user-add
usage: bin/resin.sh [-conf <file>] user-add -user <user> -password <password> -u <new user name> [-p <new user password>]

description:
   adds an administrative user

options:
   -address <address>      : ip or host name of the server
   -port <port>            : server http port
   -user <user>            : specifies name to use for authorising the request.
   -password <password>    : specifies password to use for authorising the request.
   -u <new user name>      : specifies name for a new user.
   -p <new user password>  : specifies password for a new user.

E.g. adding a foo user identified by ’secret’ password

$bin/resin.sh user-add -u foo -p secret
user `foo' added

E.g. listing users

resin-pro-4.0.24 $bin/resin.sh user-list
foo

E.g. removing a user:

resin-pro-4.0.24 $bin/resin.sh user-remove foo
user `foo' deleted
resin-pro-4.0.24 $

Resin 4.0.25 will introduce new commands and we hope that the upcoming release finishes changes to CLI and at that point the CLI can be called ’stable’.

Stay tuned!

This second part of a multi-part article on Resin configuration examines how to employ conditional XML statements and EL functions to simplify Resin configuration. When we’re done, you’ll understand how the same configuration could be shared between deployment environments with entirely different Resin operation by using some following concepts:

• Conditional XML with <resin:if>, <resin:when>, <resin:choose>, <resin:otherwise>
• Null checking with “the Elvis Operator” ?:
• Regular expression matching with =~
• Resource access with mbean() and jndi()

Background

The first part of this series of articles began with background on the standard Resin configuration, the differences between server configuration and application configuration, and the usage of a registry to tie these two together. It then presented the problem of maintaining configuration across deployment environments, and discussed specific functionality Resin provides to alleviate this problem. The remainder of the article went into more detail on how to use file imports and variable substitution in Resin configuration.

In addition to variable substitution and imports, there are a number of other means an admin can employ to design more powerful and simple Resin configuration. Resin supports a variety of classic conditional programming statements such as if-else, when, and not. As introduced in Part 1, the basis of dynamic configuration is Unified Express Language (EL). However Resin goes beyond standard EL by providing a few custom functions and operators specifically designed for usage in Resin configuration. This part of the series will examine Resin configuration conditionals in combination with configuration appropriate EL operators and functions.

<resin:if> Conditional Configuration

<resin:if> executes part of the configuration file conditionally. Along with <resin:choose>, which is discussed next, these elements are the basis for Resin conditional configuration. <resin:if> can be particularly powerful in combination with the special functions we’ll look at below.

Probably the most common example of conditional configuration with <resin:if> is checking for java command-line properties like -Ddev=true, to enable development mode debugging or elevated logging. <resin:if> takes 1 parameter, “test”, an EL expression that must evaluate to a Boolean result of true or false.

<resin:if test="${dev}">
  <logger name="com.foo" level="finer"/>
</resin:if>

This example uses EL variables substitution and system properties to increase the logging level for a specific package. Usage of EL variable substitution was described in details in Part 1 of the article. Also, refer to the Resin documentation on EL Variables and Functions for more information.

You may notice that the configuration files packaged with the Resin distribution use <resin:if> frequently in combination with ${resin.professional} to conditionally execute configuration that requires a license. In general, the skipped configuration can be executed safely in Resin Open-Source but will result in license warnings in the logs.

There is no <resin:else>. For anything more complex that a simple if condition, use the <resin:choose> conditional which is discussed next.

<resin:choose> Conditional Configuration

<resin:choose> executes parts of a configuration file conditionally. In combination with <resin:when> and <resin:otherwise>, it implements a traditional if, else-if, and else structure.

<resin:choose> itself takes no parameters. It only serves as a container for one or more <resin:when> statements. <resin:when> executes a section of configuration when the test condition evaluates to Boolean true. Only the statements following the first condition that is found to be true will be executed. All other <resin:when> blocks will be skipped. If none of the <resin:when> conditions match, the catch-all <resin:otherwise> will be executed if present.

Expanding on the example above, we can change –Ddev=true to –Denv=dev, and then match on the value of env, as show here:

<resin:choose>
  <resin:when test="${env=='dev'}">
    <logger name="com.foo" level="finer"/>
  </resin:when>
  <resin:when test="${env=='qa'}">
    <logger name="com.foo" level="info"/>
  </resin:when>
  <resin:otherwise>
    <logger name="com.foo" level="warning"/>
  </resin:otherwise>
</resin:choose>

<resin:message> Configuration Logging

Working with these more complex conditionals naturally elicits the question of how to test and debug. This is where <resin:message> proves useful. <resin:message> simply logs a message to the Resin log file. The content of the XML element is the logged message, which can include evaluation of EL expressions. This provides the ability to log helpful information describing configuration processing as it is occurring.

Consider the following log level example from above, now with <resin:message> statements inserted that describe how logging is being configured:

<resin:choose>
  <resin:when test="${env=='dev'}">
    <logger name="com.foo" level="finer"/>
    <resin:message>com.foo logging set to finer...</resin:message>
  </resin:when>
  <resin:when test="${env=='qa'}">
    <logger name="com.foo" level="info"/>
    <resin:message> com.foo logging set to info...</resin:message>
  </resin:when>
  <resin:otherwise>
    <logger name="com.foo" level="warning"/>
    <resin:message> com.foo logging set to warning...</resin:message>
  </resin:otherwise>
</resin:choose>

<resin:set> Variable Declaration

<resin:set> adds an EL variable to the EL or JNDI context. We’ll discuss working with JNDI at the end of the article, and focus now only on setting an EL variable. This element is useful anywhere declaring a value for later use is appropriate. Usually this is only necessary in more complex situations where you need to indicate some processing occurred earlier in the configuration.

Continuing with the logging example, here it is modified to take advantage of <resin:set>:

<resin:choose>
  <resin:when test="${env=='dev'}">
    <resin:set var="level" value="finer"/>
  </resin:when>
  <resin:when test="${env=='qa'}">
    <resin:set var="level" value="finer"/>
  </resin:when>
  <resin:otherwise>
    <resin:set var="level" value="finer"/>
  </resin:otherwise>
</resin:choose>

<logger name="com.foo" level="${level}"/>
<resin:message>com.foo logging set to ${level}...</resin:message>

?: Null Checking

Recent versions of Resin include the so-called Elvis Operator (?:) as a convenient means to check for null in EL. This is just a shortcut ternary operator that return an alternative value if the condition is null. Resin includes full support for all the other Unified Expression Language operators as well.

?: is used frequently in the Resin distribution configuration in combination with <resin:properties> to provide a default value in case a property value is not set. It works particularly well for configuration, as illustrated in the following example. Here, we’re starting Resin with the logging level set as system property (-Dfoo_level=info), and defaulting to “finer” level just in case Resin is started without the parameter:

<logger name="com.foo" level="${foo_level?:'finer'}"/>

Notice in the example above, ‘finer’ is enclosed in single quotes. This is necessary for EL to interpret the value as a string literal! Without the single quotes, the token “finer” will be interpreted as an EL variable, consequently assigning a null value for the unassigned variable with no warning!

=~ Regular Expression Matching

=~ is another powerful Resin extension to Unified EL. This operator permits inline regular expression matching. It should be a familiar to any Perl programmer. The following example demonstrates how to log a warning if Resin is being executed from any directory containing the string ‘tmp’.

<resin:if test="${resin.root =~ 'tmp'}">
  <resin:message>
    WARNING: Resin is running from a temp directory: ${resin.root}
  </resin:message>
</resin:if>

Regular expression matching works particularly well with the health checking system, in combination with the mbean function discussed next. Consider the following example, which sends an email upon startup if Java’s bootclasspath does not contain a required jar.

<health:SendMail>
  <to>admin@yourdomain.com</to>
  <health:Not>
    <health:IfExpr
     test="${mbean('java.lang:type=Runtime').BootClassPath =~ 'resource-16.jar'}"/>
  </health:Not>
</health:SendMail>

By convention, the snippet above should be placed in health.xml rather than resin.xml. Much more information on health checking configuration is available in the Resin health checking documentation.

mbean() JMX Access

The mbean() configuration utility function that provides access to any JMX MBean to retrieve attribute values. This can be extremely powerful and convenient, since often information in available in JMX that in not available elsewhere, as part of the system or environment properties.

Consider the following example that sets the thread pool max to a multiple of 2048 based on the number of available processors. An elvis operator is also used in case the MBean attribute is not available:

<server-default>
  ...
  <thread-max>
    ${(mbean('java.lang:type=OperatingSystem').AvailableProcessors ?: 1) * 2048}
  </thread-max>

class_exists() Class Availability Checking

The class_exists function is another handy utility that lets you conditionally execute configuration based on the availability of a Java class. It simply does a “Class.forName” and returns a Boolean result. You can see this used in the Resin distribution file cluster-default.xml, to load jsse-ssl HTTPS support only if JSSE libraries are available:

<resin:if test="${class_exists('sun.security.x509.CertAndKeyGen')}">
  <http address="*" port="443">
    <jsse-ssl self-signed-certificate-name="resin@localhost"/>
  </http>
</resin:if>

In this example, CertAndKeyGen is a class known to exist in the JSSE library, thus if it’s found we can be fairly certain the entire JSSE jar is in the classpath. Another common use-case is loading database resources on a backend server only if the JDBC driver is available. This makes it possible to share configuration between frontend and backend server, simply by not including the database driver library on the front-end server.

<resin:if test="${class_exists('com.mysql.jdbc.Driver')}">
  <resin:message>Configuring MySQL database resources...</resin:message>
  <database jndi-name="jdbc/mysql">
    <driver type="com.mysql.jdbc.Driver">
      <url>jdbc:mysql://user:password@192.168.1.1:3306/dbname</url>
    </driver>
  </database>
</resin:if>

jndi() JNDI Registry Lookup

Any object or value registered in a JNDI context can be accessed using the jndi function. It takes the JNDI name/URL as a parameter. Note, all JNDI access in Resin is assumed to be from the parent context of “java:comp/env/” unless the full URL is specified. So “jdbc/mysql” is simply shorthand for “java:comp/env/jdbc/mysql”.

The value returned by this function is the actual object bound in the registry, so you can even execute functions on it if necessary. Consider the following resin-web.xml example that uses much of what we have already discussed in the article, to conditionally register a servlet filter if the URL of the database is not on the local machine. The object retrieved from JNDI is a database pool registered in the server configuration:

<web-app xmlns="http://caucho.com/ns/resin"
        xmlns:ee="urn:java:ee"
        xmlns:resin="urn:java:com.caucho.resin">

  <resin:if test="${!(jndi('jdbc/mysql').URL =~ '127.0.0.1|localhost')}">
    <filter>
      <filter-name>db_security</filter-name>
      <filter-class>test.MyDbSecurity</filter-class>
    </filter>
    <filter-mapping>
      <filter-name>db_security</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>
  </resin:if>

</web-app>

Note: you may notice in Resin documentation that functions named “jndi_lookup” and “jndi:lookup” are mentioned. These are just aliases for the same function discussed here.

The <resin:set> section earlier in the article mentioned support for JNDI. To supplement the var attribute, <resin:set> also has a “jndi-name” attribute. This provides the convenient ability to bind EL variables in JNDI. The following example demonstrates a slick way to provide the number of CPUs as a JNDI variable:

<resin:set jndi-name="os/cpuCount"
  value="${mbean('java.lang:type=OperatingSystem').AvailableProcessors}"/>

As another example, we could use <resin:set> and jndi() rebind a JNDI resource to a different name:

<resin:set jndi-name="jdbc/mysql" value="${jndi('jdbc/wiki')}"/>

Conclusion

Resin provides conditional XML elements and handy utility functions to allow admins to design simple and powerful configuration. The first part of this series of articles examined how to use EL variable substitution imports. This part expanded on that concept by providing examples on conditional configuration with function. Maintaining configuration across deployment environments can be a cumbersome and error-prone without the proper tools. Hopefully after reading to this point you have a better understanding of the tools Resin provides to simply configuration and make job easier.