[jboss-cvs] JBossAS SVN: r68411 - projects/microcontainer/trunk/docs/User_Guide/src/main/docbook.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Dec 19 06:51:15 EST 2007
Author: newtonm
Date: 2007-12-19 06:51:15 -0500 (Wed, 19 Dec 2007)
New Revision: 68411
Modified:
projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
Log:
Added first 2 secions of Adding deployment behaviour chapter.
Modified: projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml
===================================================================
--- projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-19 11:42:57 UTC (rev 68410)
+++ projects/microcontainer/trunk/docs/User_Guide/src/main/docbook/User_Guide.xml 2007-12-19 11:51:15 UTC (rev 68411)
@@ -2384,9 +2384,178 @@
<title>Adding deployment behaviour</title>
<section>
<title>Deployment actions</title>
+ <para>In Part I - Getting Started we covered how to add behaviour to beans during the deployment and undeployment process using AOP lifecycle callbacks. This gave us a powerful way to apply common logic to a number of beans, identified using pointcut expressions, at various points in their lifecycles. However setting up AOP lifecycle callbacks for occasions when an individual bean needs to call arbitrary methods before deployment or after undeployment can be time consuming. Fortunately JBoss Microcontainer provides an alternative way to do this using deployment/undeployment actions specified with annotations or a deployment descriptor.</para>
+ <para>To specify a method within a bean that should be called after the bean reaches the START state you should use the @InstallMethod annotation or <install> element as follows:</para>
+ <programlisting>@InstallMethod
+public String doSomething() {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <install method="doSomething"/>
+</bean></programlisting>
+ <para>Parameters can also be passed in using nested <parameter> elements or by defining values with annotations.</para>
+ <programlisting>@InstallMethod
+public String doSomething(@StringValue("10") Integer integer, @StringValue("my string") String string) {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <install method="doSomething">
+ <parameter>10</parameter>
+ <parameter>my string</parameter>
+ </install>
+</bean></programlisting>
+ <para>If necessary multiple install methods can be defined. They will be called in the order in which they appear as annotations or in the deployment descriptor.</para>
+ <programlisting>@InstallMethod
+public String doSomething() {
+ ...
+}
+
+ at InstallMethod
+public String doSomethingElse() {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <install method="doSomething"/>
+ <install method="doSomethingElse"/>
+</bean></programlisting>
+ <para>During undeployment uninstall methods can also be defined which will be called before the bean reaches the STOP state.</para>
+ <programlisting>@UninstallMethod
+public String doSomething() {
+ ...
+}
+
+ at UninstallMethod
+public String doSomethingElse() {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <uninstall method="doSomething"/>
+ <uninstall method="doSomethingElse"/>
+</bean></programlisting>
+ <para>If you want a bean to call a method on another bean during deployment or undeployment then you can use the @ExternalInstalls/@ExternalUninstalls annotations or the <code>bean</code> attribute of the <install>/<uninstall> elements. You can also define parameters to pass in if necessary.</para>
+ <programlisting>@ExternalInstalls(@ExternalInstall(bean="OtherBean", method="doWork")
+ at ExternalUninstalls(@ExternalInstall(bean="OtherBean", method="doBye", parameters="{@Value(string=@StringValue("Goodbye")), at Value(string=@StringValue("Saturday"))}"))
+public class MyBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <install bean="OtherBean" method="doWork"/>
+ <uninstall bean="OtherBean" method="doBye">
+ <parameter name="message">Goodbye</parameter>
+ <parameter name="day">Saturday</parameter>
+ </uninstall>
+</bean></programlisting>
+ <note>
+ <para>Currently both the @ExternalInstalls and @ExternalUninstalls annotations take a list of @ExternalInstall annotations. </para>
+ </note>
+ <para>By default the other bean must have reached the INSTALLED state before its method will be called. This can be changed by using the <code>dependentState</code>/<code>state</code> attribute.</para>
+ <programlisting>@ExternalInstalls(@ExternalInstall(bean="OtherBean", method="doWork", dependentState="Configured")
+public class MyBean {
+ ...
+}</programlisting>
+ <programlisting><bean name="SimpleBean" class="org.jboss.example.SimpleBean">
+ <install bean="OtherBean" method="doWork" state="Configured"/>
+</bean></programlisting>
</section>
<section>
<title>Deployment callbacks</title>
+ <para>Sometimes it is useful for a bean to know when other beans have been deployed. For example a manager bean might want to keep a list of all of the beans it manages. Rather than placing code into each managed bean to register itself with the manager when deployed, it would be better if the manager was automatically called back each time to notify it. JBoss Microcontainer allows such callbacks to occur during deployment and undeployment using the @Install/@Uninstall annotations and <incallback>/<uncallback> elements.</para>
+ <note>
+ <para><incallback> is an abbreviation of installCallback and <uncallback> is an abbreviation of uninstallCallback.</para>
+ </note>
+ <programlisting>public class Example {
+ @Install
+ public void addEditor(Editor editor) {
+ ...
+ }
+
+ @Uninstall
+ public void removeEditor(Editor editor) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="editorHolder" class="com.acme.Example">
+ <incallback method="addEditor"/>
+ <uncallback method="removeEditor"/>
+</bean> </programlisting>
+ <para>In the above example the addEditor method of the editorHolder bean will be called each time a bean of class Editor is deployed. Similarly the removeEditor method will be called each time a bean of class Editor is undeployed. By default the bean class to look for is determined by the class of the parameter in the callback method. If there are multiple methods with the same name but different parameter types then you can add a <code>signature</code> attribute to the <incallback>/<uncallback> element to specify the correct one. This is not required when using annotations as we simply annotate the method we want.</para>
+ <programlisting>public class Example {
+ public void addEditor(Editor editor) {
+ ...
+ }
+
+ @Install
+ public void addEditor(DifferentEditor editor) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="editorHolder" class="com.acme.Example">
+ <incallback method="addEditor" signature="org.jboss.example.DifferentEditor"/>
+</bean> </programlisting>
+ <para>Multiple callback methods can be defined per bean. They will be called in the order that they appear as annotations or in the deployment descriptor.</para>
+ <programlisting>public class Example {
+ @Install
+ public void addEditor(Editor editor) {
+ ...
+ }
+
+ @Install
+ public void addViewer(Viewer viewer) {
+ ...
+ }
+
+ @Uninstall
+ public void removeEditor(Editor editor) {
+ ...
+ }
+
+ @Uninstall
+ public void removeViewer(Viewer viewer) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="editorHolder" class="com.acme.Example">
+ <incallback method="addEditor"/>
+ <incallback method="addViewer"/>
+ <uncallback method="removeEditor"/>
+ <uncallback method="removeViewer"/>
+</bean> </programlisting>
+ <para>By default each callback will be executed when beans matching the parameter types reach the INSTALLED state. This can be changed if necessary using the <code>dependentState</code>/<code>state</code> attribute.</para>
+ <programlisting>public class Example {
+ @Install(dependentState="Configured")
+ public void addEditor(Editor editor) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="editorHolder" class="com.acme.Example">
+ <incallback method="addEditor" state="Configured"/>
+</bean> </programlisting>
+ <para>Here we are declaring that the addEditor method of the editorHolder bean should be called when any beans of class Editor reach the CONFIGURED state.</para>
+ <para>It is also possible to configure when the callback methods are executed during the deployment of the bean using the <code>whenRequired</code> attribute.</para>
+ <programlisting>public class Example {
+ @Install(whenRequired="Installed")
+ public void addEditor(Editor editor) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="editorHolder" class="com.acme.Example">
+ <incallback method="addEditor" whenRequired="Installed"/>
+</bean> </programlisting>
+ <para>Here we are declaring that the addEditor method will be called before the editorHolder bean reaches the INSTALLED state. By default the callbacks are exceuted before the bean reaches the CONFIGURED state.</para>
+ <para>Finally we can also control when the callback methods are executed depending on how many beans matching the parameter class have been deployed. This is done using the <code>cardinality</code> attribute.</para>
+ <programlisting>public class Example {
+ @Install(cardinality="2..n")
+ public void addEditor(Editor editor) {
+ ...
+ }
+}</programlisting>
+ <programlisting><bean name="editorHolder" class="com.acme.Example">
+ <incallback method="addEditor" cardinality="2..n"/>
+</bean> </programlisting>
+ <para>Here we are declaring that the addEditor method of the editorHolder bean will only be called when two or more beans of class Editor have been deployed.</para>
+ <note>
+ <para>When using callbacks with collection classes as parameters only the following basic interfaces are currently supported; List, Set and Queue. This is done using the <code>BasicCollectionCallbackItemFactory</code> implementation. You can change this if required by setting the <code>org.jboss.dependency.collectionCallbackItemFactory</code> system property to the fully-qualified class name of your <code>CollectionCallbackItemFactory</code> implementation.</para>
+ </note>
</section>
<section>
<title>Service lifecycle</title>
More information about the jboss-cvs-commits
mailing list