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.