« Archives in August, 2010

The conf directory, JBoss v5.x

Configure what you need

So you’re ready to configure some JBoss files? Great, lets have a look at the conf directory. The jboss/server/<configured instance>/conf directory is where you’ll find the majority of the configuration files for your jboss instance. For most deployments, the majority of these folders and files will remain untouched as they default to usable configurations. In this article we’ll go over the more practical configurable files, while leaving the really low level configurations alone.

`-- conf
    |-- bootstrap/
    |--|-- bindingservice.bean
    |   `-- META-INF
    |   |    `-- bindings-jboss-beans.xml *
    |   |-- aop.xml
    |   |-- classloader.xml
    |   |-- deployers.xml
    |   |-- jmx.xml
    |   |-- logging.xml
    |   |-- profile.xml *
    |   `-- vfs.xml
    |-- props
    |   |-- jbossws-roles.properties
    |   |-- jbossws-users.properties
    |   |-- jmx-console-roles.properties
    |   `-- jmx-console-users.properties
    |-- xmdesc
    |   |-- AttributePersistenceService-xmbean.xml
    |   |-- ClientUserTransaction-xmbean.xml
    |   |-- JNDIView-xmbean.xml
    |   |-- Log4jService-xmbean.xml
    |   |-- NamingBean-xmbean.xml
    |   |-- NamingProviderURLWriter-xmbean.xml
    |   `-- NamingService-xmbean.xml
    |-- bootstrap.xml
    |-- jacorb.properties
    |-- java.policy
    |-- jax-ws-catalog.xml
    |-- jboss-log4j.xml
    |-- jboss-service.xml
    |-- jbossjta-properties.xml
    |-- jndi.properties
    |-- login-config.xml
    |-- standardjboss.xml
    `-- standardjbosscmp-jdbc.xml

For starters, the bootstrap.xml file lets you configure which microcontainer deployments are loaded on boot. The ones we want to pay special attention to are profile.xml and conf/bindingservice.beans’s bindings-jboss-beans.xml (marked with an asterisk in the layout diagram) The other files are geared for low level configurations. For example – aop.xml configured how aop is implemented in jboss, deployers.xml configures jboss’ classloaders, and vfs.xml tells jboss what lib folders to load jars from.

External deployments

If you open up profile.xml, you’ll see a set of configurations that describe what kind of deployers are used for the profile object management service. Most of the contents deal with Jboss’ innards, but worthy of reviewing is the “applicationURIs” property. It’s actually a list of java.net.URI urls, and you can add elements to this list in order to configure Jboss so that it looks in to external deployment directories in addition to the defauls deploy directory. More detail is described in the related article “External deploy directories in JBoss 5.1”.

Port Bindings

Before Jboss 5, you would have to manually go in and change each port into its own numberspace. There were a bunch of places where these ports would need to be updated (for things like the naming and rmi services) across a slew of files scattered all over the place. In Jboss 5, if you open up bindings-jboss-beans.xml, you’ll find a means of binding multiple jboss instances across different ports in a single centralized location. Out of the box, Jboss ships with 4 sets of port configurations. Each configuration set reserves a set of ports for JBoss’ use. If you trail through each of these port configurations, you’ll notice the sets are offset by increments of 100. So for example the first configuration reserves 1099 for the NamingServer, while the second set reserves 1199, and the third set uses 1299 and so on. This functionality is particularly useful when you want Jboss to run on a single IP address. Given a choice though, I would opt for using a single IP per Jboss instance. It’s nice to have this option though, in case multiple IPs is not an option.

We can get an idea of how JBoss configures these binding sets from the snippets below – both are straight out of the bindings-jboss-beans.xml file:

<!-- Provides management tools -->
<bean name="ServiceBindingManagementObject" 

     <!-- The name of the set of bindings to use for this server -->

     <!--  The binding sets -->
	    <inject bean="PortsDefaultBindings"/>
	    <inject bean="Ports01Bindings"/>
	    <inject bean="Ports02Bindings"/>
	    <inject bean="Ports03Bindings"/>

     <!-- Base binding metadata used to create bindings for each set -->
     <parameter><inject bean="StandardBindings"/></parameter>



<!-- bindings are obtained by taking the base bindings and adding offsets  -->
<bean name="Ports01Bindings"  
	<!--  The name of the set -->
	<!-- Default host name -->
	<!-- The port offset -->
	<!-- Bindings to which the "offset by X" approach can't be applied -->

If you run Jboss without a ports configuration, it will use the default port settings. If you want to use a specific port configuration, all you need to do is add the startup param to the run.sh script used to invoke jboss: “-Djboss.service.binding.set=ports-01”. This param selects which port config to use, and likewise can be used to use any of the available port bindings found in bindings-jboss-beans.xml.

The props folder – default UsersRolesLoginModule properties for jmx-console security

If you make use of jmx-console’s default UsersRolesLoginModule JAAS security domain configuration, you’ll find that the user and role properties are stored in this “props” folder. More on securing the jmx console can be found here. You can also opt to use a different security module, by defining a different login module in login-config.xml. More on this in a few paragraphs.

The xmdesc folder – mbean descriptors

This folder contains all the descriptors used for the major mbeans described in the jboss-service.xml. Not all the possible mbeans have been converted over to the new bootstrapping style format, so these legacy descriptors close the gap to allow existing mbean services to continue to work.

Logging with jboss-log4j.xml

This piece allows you to configure the logging for the entire instance. If you’re familiar with log4j, you’ll know right off the bat how to configure the logging. Out of the box Jboss ships with console output enabled. For production level environments though, we’ll want that disabled as console logging always takes up unnecessary system resources. You are able to control smtp, console, file, jms, and file based logging with levels (DEBUG, INFO, WARN, ERROR, FATAL etc) and by category (com.yourpackage.class or com.yourpackage). Asynchronous appenders allow you to configure logging that gets piped to more than one target. Learn mroe about how to configure this from Apache’s Log4J’s project website. A basic log4j configuration can be found in the example below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" 
   <!-- A time/date based rolling appender -->
      <appender class="org.jboss.logging.appender.DailyRollingFileAppender"
      <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
      <param name="File" value="${jboss.server.log.dir}/server.log"/>
      <param name="Append" value="true"/>
      <!-- Rollover at midnight each day -->
      <param name="DatePattern" value="'.'yyyy-MM-dd"/>

      <layout class="org.apache.log4j.PatternLayout">
         <!-- Default pattern: Date Priority [Category] (Thread) Messagen -->
         <param name="ConversionPattern" value="%d %-5p [%c] (%t) %m%n"/>

	<priority value="${jboss.server.log.threshold}"/>
	<appender-ref ref="FILE"/>

JAAS/Security Domains with login-config.xml

This file allows you to configure security domain with JAAS for your applications. You have a number of login modules to choose from, notably the DatabaseServerLoginModule. This module allows you to hook in a set of users and roles query into a datasource to validate authentication credentials and allow access to your application. In a default install, Jboss will have example configurations where users and roles are also stored in the props directory and accessed via the UsersRolesLoginModule.

An example JAAS database login module configuration in login-config.xml:

<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
  <application-policy xmlns="urn:jboss:security-beans:1.0" name="loginForm">
      <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
        <!--  BASE64 also possible -->
        <module-option name="hashAlgorithm">MD5</module-option> 
        <module-option name="unauthenticatedIdentity">guest</module-option>
        <module-option name="dsJndiName">java:/DefaultDS</module-option>
        <module-option name="principalsQuery">
        	SELECT password FROM User WHERE username=?
        <module-option name="rolesQuery">
        	SELECT role, 'Roles' 
        	FROM UserRoles, User 
        	WHERE User.username=? 
        		AND User.id = UserRoles.user_id

In order for this configuration to work we’ll need to also add security domains to our web application’s web.xml as well as a the Jboss only jboss-web.xml deployment descriptor. More on how to configure this can be fond in Jboss’ server manual, section 9.6.4.

The remaining files

The last remaining files cover various integration configurations, and delve into Jboss’ low level implementation. One example is the java.policy file which configures your instance’s security policy on the jvm level. You may constrain permissions to allow strictly reading across the board or some custom mix of read and write, and by class. More information can be found on Jboss Web’s security manager page. For the uninitiated, Jboss Web is the integrated version of Tomcat 6 that deploys with JBoss as a deployable service.

The jbossjta-properties.xml file configures the Jboss transaction server’s default behavior. The jax-ws-catalog.xml maps xml metadata for use with jax-ws webservices, as specified by the Oasis XML Catalog spec. The jndi.properties file maps classes used by Jboss’ naming server. The jacorb.properties file configures JacORB (Java implementation of OMG’s Corba standard) for use with Jboss.

Finally, the standardjbosscmp.xml config defines how various types of enterprise java beans are configured during regular use, while standardjbosscmp-jdbc.xml configures specific persistence dialects relating to type mappings so that datasource files can communicate correctly with different database vendors. In your datasource file you can add a type element to specify which of these defined types jboss should use:

<?xml version="1.0" encoding="UTF-8"?>  

The recap

Once you’ve gone over these configuration files, you’ll have seen with some depth part of what Jboss is capable of. As mentioned earlier, you wont want to muck around with most of these configurations unless you’re working on Jboss server code itself or unless you want to tweak the server’s behavior. The most commonly edited files end up being bindings-jboss-beans.xml (multiple port bindings), profile.xml (external deploy directories), jboss-log4j.xml (logging), login-config.xml (security domains) and java.policy (jvm level security permissions). With these basics you can be well off into configuring Jboss for whatever needs you need to fill.

Securing the JMX Console
JBoss App server Quick Tour
JBoss Web manual
Oasis XML Catalog project

Apache XSL-FO’ sho v1.0

Transforming XML into PDFs.. and stuff

If you’ve ever been tasked with providing PDF documents via xsl, you’ve surely done some homework and shopped around for viable third party libraries. Some are good, some are great and rightly so charge a price, and some are just flat out incomplete or shanty in their documentation. It’s not a knock on anyone, its just a fact well known to open source developers. Historically what has been missing is an open standard for pdf generation, and possibly other output formats.

Enter XSL-FO: XSL Formatting Objects is an open standard for formatting documents in order to produce media artifacts such as PDF, postscript (PS), rich text format (RTF), and png files. Because it’s XML centric, you can marry your XML data to an XSL-FO stylesheet and perform a translation that will output a file in any of these format or others. XSL-FO is simply the XSL dialect used to lay out the document, and Apache FOP is the open source java based software you can use to process those transformations.

Apache FOP has been slowly making its complete debut over the past 3 years. Version 1.0 was finally released around the 12th of july, so its essentially a fresh release. Before that, .95 was the closest thing to production ready, but now that 1.0 is out, a more complete implementation awaits. There are still a few loose ends to tie up though, a complete rundown of FO compliance can be found on on apache’s XSL-FO compliance page

On with the examples:

The XML data

	<date>july 27th, 2010</date>

This is a very simple xml document, which we will be reading from in order to stamp the date onto a pdf document.

The XSL-FO layout

<?xml version="1.0" encoding="ISO-8859-1"?>
	<xsl:template match="/">
	<fo:root font-family="Verdana" font-size="12pt" text-align="center"
	  <fo:simple-page-master master-name="master">
		<fo:region-body margin="0in"
			background-position="center"  />
	<fo:page-sequence master-reference="master">

	  <fo:flow flow-name="xsl-region-body">
			Today's XML date is: <xsl:value-of select="/block/date"/>


This is the XSL-FO layout we’ll be using to stamp on the pdf. It’s marked up using regular XSL-FO. Covering the syntax of XSL-FO is beyond the scope of this article, but there are plenty of resources and tutorials online such as the W3Schools.com XSL-FO and Renderx.com tutorials.

On with the java

Finally, we come to the java code and apache’s fop usage:

	protected void export() throws  IOException {
	    //Setup a buffer to obtain the content length
		FileOutputStream out = new FileOutputStream("C:/image/layout.pdf");
		try {
			// generic files to String XML and XSL
			String xml = FileUtils.readFile("C:/image/banner.text.xml");
			String xsl = FileUtils.readFile("C:/image/banner.layout.fo"); 
	        // configure fopFactory as desired
	        FopFactory fopFactory = FopFactory.newInstance();
	        TransformerFactory factory = TransformerFactory.newInstance();
		    //Setup FOP
		    Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, out);
		    //Setup Transformer
		    Source xsltSrc = new StreamSource(new StringReader(xsl));
		    Transformer transformer = factory.newTransformer(xsltSrc);
		    //Setup input
		    Source src = new StreamSource(new StringReader(xml));
		    //Make sure the XSL transformation's result is piped through to FOP
		    Result res = new SAXResult(fop.getDefaultHandler());	    
		    //Start the transformation and rendering process
		    transformer.transform(src, res);
		} catch (Exception e) {	
		} finally {

Pretty straight forward xslt looking code. But what if we want to override the FOP PDFgeneration defaults? What if we want to produce a document not regular PDF page size, like a banner or if we want to produce a png image? Luckily, FOP offers a factory configuration mechanism we can use to customize the outputs.

Rendering the output as a PNG file

The java code is pretty much the same thing, with some small differences. First you’ll want to invoke the fopFactory.setUserConfig(String pathToConfig) method on the FoPFactory object. This will flag apache FOP to load a custom configuration from the specified file. Secondly you’ll need to set the exporting mime type to MimeConstants.MIME_PNG, as show in the java code snippet below.

// configure fopFactory as desired
FopFactory fopFactory = FopFactory.newInstance();
fopFactory.setUserConfig(new File(rootPath + "export.conf.xml"));
TransformerFactory factory = TransformerFactory.newInstance();

//Setup FOP
Fop fop = fopFactory.newFop(MimeConstants.MIME_PNG, out);

Lastly, you’ll want to define your export.conf.xml file. The only thing that you’d be changing that strays from the defaults would be the exported object’s dimensions (set in the example below to 150px length by 900px wide) and adding the renderer element that defines an “image/png” type. This renderer block flags the processor to export as PNG. At the moment the only other image export format is TIFF, but between these two, most purposes are likely met. It’s worth mentioning that FOP supports export into Postscript, PCL, AFP, RTF, XML, and TXT to name a few. More details can be found on Apache FOP’s Output Target page. Here’s the source:

<?xml version="1.0"?>

<fop version="1.0">

	<!-- Base URL for resolving relative URLs -->

		Source resolution in dpi (dots/pixels per inch) for determining the
		size of pixels in SVG and bitmap images, default: 72dpi
		Target resolution in dpi (dots/pixels per inch) for specifying the
		target resolution for generated bitmaps, default: 72dpi

		Default page-height and page-width, in case value is specified as auto
	<default-page-settings height="150px" width="900px" />

	<!-- Uses renderer mime type for renderers -->

		<renderer mime="image/png">
		  <fonts><!-- described elsewhere --></fonts>



So if you want to export to a different format, all you’d need to do is use a custom configuration and set the renderer formats to match the one you’d like to use, as well as override any default document properties you wish.

By leveraging an open standard like XSL-FO you can use different vendors for your pdf generation code, and while Apache’s FOP implementation isn’t 100% complete in its support for XSL-FO, it does do a good job of supporting what most folks will need on a daily basis. It’s nice to see a complete version release after a long wait.

Apache FOP website. v1.0 Finally released on 7/12/2010?, yay!
Apache FOP compliance guide
XSL-FO Object Model documentation
Renderx.com“>Renderx.com tutorial on XSL-FO

There’s also the ultimate XSL-FO list of resources:
Whoishostingthis.com xsl-fo Resources