JBoss.orgCommunity Documentation

Snowdrop User Guide

by Marius Bogoevici and Aleš Justin
edited by Laura Bailey and Rebecca Newton

Abstract

This book is a guide for using Snowdrop.


This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:

The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.

Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:

The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in JIRA: http://jira.jboss.org/ against the project Snowdrop and component Documentation.

When submitting a bug report, be sure to mention the manual's identifier: Snowdrop 1.2 User Guide.

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

The Snowdrop distribution contains two types of artifacts:

The server-side components may include some of the utility libraries, where they are needed by the deployer or, respectively, subsystem.

Snowdrop provides the following utility libraries:

Snowdrop provides the following pre-packaged deployers and subsystems:

This chapter details how to use each of the components included in Snowdrop.

The snowdrop-vfs.jar library supports resource scanning in the JBoss Virtual File System (VFS). It must be included in Spring-based applications that use classpath and resource scanning.

When the Spring framework performs resource scanning, it assumes that resources are either from a directory or a packaged JAR, and treats any URLs it encounters accordingly.

This assumption is not correct for the JBoss VFS, so Snowdrop provides a different underlying resource resolution mechanism by amending the functionality of the PathMatchingResourcePatternResolver.

This is done by using one of two ApplicationContext implementations provided by snowdrop-vfs.jar:

In many cases, the VFSClassPathXmlApplicationContext is instantiated on its own, using something like:

ApplicationContext context = 
new VFSClassPathXmlApplicationContext("classpath:/context-definition-file.xml");

The XmlWebApplicationContext is not instantiated directly. Instead, it is bootstrapped by either the ContextLoaderListener or the DispatcherServlet. Both classes have configuration options that allow users to replace the default application context type with a custom application context type.

To change the type of application context created by the ContextLoaderListener, add the contextClass parameter as shown in the following example code:

<context-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>classpath*:spring-contexts/*.xml</param-value>
</context-param>
<context-param>
  <param-name>contextClass</param-name>
  <param-value>
    org.jboss.spring.vfs.context.VFSXmlWebApplicationContext
  </param-value>
</context-param>
<listener>
  <listener-class>
    org.springframework.web.context.ContextLoaderListener
  </listener-class>
</listener>

To change the type of application context created by the DispatcherServlet, use the same contextClass parameter on the DispatcherServlet definition as shown:

<servlet>
  <servlet-name>spring-mvc-servlet</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
  <init-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/mvc-config.xml</param-value>
  </init-param>  
  <init-param>
  <param-name>contextClass</param-name>
    <param-value>
      org.jboss.spring.vfs.context.VFSXmlWebApplicationContext
    </param-value>
  </init-param>
</servlet>

Starting with version 1.2, Snowdrop includes a custom Spring namespace for JBoss AS. The goals of this custom namespace is to simplify the development of Spring applications that run on JBoss, by reducing the amount of proprietary code and improving portability.

The amount of proprietary code is reduced because of replacing bean definitions that include references to specific JBoss classes with namespace-based constructs. All the knowledge about the proprietary classes is encapsulated in the namespace handlers.

The applications are more portable because certain proprietary classes may change when upgrading to a different version of the application server. In such cases, the runtime will be detected automatically by Snowdrop which will set up beans using the classes that are appropriate for that specific runtime.

The custom namespace can be set up as follows:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:jboss="http://www.jboss.org/schema/spring"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.jboss.org/schema/snowdrop http://www.jboss.org/schema/snowdrop/snowdrop.xsd">

The Spring deployer allows you to bootstrap a Spring application context, bind it in JNDI, and use it to provide Spring-configured business object instances.

To install the Snowdrop Deployment subsystem, unzip the jboss-spring-subsystem-as7.zip file. Create the subsystem and Spring modules in JBoss AS7 by copying the contents of the module-deployer folder and one of the module-spring-2.5 or spring-3 folders in the $JBOSS_HOME/modules directory of your JBoss Application Server installation.

The above step will create two modules inside JBoss AS7:

If you are using the distribution without dependencies, or you wish to create your own version of the Spring module, then create a $JBOSS_HOME/modules/org/springframework/spring/main directory and copy one of the two module.xml files (from either the module-spring-2.5 or the module-spring-3 directory of the distribution and copy one of the following sets of files from the corresponding Spring distribution (either Spring 2.5.6.SEC03 or Spring 3.0.6.RELEASE).

For Spring 2.5:

For Spring 3:

The final step in the installation is to change $JBOSS_HOME/standalone/configuration/standalone.xml by including <extension module="org.jboss.snowdrop"/> inside the <extensions> element, as well as including <subsystem xmlns="urn:jboss:domain:snowdrop:1.0"/> inside the <profile> element.

Revision History
Revision 0.1-0Tue May 18 2010Laura Bailey
Converted book to Publican format.