Revision as of 16:58, 7 January 2010

Migrating to Resin from WebLogic

Configuration architecture

Resin offers many advanced features and exceptional performance in a lightweight container. Users migrating from WebLogic to Resin will initially find the workflow associated with development and administration differs greatly between the two products. However Resin users tend to find configuration and development to be very natural and efficient, especially compared with other application servers.

Managing configuration

Single Server configuration

Resin's configuration is based on straightforward, compact, and uncluttered XML files. The contents of these XML files represents the operational configuration of Resin. If these configuration files are changed, Resin can detect the change and restart either a web application, a virtual host, or the entire server so that the internal configuration matches that of the file. WebLogic, on the other hand, maintains its configuration via a web-based administration console or command line tool. In fact, WebLogic's configuration tools actually write a file called "config.xml" which serves a similar purpose as Resin's XML file. The advantage of using Resin's approach to configuration is that you have direct control over server operation without relying on tools which may obscure or confuse the underlying configuration file.

Multiple Server configuration and organization

Resin's configuration across multiple servers is also handled differently than WebLogic. In Resin, each server uses the XML configuration from the file system. In contrast, WebLogic specifies an administration server that manages configuration for all of the servers in a WebLogic "Domain". In this aspect, Resin has reduced architectural overhead, but may require external management techniques for distributing configuration to all servers in a deployment such as file system synchronization or a networked file system.

WebLogic Configuration	Resin Configuration

Comparative Directory Layout

In addition to XML configuration, Resin also uses directory layout and the state maintained on the file system to configure application-related aspects of the server, such as application deployment, virtual hosts, and library management. This approach allows developers and administrators to see the state of a Resin applications simply by looking at the XML configuration and the file system. Conversely, to update Resin's applications or virtual hosts, users may simply create directories and copy files. Resin is able to use common directory structures (such as that of Apache HTTPd and Apache Tomcat) to migrate legacy applications.

WebLogic's directory structure [1] is more centralized than Resin's and is more closely managed by the application server. In contrast to Resin's application-oriented directory structure, WebLogic's directories reflect the state of the WebLogic Domains and servers. Application management is handled via a web console or command line tool; direct file system manipulation of applications is not recommended (except in the case of the "autodeploy" mechanism for non-production servers). WebLogic also uses a "Server Root" directory to store runtime data associated with each server. Depending on the server type, this directory is located in different places and has a different structure. Resin stores runtime data as well, but the directory structure used for this purpose is identical on all servers.

Starting and Stopping Resin compared to WebLogic

Resin (beginning with version 3.1) uses a manager, called the Resin Watchdog, to start, stop, and monitor the actual JVM process for Resin. The Watchdog itself is another Java program, so each server running Resin uses two processes for improved reliability. This architecture affects how Resin is started and stopped, especially compared to WebLogic. WebLogic users typically create startup scripts for their server to manage aspects of startup such as the classpath, JVM arguments, and override configuration. Resin's Watchdog uses the same configuration files as the actual Resin server and it is in charge of launching the JVM for Resin, so instead of creating scripts, Resin users simply have all of their startup configuration located in a single file. Overriding values in the Resin configuration is typically not necessary because the files are readily editable, but facilities such as using expression language for system properties allows the user to set options on the command line for this purpose. Because Resin does not have different types of servers (e.g. administration versus managed), the analogous infrastructure of WebLogic (e.g. node managers, etc.) [2] [3] does not apply.

Application Deployment

Automatic (file system-based deployment)

Resin uses a file system-based approach to deployment, meaning that .war files or exploded applications can be copied directly to a live, automatic deployment directory for production. This approach is similar, though not identical to the "autodeploy" directory concept in WebLogic. In Resin, .war and .ear files are exploded into full directories when detected by the application server. Thus every application has an associated directory that is accessible by the user. This directory represents the live state of an application, so modifications to files are immediately visible both in development and production. If the application's deployment descriptor (e.g. web.xml or resin-web.xml) are changed, Resin detects the change and restarts the application automatically.

WebLogic by comparison does not explode .war and .ear files into a live, user-accessible directory and care must be taken not to delete the .war or .ear files while the server is not running. To make changes to an application in an exploded directory, WebLogic users must create a file called REDEPLOY within the application to alert the application server to restart the application. This step is not necessary in Resin.

Comparative File System Paths in Resin versus WebLogic

Both Resin and WebLogic have "root directories", but they refer to different concepts and file system layouts. Resin's root directory is the content root in which all application files are stored. Typically on Unix or Linux systems, this directory is /var/www and on Windows it is C:\www. To deploy an application to Resin, the live deployment directory is $RESIN_ROOT/webapps. Simply copy a .war file or exploded application directory to this directory and the application will be deployed.

Distributed Deployment

Starting in version 4.0, Resin features a distributed application deployment mechanism that enables users to

• Distribute applications across all Resin servers with a single step
• Migrate applications to new servers automatically on startup
• Manage application versions without interrupting the user experience
• Verify applications in the same environment as live applications before going live

This feature of Resin 4.0 is based on Git technology which provides high performance and easy-of-use for new users and transparency and low-level access for more advanced users.

Converting weblogic.Deployer commands to task-based commands using Maven

WebLogic has many analogous features to Resin 4.0's distributed deploy mechanism and many of the commands used in WebLogic can be converted to use Resin-based tools with similar semantics. Resin provides plugins for both Ant and Maven2 which allow integration directly with two of the most popular Java build environments. The Maven2 plugin is most directly analogous to the weblogic.Deployer command, so we will limit our discussion to that tool in this document.

The first step is to add the Caucho Resin plugin to your Maven2 pom.xml file for your project. This example shows a simple pom.xml file:

 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.test</groupId>
   <artifactId>test</artifactId>
   <packaging>war</packaging>
   <version>1.0-SNAPSHOT</version>
   <name>test Maven Webapp</name>
   <url>http://maven.apache.org</url>
   <dependencies>
   </dependencies>
   <pluginRepositories>
     <pluginRepository>
       <snapshots>
         <enabled>true</enabled>
         <updatePolicy>always</updatePolicy>
         <checksumPolicy>ignore</checksumPolicy>
       </snapshots>
         <id>caucho</id>
         <name>Caucho</name>
         <url>http://caucho.com/m2-snapshot</url>
     </pluginRepository>
   </pluginRepositories>
       
   <build>
     <finalName>foo</finalName>
 
     <plugins>
       <plugin>
         <groupId>com.caucho</groupId>
         <artifactId>resin-maven-plugin</artifactId>
         <version>4.0.2</version>
         <configuration>
           <server>127.0.0.1</server>
           <port>80</port>
           <user>foo</user>
           <password>test</password>
         </configuration>
       </plugin>
     </plugins>
   </build>
 </project>

Notice the highlighted section of the plugin configuration. This section specifies one of the three core members of a Resin 4.0 cluster called a triad. For now, just think of this as the first configured server in the cluster. (More information on clustering is available below.) The address and HTTP port of the server are specified, as well as a user name and password. (Security related information will also be discussed in another section below.) This configuration is used for all the deployment related commands below.

This goal builds the war and uploads it to Resin, using the finalName ("foo" in this case) as the context root:

 mvn resin:upload-war

This is roughly analogous to the following weblogic.Deployer command:

java weblogic.Deployer -adminurl http://localhost:8080 -user foo
  -password test -deploy -targets server1,server2 myApp.war

Note that there is no equivalent of the WebLogic "targets" argument in Resin. This is because Resin automatically deploys applications throughout the cluster. In other words, Resin's view of clusters is that all servers within each cluster have the same applications. To partition applications among servers, you can set up multiple clusters.

WebLogic Side-By-Side versions and Resin application versioning

Both Resin and WebLogic have similar application versioning capabilities. When upgrading an application on a live site, users using the previous version of the application will continue to use that version so long as their sessions remain valid. New users will be directed to the newest version of the application. This feature allows a seamless transition on application version upgrades without affecting users. This is referred to as Side-By-Side Deployment for WebLogic and application versioning for Resin.

At the time of writing, no documentation to use WebLogic Side-by-Side versioning with the weblogic.Deployer command was found; the WebLogic administration console appears to be the main interface used to set versioning attributes. Thus the examples below simply show some basic interactions with Resin's Maven plugin to using versioning with an application:

To upload a version 1.0 of our "foo" application:

 mvn resin:upload-war -Dresin.version="1.0"

Upload version 2.0 of our "foo" application:

 mvn resin:upload-war -Dresin.version="2.0"

To query all versions of the webapp in the repository:

 mvn resin:query-tags -Dresin.version='.*

Application "staging"

Resin and WebLogic both use the term "staging" in application deployment, but the term refers to different concepts for each application server. For Resin, "staging" refers to a feature that allows users to test applications in a test bed environment identical to the production environment without going "live." Both applications and servers have a "stage," such as "default" or "preview." A server only serves applications with a stage matching its own. When deploying an application, the user can specify that an application is in the "default" stage, in which case the application is deployed on servers in the "default" stage. This stage is typically used for live, production deployments. Alternately the user can specify another stage such as "preview". There may be only one server in the cluster running in the "preview" stage behind a firewall, used to allow developers the chance to test the application in the same environment as the production servers. Once the developer is satisfied that this application is ready for production, its stage may be switched to "default" and deployed on the live servers.

WebLogic has a very different notion of "staging" in which applications are copied to servers first, then deployed only after all the application files have arrived at all servers. Resin's deployment mechanism always does this; applications are only started once they have been uploaded fully and are "tagged" in the Git repository.

Database connectivity

Resin provides JDBC connectivity to applications via pools, which are accessed either via JNDI reference or CanDI (JSR-299). Resin database pools can be configured on an application level using the resin-web.xml descriptor file. Configuring database pools in Resin is roughly analogous to JDBC Data Source Modules in WebLogic [4].

<jdbc-data-source xmlns="http://www.bea.com/ns/weblogic/91">
  <name>demo-database</name>

  <jdbc-driver-params>
    <url>jdbc:mysql:server://localhost:3306/demo</url>
    <driver-name>com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</driver-name>
    <properties>
      <property>
        <name>user</name>
        <value>demo</value>
      </property>
      <property>
        <name>databaseName</name>
        <value>jdbc:mysql:server://localhost:3306/demo</value>
      </property>
    </properties>
    <password-encrypted>ABCDEFGxyz</password-encrypted>
  </jdbc-driver-params>

  <jdbc-connection-pool-params>
    <max-capacity>50</max-capacity>
    <test-connections-on-reserve>true</test-connections-on-reserve>
  </jdbc-connection-pool-params>
 
  <jdbc-data-source-params>
    <jndi-name>jdbc/demo</jndi-name> 
  </jdbc-data-source-params>
 
</jdbc-data-source>

<web-app xmlns="http://caucho.com/ns/resin">
 
  <database jndi-name='jdbc/demo'>
    <driver>
      <type>com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</type>
      <url>jdbc:mysql://localhost:3306/demo</url>
      <user>demo</user>
      <password>demo</password>
    </driver>
    <ping>true</ping>
    <max-connections>50</max-connections>
  </database>

</web-app>

Given this example, below is a table of some of the most popular JDBC configuration options and their equivalents in Resin and WebLogic

Logging

Both Resin and WebLogic (since version 8.1 [5]) use java.util.logging facilities to handle logging. Resin uses java.util.logging for server-level messages and applications that use these facilities should be very portable across both application servers.

Log Levels

WebLogic's administration console and weblogic.Admin do not provide a way to set Logger levels; WebLogic users set levels via the Java API. These APIs are compatible with Resin, so existing code to perform this function will continue to work on Resin.

In addition to the Java API, Resin also features a way to set Logger levels through XML configuration. The following can be set in the top-level resin.xml file or in application-specific resin-web.xml files:

<logger name="com.example.myapp" level="fine"/>

Server-level logging is also set using this configuration on the "com.caucho" tree of Loggers.

Log files and rotation

Resin can have any number of log files, all with their own individual rotation schedules and parameters. Resin configures log files in resin.xml or even in individual resin-web.xml files. WebLogic's log configuration is handled in its administration console [6].

To configure a basic log file in Resin for all logs, you might use the following:

 <log-handler name="" level="all" path="stdout:"
              timestamp="[%y-%m-%d %H:%M:%S.%s] {%{thread}} "/>

In this special example, the path ("stdout:") is redirected to a file in the log directory specified on the command line when starting Resin. The name of the file incorporates the server name (e.g. /var/www/log/jvm-servername.log). All levels of log messages are written to the file from all sources.

To create a more selective log file that only logs fine-level (and higher) server messages and rotates when the log grows larger than 1MB, you might use the following:

 <log-handler name="com.caucho" level="fine" path="server.log"
              timestamp="[%y-%m-%d %H:%M:%S.%s] {%{thread}} " 
              rollover-size="1MB" />

Similarly rollovers based on a time period, the maximum number of rolled-over logs to keep, and log compression can be enabled using Resin's XML configuration.[7]

HTTP Configuration

Resin and WebLogic use similar concepts in configuring HTTP, though Resin uses its XML configuration whereas WebLogic uses its web console.

Resin's HTTP configuration is specified for each server, thus in the XML configuration, each <server> tag may have one or more <http> child tags. For example:

<server id="" address="127.0.0.1" port="6800">
  <http address="*" port="80"/>
 
  <user-name>www-data</user-name>
  <group-name>www-data</group-name>
</server>

The <http> tag can attach to specific IP addresses as well, so different ports may be used in case several interfaces are available on the server.

On Unix and Linux, binding to ports below 1024 requires a privileged user, but many administrators prefer running the server as a non-privileged user for security purposes. Both Resin and WebLogic are able to bind to privileged ports, then change to a non-privileged user before serving content. In the sample above, the existence of the <user-name> or <group-name> tags corresponds to the "weblogic.system.enableSetUID" and "weblogic.system.enableSetGID" WebLogic variables, respectively. The text of these tags corresponds to the "weblogic.system.nonPrivUser" and "weblogic.system.nonPrivGroup" variables, respectively.

Keepalive and other socket parameters

Both Resin and WebLogic are capable of supporting HTTP keep-alive. WebLogic configuration allows enabling keep-alives and setting the maximum idle duration of a connection. Resin allows setting these values as well as the maximum number of simultaneous connections and whether to use thread-based or select-based connection management. Thread-based connection management uses a thread for each keep-alive connection, even if the connection is not active. Select-based connection management allows the server to use fewer threads by only using them with active connections. This is a unique and powerful feature of Resin that enables advanced features such as WebSockets and other event-based web techniques. The following example shows how these options are configured in Resin:

<server id="" address="127.0.0.1" port="6800">
  <http address="*" port="80"/>
 
  <keepalive-max>256<keepalive-max>
  <keepalive-timeout>10s<keepalive-timeout>
  <keepalive-select-enable>true<keepalive-select-enable>
</server>

SSL

Both Resin and WebLogic are capable of supporting SSL HTTP connections. In addition to Java-based (JSSE) SSL, Resin Professional also allows using OpenSSL for vastly improved performance through a JNI bridge. The following is an example of Resin's OpenSSL configuration:

<server id="" address="127.0.0.1" port="6800">
  <http address="*" port="80"/>

  <http address="*" port="443">
    <openssl>
      <certificate-file>keys/mycompany.crt</certificate-file>
      <certificate-key-file>keys/mycompany.key</certificate-key-file>
      <password>test123</password>
    </openssl>
  </http>
</server>

Using OpenSSL, Resin can also cache SSL sessions, using OpenSSL's internal caching features.

Embedding Resin

Automated Testing

Integrating with other development tools

Appendix: Translation glossary