Chapter 5 MDB Component

Contract
5.1 Overview
5.2 Goals
5.3 Client View of a MDB
5.4 Protocol Between a MDB Instance and its Container
5.4.1 Required MessageDrivenBean Metadata
5.4.2 The Required Message Listener Interface
5.4.3 Dependency Injection
5.4.4 The MessageDrivenContext Interface
5.4.5 MDB Lifecycle Callback Interceptor Methods
5.4.6 The Optional MessageDrivenBean Interface
5.4.7 Timeout Callbacks
5.4.8 MDB Creation
5.4.9 Message Listener Interceptor Methods for Message-Driven Beans
5.4.10 Serializing Message-Driven Bean Methods
5.4.11 Concurrency of Message Processing
5.4.12 Transaction Context of Message-Driven Bean Methods
5.4.13 Security Context of Message-Driven Bean Methods
5.4.14 Activation Configuration Properties
5.4.15 Message Acknowledgment for JMS Message-Driven Beans
5.4.16 Message Selectors for JMS Message-Driven Beans
5.4.17 Association of a Message-Driven Bean with a Destination or
Endpoint
5.4.17.1 JMS MDBs
5.4.18 Dealing with Exceptions
5.4.19 Missed PreDestroy Callbacks
5.4.20 Replying to a JMS Message
5.5 MDB State Diagram
5.5.1 Operations Allowed in the Methods of a MDB Class
5.6 The Responsibilities of the Bean Provider
5.6.1 Classes and Interfaces
5.6.2 MDB Class
5.6.3 MDB Superclasses
5.6.4 Message Listener Method
5.6.5 Lifecycle Callback Interceptor Methods
5.7 The Responsibilities of the Container Provider
5.7.1 Generation of Implementation Classes
5.7.2 Deployment of JMS Message-Driven Beans
5.7.3 Request/Response Messaging Types
5.7.4 Non-reentrant Instances

5.7.5 Transaction Scoping, Security, Exceptions

Este captulo especifica o contrato entre um MDB e seu container. Ele define
o ciclo de vida das instncias MDB.
Este captulo define vista do desenvolvedor de gerenciamento de estado
MDB e responsabilidade do continer para gerenciar estado MDB.

5.1 Viso Geral

Um MDB um consumidor de msgs assncronas. Um MDB invocado pelo
container, como resultado da chegada de uma msg no destino ou endpoint
que atendido pelo MDB. A instncia de bean acionado por msgs uma
instncia de uma classe MDB. Um MDB definido para um nico tipo de
msgs, de acordo com a message listener interface que emprega.
Para um cliente, um MDB um consumidor de msgs que implementa
alguma lgica de negcios em execuo no servidor. Um cliente acessa um
MDB, enviando msgs para o destino ou endpoint para o qual a classe MDB
o ouvinte msg.
MDB so annimas. Eles no tm identidade visvel ao cliente.
instncias de MDB no tm estado conversacional. Isto significa que todas
as instncias de bean so equivalentes quando eles no esto envolvidos na
manuteno de uma msg do cliente.
Uma instncia de MDB criada pelo continer para lidar com o
processamento das msg para as quais o MDB o consumidor. A sua vida til
controlada pelo container.
Uma instncia de MDB no tem estado para um cliente especfico. No
entanto, as variveis de instncia da instncia de MDB pode conter o estado
entre a manipulao de msgs do cliente. Exemplos de tal estado incluem
uma conexo de bd aberto e uma referncia a um EB.

5.2 Goals
O objetivo do modelo de MDB fazer com que o desenvolvimento de um EB
que so invocados de forma assincrona para manipular o processamento de
msgs recebidas sejam to simples como desenvolver a mesma
funcionalidade em qualquer outro msg listener.
Um outro objetivo do modelo de MDB permitir o processamento
simultneo de um fluxo de msgs por meio de pooling fornecido pelo
container de instncias MDB.

5.3 Client View de um MDB

Para um cliente, um MDB simplesmente um consumidor msg. O cliente
envia mensagens para o destino ou ponto de extremidade para o qual o
MDB o ouvinte de mensagem da mesma forma que faria para qualquer

outro destino ou ponto de extremidade. O bean acionado por msg, como um

consumidor msg, lida com o processamento das msgs.

Do ponto de view client, a existncia de um MDB completamente

escondido atrs do destino ou ponto de extremidade para o qual o MDB o
msg listener. O diagrama a seguir ilustra a viso de que fornecida aos
clientes de um MDB.

A clients JNDI name space pode ser configurado para incluir os destinos
ou pontos finais de MDBs instalados em vrios containers EJB localizados em
vrias mquinas em uma rede. Os locais reais de um EB e container EJB so,
em geral, transparente para o cliente usando o EB.
As referncias aos destinos de msgs pode ser injetado, ou eles podem ser
consultados no namespace JNDI do cliente.
Por exemplo, a referncia para a fila para um MDB JMS pode ser injetado
como segue.
@Resource Queue stockInfo Queue;

Alternatively, the queue for the StockInfo JMS message-driven bean might
be located using the following code segment:
Context initialContext = new InitialContext();
Queue stockInfoQueue
=(javax.jms.Queue)initialContext.lookup(java:comp/env/jms/stockInfoQueue);

The remainder of this section describes the message-driven bean life cycle
in detail and the protocol between the message-driven bean and its
container.

5.4 Protocolo entre um MDB Instncia e seu

container
Desde a sua criao at a destruio, uma instncia de MDB vive em um
container. O container fornece a segurana, a simultaneidade, transaes e
outros servios para o MDB. O continer gerencia o ciclo de vida das
instncias MDB, notificam os casos em que pode haver uma ao de bean
necessrio, e fornecendo uma gama completa de servios para garantir que
a implementao do MDB seja seja escalvel e possa suportar o
processamento simultneo de um grande nmero de msgs.
Do ponto de vista Fornecedores Bean, um MDB existe enquanto seu
container faz. responsabilidade do recipiente garantir que o MDB passa a
existir quando o recipiente iniciado e que as instncias do bean est
pronto para receber uma entrega de msgs assncrona antes da entrega de
mensagens iniciado.
Containers prprios no fazem demandas de servio reais sobre as
instncias de MDB. As chamadas de um container faz em uma instncia de
bean fornecer-lhe o acesso aos servios de contineres e entregar
notificaes emitidas pelo continer.
Uma vez que todas as instncias de um MDB so equivalentes, uma msg do
cliente pode ser entregue a qualquer instncia disponvel.

5.4.1 Required MDB Metadata

Um MDB deve ser anotado com a anotao MessageDriven ou indicado no
D.D como um MDB.

5.4.2 The Required Message Listener Interface

A classe MDB deve implementar a MessageListener Interface apropriado para
o tipo de msgs que o MDB suporta ou especificar a interface de msg de
ouvinte usando o anotao MessageDriven ou elemento messaging-type no
D.D
Message Listener Interface especfica que implementado por uma classe MDB distingue o
tipo de msgs que o MDB suporta. A implementao da classe MDB da interface
javax.jms.MessageListener distingue o MDB como um bean controlado por mensagem JMS.

message listener method do bean (por exemplo, onMessage no caso de

javax.jms.MessageListener) chamado pelo continer quando chega uma
msg para o bean para o servio. O message listener method contm a
lgica de negcios que manipula o processamento da msg.

Message Listener Interface de um bean pode definir mais de um mtodo de ouvinte

msg. Se a interface de msgs ouvinte contm mais do que um mtodo, que o adaptador de
recursos que determina qual o mtodo chamado. Veja [15].

Se a classe de MDB implementa +de1 interface diferente

java.io.Serializable, java.io.Externalizable, ou qualquer uma das interfaces
definidas pelo pacote javax.ejb, a interface de message listener deve ser
especificado pela Interface messageListener elemento da anotao
MessageDriven ou o message type do elemento message-driven no D.D

5.4.3 Dependency Injection

Um MDB pode utilizar mecanismos de injeo de dependncia para adquirir
referncias a recursos ou outros objetos em seu ambiente (ver Captulo 16,
"EB Ambiente"). Se um MDB faz uso de injeo de dependncia, o container
injeta essas referncias aps a instncia de bean ser criada, e antes de
quaisquer mtodos mensagem-ouvinte serem invocados na instncia do
bean. Se uma dependncia no MessageDrivenContext declarada, ou se a
classe de bean implementa a interface MessageDrivenBean opcional (ver
seco 5.4.6), o MessageDrivenContext tambm injectado no momento.
Se a injeo de dependncia falhar, a instncia de bean descartada.

Sob o EJB 3.x API, a classe de bean pode adquirir a interface

MessageDrivenContext atravs de injeo de dependncia, sem ter que
implementar a interface MessageDrivenBean. Neste caso, a anotao de
recursos (ou resource-env-ref implantao elemento descritor) usado para
indicar a dependncia do bean na MessageDrivenContext. Veja o Captulo
16, "EB Ambiente".

5.4.4 A Interface MessageDrivenContext

Se o bean especifica uma dependncia na interface MessageDrivenContext (ou
se a classe bean implementa a interface MessageDrivenBean), o container
deve fornecer a instncia MDB com um MessageDrivenContext. Isto d
acesso instncia de MDB o contexto da instncia mantida pelo continer.
A interface MessageDrivenContext tem os seguintes mtodos:
O mtodo setRollbackOnly permite que a instncia marcar a transao atual
de modo que o nico resultado da transao de uma reverso. Somente
instncias de um MDB com demarcao de CMT pode usar esse mtodo.
O mtodo getRollbackOnly permite que a instncia testar se a transao
atual foi marcada para reverso. Somente instncias de um MDB com
demarcao de CMT pode usar esse mtodo.
O mtodo getUserTransaction retorna a interface
javax.transaction.UserTransaction que a instncia pode usar para demarcar
transaes e obter status da transao. Somente instncias de um MDB
com demarcao de BMT pode usar esse mtodo.
O mtodo getTimerService devolve a interface javax.ejb.TimerService.

 O mtodo getCallerPrincipal retorna java.security.Principal que est

associado com a chamada.
O mtodo isCallerInRole herdado da interface de EJBContext.
O obter mtodos EJBLocalHome getEJBHome e so herdadas a partir da
interface EJBContext. instncias Bean controlado por mensagem no deve
chamar esses mtodos.
O mtodo de lookup permite que o MDB para procurar as respectivas
entradas de ambiente no contexto JNDI de nomeao.
O mtodo getContextData permite um mtodo de negcio, o mtodo de
retorno de chamada do ciclo de vida, ou mtodo de tempo limite para
recuperar qualquer contexto interceptores / webservices associada sua
invocao.

5.4.5 MDB Lifecycle Callback Interceptor Methods

Os seguintes lifecycle event callbacks so suportados para MDBs. mtodos
de retorno de chamada pode ser definida diretamente na classe de bean ou
em uma classe separada interceptor [27]. Consulte a Seo 5.6.5.
PostConstruct
PreDestroy
O retorno de chamada PostConstruct ocorre antes da primeira chamada de
mtodo mensagem ouvinte sobre o bean. Este um ponto de injeco, aps
o que qualquer dependncia foi realizada pelo recipiente.
O mtodo de Lifecycle Callback Interceptor PostConstruct executa em um
contexto de transao e segurana no especificada.
O retorno de chamada PreDestroy ocorre no momento em que o bean
removida da pool ou destrudo.
O Lifecycle Callback Interceptor Methods PreDestroy executa em um
contexto de transao e segurana no especificada.

5.4.6 O Opcional MessageDrivenBean interface

A classe MDB no necessrio para implementar a interface
javax.ejb.MessageDrivenBean.

Compatibilidade Nota: A interface MessageDrivenBean foi exigido por

verses anteriores da especificao Enterprise JavaBeans. Em 3.x EJB, a
funcionalidade fornecida anteriormente pela interface MessageDrivenBean
est disponvel para a classe de bean atravs da utilizao selectiva de
injeo de dependncia (do MessageDrivenContext) e os mtodos de ciclo
de vida de retorno de chamada opcionais.

A interface MessageDrivenBean define dois mtodos,

setMessageDrivenContext e ejbRemove.

O mtodo setMessageDrivenContext chamado pelo continer do bean para

associar uma instncia de MDB com o seu contexto mantido pelo recipiente.
Normalmente, uma instncia de MDB mantm seu contexto controlado por
msg como parte de seu estado.

Os sinais de notificao ejbRemove que a instncia est em vias de ser

removido pelo continer. No mtodo ejbRemove, a instncia libera os
recursos que ele est segurando.

Sob o EJB 3.x API, a classe de bean pode, opcionalmente, definir um mtodo
PreDestroy callback para notificao de remoo do continer da instncia
de bean.

Esta especificao requer que o ejbRemove e os mtodos ejbCreate de um

MDB de ser tratado como os mtodos de retorno de chamada do ciclo de
vida PreDestroy e PostConstruct, respectivamente. Se o MDB implementa a
interface MessageDrivenBean, a anotao PreDestroy s pode ser aplicada
ao mtodo ejbRemove. Requisitos semelhantes aplicam-se utilizao de
implantao metadados descritor como uma alternativa ao uso de
anotaes.

5.4.7 Timeout Callbacks

Um bean acionado por msgs pode ser registrado com o servio de timer EJB
para notificaes de eventos baseados em tempo. O container invoca o
mtodo do tempo limite de retorno de chamada instncia de bean
apropriado quando um temporizador para o bean expirou. Consulte o
Captulo 18, "Servio de Timer".

5.4.8 Criao Message-Driven Bean

O container cria uma instncia de um MDB em 3 etapas. Primeiro, o
continer chama a classe bean "mtodo newInstance para criar uma nova
instncia de MDB. Em segundo lugar, o container injeta
MessageDrivenContext do bean, se for o caso, e executa qualquer outra
injeo de dependncia, conforme especificado pelo anotaes de
metadados sobre a classe bean ou pelo D.D. Em terceiro lugar, o continer
chama mtodos de ciclo de vida PostConstruct chamada de retorno da
instncia, se houver. Consulte a Seo 5.6.5.

Nota de compatibilidade: EJB 2.1 exigida a classe MDB para implementar o

mtodo ejbCreate. Este requisito foi removido em EJB 3.x. Se a classe MDB
implementa o mtodo ejbCreate, o mtodo ejbCreate tratado como
mtodo PostConstruct do bean, e a anotao PostConstruct s pode ser
aplicada com o mtodo ejbCreate.

5.4.9 Message Listener Interceptor Methods for MessageDriven Beans

Os mtodos mtodo de negcio interceptores AroundInvoke so suportados
para MDB.
Estes mtodos interceptadores podem ser definidos na classe de bean ou
em uma classe interceptor e aplicam-se a manipulao da invocao do
mtodo mensagem ouvinte do bean (s). Interceptores so descritos no
Captulo 12, "interceptadores".

5.4.10 Serializing Message-Driven Bean Methods

O recipiente serializa chamadas para cada instncia bean controlado por
mensagem.. A maioria dos containers ir apoiar muitas instncias de um
MDB de executar simultaneamente; no entanto, cada instncia s v uma
sequncia serializada de chamadas de mtodo. Portanto, um MDB no tem
de ser codificada como reentrada.
O container deve serializar todos os retornos de chamada invocado por
continer (por exemplo, ciclo de vida mtodos de retorno de interceptores e
mtodos de tempo limite de retorno de chamada), e deve serializar esses
retornos de chamada com as chamadas de mtodo mensagem ouvinte.

5.4.11 simultaneidade do processamento de mensagem

Um container permite que muitas instncias de uma classe MDB sejam
executadas simultaneamente, permitindo assim o processamento
simultneo de um fluxo de mensagens. No h garantias quanto ordem
exata em que as msgs so entregues para as instncias da classe MDB,
embora o container deve tentar entregar msgs em ordem quando no
prejudicar a simultaneidade do processamento de msg. MDB devem,
portanto, estar preparado para lidar com msgs que esto fora de seqncia:
por exemplo, a msg para cancelar uma reserva pode ser entregue antes da
msg para fazer a reserva.

5.4.12 Transaction Context of MDB Methods

A beans message listener and timeout callback methods so invocados no
mbito de uma operao determinada pelo atributo de transao especificado
em anotaes de metadados do bean ou D.D. Se o bean especificado
como a utilizao de contentores conseguiu a demarcao da transao, ou
o REQUIRED ou o NOT_SUPPORTED deve ser usado para os message
listener methods, e a REQUIRED, REQUIRES_NEW ou o NOT_SUPPORTED

para os timeout callback methods. Veja o Captulo 13, "Suporte para

Transaes"
Quando um MDB usando demarcao de BMT usa a interface
javax.transaction.UserTransaction para demarcar transaes, o recibo msg
que faz com que o bean ser chamado no faz parte da transao. Se o
recebimento da mensagem faz parte da transao, a demarcao da CMT
com o atributo de transao REQUIRED deve ser utilizado.

O mtodo newInstance, setMessageDrivenContext, mtodos de injeo de

dependncia do MDB e mtodos de ciclo de vida de retorno de chamada so
chamados com um contexto de transao no especificado. Consulte a
subseco 13.6.5 para saber como o recipiente executa mtodos com um
contexto de transao no especificado.

5.4.13 Contexto de Segurana de Mtodos MDB

Um caller principal pode propagar para message listener methods de um
MDB. Se isso ocorre uma funo da interface de mensagem-ouvinte
especfico e provedor de msgs associado, mas no regido por esta
especificao.

O Provedor de bean pode usar a anotao RunAs metadados (ou

implantao correspondente elemento descritor) para definir um run-as de
identidade para o EB. O RunAs a identidade se aplica a message listener
methods do bean e mtodos de tempo de espera. RunAs o comportamento
de identidade so tambm definidas no captulo Segurana na Seo
17.3.4.1.

5.4.14 Propriedades de configurao de ativao

O Bean Provider pode fornecer informaes ao Deployer sobre a
configurao do MDB no seu ambiente operacional. Isso pode incluir
informaes sobre os modos de reconhecimento de mensagens, seletores
de mensagem, destino esperado ou tipos de endpoint, etc.
propriedades de configurao de ativao so especificados por meio do
elemento activationConfig da anotao MessageDriven ou activation-config
no D.D.
propriedades de configurao de ativao especificadas no D.D so
adicionados aos especificados por meio da anotao MessageDriven. Se
uma propriedade com o mesmo nome especificado em ambos, o valor do
D.D substitui o valor especificado nas propriedades de configurao
annotation.Activation para JMS MDB so descritas nas seces 5.4.15
atravs 5.4.17.

5.4.15 mensagem de confirmao para JMS MDB

JMS MDB no deve tentar usar a API JMS para a msg de confirmao.
reconhecimento mensagem manipulada pelo continer. Se o MDB usa
demarcao de CMT, mensagem de confirmao feita automaticamente
como parte da transao de submisso. Se demarcao de BMT usado, o
recebimento da msg no pode ser parte da BMT, e, neste caso, o recibo
reconhecido pelo continer. Se demarcao de BMT usado, o Provedor de
beab pode indicar se a semntica JMS AUTO_ACKNOWLEDGE ou semntica
DUPS_OK_ACKNOWLEDGE deve aplicar-se utilizando o elemento
activationConfig da anotao MessageDriven ou usando a activation-configproperty do D.D. O nome da propriedade utilizada para especificar o modo
de reconhecimento acknowledgeMode. Se a propriedade
acknowledgeMode no for especificado, a semntica JMS
AUTO_ACKNOWLEDGE so assumidas. O valor da propriedade
acknowledgeMode deve ser ou o reconhecimento automtico ou Dups okreconhecemos para um bean controlado por mensagem JMS.

5.4.16 Seletores de mensagens para JMS MDB

O Provedor de Bean pode declarar o seletor de msg JMS a ser usado na
determinao de quais msgs de um MDB JMS receber. Se o Provedor de
bean pretende restringir as msgs que um MDB JMS recebe, o Provedor de
bean pode especificar o valor do seletor de msg usando o elemento
activationConfig da anotao MessageDriven ou usando a ativao-configpropriedade do elemento D.D . O nome da propriedade utilizada para
especificar o seletor de msg messageSelector.

For example:
@MessageDriven(activationConfig={
@ActivationConfigProperty(propertyName=messageSelector,
propertyValue=JMSType = car AND color = blue and weight > 2500)})
<activation-config>
<activation-config-property>
<activation-config-property-name>messageSelector</activationcon-fig-property-name>

<activation-config-property-value>JMSType = car AND color =

blue
AND weight &gt; 2500</activation-config-property-value>
</activation-config-property>
</activation-config>

O montador de aplicativos podem ainda restringir, mas no substituir, o

valor da propriedade messageSelector de um MDB JMS.

5.4.17 Associao de um MDB com um destino ou Endpoint

Um MDB est associada a um destino ou endpoint quando o bean
implantado no container. da responsabilidade do Deployer associar o MDB
com um destino ou endpoint

5.4.17.1 JMS MDB

Um MDB JMS associado com um Destino JMS (Fila ou Tpico) quando o
bean implantado no container. da responsabilidade do Deployer associar
o MDB com uma fila ou tpico.