[gatein-dev] MC-kernel integration

[Marko Strukelj]

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.

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).


*Building*

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.

svn co http://anonsvn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch/exo-kernel-mc-int-branch

cd exo-kernel-mc-int-branch
mvn install




*Deploying to GateIn-3.0.0-Beta02 JBoss*

You can use gatein/portal/trunk/packaging/pkg to deploy exo-kernel jars:

mvn -Ppkg-jboss package

There are additional jars required though ...


These are instructions for deploying manually - as automation of the
deployment is not done yet.

Unix:

#Set env constants we need
export JBOSS_HOME=<path_to_jboss-gatein-3.0.0-Beta02>
export GATEIN_LIB=$JBOSS_HOME/server/default/deploy/gatein.ear/lib

#Deploy exo-kernel jars - you can do this with packaging/pkg as well
cp
exo.kernel.container/target/exo.kernel.container-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB
cp exo.kernel.commons/target/exo.kernel.commons-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB
cp
exo.kernel.component.cache/target/exo.kernel.component.cache-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB
cp
exo.kernel.component.command/target/exo.kernel.component.command-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB
cp
exo.kernel.component.common/target/exo.kernel.component.common-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB
cp
exo.kernel.component.remote/target/exo.kernel.component.remote-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB

#Delete any previous versions:
rm $GATEIN_LIB/exo.kernel.*-2.2.0-Beta02.jar

#Copy extra jars needed for MC integration - this part will need automation,
so that these are automatically included when building the jboss package
cp
org.jboss.mc-kernel-extras/target/mc-kernel-extras-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB
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
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



Windows:

@rem Set env constants we need
set JBOSS_HOME=<path_to_jboss-gatein-3.0.0-Beta02>
set GATEIN_LIB=%JBOSS_HOME%\server\default\deploy\gatein.ear\lib

@rem Deploy exo-kernel jars - you can do this with packaging\pkg
copy /Y
exo.kernel.container\target\exo.kernel.container-2.2.0-Beta04-SNAPSHOT.jar
%GATEIN_LIB%
copy /Y
exo.kernel.commons\target\exo.kernel.commons-2.2.0-Beta04-SNAPSHOT.jar
%GATEIN_LIB%
copy /Y
exo.kernel.component.cache\target\exo.kernel.component.cache-2.2.0-Beta04-SNAPSHOT.jar
%GATEIN_LIB%
copy /Y
exo.kernel.component.command\target\exo.kernel.component.command-2.2.0-Beta04-SNAPSHOT.jar
%GATEIN_LIB%
copy /Y
exo.kernel.component.common\target\exo.kernel.component.common-2.2.0-Beta04-SNAPSHOT.jar
%GATEIN_LIB%
copy /Y
exo.kernel.component.remote\target\exo.kernel.component.remote-2.2.0-Beta04-SNAPSHOT.jar
%GATEIN_LIB%

@rem Delete any previous versions:
del %GATEIN_LIB%\exo.kernel.*-2.2.0-Beta02.jar

@rem Copy extra jars needed for MC integration - this part will need
automation, so that these are automatically included when building the jboss
package
copy /Y
org.jboss.mc-kernel-extras\target\mc-kernel-extras-2.2.0-Beta04-SNAPSHOT.jar
%GATEIN_LIB%
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%
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%




*Deploying to GateIn-3.0.0-Beta02 Tomcat*

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.

If a component annotated with @InterceptMC is deployed, a warning is logged,
but the component will be deployed anyway - without injections being
applied.




*MC Integration Demos*

Demos are available in submodule exo.kernel.demos.

*
*
*Build and deploy*

mvn install
cp
exo.kernel.demos/mc-injection/target/exo.mc-int.mc-injection-2.2.0-Beta04-SNAPSHOT.jar
$JBOSS_HOME/server/default/deploy/

(On Windows:
copy /Y
exo.kernel.demos\mc-injection\target\exo.mc-int.mc-injection-2.2.0-Beta04-SNAPSHOT.jar
%JBOSS_HOME%\server\default\deploy\
)


There's one demo at the moment ...



*mc-injection demo*

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.

We have two service objects - InjectedBean and InjectingBean, packaged in a
single jar.

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

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.

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.

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.

There are many annotations used in InjectingBean.java. Apart from
@InterceptMC they are all mc-kernel annotations used to configure
injections.

@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.

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.

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.



*Things to look out for ...*

There are several exo-kernel bootstrap points in gatein .ears deployed in
GateIn JBossAS distribution:

exo-kernel/exo.kernel.container:

   org.exoplatform.container.web.PortalContainerConfigOwner
   org.exoplatform.container.web.PortalContainerCreator


gatein/portal/trunk/component/web:

   org.exoplatform.web.GenericHttpListener


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.

At the moment first two classes are modified to perform interception.
GenericHttpListener is in gatein portal trunk and I did not modify that one.

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.

I'm also looking into another possible solution that requires no Servlet API
level interception.



*TODOs*

1) I'm looking for a way to add server specific dependencies for packaging
the gateIn-jboss distro.

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.

Extra jars are the following:

cp
org.jboss.mc-kernel-extras/target/mc-kernel-extras-2.2.0-Beta04-SNAPSHOT.jar
$GATEIN_LIB
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
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

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 2.0.6.GA - 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.

These three jars are not needed in Tomcat distribution, so they don't need
to be included.

Normally dependencies are declared in
packaging/modules/src/main/javascript/kernel.packaging.module.js, but these
are not deployment environment specific.

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.

2) I'm also looking into testing, and additional demos (AOP demo).

3) There's the already mentioned alternative interception I'm looking into

4) Also, this post is better suited for wiki where it can evolve through
time. Which wiki would be the best for this?


If someone is interested in a specific use-case, please let me know, and
I'll look into it, do a demo ...


Cheers,

- marko
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/gatein-dev/attachments/20091117/6223bc9d/attachment.html