Intersult: Intersult Live

Intersult Live is a very simple product for live mapping of workspace file into deployment. All is managed by slim live.xml configurations. Using maven build process, just copy the examples into your resource path without any changes.

Background#

When developing web projects, the flow of creation is interrupted by redployments. Especially in projects with dependencies, using maven or other build processes. Changing some XHTML or Java-Code causes build, build of dependencies, redeploy and loss of server state.

Solution#

Intersult Live connects resource and class loading to arbitrary paths. Each resource loading location, packed as JAR, WAR, EAR or unpacked can be mapped directly to a workspace location. Intersult Live is a very generic solution of resource loading redirect, thus it supports a large variety of application servers. It has been testet with Tomcat, JBoss and Glassfish without any problems.

State of Development#

The project is very new. Currently the following features are supported:

reloading of resources like .XHTML or .properties files
redirection of JAR-Entries to individual files in workspace
redirection of JNDI-locations and other URLs

Intersult Live works together with Dynamic Code Evolution:

Add/remove methods
Change method signature
Add/remove superclass and interfaces

Note: If you have problems using the Dynamic Code Evolution patch with Eclipse or other applications, you should use a copy of your VM eg. C:\Java\jdk1.6.0_23 -> C:\Java\jdk1.6.0_23dce.

Usage#

Download current version of http://intersult.com/public/maven/com/intersult/live/1.0-SNAPSHOT/live-1.0-SNAPSHOT.jar from Intersult repository.
Place on some path on you local file system, prefered having no spaces inside
Add -noverify -javaagent:<path>\live-1.0-SNAPSHOT.jar to your JVM-Options, where <path> is local path to live-1.0-SNAPSHOT.jar
Restart your application server and watch for ##### Starting Intersult Live ##### on the output or logfile
Place a live.xml in your WARs, EARs and JARs
Start your application server and live deployment will work

Example run Java-Class using Intersult Live:

java -noverify -javaagent:live.jar -cp test.jar com.intersult.Test

Example in Pure Java#

<?xml version="1.0" encoding="UTF-8"?>
<live xmlns="http://intersult.com/live/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://intersult.com/live/1.0 http://intersult.com/public/maven/com/intersult/live/1.0-SNAPSHOT/live.xsd">
    <mapping source="C\:\Java\workspace-helios\com.intersult\public\jsf-desktop\target/classes" target="/"/>
</live>

The live.xml has to be located in the root directory of the resulting JAR file. It is independent using \ or / as path separators, paths are normalized.

In most cases you want to exclude mapping of files in /META-INF, because this would break the system JAR loader:

<?xml version="1.0" encoding="UTF-8"?>
<live xmlns="http://intersult.com/live/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://intersult.com/live/1.0 http://intersult.com/public/maven/com/intersult/live/1.0-SNAPSHOT/live.xsd">
    <mapping source="C:/<your-path>/classes" target="/">
	<exclude path="/META-INF*"/>
    </mapping>
</live>

In most cases there is only some static compiler stuff.

Examples with Maven 2/3#

If you use maven 2/3 for the build process, it is very nice to generate source path into the live.xml. To advice maven to replace variables, just put the live.xml in you projects /src/main/resources source folder. To activate resource filtering, place the following configuration into your pom.xml:

<project>
        ...
	<build>
		<resources>
			<resource>
				<directory>src/main/resources</directory>
				<filtering>true</filtering>
			</resource>
		</resources>
	</build>
	...
	<repositories>
		<repository>
			<id>intersult-repo</id>
			<name>Intersult Repository</name>
			<url>http://intersult.com/public/maven</url>
		</repository>
	</repositories>
	...
</project>

After this step you are able to use ${...}-Expressions in live.xml files: Simply JAR:

<?xml version="1.0" encoding="UTF-8"?>
<live xmlns="http://intersult.com/live/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://intersult.com/live/1.0 http://intersult.com/public/maven/com/intersult/live/1.0-SNAPSHOT/live.xsd">
	<mapping source="${project.build.directory}/classes" target="/"/>
</live>

JAR with resources:

<?xml version="1.0" encoding="UTF-8"?>
<live xmlns="http://intersult.com/live/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://intersult.com/live/1.0 http://intersult.com/public/maven/com/intersult/live/1.0-SNAPSHOT/live.xsd">
	<mapping source="${project.build.directory}/classes" target="/">
		<exclude path="/META-INF*"/>
	</mapping>
</live>

WAR on Tomcat or JBoss:

<?xml version="1.0" encoding="UTF-8"?>
<live xmlns="http://intersult.com/live/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://intersult.com/live/1.0 http://intersult.com/public/maven/com/intersult/live/1.0-SNAPSHOT/live.xsd">
	<mapping source="${project.build.directory}/classes" target="/WEB-INF/classes"/>
	<mapping source="${basedir}/src/main/webapp" target="/" loader="jndi:/localhost/${project.name}">
		<exclude path="/META-INF*"/>
	</mapping>
</live>

WAR on Glassfish (only difference is JNDI-location):

<?xml version="1.0" encoding="UTF-8"?>
<live xmlns="http://intersult.com/live/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://intersult.com/live/1.0 http://intersult.com/public/maven/com/intersult/live/1.0-SNAPSHOT/live.xsd">
	<mapping source="${project.build.directory}/classes" target="/WEB-INF/classes"/>
	<mapping source="${basedir}/src/main/webapp" target="/" loader="jndi:/server/${project.name}">
		<exclude path="/META-INF*"/>
	</mapping>
</live>

Working with Development Environments#

If you continue using Eclipse server plugin, you should mind to disable resource publishing. Disabling this feature will prevent Eclipse to restart the application server.

XML Schema#

The live.xml definitions above references the live.xsd schema from intersult.com repository. Manually you can access the XML Schema Definition (XSD) at live.xsd

How it works#

The key to live mapping is the live.xml defintion files. These files contains a few specifications, how Intersult Live will map workspace files to the deployment. The XML-File contains the following elements:

live: Every live.xml contains a <live> element as root definition
mapping: Each deployment-to-workspace-mapping is described by a <mapping> element
- source: The source attribute describes an absolute path in the system which is mapped into the deployment
- target: The target attribute describes a relative path to map the source into a deployment WAR, EAR or JAR
- loader: An optional attribute to specify a loader URL prefix. If no loader is specified, the URL prefix found while class loading is used. Usually, this is a file or JAR URL.
include/exclude: These elements are nested in <mapping> elements to specify inclusion or exclusion of files. Wildcards like ? and * can be used.