| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
 Previous |
 Next |
| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
Previous |
Next |
This chapter describes the various options that you must configure in order to use an EJB 3.0 message-driven bean.
|
Note: In this release, OC4J supports a subset of the functionality specified in the EJB 3.0 public review draft. You may need to make code changes to your EJB 3.0 OC4J application after the EJB 3.0 specification is finalized and OC4J is updated to full EJB 3.0 compliance. For more information, see "Understanding EJB Support in OC4J".There are no OC4J-proprietary EJB 3.0 annotations. For all OC4J-specific configuration, you must still use the EJB 2.1 |
Table 10-1 lists these options and indicates which are basic (applicable to most applications) and which are advanced (applicable to more specialized applications).
For more information, see:
Table 10-1 Configurable Options for an EJB 3.0 Message-Driven Bean
You can configure an EJB 3.0 MDB to use a non-J2CA message service provider using annotations (see "Using Annotations") or deployment XML (see "Using Deployment XML").
For more information, see:
You associate an EJB 3.0 MDB with a message service provider using the @MessageDriven annotation activationConfig attribute.
Example 10-3 shows how to configure a message-driven bean to use a non-J2CA JMS message service provider. It assumes that connection factory jms/MyQCF and queue jms/MyQueue are defined in the jms.xml file. For more information on configuring a non-J2CA message service provider, see "Configuring an OracleAS JMS Message Service Provider" or "Configuring an OJMS Message Service Provider".
Example 10-1 @MessageDriven Annotation for a Non-J2CA Message Service Provider
import javax.ejb.ActivationConfigProperty;
import javax.ejb.MessageDriven;
import javax.jms.Message;
import javax.jms.TextMessage;
import javax.jms.MessageListener;
@MessageDriven(
messageListenerInterface=MessageListener.class,
activationConfig = {
@ActivationConfigProperty(
propertyName="connectionFactoryJndiName", propertyValue="jms/MyQCF"),
@ActivationConfigProperty(
propertyName="destinationName", propertyValue="jms/MyQueue"),
@ActivationConfigProperty(
propertyName="destinationType", propertyValue="javax.jms.Queue"),
@ActivationConfigProperty(
propertyName="messageSelector", propertyValue="RECIPIENT = 'simple_test'")
})
public class QueueMDB implements MessageListener
{
public void onMessage(Message msg)
{
...
}
}
The @MessageDriven annotation activationConfig attribute contains a list of @ActivationConfigProperty annotations whose propertyName and propertyValue attributes you use to specify activation configuration properties. Table 10-2 lists the mandatory and commonly used activation configuration properties you must set.
Table 10-2 Mandatory @ActivationConfigProperty Attributes
| Property Name | Value |
|---|---|
|
The JNDI name of the message service provider connection factory. You define this name when you configure your message service provider. |
|
|
The JNDI name of the message service provider destination name. You define this name when you configure your message service provider |
|
|
Specify the fully qualified class name of the destination type for your message service provider. For a JMS MDB, either |
|
|
Specify the boolean expression of message properties that match the type of message your MDB should receive. |
For a complete list of all activation configuration properties, download and unzip one of the how-to-gjra-with-xxx.zip files from http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html, where xxx is the name of the relevant resource provider. The orion-ejb-jar.xml demo file contains comments describing all activation configuration properties. For more information, see "JMS Resource Adapter" in the Oracle Containers for J2EE Services Guide.
The actual names you use depend on your message service provider installation. For more information, see:
You can associate an EJB 3.0 MDB with a non-J2CA message service provider by configuring the ejb-jar.xml file message-driven element with an activation-config element and orion-ejb-jar.xml file message-driven-deployment element with an activation-config element as you would for an EJB 2.1 MDB. Configuration in the orion-ejb-jar.xml file will override annotations and ejb-jar.xml file configuration.
For more information, see "Using Deployment XML".
You can configure an EJB 3.0 MDB to use a J2CA message service provider using annotations (see "Using Annotations").
For more information, see "J2EE Connector Architecture (J2CA) Adapter Message Provider".
You associate an EJB 3.0 MDB with a J2CA message service provider using the @MessageDriven annotation activationConfig attribute and @MessageDrivenDeployment annotation resourceAdapter attribute. You must use @MessageDrivenDeployment annotation to specify the resource adapter that your message-driven bean uses.
Example 10-3 shows how to configure a message-driven bean to use the Oracle JMS resource adapter named "OracleASjms". It assumes that connection factory OracleASjms/MyQCF is defined in oc4j-ra.xml file and destination name OracleASjms/MyQueue is defined in oc4j-connectors.xml file. For more information on configuring a J2CA message service provider, see "Configuring a Message Service Provider Using J2CA".
Example 10-2 @MessageDriven and @MessageDrivenDeployment Annotation for a J2CA Message Service Provider
import javax.ejb.ActivationConfigProperty;
import javax.ejb.MessageDriven;
import javax.jms.Message;
import javax.jms.MessageListener;
// Oracle deployment annotation for MDB
import oracle.j2ee.ejb.MessageDrivenDeployment;
@MessageDriven(
activationConfig = {
@ActivationConfigProperty(
propertyName="ConnectionFactoryJndiName", propertyValue="OracleASjms/MyQCF"),
@ActivationConfigProperty(
propertyName="DestinationName", propertyValue="OracleASjms/MyQueue"),
@ActivationConfigProperty(
propertyName="DestinationType", propertyValue="javax.jms.Queue"),
@ActivationConfigProperty(
propertyName="messageSelector", propertyValue="RECIPIENT = 'simple_jca_test'")
})
// associate MDB with the resource adapter
@MessageDrivenDeployment(resourceAdapter = "OracleASjms")
public class JCAQueueMDB implements MessageListener
{
public void onMessage(Message msg)
{
...
}
}
The @MessageDriven annotation activationConfig attribute contains a list of @ActivationConfigProperty annotations whose propertyName and propertyValue attributes you use to specify activation configuration properties. Table 10-2 lists the mandatory and commonly used activation configuration properties you must set.
Table 10-3 Mandatory @ActivationConfigProperty Attributes
| Property Name | Value |
|---|---|
|
The JNDI name of the message service provider connection factory. You define this name when you configure your message service provider. |
|
|
The JNDI name of the message service provider destination name. You define this name when you configure your message service provider |
|
|
Specify the fully qualified class name of the destination type for your message service provider. For a JMS MDB, either |
|
|
Specify the boolean expression of message properties that match the type of message your MDB should receive. |
For a complete list of all activation configuration properties, download and unzip one of the how-to-gjra-with-xxx.zip files from http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html, where xxx is the name of the relevant resource provider. The orion-ejb-jar.xml demo file contains comments describing all activation configuration properties. For more information, see "JMS Resource Adapter" in the Oracle Containers for J2EE Services Guide.
You may also set the optional attributes that Table A-3 lists.
The actual names you use depend on your message service provider installation. For more information, see "J2CA Message Service Provider Connection Factory Names".
You can associate an EJB 3.0 MDB with a J2CA message service provider using the orion-ejb-jar.xml file by configuring the message-driven-deployment element with an activation-config element and setting the message-driven-deployment element resource-adapter attribute as you would for an EJB 2.1 MDB. Configuration in the orion-ejb-jar.xml file will override annotations, if present.
For more information, see "Using Deployment XML".
The number of listener threads is an Oracle-specific option that you configure using the EJB 2.1 orion-ejb-jar.xml file.
For more information, see "Configuring Listener Threads".
The maximum delivery count is an Oracle-specific option that you configure using the EJB 2.1 orion-ejb-jar.xml file.
For more information, see "Configuring Maximum Delivery Count".
The dequeue retry count and dequeue retry interval are Oracle-specific options that you configure using the EJB 2.1 orion-ejb-jar.xml file.
For more information, see "Configuring Dequeue Retry Count and Interval".
You can designate one non-business method as the interceptor method for a message-driven bean (see "Using Annotations"). The method must have a signature of:
public Object <MethodName>(InvocationContext) throws Exception
For more information, see "Understanding EJB 3.0 Interceptors".
Example 10-3 shows how to designate a method of a message-driven bean class as an interceptor method using the @AroundInvoke annotation. Each time the onMessage method is invoked, OC4J intercepts the invocation and invokes the interceptor method myInterceptor. The onMessage method invocation proceeds only if the interceptor method returns InvocationContext.proceed().
Example 10-3 @AroundInvoke in an EJB 3.0 Message-Driven Bean
@MessageDriven
public class MessageLogger implements MessageListener
{
@Resource javax.ejb.MessageDrivenContext mc;
public void onMessage(Message message)
{
....
}
@AroundInvoke
public Object myInterceptor(InvocationContext ctx) throws Exception
{
if (!userIsValid(ctx. getEJBContext().getCallerPrincipal()))
{
throw new SecurityException(
"Caller: '" + ctx.getEJBContext().getCallerPrincipal().getName() +
"' does not have permissions for method " + ctx.getMethod()
);
}
return ctx.proceed();
}
}
You can specify an EJB 3.0 message-driven bean class method as a callback method for any of the following lifecycle events (see "Using Annotations"):
Post-construct: a method called before the first message listener method invocation on the bean. This is at a point after which any dependency injection has been performed by the container.
Pre-destroy: a method called at the time the bean is removed from the pool or destroyed.
The message-driven bean class method must have the following signature:
public void <MethodName>()
For more information, see "Callback Methods".
You can specify an EJB 3.0 message-driven bean class method as a lifecycle callback method using any of the following annotations:
Example 10-4 shows how to use the @PostConstruct annotation to specify EJB 3.0 message-driven bean class method initialize as a lifecycle callback method.
