9:30 a.m.
Author: mstruk
Date: 2009-12-01 10:30:21 -0500 (Tue, 01 Dec 2009)
New Revision: 911
Added:
kernel/branches/mc-int-branch/exo.kernel.mc-int/README.txt
Log:
Added README.txt for a quick start
Added: kernel/branches/mc-int-branch/exo.kernel.mc-int/README.txt
===================================================================
--- kernel/branches/mc-int-branch/exo.kernel.mc-int/README.txt
(rev 0)
+++ kernel/branches/mc-int-branch/exo.kernel.mc-int/README.txt 2009-12-01 15:30:21 UTC
(rev 911)
@@ -0,0 +1,114 @@
+
+
+MC-INTEGRATION QUICK START
+
+
+
+
+== How to use ==
+
+
+MC integration adds two capabilities to exo-kernel. One is JBoss AOP, the other is
support for mc-kernel injections, that can be used to inject mc beans deployed in JBossAS
into exo-kernel deployed service objects. MC integration only works when deployed in
JBossAS5. In Tomcat everything still works, no additional jars are needed, and MC
integration is off.
+
+To enable a component for any of these two capabilities the component must first be
marked with @InterceptMC annotation. A straight-forward way to do this is by putting the
annotation on your service class. See
https://svn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch/exo.ker...
+
+Another way to do this is to apply the annotation to a specific component instance
through mc-int-beans.xml configuration file.
+See
https://svn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch/exo.ker...
+
+Here 'bean' element's 'name' attribute refers to 'component'
element's 'key' attribute in configuration.xml.
+See
https://svn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch/exo.ker...
+
+Annotation configuration in mc-int-beans.xml overrides any compiled annotations on
classes. That means, every instance of the same service class can be specifically targeted
for AOP/Injection, and any existing hardwired class annotation can be nullified through
configuration.
+
+When a component is marked with @InterceptMC annotation it will have its mc-kernel
injection annotations process by mc-kernel, as part of mc-kernel integration. To enable
AOP, @InterceptMC's 'enableAOP' attribute has to be set to true.
+
+When AOP is enabled, a service object will be wrapped into an AOP proxy. To implement and
activate some specific AOP interception, mc-beans.xml configuration file has to be used to
configure AOP interception points and map concrete interceptor classes to them.
+See
https://svn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch/exo.ker...
+
+
+We obviously have to deal with several configuration files here. Let's describe what
each of them is for:
+
+conf/configuration.xml ... that's eXo kernel configuration file, with eXo
configurator specific syntax, used to configure DI performed by eXo kernel when
configuring and instantiating service components. All gatein services are configured
through this.
+
+conf/mc-int-beans.xml ... that's mc-integration configuration file that uses
mc-kernel configuration library to describe annotation overrides. This configuration is
read and applied by mc-integration code.
+This configuration essentially enhances configuration.xml, so even though it looks like
jboss-beans configuration, its function is to additionally describe services in
configuration.xml, and therefore has specific semantics.
+
+conf/mc-beans.xml ... that's mc-kernel configuration file that can be used for
AOP configuration, and mc bean instantiations. It has exactly the same semantics as
jboss-beans.xml, but is not supposed
+to be picked up by JBossAS deployers, because it needs to be applied by mc-integration
code to mc-integration specific mc-kernel controller instance - that's why it's
not called jboss-beans.xml
+
+
+
+
+== Limitations of the current AOP solution ==
+
+
+Because proxy mechanism is used to do AOP, there is a requirement that a class to be
AOP-ed needs to have a public or protected zero-args constructor.
+
+Service objects that make up exo-kernel and gatein mostly use constructor based DI, and
only have constructors that take some injected parameters. In order to make these eligible
for AOP, we would have to make sure they all have a protected zero-args constructor.
+
+Also, when AOP is activated, field injection doesn't work even if it's turned on.
This is again a limitation of proxy mechanism and inability to intercept set-field
operations in java.
+
+As a rule of thumb:
+ - Always put protected or public zero-arg constructor on your service objects
+ - Don't use MC field injections - only use method injections
+
+That way your service object can be AOP-ed without side-effects.
+
+
+
+
+== Trying it out ==
+
+
+(CONSOLE 1 - exo-kernel)
+cd $REPO/exo-jcr/kernel/branches
+svn co https://svn.jboss.org/repos/exo-jcr/kernel/branches/mc-int-branch
+cd mc-int-branch
+mvn install
+
+(CONSOLE 2 - packager)
+cd $REPO/gatein/tools/packager/branches
+svn co https://svn.jboss.org/repos/gatein/tools/packager/branches/mc-integration
+cd mc-integration
+mvn install
+
+(CONSOLE 3 - portal)
+cd $REPO/gatein/portal/branches
+svn co https://svn.jboss.org/repos/gatein/portal/branches/mc-integration
+cd mc-integration
+mvn install -Dmaven.test.skip=true
-Dgatein.checkout.dir=$REPO/gatein/portal/branches/mc-integration
+
+cd packaging/pkg
+
+
+
+FOR JBOSSAS:
+
+ mvn install -Ppkg-jbossas-tests
-Dexo.projects.directory.dependencies=REPLACE_WITH_YOUR_OWN_DIRECTORY
-Dgatein.checkout.dir=$REPO/gatein/portal/branches/mc-integration
+
+ (CONSOLE 4 - run packaged jboss)
+ cd $REPO/gatein/portal/branches/mc-integration/packaging/pkg/target/jboss/bin
+ run
+
+FOR TOMCAT:
+
+ mvn install -Ppkg-tomcat-tests
-Dexo.projects.directory.dependencies=REPLACE_WITH_YOUR_OWN_DIRECTORY
-Dgatein.checkout.dir=$REPO/gatein/portal/branches/mc-integration
+
+ (CONSOLE 4 - run packaged tomcat)
+ cd $REPO/gatein/portal/branches/mc-integration/packaging/pkg/target/tomcat/bin
+ gatein run
+
+
+
+(CONSOLE 1 - run integration tests)
+cd exo.kernel.tests/integration-tests
+mvn -Ptests
+
+If you run your server on non-default IP:port use something like:
+mvn -Ptests -DforkMode=none -Dserver.host=127.0.0.1 -Dserver.port=8000
+
+(Don't forget -DforkMode=none otherwise system properties won't get propagated to
the test class)
+
+
+
+(eof)
\ No newline at end of file