Code example for a basic parsing deployer

[dmlloyd]

Just wondering if there is a code example somewhere of a simple parsing deployer using the JAXB stuff. I'm having a hard time figuring out the intended usage based on the documentation (a lot of the deployer stuff is still missing from the docs it seems).

The documentation, in many cases, says things like "The BeanMetaData provides top level information and access to the more detailed information about the bean deployment" or "The purpose of Structure Deployer is to recognise the deployment type and prepare this information for the actual Deployers." These are all good, concise explanations for the purpose of these concepts. But then fails to explain how to actually use them in practice; e.g. I'm looking for something that says "To actually implement a deployer, extend XXX and provide implementations for YYY and ZZZ".

[alesj]

Just wondering if there is a code example somewhere of a simple parsing deployer using the JAXB stuff. I'm having a hard time figuring out the intended usage based on the documentation (a lot of the deployer stuff is still missing from the docs it seems).

ATM I don't think there is any 'production' usage of the new JBossXB.Builder/JAXB parsing.
Since we haven't done the full switch yet.

I'll have a look today, trying to provide the initial parsing deployer based on this stuff.
But for time being have a look at any XYZJaxbTestCase in Microcontainer module, and follow the trail to the parsing bit.

The documentation, in many cases, says things like "The BeanMetaData provides top level information and access to the more detailed information about the bean deployment" or "The purpose of Structure Deployer is to recognise the deployment type and prepare this information for the actual Deployers." These are all good, concise explanations for the purpose of these concepts. But then fails to explain how to actually use them in practice; e.g. I'm looking for something that says "To actually implement a deployer, extend XXX and provide implementations for YYY and ZZZ".

All agreed.
But the MC's VDF is a huge huge beast.
Providing example for every part is virtually impossible.

But I think the new concept of being able to comment on the docs will help with this problem. e.g. users providing best practices

And we can also keep a note of the things you users :-) want in the docs from the beginning.
Having example of new cool JBossXB.Builder is a reasonable choice. :-)

[newtonm]

Hi David,

Finishing the Deployment Framework sections of the JBoss Microcontainer User Guide is the very next thing on my list.

I've been wanting to do this for a while but I've been held up trying to get the JBoss Documentation project back on its feet so that all JBoss.org projects can produce docs from DocBook using Maven and the JBoss.org style (as used by the JBoss MC Guide).

For the moment, until I can complete the content, looking at the Unit Test for the JAXB parsing deployer is probably the best you can do.

Mark

[adrian.brock]

You don't need to write code for a parsing deployer if you use the annotations.

You need to do two things:

1) Configure the generic JBossXB deployer

 <bean name="ClassLoadingMetaDataParser" class="org.jboss.deployers.vfs.spi.deployer.SchemaResolverDeployer">

<!-- This is what you expect the metadata to parsed to -->

 <constructor>
 <parameter>org.jboss.classloading.spi.metadata.ClassLoadingMetaData</parameter>
 </constructor>

<!-- This says you want to parse any META-INF/jboss-classloading.xml -->

 <property name="name">jboss-classloading.xml</property>

<!-- This is "optional" for the profile service - it builds the management information from annotations -->

 <property name="buildManagedObject">true</property>
 </bean>

2) But there is one extra step that JBossXB needs.
It needs to know that your schema name maps to that class.

Technically, this should be redundant, but the deployer doesn't do this for you. :-(

You either make it a factory setting in the SingletonSchemaBindingResolver
or you have to add some extra metadata to JBossXB,
e.g. see deployers/metadata-beans.xml in the appserver

I guess we could add an extra option to the SchemaResolverParser

 <propertry name="registerWithJBossXB">true</property>

which would take the schema name from the annotation on the class/package
and register the generated schema binding with JBossXB?
Which would remove the need for step (2)

[adrian.brock]

Off Topic

Ales, this kind of thing would be a good example for the "use case" xml.

i.e. instead of

 <bean name="ClassLoadingMetaDataParser" class="org.jboss.deployers.vfs.spi.deployer.SchemaResolverDeployer">

 <constructor>
 <parameter>org.jboss.classloading.spi.metadata.ClassLoadingMetaData</parameter>
 </constructor>

 <property name="name">jboss-classloading.xml</property>
 </bean>

you do

<jbossxb-parser xmlns="urn:jboss:deployers:2.0"
 name="FooParser"
 class="com.foo.MetaData"
 suffix="-foo.xml"/>

[alesj]

I guess we could add an extra option to the SchemaResolverParser

 <propertry name="registerWithJBossXB">true</property>

which would take the schema name from the annotation on the class/package
and register the generated schema binding with JBossXB?
Which would remove the need for step (2)

OK, I'll add this.
Since I think that step (2) is pita, and a very possible root of problems.
e.g. recent jboss:security-config:5.0 ;-)

[alesj]

Ales, this kind of thing would be a good example for the "use case" xml.

You mean a "use case" of a "use case". :-)
I'll add this as well then.

[dmlloyd]

OK, looks good so far. The only piece of the puzzle missing for me is how to write the actual deployer which takes the metadata and converts it into a bean deployment (that's how it's supposed to work, right?), presumably feeding that back to the MC so that it can do its magic.

[dmlloyd]

You don't need to write code for a parsing deployer if you use the annotations.

You need to do two things:

1) Configure the generic JBossXB deployer

2) But there is one extra step that JBossXB needs.
It needs to know that your schema name maps to that class.

Cool, easier than I thought. Adding an option for registering the schema binding would be very handy.

[alesj]

The only piece of the puzzle missing for me is how to write the actual deployer which takes the metadata and converts it into a bean deployment (that's how it's supposed to work, right?), presumably feeding that back to the MC so that it can do its magic.

You (usually) don't have to write the deployer, you only need to write your metadata classes. Or better, you need to properly annotate them.

You have two approaches - if we're talking about creating bean deployment.

1) Your custom xml is included in existing beans deployment

Have proper annotations on metadata, register schema and your metadata class must implement org.jboss.beans.metadata.spi.BeanMetaDataFactory.
e.g.
- http://anonsvn.jboss.org/repos/jbossas/projects/jboss-cl/trunk/classloading-vfs/src/main/org/jboss/classloading/spi/vfs/metadata/VFSClassLoaderFactory.java

2) You have custom xml file

Have proper annotations on metadata.
Use both of previous Adrian's suggestions.
Now you need to create proper components that MC will understand.
See this thread for more info:
- http://www.jboss.org/index.html?module=bb&op=viewtopic&t=130527

[dmlloyd]

OK, I'm going with #1 for now. What about composite metadata objects though? For example I'd have a RemotingMetaData that contains EndpointMetaDatas. Should the nested MetaData objects implement BeanMetaDataFactory as well? Or, should just my "outermost" metadata class implement the interface, and produce BeanMetaData for all the nested items as a flat list?

[dmlloyd]

Of course now that I think of it, I'd like other deployers to be able to produce metadata instances for the various Remoting entites, so that deployments can be dynamically created - I guess that implies that each metadata type that can produce a bean or beans ought to implement BeanMetaDataFactory.

I guess in this case my "outer" metadata unit is just a "holder" for the different types of actual metadata. In this case I guess I won't implement BeanMetaDataFactory on it, but rather on each metadata class that translates into beans.

[alesj]

I guess in this case my "outer" metadata unit is just a "holder" for the different types of actual metadata. In this case I guess I won't implement BeanMetaDataFactory on it, but rather on each metadata class that translates into beans.

Your top element/metadata must implement BMDF, since that is how AbstractKernelDeployment is able to understand what you've put as any element:

 @XmlElements
 ({
 @XmlElement(name="bean", type=AbstractBeanMetaData.class),
 @XmlElement(name="beanfactory", type=GenericBeanFactoryMetaData.class),
 @XmlElement(name="lazy", type=AbstractLazyMetaData.class)
 })
 @XmlAnyElement
 public void setBeanFactories(List<BeanMetaDataFactory> beanFactories)
 {
 this.beanFactories = beanFactories;
 flushJBossObjectCache();
 }

What you do in that method, how you get the beanmetadatas, is up to you.

[alesj]

"alesj" wrote:

Use both of previous Adrian's suggestions.

This is now done - in deployers trunk.
See SchemaResolverXBTestCase for the usage.

Adrian, are the class/files locations OK?

[dmlloyd]

I tried this out using jboss-deployers from trunk:

<?xml version="1.0" encoding="UTF-8"?>
<!--
 JBoss Remoting Deployer
-->

<deployment xmlns="urn:jboss:bean-deployer:2.0">
 <bean name="RemotingMetaDataParser" class="org.jboss.deployers.vfs.spi.deployer.SchemaResolverDeployer">
 <constructor>
 <parameter>org.jboss.cx.remoting.metadata.RemotingMetaData</parameter>
 </constructor>
 <property name="name">jboss-remoting.xml</property>
 <property name="registerWithJBossXB">true</property>
 <!-- TODO - build management info from annotations -->
 </bean>
</deployment>

It accepts the new property but it doesn't seem to notice the jboss-remoting.xml file which is in the same place as the jboss-beans.xml that contains the above.

To verify that it's finding my jboss-beans.xml, I tried changing "true" to "banana" and it blew up as expected. :-)

I'm just using a StandaloneBootstrap with Beta11, using the deployer jars I built from trunk.