JBoss.org Community Documentation
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.
<incallback> is an abbreviation of installCallback and <uncallback> is an abbreviation of uninstallCallback.
public class Example {
@Install
public void addEditor(Editor editor) {
...
}
@Uninstall
public void removeEditor(Editor editor) {
...
}
}
<bean name="editorHolder" class="com.acme.Example">
<incallback method="addEditor"/>
<uncallback method="removeEditor"/>
</bean>
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 signature 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.
public class Example {
public void addEditor(Editor editor) {
...
}
@Install
public void addEditor(DifferentEditor editor) {
...
}
}
<bean name="editorHolder" class="com.acme.Example">
<incallback method="addEditor" signature="org.jboss.example.DifferentEditor"/>
</bean>
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.
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) {
...
}
}
<bean name="editorHolder" class="com.acme.Example">
<incallback method="addEditor"/>
<incallback method="addViewer"/>
<uncallback method="removeEditor"/>
<uncallback method="removeViewer"/>
</bean>
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 dependentState/state attribute.
public class Example {
@Install(dependentState="Configured")
public void addEditor(Editor editor) {
...
}
}
<bean name="editorHolder" class="com.acme.Example">
<incallback method="addEditor" state="Configured"/>
</bean>
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.
It is also possible to configure when the callback methods are executed during the deployment of the bean using the whenRequired attribute.
public class Example {
@Install(whenRequired="Installed")
public void addEditor(Editor editor) {
...
}
}
<bean name="editorHolder" class="com.acme.Example">
<incallback method="addEditor" whenRequired="Installed"/>
</bean>
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.
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 cardinality attribute.
public class Example {
@Install(cardinality="2..n")
public void addEditor(Editor editor) {
...
}
}
<bean name="editorHolder" class="com.acme.Example">
<incallback method="addEditor" cardinality="2..n"/>
</bean>
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.
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 BasicCollectionCallbackItemFactory implementation. You can change this if required by setting the org.jboss.dependency.collectionCallbackItemFactory system property to the fully-qualified class name of your CollectionCallbackItemFactory implementation.