You can deploy several different types of enterprise applications in JBoss AS:

The JBoss Application Server ships with three server configurations. You can choose which configuration to start by passing the -c parameter to the server startup script. For instance, command run.sh -c all would start the server in the all configuration. Each configuration is contained in a directory named JBOSS_HOME/server/[config name]/. You can look into each server configuration's directory to see the default services, applications, and libraries supported in the configuration.

The detailed services and APIs supported in each of those configurations will be discussed throughout this book.

This section introduces the various Microcontainer modules. The figure below gives an overview of the modules.

To configure your microcontainer the you can use the JBOSS_HOME/server/<server_configuration>/conf/bootstrap-beans.xml and JBOSS_HOME/server/<server_configuration>/conf/bootstrap-repo-beans.xml files where <server_configuration> represents the all , default or minimal JBoss AS configurations. The configuration files have comments to guide you on the specific configurations available as illustrated by the example below.

	<deployment xmlns="urn:jboss:bean-deployer:2.0">
		
		<!-- All beans use the bootstrap classloader -->
		<classloader><inject bean="BootstrapClassLoader"/></classloader>
		
		<!-- TODO Should split this file up and use the new classloader -->
		<bean name="BootstrapClassLoader" class="org.jboss.system.NoAnnotationURLClassLoader">
		<classloader><null/></classloader>
			<constructor factoryClass="org.jboss.system.NoAnnotationURLClassLoader" factoryMethod="createClassLoader">
		<parameter>
.....
......
<bean name="ProfileServiceBootstrap" class="org.jboss.system.server.profileservice.ProfileServiceBootstrap">
<property name="kernel"><inject bean="jboss.kernel:service=Kernel"/></property>
</bean>

<!-- The legacy JMX kernel -->
<bean name="JMXKernel" class="org.jboss.system.server.jmx.JMXKernel">
<property name="kernel"><inject bean="jboss.kernel:service=Kernel"/></property>
	<property name="serverImpl"><inject bean="JBossServer"/></property>
	<property name="oldClassLoader">false</property>
</bean>
....(content truncated)
......

	<!-- The ManagedDeploymentCreator implementation -->
	<bean name="ManagedDeploymentCreator" 	class="org.jboss.deployers.plugins.managed.DefaultManagedDeploymentCreator" />
   
	<!-- The holder for deployers that determine structure -->
	<bean name="StructuralDeployers" 		class="org.jboss.deployers.vfs.plugins.structure.VFSStructuralDeployersImpl">
		<property name="structureBuilder">
		<!-- The consolidator of the structure information -->
		<bean name="StructureBuilder" 		class="org.jboss.deployers.vfs.plugins.structure.VFSStructureBuilder"/>
	</property>
	<!-- Accept any implementor of structure deployer -->
	<incallback method="addDeployer"/>
	<uncallback method="removeDeployer"/>
</bean>
...(content truncated)
...

The main beans are:

Enterprise systems communication may benefit from a wise adoption of WS technologies. Exposing well designed contracts allows developers to extract an abstract view of their service capabilities. Considering the standardized way contracts are written, this definitely helps communication with third-party systems and eventually support business-to-business integration. No more agreement required on vendor specific implementation details, home-brew communication protocol or custom per-customer settings. Everything is clear and standardized in the contract the provider and consumer agree on. Of course this also reduces the dependencies between implementations allowing other consumers to easily use the provided service without major changes.

Enterprise system may benefit from web service technologies also for internal heterogenous subsystems communication. As a matter of fact their interoperability boosts service reuse and composition. No more need to rewrite whole functionalities only because they were developed by another enterprise department using another software language.

In case you think you already heard something like this... yes, those in previous paragraph are some of the principles Service Oriented Architecture is based on.

Transforming an enterprise business to Service Oriented Architecture includes obtaining standardized service contract, service reusability, service abstraction, service loose coupling, service composability and so on.

Of course SOA is an architectural model agnostic to technology platforms and every enterprise can pursue the strategic goals associated with service-oriented computing using different technologies. However in the current marketplace, Web Services are probably the technology platform that better suits SOA principles and are most used to get to this architecture.

Needless to say that web services are not the solution for every software system communication.

Nowadays they are meant to be used for loosely-coupled coarse-grained communication, for message (document) exchange. Moreover during the last years a lot of specifications (WS-*) were discussed and finally approved to standardize ws-related advanced aspects including reliable messaging, message-level security, cross-service transactions, etc. Finally web service specifications also include notion of registries to collect service contract references, to easily discover service implementations, etc.

This all means that the web services technology platform suits complex enterprise communication and is not simply the latest way of doing remote procedure calls.

JBoss-WS4EE relied on a deprecated attachments technology called SwA (SOAP with Attachments). SwA required soap/encoding which is disallowed by the WS-I Basic Profile. JBossWS provides support for WS-I AP 1.0, and MTOM instead. There will be no API change for users, however, since this is an updated protocol you will not be able to transfer attachments between older versions of JBoss AS and JBoss AS 4.0.4 or above.

WS-I Attachment Profile 1.0 defines mechanism to reference MIME attachment parts using swaRef. In this mechanism the content of XML element of type wsi:swaRef is sent as MIME attachment and the element inside SOAP Body holds the reference to this attachment in the CID URI scheme as defined by RFC 2111.

JAX-WS endpoints delegate all marshalling/unmarshalling to the JAXB API. The most simple way to enable SwaRef encoding for DataHandler types is to annotate a payload bean with the @XmlAttachmentRef annotation as shown below:

/** 
* Payload bean that will use SwaRef encoding 
*/ 
@XmlRootElement 
public class DocumentPayload 
{ 
private DataHandler data; 
public DocumentPayload() 
{ 
} 
		
public DocumentPayload(DataHandler data) 
{ 
this.data = data; 
} 

@XmlElement 
@XmlAttachmentRef 
public DataHandler getData() 
{ 
return data; 
	} 
	
public void setData(DataHandler data) 
{ 
	this.data = data; 
	} 
} 
	
	With document wrapped endpoints you may even specify the @XmlAttachmentRef annotation on the service endpoint interface: 

@WebService 
public interface DocWrappedEndpoint 
	{ 
	@WebMethod 
	DocumentPayload beanAnnotation(DocumentPayload dhw, String test); 
	
	@WebMethod 
	@XmlAttachmentRef 
	DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test); 
	
	}

The message would then refer to the attachment part by CID:

<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> 
	     <env:Header/> 
	     <env:Body> 
	     <ns2:parameterAnnotation xmlns:ns2='http://swaref.samples.jaxws.ws.test.jboss.org/'> 
	     <arg0>cid:0-1180017772935-32455963@ws.jboss.org</arg0> 
	     <arg1>Wrapped test</arg1> 
	</ns2:parameterAnnotation> 
	</env:Body> 
	</env:Envelope>

This chapter describes Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP), a means of more efficiently serializing XML Infosets that have certain types of content. The related specifications are

The above table shows a list of supported endpoint parameter types. The recommended approach is to use the javax.activation.DataHandler classes to represent binary data as service endpoint parameters.

On the server side MTOM processing is enabled through the @BindingType annotation. JBossWS does handle SOAP1.1 and SOAP1.2. Both come with or without MTOM flavours: MTOM enabled service implementations

package org.jboss.test.ws.jaxws.samples.xop.doclit; 
	
	import javax.ejb.Remote; 
	import javax.jws.WebService; 
	import javax.jws.soap.SOAPBinding; 
	import javax.xml.ws.BindingType; 
	
	@Remote 
	@WebService(targetNamespace = "http://org.jboss.ws/xop/doclit") 
	@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, parameterStyle = SOAPBinding.ParameterStyle.BARE) 
	@BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true")                         (1) 
	public interface MTOMEndpoint { 
	
	[...] 
	} 

With document style web services two business partners agree on the exchange of complex business documents that are well defined in XML schema. For example, one party sends a document describing a purchase order, the other responds (immediately or later) with a document that describes the status of the purchase order. No need to agree on such low level details as operation names and their associated parameters. The payload of the SOAP message is an XML document that can be validated against XML schema. Document is defined by the style attribute on the SOAP binding.

<binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
	<soap:binding style='document' transport='http://schemas.xmlsoap.org/soap/http'/>
<operation name='concat'>
	<soap:operation soapAction=''/>
<input>
	<soap:body use='literal'/>
</input>
	<output>
	<soap:body use='literal'/>
</output>
	</operation>
	</binding>

With document style web services the payload of every message is defined by a complex type in XML schema.

<complexType name='concatType'>
	<sequence>
	<element name='String_1' nillable='true' type='string'/>
	<element name='long_1' type='long'/>
	</sequence>
	</complexType>
	<element name='concat' type='tns:concatType'/>
	Therefore, message parts must refer to an element from the schema. 
	<message name='EndpointInterface_concat'>
	<part name='parameters' element='tns:concat'/>
	</message>
The following message definition is invalid. 
<message name='EndpointInterface_concat'>
	<part name='parameters' type='tns:concatType'/>
</message>

Bare is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a bare endpoint recognizable. A bare endpoint or client uses a Java bean that represents the entire document payload.

@WebService
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
public class DocBareServiceImpl
{
@WebMethod
public SubmitBareResponse submitPO(SubmitBareRequest poRequest)
{
			...
}
}

The trick is that the Java beans representing the payload contain JAXB annotations that define how the payload is represented on the wire.

@XmlAccessorType(XmlAccessType.FIELD)
	@XmlType(name = "SubmitBareRequest", namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", propOrder = { "product" })
	@XmlRootElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/", name = "SubmitPO")
	public class SubmitBareRequest
	{
	@XmlElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/",  required = true)
	private String product;
			
			...
}

Wrapped is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a wrapped endpoint recognizable. A wrapped endpoint or client uses the individual document payload properties. Wrapped is the default and does not have to be declared explicitly.

@WebService
public class DocWrappedServiceImpl
	{
	@WebMethod
	@RequestWrapper (className="org.somepackage.SubmitPO")
	@ResponseWrapper (className="org.somepackage.SubmitPOResponse")
	public String submitPO(String product, int quantity)
	{
	...
	}
	}

Note, that with JBossWS the request/response wrapper annotations are not required, they will be generated on demand using sensible defaults.

With RPC there is a wrapper element that names the endpoint operation. Child elements of the RPC parent are the individual parameters. The SOAP body is constructed based on some simple rules:

RPC is defined by the style attribute on the SOAP binding.

	<binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
	<soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/>
	<operation name='echo'>
		<soap:operation soapAction=''/>
		<input>
			<soap:body namespace='http://org.jboss.ws/samples/jsr181pojo' use='literal'/>
		</input>
		<output>
			<soap:body namespace='http://org.jboss.ws/samples/jsr181pojo' use='literal'/>
		</output>
	</operation>
</binding>

With rpc style web services the portType names the operation (i.e. the java method on the endpoint)

<portType name='EndpointInterface'>
	<operation name='echo' parameterOrder='String_1'>
	<input message='tns:EndpointInterface_echo'/>
<output message='tns:EndpointInterface_echoResponse'/>
	</operation>
  </portType>

Operation parameters are defined by individual message parts.

 <message name='EndpointInterface_echo'>
 <part name='String_1' type='xsd:string'/>
 </message>
 <message name='EndpointInterface_echoResponse'>
 <part name='result' type='xsd:string'/>
 </message>

Note, there is no complex type in XML schema that could validate the entire SOAP message payload.

 @WebService
 @SOAPBinding(style = SOAPBinding.Style.RPC)
 public class JSEBean01
 {
 @WebMethod
 @WebResult(name="result")
 public String echo(@WebParam(name="String_1") String input)
 {
 ...
 }
} 

The element names of RPC parameters/return values may be defined using the JAX-WS Annotations#javax.jws.WebParam and JAX-WS Annotations#javax.jws.WebResult respectively.

JAX-WS simplifies the development model for a web service endpoint a great deal. In short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. The server automatically generates and publishes the abstract contract (i.e. wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to JAXB [2].

Let's take a look at simple POJO endpoint implementation. All endpoint associated metadata is provided via JSR-181 annotations

@WebService
@SOAPBinding(style = SOAPBinding.Style.RPC)
public class JSEBean01
   {
    @WebMethod
    public String echo(String input)
    {
    ...
    }
 } 

A JAX-WS java service endpoint (JSE) is deployed as a web application.

<web-app ...>
	<servlet>
	<servlet-name>TestService</servlet-name>
	<servlet-class>org.jboss.test.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class>
	</servlet>
	<servlet-mapping>
<servlet-name>TestService</servlet-name>
	<url-pattern>/*</url-pattern>
	</servlet-mapping>
</web-app>

A JSR-181 java service endpoint (JSE) is packaged as a web application in a *.war file.

<war warfile="${build.dir}/libs/jbossws-samples-jsr181pojo.war" webxml="${build.resources.dir}/samples/jsr181pojo/WEB-INF/web.xml">
	<classes dir="${build.dir}/classes">
<include name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/>
	</classes>
</war> 

Note that only the endpoint implementation bean and web.xml are required.

A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated wsdl.

http://yourhost:8080/jbossws/services

JAX-WS services typically implement a native Java service endpoint interface (SEI), perhaps mapped from a WSDL port type, either directly or via the use of annotations.

Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages. However, in some cases it is desirable for services to be able to operate at the XML message level. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.

A Provider based service instance’s invoke method is called for each message received for the service.

@WebServiceProvider
@ServiceMode(value = Service.Mode.PAYLOAD)
public class ProviderBeanPayload implements Provider<Source>
{
public Source invoke(Source req)
{
// Access the entire request PAYLOAD and return the response PAYLOAD
 }
} 

Note, Service.Mode.PAYLOAD is the default and does not have to be declared explicitly. You can also use Service.Mode.MESSAGE to access the entire SOAP message (i.e. with MESSAGE the Provider can also see SOAP Headers)

The WebServiceContext is treated as an injectable resource that can be set at the time an endpoint is initialized. The WebServiceContext object will then use thread-local information to return the correct information regardless of how many threads are concurrently being used to serve requests addressed to the same endpoint object.

@WebService
public class EndpointJSE
{
@Resource
WebServiceContext wsCtx;
 
@WebMethod
public String testGetMessageContext()
{
SOAPMessageContext jaxwsContext = (SOAPMessageContext)wsCtx.getMessageContext();
return jaxwsContext != null ? "pass" : "fail";
}
..
@WebMethod
public String testGetUserPrincipal()
{
Principal principal = wsCtx.getUserPrincipal();
return principal.getName();
}
  
@WebMethod
public boolean testIsUserInRole(String role)
{
return wsCtx.isUserInRole(role);
}
}

The JAX-WS tools provided by JBossWS can be used in a variety of ways. First we will look at server-side development strategies, and then proceed to the client. When developing a Web Service Endpoint (the server-side) you have the option of starting from Java (bottom-up development), or from the abstact contract (WSDL) that defines your service (top-down development). If this is a new service (no existing contract), the bottom-up approach is the fastest route; you only need to add a few annotations to your classes to get a service up and running. However, if you are developing a service with an already defined contract, it is far simpler to use the top-down approach, since the provided tool will generate the annotated code for you.

Bottom-up use cases:

Top-down use cases:

The following JAX-WS command line tools are included in JBossWS:

This section describes propriatary JBoss extensions to JAX-WS.

The org.jboss.deployers.plugins.deployment.MainDeployerImpl implementation of the org.jboss.deployers.spi.deployment.MainDeployer interfaces, includes the following standard method details:

In addition, the implementation adds the following methods.

org.jboss.deployers.plugins.structure.vfs.AbstractStructureDeployer

org.jboss.deployers.plugins.deployer.AbstractDeployer - simply stubs out isRelevant to return true and getRelativeOrder to return Integer.MAX_VALUE.

The virtual file system model of the deployment framework provides a consistent api for accessing logical files in logical file systems referenced by a URI/URL.

Joinpoint

A joinpoint is any point in your java program. The call of a method. The execution of a constructor the access of a field. All these are joinpoints. You could also think of a joinpoint as a particular Java event. Where an event is a method call, constructor call, field access etc...

Invocation

An Invocation is a JBoss AOP class that encapsulates what a joinpiont is at runtime. It could contain information like which method is being called, the arguments of the method, etc...

Advice

An advice is a method that is called when a particular joinpoint is executed, i.e., the behavior that is triggered when a method is called. It could also be thought of as the code that does the interception. Another analogy is that an advice is an "event handler".

Pointcut

Pointcuts are AOP's expression language. Just as a regular expression matches strings, a pointcut expression matches a particular joinpoint.

Introductions

An introduction modifies the type and structure of a Java class. It can be used to force an existing class to implement an interface or to add an annotation to anything.

Aspect

An Aspect is a plain Java class that encapsulates any number of advices, pointcut definitions, mixins, or any other JBoss AOP construct.

Interceptor

An interceptor is an Aspect with only one advice named "invoke". It is a specific interface that you can implement if you want your code to be checked by forcing your class to implement an interface. It also will be portable and can be reused in other JBoss environments like EJBs and JMX MBeans.

In AOP, a feature like metrics is called a crosscutting concern , as it's a behavior that "cuts" across multiple points in your object models, yet is distinctly different. As a development methodology, AOP recommends that you abstract and encapsulate crosscutting concerns.

For example, let's say you wanted to add code to an application to measure the amount of time it would take to invoke a particular method. In plain Java, the code would look something like the following.

public class BankAccountDAO
{
 public void withdraw(double amount)
 {
  long startTime = System.currentTimeMillis();
  try
  {
   // Actual method body...
  }
  finally
  {
   long endTime = System.currentTimeMillis() - startTime;
   System.out.println("withdraw took: " + endTime);
  }
 }
}

While this code works, there are a few problems with this approach:

This approach to metrics is very difficult to maintain, expand, and extend, because it's dispersed throughout your entire code base. And this is just a tiny example! In many cases, OOP may not always be the best way to add metrics to a class.

Aspect-oriented programming gives you a way to encapsulate this type of behavior functionality. It allows you to add behavior such as metrics "around" your code. For example, AOP provides you with programmatic control to specify that you want calls to BankAccountDAO to go through a metrics aspect before executing the actual body of that code.

In short, all AOP frameworks define two things: a way to implement crosscutting concerns, and a programmatic construct -- a programming language or a set of tags -- to specify how you want to apply those snippets of code. Let's take a look at how JBoss AOP, its cross-cutting concerns, and how you can implement a metrics aspect in JBoss.

The first step in creating a metrics aspect in JBoss AOP is to encapsulate the metrics feature in its own Java class. Listing Two extracts the try/finally block in Listing One's BankAccountDAO.withdraw() method into Metrics, an implementation of a JBoss AOP Interceptor class.

The following listing demonstrates Implementing metrics in a JBoss AOP Interceptor

01. public class Metrics implements org.jboss.aop.advice.Interceptor
02. {
03.   public Object invoke(Invocation invocation) throws Throwable
04.   {
05.     long startTime = System.currentTimeMillis();
06.     try
07.     {
08.       return invocation.invokeNext();
09.     }
10.     finally
11.     {
12.       long endTime = System.currentTimeMillis() - startTime;
13.       java.lang.reflect.Method m = ((MethodInvocation)invocation).method;
14.       System.out.println("method " + m.toString() + " time: " + endTime + "ms");
15.     }
16.   }
17. }

Under JBoss AOP, the Metrics class wraps withdraw(): when calling code invokes withdraw(), the AOP framework breaks the method call into its parts and encapsulates those parts into an Invocation object. The framework then calls any aspects that sit between the calling code and the actual method body.

When the AOP framework is done dissecting the method call, it calls Metric's invoke method at line 3. Line 8 wraps and delegates to the actual method and uses an enclosing try/finally block to perform the timings. Line 13 obtains contextual information about the method call from the Invocation object, while line 14 displays the method name and the calculated metrics.

Having the metrics code within its own object allows us to easily expand and capture additional measurements later on. Now that metrics are encapsulated into an aspect, let's see how to apply it.

To apply an aspect, you define when to execute the aspect code. Those points in execution are called pointcuts. An analogy to a pointcut is a regular expression. Where a regular expression matches strings, a pointcut expression matches events/points within your application. For example, a valid pointcut definition would be "for all calls to the JDBC method executeQuery(), call the aspect that verifies SQL syntax."

An entry point could be a field access, or a method or constructor call. An event could be an exception being thrown. Some AOP implementations use languages akin to queries to specify pointcuts. Others use tags. JBoss AOP uses both. Listing Three shows how to define a pointcut for the metrics example.

The following listing demonstrates defining a pointcut in JBoss AOP

1. <bind pointcut="public void com.mc.BankAccountDAO->withdraw(double amount)">
2.       <interceptor class="com.mc.Metrics"/>
3. </bind >
	
4. <bind pointcut="* com.mc.billing.*->*(..)">
5.       <interceptor class="com.mc.Metrics"/>
6. </bind >]]></programlisting>

Lines 1-3 define a pointcut that applies the metrics aspect to the specific method BankAccountDAO.withdraw(). Lines 4-6 define a general pointcut that applies the metrics aspect to all methods in all classes in the com.mc.billing package. There is also an optional annotation mapping if you do not like XML. See our Reference Guide for more information.

JBoss AOP has a rich set of pointcut expressions that you can use to define various points/events in your Java application so that you can apply your aspects. You can attach your aspects to a specific Java class in your application or you can use more complex compositional pointcuts to specify a wide range of classes within one expression.

With AOP, as this example shows, you're able to pull together crosscutting behavior into one object and apply it easily and simply, without polluting and bloating your code with features that ultimately don't belong mingled with business logic. Instead, common crosscutting concerns can be maintained and extended in one place.

Notice too that the code within the BankAccountDAO class has no idea that it's being profiled. This is what aspect-oriented programmers deem orthogonal concerns. Profiling is an orthogonal concern. In the OOP code snippet in Listing One, profiling was part of the application code. With AOP, you can remove that code. A modern promise of middleware is transparency, and AOP (pardon the pun) clearly delivers.

Just as important, orthogonal behavior could be bolted on after development. In Listing One, monitoring and profiling must be added at development time. With AOP, a developer or an administrator can (easily) add monitoring and metrics as needed without touching the code. This is a very subtle but significant part of AOP, as this separation (obliviousness, some may say) allows aspects to be layered on top of or below the code that they cut across. A layered design allows features to be added or removed at will. For instance, perhaps you snap on metrics only when you're doing some benchmarks, but remove it for production. With AOP, this can be done without editing, recompiling, or repackaging the code.

JBoss Cache is a tree-structured, clustered, transactional cache. It is the backbone for many fundamental JBoss Application Server clustering services, including - in certain versions - clustering JNDI, HTTP and EJB sessions.

JBoss Cache can also be used as a standalone transactional and clustered caching library or even an object oriented data store. It can even be embedded in other enterprise Java frameworks and application servers such as BEA WebLogic or IBM WebSphere, Tomcat, Spring, Hibernate, and many others. It is also very commonly used directly by standalone Java applications that do not run from within an application server, to maintain clustered state.

Pojo Cache is an extension of the core JBoss Cache API. Pojo Cache offers additional functionality such as:

Pojo Cache has a complete and separate set of documentation, including a user guide, FAQ and tutorial and as such, Pojo Cache is not discussed further in this book.

JBoss Cache offers a simple and straightforward API, where data (simple Java objects) can be placed in the cache and, based on configuration options selected, this data may be one or all of:

In addition, JBoss Cache offers a rich set of enterprise-class features:

A cache is organised as a tree, with a single root. Each node in the tree essentially contains a Map, which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that they implement java.io.Serializable . Note that this requirement does not exist for Pojo Cache.

JBoss Cache can be either local or replicated. Local trees exist only inside the JVM in which they are created, whereas replicated trees propagate any changes to some or all other trees in the same cluster. A cluster may span different hosts on a network or just different JVMs on a single host.

When a change is made to an object in the cache and that change is done in the context of a transaction, the replication of changes is deferred until the transaction commits successfully. All modifications are kept in a list associated with the transaction for the caller. When the transaction commits, we replicate the changes. Otherwise, (on a rollback) we simply undo the changes locally resulting in zero network traffic and overhead. For example, if a caller makes 100 modifications and then rolls back the transaction, we will not replicate anything, resulting in no network traffic.

If a caller has no transaction associated with it (and isolation level is not NONE - more about this later), we will replicate right after each modification, e.g. in the above case we would send 100 messages, plus an additional message for the rollback. In this sense, running without a transaction can be thought of as analogous as running with auto-commit switched on in JDBC terminology, where each operation is committed automatically.

JBoss Cache works out of the box with most popular transaction managers, and even provides an API where custom transaction manager lookups can be written.

The cache is also completely thread-safe. It uses a pessimistic locking scheme for nodes in the tree by default, with an optimistic locking scheme as a configurable option. With pessimistic locking, the degree of concurrency can be tuned using a number of isolation levels, corresponding to database-style transaction isolation levels, i.e., SERIALIZABLE, REPEATABLE_READ, READ_COMMITTED, READ_UNCOMMITTED and NONE. Concurrency, locking and isolation levels will be discussed later.

There are a number of ways to deploy POJO Cache:

More information on JBoss Cache can be obtained from the following resources:

In todays business environment data corruption can have serious consequences for the enterprise including service unavailability, system reconciliation costs, and damage to customer relationships and business reputation. The JBoss Transaction Service (JBossTS) protects businesses from data corruption by guaranteeing complete, accurate business transactions for Java based applications (including those written for the JEE and EJB frameworks) thereby eliminating the risks and costs associated with time-consuming manual reconciliation following failures.

In the modern business environment of system consolidations, worldwide utilization, and "always- on" availability, enterprises need distributed transaction processing infrastructure to build reliable, sophisticated business applications that can guarantee absolute completion and accuracy of business processes. Transaction services ensure that sequences of database updates have been accurately and reliably committed as a single complete unit of work or that, in the event of failure, the database information is recovered. "Multimodal Transaction Processing" is the term coined by Gartner to describe the new generation of transactional application required to face the challenges posed by new business requirements, technologies and innovative computing architectures.

JBossTS is a middleware solution that supports mission-critical applications in distributed computing environments. It plays a critical role in building reliable, sophisticated e-business applications guaranteeing absolute completion and accuracy of business processes. JBossTS supports "multimodal transaction processing" by enabling reliable transactions to span from front-end e-commerce applications to back office systems and beyond the enterprise firewall to business partners - across any system, anywhere in the world.

Building on the industry proven Java EE 5 transaction technology, version 4.0 adds native support for Web services transactions by providing all of the components necessary to build interoperable, reliable, multi-party, Web services-based applications with the minimum of effort. The product supports the WS-AtomicTransaction and WS-BusinessActivity specifications.

In traditional ACID transaction systems, transactions are short lived, resources (such as databases) are locked for the duration of the transaction and participants have a high degree of trust with each other. With the advent of the Internet and Web services, the scenario that is now emerging requires involvement of participants unknown to each other in distributed transactions. These transactions have the following characteristics:

Building on the industry proven JEE transaction technology, version 4.0 adds native support for Web services transactions by providing all of the components necessary to build interoperable, reliable, multi-party, Web services-based applications with the minimum of effort. The programming interfaces are based on the Java API for XML Transactioning (JAXTX) and the product includes protocol support for the WS-AtomicTransaction and WS-BusinessActivity specifications. JBossTS 4.2 is designed to support multiple coordination protocols and therefore helps to future-proof transactional applications. For a more detailed description of the product capabilities, see the full feature list below for more details.

JBossTS is a pure Java multi-modal transaction service that supports distributed transactions in CORBA, JEE and Web services environments.

The most powerful feature of JGroups is its flexible protocol stack, which allows developers to adapt it to exactly match their application requirements and network characteristics. The benefit of this is that you only pay for what you use. By mixing and matching protocols, various differing application requirements can be satisfied. JGroups comes with a number of protocols (but anyone can write their own), for example.

The features available with JBoss Remoting are:

As indicated earlier in this chapter, JBoss Remoting manages synchronous and asynchronous remote calls, push and pull callbacks, and automatic discovery of remoting servers. You can configure JBoss Remoting through the JBoss Messaging service configuration file JBOSS_HOME/server/<your_configuration>/deploy/messaging/remoting-service.xml.

The JBoss Messaging service configuration is spread among several configuration files. Depending on the functionality provided by the services it configures, the configuration data is distributed between <JBOSS_HOME>/server/<configuration>/deploy/messaging-service.xml, remoting-service.xml, connection-factories-service.xml, destinations-service.xml and xxx-persistence-service.xml (where xxx is the name of your database). The default will be hsqldb-persistence-service.xml for the hsqldb database.

The Server Peer is the heart of the JBoss Messaging JMS facade. The server's configuration, resides in messaging-service.xml configuration file. All JBoss Messaging services are rooted at the server peer. An example of a Server Peer configuration is presented below. Note that not all values for the server peer's attributes are specified in the example.

<!-- ServerPeer MBean configuration
	============================== -->
	
	<mbean code="org.jboss.jms.server.ServerPeer"
	name="jboss.messaging:service=ServerPeer"
	xmbean-dd="xmdesc/ServerPeer-xmbean.xml">
	
	<!-- The unique id of the server peer - in a cluster each node MUST have a unique value - must be an integer -->
	
	<attribute name="ServerPeerID">${jboss.messaging.ServerPeerID:0}</attribute>
	
	<!-- The default JNDI context to use for queues when they are deployed without specifying one --> 
	
	<attribute name="DefaultQueueJNDIContext">/queue</attribute>
	
	<!-- The default JNDI context to use for topics when they are deployed without specifying one --> 
	
	<attribute name="DefaultTopicJNDIContext">/topic</attribute>
	
	<attribute name="PostOffice">jboss.messaging:service=PostOffice</attribute>
	
	<!-- The default Dead Letter Queue (DLQ) to use for destinations.
	This can be overridden on a per destinatin basis -->
	
	<attribute name="DefaultDLQ">jboss.messaging.destination:service=Queue,name=DLQ</attribute>
	
	<!-- The default maximum number of times to attempt delivery of a message before sending to the DLQ (if configured).
	This can be overridden on a per destinatin basis -->
	
	<attribute name="DefaultMaxDeliveryAttempts">10</attribute>
	
	<!-- The default Expiry Queue to use for destinations. This can be overridden on a per destinatin basis -->
	
	<attribute name="DefaultExpiryQueue">jboss.messaging.destination:service=Queue,name=ExpiryQueue</attribute>
	
	<!-- The default redelivery delay to impose. This can be overridden on a per destination basis -->
	
	<attribute name="DefaultRedeliveryDelay">0</attribute>
	
	<!-- The periodicity of the message counter manager enquiring on queues for statistics -->
	
	<attribute name="MessageCounterSamplePeriod">5000</attribute>
	
	<!-- The maximum amount of time for a client to wait for failover to start on the server side after
	it has detected failure -->
	
	<attribute name="FailoverStartTimeout">60000</attribute>
	
	<!-- The maximum amount of time for a client to wait for failover to complete on the server side after
	it has detected failure -->
	
	<attribute name="FailoverCompleteTimeout">300000</attribute>
	
	<attribute name="StrictTck">false</attribute>
	
	<!-- The maximum number of days results to maintain in the message counter history -->
	
	<attribute name="DefaultMessageCounterHistoryDayLimit">-1</attribute>
	
	<!-- The name of the connection factory to use for creating connections between nodes to pull messages -->
	
	<attribute name="ClusterPullConnectionFactoryName">jboss.messaging.connectionfactory:service=ClusterPullConnectionFactory</attribute>
	
	<!-- When redistributing messages in the cluster. Do we need to preserve the order of messages received
	by a particular consumer from a particular producer? -->
	
	<attribute name="DefaultPreserveOrdering">false</attribute>
	
	<!-- Max. time to hold previously delivered messages back waiting for clients to reconnect after failover -->
	
	<attribute name="RecoverDeliveriesTimeout">300000</attribute>
	
	<!-- The password used by the message sucker connections to create connections.
	THIS SHOULD ALWAYS BE CHANGED AT INSTALL TIME TO SECURE SYSTEM
	<attribute name="SuckerPassword"></attribute>
	-->
	
	<!-- The name of the server aspects configuration resource
	<attribute name="ServerAopConfig">aop/jboss-aop-messaging-server.xml</attribute>
	-->
	<!-- The name of the client aspects configuration resource
	<attribute name="ClientAopConfig">aop/jboss-aop-messaging-client.xml</attribute>
	-->
	
	<depends optional-attribute-name="PersistenceManager">jboss.messaging:service=PersistenceManager</depends>
	
	<depends optional-attribute-name="JMSUserManager">jboss.messaging:service=JMSUserManager</depends>
	
	<depends>jboss.messaging:service=Connector,transport=bisocket</depends>
	<depends optional-attribute-name="SecurityStore"
	proxy-type="org.jboss.jms.server.SecurityStore">jboss.messaging:service=SecurityStore</depends>
</mbean>
...

This section discusses the MBean attributes of the ServerPeer MBean.

JBoss utilizes the Hypersonic database as its default database. While this is good for development and prototyping, you or your company will probably require another database to be used for production. This chapter covers configuring JBoss AS to use alternative databases. We cover the procedures for all officially supported databases on the JBoss Application Server. They include: MySQL 5.0, PostgreSQL 8.1, Oracle 9i and 10g R2, DB2 7.2 and 8, Sybase ASE 12.5, as well as MS SQL 2005.

Please note that in this chapter, we explain how to use alternative databases to support all services in JBoss AS. This includes all the system level services such as EJB and JMS. For individual applications (e.g., WAR or EAR) deployed in JBoss AS, you can still use any backend database by setting up the appropriate data source connection.

We assume that you have already installed the external database server, and have it running. You should create an empty database named jboss, accessible via the username / password pair jbossuser / jbosspass. The jboss database is used to store JBoss AS internal data -- JBoss AS will automatically create tables and data in it.

For the JBoss Application Server and our applications to use the external database, we also need to install the database's JDBC driver. The JDBC driver is a JAR file, which you'll need to copy into your JBoss AS's <JBoss_Home>/server/all/lib directory. Replace all with the server configuration you are using if needed. This file is loaded when JBoss starts up. So if you have the JBoss AS running, you'll need to shut down and restart. The availability of JDBC drivers for different databases are as follows.

JBoss AS connects to relational databases via datasources. These datasource definitions can be found in the <JBoss_Home>/server/all/deploy directory. The datasource definitions are deployable just like WAR and EAR files. The datasource files can be recognized by looking for the XML files that end in *-ds.xml.

The following code snippet shows the mysql-ds.xml file as an example. All the other *-ds.xml files are very similiar. You will need to change the connection-url, as well as the user-name / password, to fit your own database server installation.

<datasources>
<local-tx-datasource>
<jndi-name>MySqlDS</jndi-name>
<connection-url>jdbc:mysql://localhost:3306/jboss</connection-url>
<driver-class>com.mysql.jdbc.Driver</driver-class>
<user-name>jbossuser</user-name>
<password>jbosspass</password>
<exception-sorter-class-name>
org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter
</exception-sorter-class-name>
<!-- should only be used on drivers after 3.22.1 with "ping" support
<valid-connection-checker-class-name>
org.jboss.resource.adapter.jdbc.vendor.MySQLValidConnectionChecker
</valid-connection-checker-class-name>
-->
<!-- sql to call when connection is created
<new-connection-sql>some arbitrary sql</new-connection-sql>
-->
<!-- sql to call on an existing pooled connection when it is obtained from pool - 
 MySQLValidConnectionChecker is preferred for newer drivers
<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
 -->
   
<!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
   <metadata>
 <type-mapping>mySQL</type-mapping>
 </metadata>
 </local-tx-datasource>
    
</datasources>

Once you customized the *-ds.xml file to connect to your external database, you need to copy it to the <JBoss_Home>/server/all/deploy directory. The database connection is now available through the JNDI name specified in the *-ds.xml file.

The JMS service in the JBoss AS uses relational databases to persist its messages. For improved performance, we should change the JMS service to take advantage of the external database. To do that, we need to replace the file <JBoss_Home>/server/all/deploy/jms-singleton/hsqldb-jdbc2-service.xml with a file in <JBoss_Home>/docs/examples/jms/ depending on your external database. Notice that if you are using the default server profile, the file path is <JBoss_Home>/server/default/deploy/jms/hsqldb-jdbc2-service.xml.

Next, we need to go change the <JBoss_Home>/server/all/conf/standardjbosscmp-jdbc.xml file so that the fk-constraint property is true. That is needed for all external databases we support on the JBoss Application Server. This file configures the database connection settings for the EJB2 CMP beans deployed in the JBoss AS.

<fk-constraint>true</fk-constraint>

The Java Persistence API (JPA) entity manager can save EJB3 entity beans to any backend database. Hibernate provides the JPA implementation in JBoss AS. Hibernate has a dialect auto-detection mechanism that works for most databases including the dialects for databases referenced in this appendix which are listed below. If a specific dialect is needed for alternative databases, you can configure the database dialect in the <JBoss_Home>/server/all/deploy/ejb3.deployer/META-INF/persistence.properties file. You need to un-comment the hibernate.dialect property and change its value to the following based on the database you setup. For a complete list of dialects, refer to the Hibernate Reference Guide, Chapter 3, Section 4.1 SQL Dialects.

Besides JMS, CMP, and JPA, we still need to hook up the rest of JBoss services with the external database. There are two ways to do it. One is easy but inflexible. The other is flexible but requires more steps. Now, let's discuss those two approaches respectively.

In our setup discussed in this chapter, we rely on the JBoss AS to automatically create needed tables in the external database upon server startup. That works most of the time. But for databases like Oracle, there might be some minor issues if you try to use the same database server to back more than one JBoss AS instance.

The Oracle database creates tables of the form schemaname.tablename. The TIMERS and HILOSEQUENCES tables needed by JBoss AS would not get created on a schema if the table already exists on a different schema. To work around this issue, you need to edit the <JBoss_Home>/server/all/deploy/ejb-deployer.xml file to change the table name from TIMERS to something like schemaname2.tablename.

<mbean code="org.jboss.ejb.txtimer.DatabasePersistencePolicy" 
name="jboss.ejb:service=EJBTimerService,persistencePolicy=database">
<!-- DataSourceBinding ObjectName -->
<depends optional-attribute-name="DataSource">
 jboss.jca:service=DataSourceBinding,name=DefaultDS
</depends>
<!-- The plugin that handles database persistence -->
<attribute name="DatabasePersistencePlugin">
org.jboss.ejb.txtimer.GeneralPurposeDatabasePersistencePlugin
</attribute>
<!-- The timers table name -->
<attribute name="TimersTable">TIMERS</attribute>
</mbean> 

Similarly, you need to change the <JBoss_Home>/server/all/deploy/uuid-key-generator.sar/META-INF/jboss-service.xml file to change the table name from HILOSEQUENCES to something like schemaname2.tablename as well.

<!-- HiLoKeyGeneratorFactory -->
<mbean code="org.jboss.ejb.plugins.keygenerator.hilo.HiLoKeyGeneratorFactory"
name="jboss:service=KeyGeneratorFactory,type=HiLo">
	
<depends>jboss:service=TransactionManager</depends>
	
<!-- Attributes common to HiLo factory instances -->
	
<!-- DataSource JNDI name -->
<depends optional-attribute-name="DataSource">jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
	
<!-- table name -->
<attribute name="TableName">HILOSEQUENCES</attribute>

DataSources are defined inside a <datasources> element.