JBoss5 custom metadata files

With new Microcontainer, its Deployers and JBossXB,

it's super easy to write some custom metadata along with its matching/handling deployer.

We use different files to add to deployment information, ranging from performance benefits to easily customizable classloading metadata.

 

This wiki page should contain the list of them, its metadata class and the most inmportant, their usage / purpose.

 

File name
Usage
MetaDataDeployer
jboss-scanning.xmlFilter annotation scanningAbstractScanningMetaDataScanningMetaDataDeployer
jboss-classloading.xmlClassloader metadataClassLoadingMetaDataSchemaResolverDeployer
jboss-classloading-domain.xmlCL domain metadataClassLoadingDomainMetaDataSchemaResolverDeployer
jboss-translator.xmlCL translatorsClassLoadingTranslatorsMetaDataSchemaResolverDeployer
jboss-structure.xmlDeployment structureStructureMetaDataObjectFactory / ContextInfoImplDeclaredStructure
aliases.txtDeployment unit aliasesDeploymentAliasesMetaDataDeploymentAliasesDeployer
jboss-dependency.xmlGeneric dependencyDependenciesMetaDataDeploymentDependenciesDeployer
jboss-deployment.xmlLazy CL handlingDeploymentMetaDataDeploymentValidationDeployer
jboss-ignore.txtIgnore filesNameIgnoreMechanismAbstractIgnoreFilesDeployer

 

jboss-scanning.xml:

 

Current JEE specs reduced the number of configuration files,

but they now require the container to do most of the job based on @annotations.

In order to get @annotation info, containers must scan classes.

This is often performance penalty.

 

In order to minimize what/where we scan, we can provide this info in this file.

 

<scanning xmlns="urn:jboss:scanning:1.0">
  <path name="myejbs.jar">
    <include name="com.acme.foo"/>
    <exclude name="com.acme.foo.bar"/>
  </path>
  <path name="my.war/WEB-INF/classes">
    <include name="com.acme.foo"/>
  </path>
</scanning>

 

jboss-classloading.xml:

 

Simple version.

I'll let Adrian provide more complex example. ;-)

 

<classloading xmlns="urn:jboss:classloading:1.0" export-all="NON_EMPTY">
   <capabilities>
      <module name="test5"/>
   </capabilities>

   <requirements>
      <module name="test2"/>
   </requirements>
</classloading>

 

Here's an article which explains the jboss-classloading.xml in detail http://phytodata.wordpress.com/2010/10/21/demystifying-the-jboss5-jboss-classloading-xml-file/

 

 

jboss-classloading-domain.xml

 

Here we configure CL domain lookup in more fine-grained way.

e.g. custom parent policy

 

<classloading-domain xmlns="urn:jboss:classloading-domain:1.0" name="test">
   <parent-policy>
      <before-filter>org.jboss.acme,com.redhat.acme</before-filter>
      <after-filter>org.jboss.foobar,com.redhat.foobar</after-filter>
      <description>Qwert</description>
   </parent-policy>
</classloading-domain>

 

jboss-translator.xml

 

Here we add CL translators at runtime.

It could be added to system, domain or policy -- see scope attribute.

If class already has matching method, it can also be used as translator via reflection.

e.g. instrumentation's ClassFileTransformer

 

<classloading-translators xmlns="urn:jboss:classloading-translators:1.0">

    <translator class="org.jboss.test.deployers.vfs.classloading.support.MockTranslator" scope="DOMAIN" />

    <translator class="org.jboss.test.deployers.vfs.classloading.support.IATranslator" method="transform" scope="POLICY" />

    <translator class="org.jboss.test.deployers.vfs.classloading.support.BableFish" method="bable" scope="SYSTEM" />

</classloading-translators>

 

jboss-structure.xml:

 

This is where we describe our deployment's structure.

e.g. what is the context's path, its metadata path, classpath, comparator, modifications

You would use this in case your deployment does not comply to the usual/spec deployments,

 

<structure>
    <context comparator="org.jboss.test.deployment.test.SomeDeploymentComparatorTop">
        <path name=""/>
        <metaDataPath>
         <path name="META-INF"/>
      </metaDataPath>
      <classpath>
            <path name="jar1.jar"/>
            <path name="lib-dir" suffixes=".jar"/>
        </classpath>
    </context>
    <context modification="unpack">
        <path name="sub.jar"/>
      <metaDataPath>
         <path name="META-INF"/>
      </metaDataPath>
    </context>
    <context comparator="org.jboss.test.deployment.test.SomeDeploymentComparatorX">
        <path name="x.war"/>
      <metaDataPath>
         <path name="WEB-INF"/>
      </metaDataPath>
        <classpath>
            <path name="x.war/WEB-INF/classes"/>
            <path name="x.war/WEB-INF/lib" suffixes=".jar"/>
        </classpath>
    </context>
</structure>

 

aliases.txt:

 

It's a plain txt file, each line containing new alias.

(see jboss-dependency.xml for the usage)

 

e.g.

my-human-readable-deployment-alias

 

Note: this only works on top level deployment

 

jboss-dependency.xml:

 

You can define generic dependencies of your deployment wrt other deployments or even services.

e.g. my x-app.ear should start after x-util.jar is installed

e.g. my z-app.war depends on TransactionManager bean

 

<dependency xmlns="urn:jboss:dependency:1.0">
  <item whenRequired="Real" dependentState="Create">TransactionManager</item>
  <item>my-human-readable-deployment-alias</item>
</dependency>

 

For deployments the state is DeploymentStage class, for services the state is ControllerState class.

 

Note: module/deployment dependency can be described in jboss-classloading.xml as well.

Note2: this can be also added to sub-deployments.

 

jboss-deployment.xml

 

You can define lazy handling of deployment's ClassLoader.

e.g. don't create ClassLoader until needed by some other deployment/bundle,

or, don't move the deployment to Real stage until some class from this deployment is loaded

 

<deployment xmlns="urn:jboss:deployment:1.0" required-stage="PreDescribe" lazy-resolve="true">

 

    <lazy-start-filter recurse="false">org.foo.bar</lazy-start-filter>
    <lazy-start-filter recurse="true">com.acme.somepackage</lazy-start-filter>

 

</deployment>

 

jboss-ignore.txt

 

The file should include relative paths wrt its owner (sub)deployment.
e.g. META-INF/some-custom.xml or WEB-INF/lib/ui.jar/META-INF/persistence.xml

 

This files will then be ignored while using matching parsing deployer.