<div><div><div><br></div><div><br></div></div><div>I've committed mc-integration code to exo-kernel mc-int branch. Here are the instructions how to build, and deploy, and a walk through the demo.</div><div><br></div><div>
What exactly does the integration do? It makes it possible to inject components deployed as MC beans into components deployed as exo-kernel services. There is an annotation @InterceptMC, that you annotate your service component with, to turn on mc integration for that component. MC integration only works in JBossAS, so any components that rely on it have to provide alternative injection mechanisms when deployed in Tomcat or somewhere else (i.e. using exo-kernel configuration for injections, or wiring up components manually - hardcoded in a component that does just that).</div>
<div><br></div><div><br></div><div><b>Building</b></div><div><br></div><div>This used to be a multistep process right up until today (there have supposedly been some problems with jboss snapshot repository - artifacts missing even though they should be there). But now all external SNAPSHOT dependencies have been upgraded to release versions, as some releases were done yesterday, so it's now a piece-of-cake to build. </div>
<div><br></div><div>svn co <a href="http://anonsvn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch/">http://anonsvn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch/</a> exo-kernel-mc-int-branch</div><div><br></div>
<div>cd exo-kernel-mc-int-branch</div><div>mvn install</div><div><br></div><div><br></div><div><br></div><div><br></div><div><b>Deploying to GateIn-3.0.0-Beta02 JBoss</b></div><div><br></div><div>You can use gatein/portal/trunk/packaging/pkg to deploy exo-kernel jars:</div>
<div><br></div><div>mvn -Ppkg-jboss package</div><div><br></div><div>There are additional jars required though ...</div><div><br></div><div><br></div><div>These are instructions for deploying manually - as automation of the deployment is not done yet.</div>
<div><br></div><div>Unix:</div><div><br></div><div>#Set env constants we need</div><div>export JBOSS_HOME=<path_to_jboss-gatein-3.0.0-Beta02></div><div>export GATEIN_LIB=$JBOSS_HOME/server/default/deploy/gatein.ear/lib</div>
<div><br></div><div>#Deploy exo-kernel jars - you can do this with packaging/pkg as well</div><div>cp exo.kernel.container/target/exo.kernel.container-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div><div>cp exo.kernel.commons/target/exo.kernel.commons-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div>
<div>cp exo.kernel.component.cache/target/exo.kernel.component.cache-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div><div>cp exo.kernel.component.command/target/exo.kernel.component.command-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div>
<div>cp exo.kernel.component.common/target/exo.kernel.component.common-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div><div>cp exo.kernel.component.remote/target/exo.kernel.component.remote-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div>
<div><br></div><div>#Delete any previous versions:</div><div>rm $GATEIN_LIB/exo.kernel.*-2.2.0-Beta02.jar</div><div><br></div><div>#Copy extra jars needed for MC integration - this part will need automation, so that these are automatically included when building the jboss package</div>
<div>cp org.jboss.mc-kernel-extras/target/mc-kernel-extras-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div><div>cp ~/.m2/repository/org/jboss/mc-int/jboss-mc-int-common/2.2.0.Alpha2/jboss-mc-int-common-2.2.0.Alpha2.jar $GATEIN_LIB</div>
<div>cp ~/.m2/repository/org/jboss/mc-int/jboss-mc-int-servlet/2.2.0.Alpha2/jboss-mc-int-servlet-2.2.0.Alpha2.jar $GATEIN_LIB</div><div><br></div><div><br></div><div><br></div><div>Windows:</div><div><br></div><div>@rem Set env constants we need</div>
<div>set JBOSS_HOME=<path_to_jboss-gatein-3.0.0-Beta02></div><div>set GATEIN_LIB=%JBOSS_HOME%\server\default\deploy\gatein.ear\lib</div><div><br></div><div>@rem Deploy exo-kernel jars - you can do this with packaging\pkg</div>
<div>copy /Y exo.kernel.container\target\exo.kernel.container-2.2.0-Beta04-SNAPSHOT.jar %GATEIN_LIB%</div><div>copy /Y exo.kernel.commons\target\exo.kernel.commons-2.2.0-Beta04-SNAPSHOT.jar %GATEIN_LIB%</div><div>copy /Y exo.kernel.component.cache\target\exo.kernel.component.cache-2.2.0-Beta04-SNAPSHOT.jar %GATEIN_LIB%</div>
<div>copy /Y exo.kernel.component.command\target\exo.kernel.component.command-2.2.0-Beta04-SNAPSHOT.jar %GATEIN_LIB%</div><div>copy /Y exo.kernel.component.common\target\exo.kernel.component.common-2.2.0-Beta04-SNAPSHOT.jar %GATEIN_LIB%</div>
<div>copy /Y exo.kernel.component.remote\target\exo.kernel.component.remote-2.2.0-Beta04-SNAPSHOT.jar %GATEIN_LIB%</div><div><br></div><div>@rem Delete any previous versions:</div><div>del %GATEIN_LIB%\exo.kernel.*-2.2.0-Beta02.jar</div>
<div><br></div><div>@rem Copy extra jars needed for MC integration - this part will need automation, so that these are automatically included when building the jboss package</div><div>copy /Y org.jboss.mc-kernel-extras\target\mc-kernel-extras-2.2.0-Beta04-SNAPSHOT.jar %GATEIN_LIB%</div>
<div>copy /Y %HOMEPATH%\.m2\repository\org\jboss\mc-int\jboss-mc-int-common\2.2.0.Alpha2\jboss-mc-int-common-2.2.0.Alpha2.jar %GATEIN_LIB%</div><div>copy /Y %HOMEPATH%\.m2\repository\org\jboss\mc-int\jboss-mc-int-servlet\2.2.0.Alpha2\jboss-mc-int-servlet-2.2.0.Alpha2.jar %GATEIN_LIB%</div>
<div><br></div><div><br></div><div><br></div><div><br></div><div><b>Deploying to GateIn-3.0.0-Beta02 Tomcat</b></div><div><br></div><div>There is no support for MC integration in Tomcat deployment. No additional jars need to be deployed. Integration code is factored in such a way that in the absence of correct environment (existence of certain classes) it remains dormant - no additional classes are required.</div>
<div><br></div><div>If a component annotated with @InterceptMC is deployed, a warning is logged, but the component will be deployed anyway - without injections being applied.</div><div><br></div><div><br></div><div><br></div>
<div><br></div><div><b>MC Integration Demos</b></div><div><br></div><div>Demos are available in submodule exo.kernel.demos.</div><div><br></div><div><i><br></i></div><div><i>Build and deploy</i></div><div><br></div><div>mvn install</div>
<div>cp exo.kernel.demos/mc-injection/target/exo.mc-int.mc-injection-2.2.0-Beta04-SNAPSHOT.jar $JBOSS_HOME/server/default/deploy/</div><div><br></div><div>(On Windows: </div><div>copy /Y exo.kernel.demos\mc-injection\target\exo.mc-int.mc-injection-2.2.0-Beta04-SNAPSHOT.jar %JBOSS_HOME%\server\default\deploy\</div>
<div>)</div><div><br></div><div><br></div><div>There's one demo at the moment ...</div><div><br></div><div><br></div><div><br></div><div><i>mc-injection demo</i></div><div><br></div><div>This demo demonstrates POJO creation via exo-kernel and use of MC injection annotations to have some services injected into our exo-kernel-deployed POJO by MC.</div>
<div><br></div><div>We have two service objects - InjectedBean and InjectingBean, packaged in a single jar.</div><div><br></div><div>InjectedBeans gets instantiated by JBossAS deployer via META-INF/jboss-beans.xml. InjectingBean on the other hand gets instantiated by exo-kernel via conf/configuration.xml</div>
<div><br></div><div>Exo-kernel knows nothing about InjectedBean, but because InjectingBean is annotated with @InterceptMC it is processed by MC integration logic when instantiated by exo-kernel. The processing pipes it through MC-kernel logic which processes MC-kernel injection annotations, and performs injection of components.</div>
<div><br></div><div>Of course, MC-kernel knows nothing about exo-kernel service objects - it can only inject components deployed through one of jbossas deployers that use MC-kernel to instantiate, or at least register, components.</div>
<div><br></div><div>InjectingBean demonstrates several different ways in which you can perform injection of JBoss services into a component. If instead of using exo-kernel to deploy InjectingBean, you deploy it through JBossAS, these annotations will work just the same - JBossAS uses MC-kernel, and MC-kernel will process the annotations.</div>
<div><br></div><div>There are many annotations used in InjectingBean.java. Apart from @InterceptMC they are all mc-kernel annotations used to configure injections.</div><div><br></div><div>@InterceptMC is introduced by MC integration to mark classes that should be integrated with MC. Through it you can also control if you want to use AOP integration, and what kind of injections you want MC to perform. By default, field injections are disabled by MC-kernel, as they are deemed an anti-pattern for service objects - they may make your code more difficult to maintain in the long run, as you are giving up the ability to intercept the setting-of-the-field.</div>
<div><br></div><div>Service objects instantiated through exo-kernel don't become part of MC-kernel object repository. That means that dependency management can't be performed by MC-kernel, which means that all the dependencies InjectingBean needs have to be fulfilled before MC-kernel first learns about it. Usually MC-kernel makes several passes over the whole deployment (all the deployment archives), first learning about services and their dependencies, then starting up services that have no dependencies first, and services with dependencies later - when their dependencies are fulfilled.</div>
<div><br></div><div>When using MC integration, we need to make sure, that all the dependencies have already been installed before exo-kernel bootstrap happens. This can be done by deploying all jboss beans as .jars containing META-INF/jboss-beans.xml in deploy dir. JBossAS deploys .jars before .wars and .ears.</div>
<div><br></div><div><br></div><div><br></div><div><b>Things to look out for ...</b></div><div><br></div><div>There are several exo-kernel bootstrap points in gatein .ears deployed in GateIn JBossAS distribution:</div><div>
<br></div><div>exo-kernel/exo.kernel.container:</div><div><br></div><div> org.exoplatform.container.web.PortalContainerConfigOwner</div><div> org.exoplatform.container.web.PortalContainerCreator</div><div><br></div><div>
<br></div><div>gatein/portal/trunk/component/web:</div><div><br></div><div> org.exoplatform.web.GenericHttpListener</div><div><br></div><div><br></div><div>Any of these can trigger exo-kernel initialization by triggering a call to RootContainer.getInstance(). MC-integration has to intercept this call at Servlet API level, because it needs some ServletContext attributes. If the call is not intercepted, then MC-integration doesn't work.</div>
<div><br></div><div>At the moment first two classes are modified to perform interception. GenericHttpListener is in gatein portal trunk and I did not modify that one.</div><div><br></div><div>If any gatein-sample ear is present in jboss deploy, as is currently the case, then that one is deployed before gatein.ear. That one uses PortalContainerConfigOwner to trigger exo-kernel initialization, so everything is fine. If gatein-sample ears are removed, then gatein.ear is started first, and that one uses GenericHttpListener to trigger exo-kernel initialization. In that case MC integration won't work - that's until GenericHttpListener is modified to do interception - I should probably make another branch in gatein portal, do that there, then at some point merge in trunk.</div>
<div><br></div><div>I'm also looking into another possible solution that requires no Servlet API level interception.</div><div><br></div><div><br></div><div><br></div><div><b>TODOs</b></div><div><br></div><div>1) I'm looking for a way to add server specific dependencies for packaging the gateIn-jboss distro.</div>
<div><br></div><div>MC integration requires certain extra jars - but only when deployed to JBoss. MC integration is not active when deployed to Tomcat, and is written in a way that everything works without the extra MC integration jars.</div>
<div><br></div><div>Extra jars are the following:</div><div><br></div><div>cp org.jboss.mc-kernel-extras/target/mc-kernel-extras-2.2.0-Beta04-SNAPSHOT.jar $GATEIN_LIB</div><div>cp ~/.m2/repository/org/jboss/mc-int/jboss-mc-int-common/2.2.0.Alpha2/jboss-mc-int-common-2.2.0.Alpha2.jar $GATEIN_LIB</div>
<div>cp ~/.m2/repository/org/jboss/mc-int/jboss-mc-int-servlet/2.2.0.Alpha2/jboss-mc-int-servlet-2.2.0.Alpha2.jar $GATEIN_LIB</div><div><br></div><div>The first one is a module in exo-kernel-mc-int-branch, and contains an mc-kernel class that wasn't there yet in version <a href="http://2.0.6.GA">2.0.6.GA</a> - which is the one that ships with JBossAS 5.1.0. The second two are MC integration jars that don't come with JBossAS 5.1.0 in any version.</div>
<div><br></div><div>These three jars are not needed in Tomcat distribution, so they don't need to be included.</div><div><br></div><div>Normally dependencies are declared in packaging/modules/src/main/javascript/kernel.packaging.module.js, but these are not deployment environment specific. </div>
<div><br></div><div>I've seen some hacks in gatein/portal/trunk/packaging/pkg/target/exopackage/javascript/eXo/server/Jboss.js, but maybe there exists a better way to do this.</div><div><br></div><div><div>2) I'm also looking into testing, and additional demos (AOP demo).</div>
<div><br></div><div>3) There's the already mentioned alternative interception I'm looking into</div></div><div><br></div><div>4) Also, this post is better suited for wiki where it can evolve through time. Which wiki would be the best for this?</div>
<div><br></div><div><br></div><div>If someone is interested in a specific use-case, please let me know, and I'll look into it, do a demo ...</div><div><br></div><div><br></div><div>Cheers,</div><div><br></div><div>- marko</div>
<div><br></div><div><br></div><div><br></div><div><br></div></div>