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