Visão Geral de Ligações de Aplicativos EJB 3.0 e EJB 3.1

Antes de iniciar um aplicativo que é instalado em um servidor de aplicativos, todas as referências de Enterprise JavaBeans (EJB) e as referências de recursos definidas no aplicativo deverão estar ligadas aos artefatos reais (enterprise beans ou recursos) definidos no servidor de aplicativos.

Iniciando na Versão 8.0, o suporte de ligações no contêiner EJB foi expandido. O contêiner EJB designa ligações JNDI padrão para interfaces de negócios EJB 3.x com base no nome do aplicativo, no nome do módulo e no nome do componente. Você não tem que definir explicitamente os nomes de ligação JNDI para cada uma das interfaces ou inícios EJB dentro de um módulo EJB 3.x ou visualizações sem interface dentro de um módulo EJB 3.1.

Ao definir ligações, você especifica os nomes de Java™ Naming and Directory Interface (JNDI) para os artefatos referenciáveis e referenciados em um aplicativo. Os valores jndiName especificados para os artefatos devem ser nomes de consulta qualificados.

Você não precisa designar manualmente nomes de ligações JNDI a cada uma das interfaces, inícios EJB ou visualizações sem interface em seus enterprise beans em módulos EJB 3.x. Se você não designar ligações explicitamente, o contêiner de EJB designará ligações padrão.

Namespaces para ligações JNDI EJB padrão

As ligações EJB padrão podem ser substituídas pelo servidor de aplicativos tanto nos conjuntos de namespaces clássicos quanto nos java:[escopo].

O conjunto de namespaces clássicos consiste nos namespaces JNDI ejblocal: e Global. Os namespaces clássicos incluem uma extensão do WebSphere e existem no servidor de aplicativos anteriores à versão 8.0

O conjunto de namespaces java:[escopo] consiste nos namespaces java:global, java:app e java:module. Os namespaces java:[scope] são definidos pela especificação Java EE 6 e são introduzidos no WebSphere Application Server na Versão 8. Eles não são uma substituição para o namespaces clássicos. Em vez disso, eles foram incluídos em adição aos namespaces clássicos.

Detalhes do namespace clássicos

Para o nível EJB 3.x, o produto fornece dois namespaces clássicos distintos para interfaces EJB, dependendo se a interface é local ou remota. A mesma provisão se aplica aos inícios EJB e às visualizações sem interface, que podem ser considerados tipos especiais de interfaces. Existem os seguintes nomes de espaços clássicos a seguir:
  • Namespace ejblocal: com escopo definido na Java virtual machine (JVM)
  • Namespace JNDI global

Interfaces EJB locais, inícios e visualizações sem interface devem estar ligadas a um namespace ejblocal: clássico com escopo definido na JVM. Elas são acessíveis apenas a partir do mesmo processo do servidor de aplicativos.

Em contraste, as interfaces EJB remotas e homes devem ser sempre ligadas ao namespace WebSphere JNDI clássico com escopo definido globalmente; elas podem ser acessadas de qualquer lugar, incluindo outros processos do servidor e outros clientes remotos. As interfaces locais e as visualizações sem interface não podem ser ligadas ao namespace JNDI com escopo definido globalmente clássico, nem as interfaces remotas podem ser ligadas ao namespace ejblocal: clássico com escopo definido na JVM.

Os namespaces ejblocal: clássico e JNDI com escopo definido globalmente clássico são separados e distintos. Por exemplo, uma interface local EJB ou uma visualização sem interface ligada a "ejblocal:AccountHome" não é o mesmo que uma interface remota ligada a "AccountHome" no namespace com escopo definido globalmente clássico. Esse comportamento ajuda a manter a distinção entre as referências de interfaces locais e remotas. Ter um namespace local com escopo definido na JVM também permite que os aplicativos consultem diretamente ou façam referência a interfaces EJB locais e visualizações sem interface a partir de qualquer lugar no processo de servidor da JVM, incluindo nos limites do aplicativo Java Platform, Enterprise Edition (Java EE).

Ligações JNDI Clássicas Padrão para Interfaces de Negócios EJB no Contêiner EJB 3.x Baseado em Nomes de Aplicativo, Módulo e Componente

O contêiner EJB designa ligações JNDI clássicas padrão para interfaces de negócios EJB 3.x com base no nome do aplicativo, nome do módulo e nome do componente, portanto, é importante entender como esses nomes são definidos. Cada um dos nomes é uma cadeia de caracteres.

Aplicativos Java EE são compactados em um formato padronizado chamado arquivo Enterprise Application Archive (EAR). O EAR é um arquivo compactado cujo formato é semelhante ao do arquivo .zip ou .tar, podendo, desse modo, ser visualizado como uma coleta de diretórios e arquivos lógicos compactados em um único arquivo físico. Dentro de cada arquivo EAR estão um ou mais arquivos de módulo Java EE, que podem incluir:
  • Arquivos Java Application Archive (JAR) para módulos EJB, módulos aplicativos clientes Java EE e módulos de classe do utilitário
  • Arquivos Web Application Archive (WAR) para módulos da Web
  • Outros módulos específicos de tecnologia, como arquivos Resource Application Archive (RAR) e outros tipos de módulos
Em cada arquivo de módulo há, normalmente, um ou mais componente Java EE. Exemplos de componentes Java EE são enterprise beans, servlets e classes principais de aplicativos clientes.

Como os módulos Java EE são empacotados dentro de archives do aplicativo Java EE, e os componentes Java EE são, por sua vez, empacotados dentro de módulos Java EE, o "caminho de aninhamento" de cada componente pode ser usado para identificar exclusivamente cada componente dentro de um archive de aplicativo Java EE de acordo com seu nome de aplicativo, nome de módulo e nome de componente.

Nome do aplicativo usado em ligações clássicas

O nome de um aplicativo é definido pelo seguinte (por ordem de prioridade):
  • O valor do nome do aplicativo especificado para o console administrativo do produto ou o parâmetro appname fornecido para a ferramenta de script da linha de comandos wsadmin, durante a instalação do aplicativo no produto.
  • O valor do parâmetro <display-name> no descritor de implementação META-INF/application.xml para o aplicativo.
  • O nome de arquivo EAR, excluindo o sufixo de arquivo .ear. Por exemplo, um arquivo EAR de aplicativo denominado CustomerServiceApp.ear pode ter um nome de aplicativo de "CustomerServiceApp" neste caso.
A especificação do Java EE 6 fornece nomes de consulta do JNDI do EJB da forma geral, java:global[/appName]/moduleName/beanName. O componente appName do nome de consulta é mostrado como opcional pois não se aplica aos beans implementados em módulos independentes. Apenas os beans compactados em arquivos .ear contêm o componente appName no nome de consulta java:global. As regras que determinam o valor de appName são diferentes das regras descritas anteriormente para os nomes de aplicativos. O valor appName no modelo de nome de consulta java:global mostrado anteriormente é definido pelo seguinte, em ordem de prioridade:
  • O valor do parâmetro <application-name> no descritor de implementação application.xml para o aplicativo.
  • O nome de arquivo EAR, excluindo o sufixo de arquivo .ear. Por exemplo, um arquivo EAR de aplicativo denominado CustomerServiceApp.ear tem um nome de aplicativo de "CustomerServiceApp". Se o aplicativo for um módulo independente, o nome de consulta java:global não terá um componente de aplicativo.
O valor de appName é também o limite do valor de sequência do nome, java:app/AppName, de acordo com a especificação do Java EE 6.

Nome do módulo usado em ligações clássicas

O nome de um módulo é definido como o Identificador Uniforme de Recursos (URI) do arquivo de módulo, relativo à raiz do arquivo EAR no qual ele reside. Definido de outra maneira, o nome do módulo é o nome do arquivo do módulo relativo à raiz do arquivo EAR, incluindo os subdiretórios nos quais o arquivo do módulo é aninhado. Essa convenção de nomenclatura continua verdadeira mesmo quando um nome de módulo lógico é especificado explicitamente usando o elemento module-name no descritor de implementação.

No exemplo a seguir, o aplicativo "CustomerServiceApp" contém três módulos cujos nomes são AccountProcessing.jar, Utility/FinanceUtils.jar e AppPresentation.war:
CustomerServiceApp.ear:AccountProcessing.jar
com/mycompany/AccountProcessingServiceBean.class AccountProcessingService.class
Utility/FinanceUtils.jar META-INF/ejb-jar.xml
com/mycompany/InterestCalculatorServiceBean.class InterestCalculatorService.class
AppPresentation.war META-INF/web.xml  
A especificação do Java EE 6 fornece nomes de consulta do JNDI do EJB da forma geral, java:global[/appName]/moduleName/beanName. O componente appName do nome de consulta é mostrado como opcional pois não se aplica aos beans implementados em módulos independentes. Apenas os beans compactados nos arquivos .ear contêm o componente appName no nome da consulta java:global. Outra variante do nome de consulta do JNDI que inclui o nome do módulo é java:app/moduleName/beanName. O valor de moduleName não é o URI do módulo. O valor moduleName nos modelos de nomes de consulta java:global e java:app é definido pelo seguinte, em ordem de prioridade:
  • O valor do parâmetro <module-name> no descritor de implementação ejb-jar.xml ou web.xml para o módulo.
  • A URI do módulo, excluindo seu sufixo .jar ou .war. Por exemplo, um módulo com uma URI de CustomerService.jar ou CustomerService.war tem um nome de módulo de "CustomerService".
O valor de moduleName é também o limite do valor de sequência do nome, java:module/moduleName, de acordo com a especificação do Java EE 6. Isso também se aplica aos módulos do cliente. Para módulos do cliente, o parâmetro <module-name> é localizado no arquivo descritor de implementação application-client.xml.

Nome do componente EJB usado em ligações clássicas

O nome de um componente EJB é definido pelo seguinte valor, em ordem de prioridade:
  • O valor da tag ejb-name associado ao bean no descritor de implementação ejb-jar.xml, se presente.
  • O valor do parâmetro "name", se presente, na anotação @Stateless ou @Stateful, associado ao bean.
  • O nome da classe de implementação do bean, sem nenhum qualificador do nível do pacote.

Ligações clássicas padrão para interfaces de negócios EJB, inícios e visualizações sem interface

Você não precisa definir explicitamente nomes de ligação JNDI para cada uma das interfaces ou EJB homes dentro de um módulo EJB 3.x ou visualizações sem interface dentro de um módulo EJB 3.1. Se você não designar ligações explicitamente, o contêiner de EJB do produto designará ligações clássicas padrão usando as regras descritas aqui. Isto é diferente do suporte EJB no produto anterior à especificação de EJB 3.0 que está sendo suportada.

O contêiner EJB executa duas ligações clássicas padrão para cada visualização de interface (negócios, início remoto ou início local) ou sem interface em cada enterprise bean. Estas duas ligações clássicas são mencionadas aqui como as visualizações da ligação curta e da ligação longa da interface ou sem interface. A ligação curta usa apenas o nome de classe do Java qualificado pelo pacote da interface ou visualização de não interface, enquanto a ligação longa usa o ID de componente do enterprise bean como um qualificador extra antes do nome de classe da interface qualificada pelo pacote ou visualização de não interface, com um símbolo de hash ou numérico (símbolo #) entre o ID de componente e o nome de classe da interface ou visualização de não interface. É possível pensar na diferença entre as duas formas como sendo análogas a um nome do host TCP/IP curto (apenas o nome da máquina) versus um nome do host longo (nome da máquina com nome de domínio pré-anexado a ele).

Por exemplo, as ligações clássicas padrão curta e longa para uma interface ou visualização sem interface podem ser com.mycompany.AccountService e AccountApp/module1.jar/ServiceBean#com.mycompany.AccountService, respectivamente.

Por padrão, o ID de componente para as ligações clássicas padrão EJB é formado pelo uso do nome do aplicativo, nome do módulo e nome do componente do enterprise bean, mas é possível designar qualquer sequência desejada. Ao definir sua própria cadeia como o ID do componente, é possível configurar uma convenção de nomenclatura em que as ligações de forma longa do enterprise bean compartilhem uma parte comum definida pelo usuário e ainda ter uma parte definida pelo sistema com base no nome de cada classe de visualização de interface ou sem interface. Ela também permite tornar os nomes de ligação EJB padrão independentes de como os enterprise beans foram compactados na hierarquia do módulo aplicativo. Substituir um ID de componente padrão de um enterprise bean está descrito na seção "Ligações definidas pelo usuário para interface de negócios, homes e visualizações de não interface de EJB" deste tópico.

Conforme mencionado anteriormente na seção sobre namespace local clássico com escopo definido por JVM e namespace JNDI clássico com escopo definido globalmente, todas as interfaces locais, homes e visualizações sem interface devem ser ligadas ao namespace clássico ejblocal:, que é acessível apenas de dentro do mesmo processo do servidor (JVM), enquanto que interfaces remotas e homes devem ser ligadas ao namespace clássico com escopo definido globalmente, que é acessível em qualquer lugar na célula do produto WebSphere. E como você deveria esperar, o contêiner de EJB segue essas regras para as ligações padrão.

Além disso, as ligações padrão longas das interfaces remotas seguem as boas práticas Java EE recomendadas, em que são agrupadas com um nome de contexto ejb. Por padrão, as interfaces de negócios e home remotos EJB são ligados na raiz do contexto de nomenclatura do servidor de aplicativos. Entretanto, o contexto raiz do servidor de aplicativos é usado para ligar mais do que apenas interfaces de EJB, portanto para evitar que este contexto fique muito desordenado, é uma boa prática agrupar ligações relacionadas a EJB em um subcontexto "ejb" comum ao invés de posicioná-las diretamente no contexto raiz do servidor. É o mesmo que usar subdiretórios em um volume do disco, em vez de colocar todos os arquivos no diretório-raiz.

As ligações padrão curtas de interfaces remotas não são ligadas no contexto ejb. As ligações padrão curtas estão localizadas na raiz do contexto raiz do servidor. Embora seja uma boa prática agrupar todas as ligações relacionadas ao EJB em um contexto ejb, há outras considerações, incluindo as seguintes situações:
  • As ligações padrão curtas fornecem uma maneira simples e direta de acessar uma interface EJB. Colocá-las diretamente no contexto raiz do servidor e se referir a elas apenas pelo nome da interface ou pelo nome da interface com ejblocal: anexado mantinha o objetivo da simplicidade.
  • Ao mesmo tempo, colocar as ligações padrão longas no contexto ejb ou no contexto ejblocal:, no caso de uma interface local, mantinha essas ligações fora do contexto-raiz do servidor e reduzia a confusão o suficiente para permitir que se tivesse as ligações curtas no contexto-raiz.
  • Ela fornece um grau de compatibilidade cruzada com outros servidores de aplicativos Java EE que utilizam convenções de nomenclatura semelhantes.

Resumindo, todas as ligações padrão locais, curtas e longas, são colocadas no ejblocal clássico: namespace com escopo definido no servidor/JVM, enquanto as ligações padrão remotas são colocadas no contexto raiz do servidor do namespace clássico com escopo definido globalmente, se elas forem curtas ou no contexto <server_root>/ejb (seguindo o contexto raiz do servidor), se forem longas. Desse modo, as únicas ligações padrão no contexto-raiz do servidor com escopo definido globalmente são as ligações curtas para interfaces remotas, que é o melhor equilíbrio entre fornecer um modelo de uso simples e portável e evitar que o contexto-raiz do servidor com escopo definido globalmente se torne muito confuso.

Padrão de ligação clássica padrão

Os padrões para cada tipo de ligação clássica são exibidos na tabela. Nesses padrões, cadeias gravadas em <itálico dentro dos colchetes> representam um valor. Por exemplo, <package.qualified.interface> pode ser com.mycompany.AccountService, e <component-id> pode ser AccountApp/module1.jar/ServiceBean.

Tabela 1. Padrões de Ligação Padrão. Padrões de Ligação Padrão
Padrões de ligação Descrição
ejblocal:<interface qualificada do pacote> Forma curta para interfaces locais, inícios e visualizações sem interface
<interface qualificada do pacote> Forma curta das interfaces e inícios remotos
ejblocal:<component-id>#<package.qualified.interface> Forma longa para interfaces locais, inícios e visualizações sem interface
ejb/<id do componente>#<interface qualificada do pacote> Forma longa das interfaces e inícios remotos

O padrão component-id é <application-name>/<module-jar-name>/<ejb-name>, a menos que ele seja substituído no arquivo de ligação do módulo EJB usando o atributo de componente-id, conforme descrito na seção a seguir, "Conflitos em nomes de ligação padrão curtos quando a mesma interface é implementada por vários enterprise beans". A variável <module-jar-name>, quando não substituída pelo arquivo de ligação do módulo EJB, é o nome do arquivo do módulo físico no EAR, incluindo a extensão, por exemplo, .jar, .ear, .war, conforme descrito na seção anterior "Nome do módulo", mesmo que haja um nome de módulo lógico especificado no descritor de implementação.

Conflitos em nomes de ligação clássica padrão curta quando diversos enterprise beans implementam a mesma interface

Quando mais de um enterprise bean em execução no servidor de aplicativos implementa uma determinada interface ou visualização sem interface, o nome da ligação clássica padrão curta se torna ambíguo porque o nome curto pode se referir a qualquer Enterprise JavaBeans que implementa essa interface ou visualização sem interface. Para evitar essa situação, você deve definir explicitamente uma ligação para cada Enterprise JavaBeans que implementa a interface ou visualização sem interface específica, conforme descrito na próxima seção, ou desativar ligações clássicas padrão curtas para os aplicativos contendo esses Enterprise JavaBeans definindo uma propriedade customizada de JVM do produto WebSphere, com.ibm.websphere.ejbcontainer.disableShortDefaultBindings. Para obter informações adicionais sobre como definir a propriedade customizada JVM, leia sobre propriedades customizadas da Java Virtual Machine.

Para usar essa propriedade customizada de JVM, configure o nome da propriedade como com.ibm.websphere.ejbcontainer.disableShortFormBinding e seu valor para * (asterisco), como um valor curinga para desativar as ligações clássicas padrão de formato curto para todos os aplicativos no servidor, ou para uma sequência delimitada por dois pontos de nomes de aplicativos Java EE para os quais deseja desativar ligações clássicas padrão curtas como, por exemplo, PayablesApp:InventoryApp:AccountServicesApp.

Efeito de assinatura explícita em ligações clássicas padrão

Se você designar explicitamente uma definição de ligação para uma interface, home ou visualização sem interface, nenhuma ligação clássica padrão curta ou longa será executada para essa interface ou visualização sem interface.
Configurações suportadas Configurações suportadas: Isto se aplica apenas às interfaces específicas ou visualizações sem interface para as quais você designa uma ligação explícita. Outras interfaces nesse enterprise bean, sem ligações designadas explicitamente, são ligadas por meio do uso de nomes de ligações clássicas padrão. sptcfg

Ligações java:[scope]

Os namespaces java:global, java:app e java:module são introduzidos pela especificação Java EE 6. Eles fornecem um mecanismo para ligação e procura dos recursos que são móveis nos servidores de aplicativos.

O servidor sempre cria uma ligação padrão de formato longo para cada interface EJB, incluindo visualização sem interface, e a coloca nos namespaces java:global, java:app e java:module. Uma ligação de formato curto também é criada e colocada nos namespaces java:global, java:app e java:module se o bean expuser apenas uma interface, incluindo a visualização sem interface. As ligações padrão são criadas apenas para beans de sessão. Elas não são criadas para beans de entidade ou beans acionados por mensagem.

As ligações de formato longo e formato curto contêm o nome do aplicativo, o nome do módulo e o nome do componente do bean. O nome do aplicativo é padronizado para o nome base do arquivo .ear sem a extensão. O nome do aplicativo pode ser substituído usando o elemento application-name no arquivo application.xml. O nome do módulo é padronizado para o nome do caminho do módulo com a extensão removida e quaisquer nomes de diretório incluídos. O nome do módulo pode ser substituído com o uso do elemento module-name no arquivo ejb-jar.xml ou web.xml. O nome do componente do bean é padronizado para o nome não qualificado da classe de bean. O nome do componente do bean pode ser substituído usando o atributo name do componente EJB definindo a anotação ou o elemento ejb-name no arquivo ejb-jar.xml.

O padrão de ligação de formato longo é java:global/<applicationName>/<moduleName>/<bean component name>!<fully qualified interface name>.

O padrão de ligação de formato curto é java:global/<applicationName>/<moduleName>/<bean component name>.

Por exemplo, o componente bean MyBeanComponent expõe apenas a interface com.foo.MyBeanComponentLocalInterface e é compactado no módulo myModule.jar no arquivo myApp.ear. Como resultado, as ligações a seguir são criadas nos namespaces java:[scope]:
  • java:global/myApp/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
  • java:global/myApp/myModule/MyBeanComponent
  • java:app/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
  • java:app/myModule/MyBeanComponent
  • java:module/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
  • java:module/MyBeanComponent
O bean MyBeanComponent pode ser obtido dos namespaces java:[scope] usando uma das seguintes técnicas:
  • Usar o atributo lookup na anotação @EJB; por exemplo:
    @EJB(lookup="java:global/myApp/myModule/MyBeanComponent")
  • Use o elemento lookup-name em ejb-jar.xml; por exemplo:
    <lookup-name>java:global/myApp/myModule/MyBeanComponent!com.ibm.MyBeanComponentLocalInterfaces</lookup-name>
  • Concluir uma consulta no objeto InitialContext; por exemplo:
    initialContext.lookup("java:global/myApp/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterfaces")

Além das ligações padrão criadas pelo servidor de aplicativos, é possível definir referências nos namespaces java:global, java:app e java:module. As referências definidas nos namespaces java:global, java:app e java:module não entram no namespace do componente. As referências definidas nos namespaces java:global, java:app ou java:module devem ser consultadas ou injetadas desses namespaces. Elas não podem ser consultadas ou injetadas a partir do namespace do componente.

Um componente de bean pode usar o namespace java:module para declarar uma referência que pode ser usada por um componente empacotado no mesmo módulo. Ele pode usar o namespace java:app para declarar uma referência que pode ser usada por um componente empacotado em um módulo diferente no mesmo aplicativo. Ele pode usar o namespace java:global para declarar uma referência que pode ser usada por um componente empacotado em um aplicativo diferente.

As referências com nomes idênticos nos namespaces java:global, java:app ou java:module podem entrar em conflito entre si, assim como as referências com nomes idênticos no namespace do componente também podem conflitar. Uma referência com escopo definido para o namespace java:app para um aplicativo não entra em conflito com uma referência com nome idêntico cujo escopo foi definido para o namespace java:app para um aplicativo diferente. Da mesma forma, uma referência com escopo definido para o namespace java:module para um módulo não entra em conflito com uma referência com nome idêntico cujo escopo foi definido para o namespace java:module para um módulo diferente.

Uma referência pode ser declarada no namespace java:global usando anotações; por exemplo:
@EJB(name="java:global/env/myBean")
Uma referência pode ser declarada no arquivo ejb-jar.xml; por exemplo:
<resource-ref>
    <res-ref-name>java:global/env/myDataSource</res-ref-name>
    ....
</resource-ref>         

Para obter a documentação adicional sobre namespaces java:[scope], consulte a seção 5.2.2 da especificação Java EE 6 e a seção 4.4 da especificação Enterprise JavaBeans 3.1.

Ligações definidas pelo usuário para interfaces de negócios EJB, inícios e visualizações sem interface

Para casos em que se deseja designar manualmente locais de ligação, em vez de usar as ligações padrão do produto, é possível usar o arquivo de ligação do módulo EJB para designar seus próprios locais de ligação a interfaces, inícios e visualizações sem interface específicos. Também é possível utilizar esse arquivo para substituir somente a parte do ID do componente das ligações padrão em um ou mais enterprise beans no módulo. Substituir o ID do componente fornece um meio termo entre o uso de todas as ligações padrão e a especificação completa do nome de ligação de cada visualização de interface ou sem interface.

Para especificar informações sobre ligações definidas pelo usuário para módulos EJB 3.x, coloque o arquivo ibm-ejb-jar-bnd.xml no diretório META-INF para o arquivo Java archive (JAR) EJB. O sufixo nesse arquivo é XML. Além disso, ao definir uma ligação clássica para uma interface local ou visualização sem interface, você deve anteceder o nome com a sequência "ejblocal:" para que ela seja ligada ao namespace ejblocal: com escopo definido como clássico.

O arquivo ibm-ejb-jar-bnd.xml é usado para os módulos EJB 3.0 e posterior executados no produto, enquanto que o arquivo ibm-ejb-jar.bnd.xmi é usado para os módulos pré-EJB 3.0 e para módulos da Web. O formato do arquivo de ligação no arquivo ibm-ejb-jar.bnd.xml é diferente do formato do arquivo XMI pelos seguintes motivos:
  • Ligações e extensões declaradas no formato de arquivo XMI dependem da presença de um arquivo do descritor de implementação ejb-jar.xml correspondente que se refere explicitamente a números de ID exclusivos que são anexados aos elementos nesse arquivo. Este sistema não é mais viável para módulos EJB 3.0 e posteriores, já que não é mais um requisito para que o módulo contenha um descritor de implementação ejb-jar.xml.
  • O formato de arquivo XMI foi projetado para ser editado por máquina apenas pelas ferramentas de desenvolvimento do produto e pelas funções de gerenciamento de sistemas; ele era efetivamente parte da implementação interna do produto e a estrutura do arquivo nunca foi documentada externamente. Isso impossibilitou que os desenvolvedores editassem manualmente arquivos de ligação ou os criassem como parte de um processo de construção independente do WebSphere, de maneira suportada.
  • Em vez de se referir aos números de ID codificados no descritor de implementação ejb-jar.xml, o arquivo de ligação baseado em XML refere-se a um componente EJB por seu nome EJB. Cada componente EJB em um módulo tem um nome EJB exclusivo, seja por padrão ou por meio de designação explícita feita pelo desenvolvedor. Portanto, esse comportamento fornece uma forma ambígua de destinar ligações e extensões.
  • Os novos arquivos de ligação são baseados em XML e um arquivo XML Schema Definition (XSD) é fornecido para documentar a estrutura externamente. Esses arquivos .xsd podem ser consumidos por muitos editores de arquivos XML comum para ajudar nas funções de verificação sintática e de conclusão de código. Como resultado, agora é possível que os desenvolvedores produzam e editem os arquivos de ligação e extensão independentemente da infraestrutura do servidor de aplicativos.
A tabela a seguir lista os elementos e atributos ibm-ejb-jar-bnd.xml que são usados para designar ligações às interfaces EJB e inícios aos módulos EJB 3.x e visualizações sem interface para módulos EJB 3.1.
Tabela 2. Elementos e Atributos ibm-ejb-jar-bnd.xml. Elementos e Atributos ibm-ejb-jar-bnd.xml
Elemento ou Atributo Como é utilizado Exemplo Comentários
<session> Declara um grupo de designações de ligação para um bean de sessão. <session name="AccountServiceBean"/> Requer o atributo de nome e pelo menos um dos atributos a seguir: atributo simple-binding-name, atributo local-home-binding-name, atributo remote-home-binding-name ou elemento <interface>.
name Atributo que identifica o nome ejb do enterprise bean que uma <session>, <message-driven> ou <entity> ou outro elemento se aplica. <session name="AccountServiceBean"/> O valor do nome é o nome declarado no elemento <ejb-name> de um arquivo descritor de implementação ejb-jar.xml, o atributo de nome de uma anotação @Stateful, @Stateless, @Singleton ou @MessageDriven ou padronizado para o nome da classe incompleto da classe de implementação do EJB anotado com a anotação @Session ou @MessageDriven (se nenhum valor <ejb-name> estiver declarado no descritor de implementação XML e nenhum parâmetro de nome estiver declarado na anotação).
component-id Atributo que fornece o valor do ID do componente padrão para um enterprise bean. As ligações clássicas de formato longo padrão para este enterprise bean usam o ID de componente especificado em vez de <app_name>/<module_jar_name>/<bean_name>.
<nome da sessão="AccountServiceBean"/> 
component-id="Dept549/AccountProcessor"/>

O exemplo anterior resulta no bean cujo nome ejb é AccountServiceBean, com suas interfaces locais clássicas padrão de formato longo ligadas a ejblocal:Department549/AccountProcessor#<package.qualified.interface> Suas interfaces remotas clássicas padrão de formato longo estão ligadas a ejb/Department549/AccountProcessor#<package.qualified.interface>

Pode ser usado sozinho ou em combinação com o elemento <interface>, o atributo local-home-binding-name attribute ou o atributo remote-home-binding-name. Interfaces que não recebem designações de ligações explícitas podem ter ligações clássicas padrão executadas com o uso do valor do ID de componente especificado pelo usuário. Interfaces que recebem ligações explícitas são ligadas utilizando-se esses valores.

Como o atributo simple-binding-name destina-se à aplicação em todas as interfaces definidas em um enterprise bean específico (sem padronizar nenhuma interface), aplicar um component-id em combinação com um simple-binding-name não é útil, em geral.

simple-binding-name Um mecanismo simples para designar ligações de interface para Enterprise JavaBeans t que:
  • Implementem uma única interface de negócios EJB 3.x
  • Implementem uma interface do componente do estilo pré-EJB 3.0 (local, remota ou ambas) com um home EJB acompanhante.
O valor do atributo é usado como o local de ligação da interface de negócios do enterprise bean, ou o local de ligação do Enterprise JavaBeans local, inícios remotos, ou ambos. A ligação é colocada no namespace ejblocal: clássico se a interface ou home for local e é colocada no contexto-raiz do servidor de aplicativos do namespace JNDI clássico com escopo definido globalmente se a interface ou home for remota.
<nome da sessão="AccountServiceBean"/>
simple-binding-name="ejb/AccountService"/>
Esse exemplo resulta no bean cujo ejb-name é AccountServiceBean, com sua home ou interface de negócios local, se houver alguma, ligada a ejblocal:ejb/AccountService no namespace EJB local clássico com escopo definido pela JVM, e sua home ou interface de negócios remota, se houver alguma, ligada a ejb/AccountService no contexto-raiz do servidor de aplicativos do namespace JNDI clássico com escopo definido globalmente.
Importante: Importante:
O valor exato do atributo, incluindo este exemplo específico, o nome do subcontexto "ejb" é usado mesmo se a interface for uma interface logal limitada no namespace ejblocal:. Quando ligações definidas pelo usuário são especificadas, o nome exato especificado pelo atributo é utilizado.
Não deve ser usado em combinação com atributos local-home-binding-name ou remote-home-binding-name ou o elemento <interface>. Além disso, não deve ser usado em beans que implementam mais de uma interface de negócios - use o elemento <interface> nesse caso.

Se esse atributo for usado em um enterprise bean que implemente mais de uma interface de negócios, ou uma combinação de interface de negócios e interface de componente local/remoto com início, a ambiguidade das ligações resultantes será removida anexando-se um sinal hash ou numérico (símbolo #) ao valor do atributo, seguido do nome de classe qualificado do pacote de cada interface, início, ou ambos, no enterprise bean. Esta condição pode ser evitada, no entanto, ao usar o elemento <interface> para definir uma ligação para cada uma das interfaces de negócios em vez de usar simple-binding-name.

Importante: Importante:
definir um simple-binding-name em um bean que implemente mais de uma interface de negócios não é o mesmo que substituir o ID do componente padrão para um bean que use <component-id>. As ligações padrão de interface remota definidas com um component-id ainda são agrupadas no contexto EJB (como são todas as ligações padrão de interface remota), enquanto as ligações de interface remota cuja ambiguidade foi removida pelo contêiner EJB em resposta ao uso incorreto de simple-binding-name em um bean com múltiplas interfaces não são agrupadas no contexto ejb.
Além disso, a inclusão do nome de classe package-qualified sempre ocorre para ligações clássicas padrão de formato longo, considerando que com simple-binding-name ele ocorre apenas em condições de erro, em que a desambiguação é necessária. Não dependa do nome de ligação criado por meio de remoção de ambiguidade, uma vez que, esse efeito ocorrendo, poderá haver mudança se o bean for alterado para implementar mais ou menos interfaces.
local-home-binding-name Atributo para especificar o local da ligação do início local de um enterprise bean.
<session name="AccountServiceBean"
 local-home-binding-name="ejblocal:AccountService"/>
Não deve ser utilizado em combinação com o atributo simple-binding-name. Como homes locais devem ser sempre ligadas ao namespace clássico com escopo definido por JVM, o valor deve começar com o prefixo ejblocal:
remote-home-binding-name Atributo para especificar o local da ligação do início remoto de um enterprise bean.
<nome da sessão="AccountServiceBean"/>
 remote-home-binding-name=
 "ejb/services/AccountService"/>
Não deve ser utilizado em combinação com o atributo simple-binding-name. O valor não pode começar com o prefixo ejblocal: clássico, pois homes remotas não podem ser ligadas ao namespace ejblocal: clássico.
<interface> Um subelemento do elemento <session> que designa uma ligação para uma interface de negócios EJB específica ou visualização sem interface. Em contraste com os atributos simple-binding-name, local-home-binding-name e remote-home-binding-name, um parâmetro binding-name e um parâmetro class são necessários (de fato, essa distinção é o porquê um elemento XML separado é necessário, e não um atributo). O parâmetro class especifica o nome qualificado do pacote da classe da interface de negócios ou da visualização sem interface a ser ligada.
<interface class="com.ejbs.InventoryService" 
binding-name="ejb/Inventory"/> 
(declarado como subelemento dentro de um elemento <session>)
Não deve ser utilizado em combinação com o atributo simple-binding-name. Como interfaces locais e visualizações sem interface devem ser sempre ligadas ao namespace clássico com escopo definido por JVM, o valor binding-name deve começar com o prefixo ejblocal: quando esse elemento for aplicado a uma interface local ou visualização sem interface.
binding-name Atributo para especificar o local de ligação de uma interface de negócios ligada ao elemento <interface>.
<interface class="com.ejbs.InventoryService" 
binding-name="ejb/Inventory"/>
(declarado como subelemento dentro de um elemento <session>)
Necessário em combinação com o elemento <interface> (e utilizado somente nesse elemento). Como interfaces locais devem ser sempre ligadas ao namespace clássico com escopo definido por JVM, o valor binding-name deve começar com o prefixo ejblocal: quando aplicado a uma interface local.

Exemplo de Arquivo de Ligação 1

O exemplo a seguir é um arquivo ibm-ejb-jar-bnd.xml básico que contém apenas os elementos e atributos que designam nomes de ligação a interfaces EJB e visualizações sem interface. Ele substitui o ID de componente usado para ligações padrão no enterprise bean chamado S01, e designa ligações explícitas a algumas das interfaces nos enterprise beans, S02 e S03, neste módulo.
<?xml version="1.0" encoding="UTF-8?"> 
<ejb-jar-bnd xmlns=http://websphere.ibm.com/xml/ns/javaee xmlns:xsi="
 http://www.w3.org/2001/XMLSchema-instance "xsi:schemaLocation"=
 http://websphere.ibm.com/xml/ns/javaee 
 http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd "version 1.0">
 <session name="S01" component-id="Department549/AccountProcessors"/>
 <session name="S02" simple-binding-name="ejb/session/S02"/> 
 <session name="S03"> 
  <interface class="com.ejbs.BankAccountService" binding-name="ejblocal:session/BAS"/>
 </session>  
</ejb-jar-bnd>
O arquivo de ligação apresenta os seguintes resultados:
  • O bean de sessão com ejb-name S01 é designado a um ID de componente definido pelo usuário, substituindo o ID de componente padrão (nome do aplicativo/nome do módulo ejb-jar/nome do bean) para todas as interfaces e visualizações sem interface nesse bean. As interfaces locais e as visualizações sem interface nesse bean são ligadas em ejblocal:Department549/AccountProcessors#<package.qualified.interface.name>, enquanto as interfaces remotas são ligadas em ejb/Department549/AccountProcessors#<package.qualified.interface.name>
  • Supõe-se que o bean de sessão com ejb-name S02 tenha uma única interface de negócios EJB 3.x ou visualização sem interface EJB 3.1. Como alternativa, ele poderia ter uma interface de "componente" pré-EJB 3.0 com home local, home remoto ou ambos. A interface de negócios, ou o início ou inícios da interface do componente, são ligados a ejblocal:ejb/session/S02 se for local, ou a ejb/session/S02 se for remota.

    Se o bean S02 possuir mais de uma interface de negócios, ou possuir interfaces de negócios e uma home, um nome de simples ligação será ambíguo. Nesse caso, o contêiner elimina a ambiguidade das designações de ligação anexando #<package.qualified.interface.name> ao nome de ligação simples, ejb/session/S02, para cada uma das interfaces do bean.

  • A interface de negócios EJB 3.x ou visualização sem interface EJB 3.1, com.ejbs.BankAccountService, no bean de sessão com ejb-name S03 é ligada a ejblocal:session/BAS.
Todas as outras interfaces de negócios, homes ou visualizações sem interface neste bean, se presentes, vão receber designações de ligações clássicas padrão. Supõe-se que a interface com.ejbs.BankAccountService seja local, uma vez que foi designada para o namespace ejblocal: neste exemplo; ocorrerá um erro se a interface não for local.

A próxima seção expande esse exemplo, apresentando os elementos para resolver os destinos dos vários tipos de entradas de injeção e referência que são declarados no descritor de implementação XML ou através de anotações.

Ligações Definidas pelo Usuário para Resolver Destinos de Injeção e Referências

A seção anterior mostrou exemplos de como designar nomes de ligação definidos pelo usuário para interfaces de negócios, inícios e visualizações sem interface. Esta seção abrange destinos de ligação de resolução para referências, diretivas de injeção e destinos de bean acionado por mensagens.

Tabela 3. Elementos e Atributos para Resolver Destinos de Vínculo para Referências e Destinos de Injeção. Elementos e Atributos para Resolver Destinos de Vínculo para Referências e Destinos de Injeção
Elemento ou atributo Como é utilizado Exemplo: Comentários
<jca-adapter> Define a especificação de ativação do adaptador JCA 1.5, e um local JNDI de destino da mensagem, para entrega de mensagens a um bean acionado por mensagens.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name="jms/ServiceQueue"/>
Requer o atributo activation-spec-binding-name. Se o bean acionado por mensagem correspondente não identificar seu destino de mensagem usando o elemento <message-destination-link>, o atributo destination-binding-name também será necessário. Opcionalmente, ele pode incluir o atributo activation-spec-auth-alias.
<ejb-ref> Resolve o destino de uma declaração ejb-ref, que é declarada por meio da anotação @EJB ou por meio de ejb-ref no descritor de implementação ejb-jar.xml, fornecendo a ligação entre o nome declarado no namespace java:comp/env com escopo definido por componente, o nome do enterprise bean de destino no namespace clássico ejblocal: com escopo definido por JVM ou JNDI clássico com escopo definido globalmente.
<ejb-ref name="com.ejbs.BankAccountServiceBean/s02Ref" 
binding-name="ejb/session/S02"/>
Requer os atributos name e binding-name.
<message-driven> Declara um grupo de designações de ligação para um bean acionado por mensagens.
<message-driven name="EventRecorderBean">
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec" 
destination-binding-name="jms/ServiceQueue"/>
</message-driven>
Requer o atributo de nome e o subelemento <jca-adapter>.
<message-destination> Associa o nome de um destino de mensagem, que é um nome lógico definido em um descritor de implementação do módulo Java EE, a um nome de JNDI global específico, que é um nome real no namespace JNDI. Em seguida, os elementos <message-destination-ref> no descritor de implementação do módulo Java EE ou as diretivas de injeção @Resource que injetam destinos de mensagem podem usar o elemento <message-destination-line> para referir-se a este message-destination pelo nome lógico de destino, em vez de requerer entradas de ligação <message-destination-ref> individuais no arquivo de ligação de cada message-destination-ref definido.
<message-destination name="EventProcessingDestination"
binding-name="jms/ServiceQueue"/>
Requer os atributos name e binding-name.
<message-destination-ref> Resolve o destino de uma declaração de referência de destino da mensagem que é declarado através da anotação @Resource ou através da referência de destino da mensagem no ejb-jar.xml, fornecendo a ligação entre o nome declarado no namespace java:comp/env com escopo definido no componente e o nome do ambiente de recursos de destino no namespace JNDI global.
<message-destination-ref
name="com.ejbs.BankAccountServiceBean/serviceQueue"
binding-name="jms/ServiceQueue"/>
Requer os atributos name e binding-name.
<resource-ref> Resolve o destino de uma declaração de referência de recurso que é declarado através da anotação @Resource ou através da referência de recurso no ejb-jar.xml, fornecendo a ligação entre o nome declarado no namespace java:comp/env com escopo definido no componente e o nome do recurso de destino no namespace JNDI global.
<resource-ref 
name="com.ejbs.BankAccountServiceBean/dataSource" 
binding-name="jdbc/Default"/>
Requer os atributos name e binding-name. Pode incluir os atributos authentication-alias ou custom-login-configuration.
<resource-env-ref> Resolve o destino de uma declaração de referência de ambiente de recursos que é declarado através da anotação @Resource ou através da referência de ambiente de recursos no ejb-jar.xml, fornecendo a ligação entre o nome declarado no namespace java:comp/env com escopo definido no componente e o nome do ambiente de recursos de destino no namespace JNDI global.
<resource-env-ref 
name="com.ejbs.BankAccountServiceBean/dataFactory"
binding-name="jdbc/Default"/>
Requer os atributos name e binding-name.
<env-entry> Substitui uma entrada de ambiente com o valor especificado representado no formato de sequência ou um objeto que pode ser acessado com uma consulta do JNDI no nome de consulta especificado aplicado ao contexto inicial padrão.
<env-entry name="java:module/env/taxYear" value="2010"/>
<env-entry name="java:module/env/taxYear" 
binding-name="cell/persistent/MyApp/MyModule/taxYear"/
Requer o atributo de nome e o valor ou o atributo binding-name, mas não ambos.
<data-source> Substitui uma definição de origem de dados, declarada por meio da anotação @DataSourceDefinition ou por meio do elemento data-source no aplicativo, ou um descritor de implementação de módulo com um recurso gerenciado.
<data-source name="java:module/env/myDS" 
binding-name="jdbc/DB2DS"/>
Requer os atributos name e binding-name.
nome Atributo que identifica o local da nomenclatura, normalmente dentro do namespace java:comp/env específico do componente, que define o lado "origem" de uma ligação referência/destino, como em ejb-ref, resource-ref, resource-env-ref, message-destination ou message-destination-ref.
<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye"
binding-name="ejb/session/S02"/>
 
binding-name Atributo que identifica o local de nomenclatura dentro do namespace ejblocal: clássico, ou JNDI clássico com escopo definido globalmente, ou namespace java:global que define o lado do "destino" de uma ligação referência/destino, como em ejb-ref, resource-ref, resource-env-ref, message-destination ou message-destination-ref.
<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye"
binding-name="ejb/session/S02"/>
 
Value Atributo que especifica o valor a utilizar para uma ligação envy-entry.
<env-entry name="java:module/env/taxYear" value="2010"/>
 
activation-spec-binding-name Atributo que identifica o local JNDI da especificação de ativação associado ao adaptador JCA 1.5 a ser utilizado para entregar mensagens a um bean acionado por mensagens.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name="jms/ServiceQueue"/>
Esse nome deve corresponder ao nome de uma especificação de ativação JCA 1.5 definida para o WebSphere Application Server.
activation-spec-auth-alias Atributo opcional que identifica o nome de um alias de autenticação J2C utilizado para a autenticação de conexões com o adaptador de recursos JCA. Um alias de autenticação J2C especifica o ID de usuário e a senha utilizados para autenticar a criação de uma nova conexão com o adaptador de recursos JCA.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
activation-spec-auth-alias="jms/Service47Alias"
destination-binding-name="jms/ServiceQueue"/>
Esse nome deve corresponder ao nome de um alias de autorização J2C definido para o WebSphere Application Server
destination-binding-name Atributo que identifica o nome JNDI que o bean acionado por mensagens utiliza para consultar seu destino JMS no namespace JNDI.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name="jms/ServiceQueue"/>
Esse nome deve corresponder ao nome de uma fila ou tópico JMS definido para o WebSphere Application Server.
authentication -alias Subelemento opcional do elemento de ligação <resource-ref>. Se a referência de recurso for para uma connection factory, uma configuração de login opcional JAAS pode ser especificada; nesse caso, um nome de alias de autenticação simples.
<resource-ref
name="com.ejbs.BankAccountServiceBean/dataSource"
binding-name="jdbc/Default">
<authentication-alias name="defaultAuth"/>
<resource-ref>
Esse nome deve corresponder ao nome de um alias de autenticação JAAS definido para o WebSphere Application Server.
custom-login-configuration Subelemento opcional do elemento de ligação <resource-ref>. Se a referência de recurso for para uma connection factory, uma configuração de login opcional JAAS pode ser especificada; nesse caso, um conjunto de propriedades (pares nome/valor).
<resource-ref 
name="com.ejbs.BankAccountServiceBean/dataSource"
binding-name="jdbc/Default">
<custom-login-configuration-name="customLogin">
<property name="loginParm1" value="ABC123"/>
<property name="loginParm2" value="DEF456"/>
</custom-login-configuration> 
</resource-ref>
Esse nome deve corresponder ao nome de uma configuração de login do JAAS definido para o WebSphere Application Server.

Exemplo 2 do Arquivo de Ligação

O exemplo a seguir é uma expansão do arquivo ibm-ejb-jar-bnd.xml básico apresentado no Exemplo 1.
<?xml version="1.0" encoding="UTF-8"?> 
<ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" "xmlns:xsi"=
"http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee" 
"http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd version" "1.0">
 <session name="S01" component-id="Department549/AccountProcessors"/>
 <session name="S02" simple-binding-name="ejb/session/S02"/>
 <session name="S03">
  <interface class="com.ejbs.BankAccountService"
   binding-name="ejblocal:session/BAS"/>
  <ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye"
   binding-name="ejb/session/S02"/>
  <resource-ref name="com.ejbs.BankAccountServiceBean/dataSource"
   binding-name="jdbc/Default"/>
 </session>
 <message-driven name="MO1">
  <jca-adapter activation-spec-binding-name="jms/InternalProviderSpec"
   destination-binding-name=jms/"ServiceQueue"/>
 </message-driven>
 <session name="S04" simple-binding-name="ejb/session/S04">
  <resource-ref name="ejbs.S04Bean/dataSource"
   binding-name="jdbc/Default">
   <authentication-alias name="defaultlogin"/>
  </resource-ref>
 </session>
 <session name="S05">
  <interface class="com.ejbs.InventoryService"
   binding-name="ejb/session/S05Inventory"/>
  <resource-ref name="ejbs.S05Bean/dataSource"
   binding-name="jdbc/Default">
   <custom-login-configuration name="customLogin">
    <property name="loginParm1" value="ABC123"/>
    <property name="loginParm2" value="DEF456"/>
   </custom-login-configuration>
  </resource-ref>
 </session>
</ejb-jar-bnd>
Essa ligação apresenta os seguintes resultados:
  1. A interface de negócios, a home e as ligações da visualização sem interface dos beans de sessão chamados S01, S02 e S03 do exemplo anterior não foram alteradas.
  2. O bean de sessão cujo ejb-name é S03 inclui agora duas ligações de resolução de destino de referência:
    • A ligação ejb-ref resolve a referência EJB definida em java:comp/env/com.ejbs.BankAccountServiceBean/goodBye, para o local JNDI ejb/session/S02 no contexto JNDI raiz do servidor de aplicativos. A referência EJB também pode ser definida por uma injeção de @EJB na classe com.ejbs.BankAccountServiceBean, em uma variável de instância chamada "goodBye".
      Nota: ejb/session/S02 é o local JNDI do bean de sessão S02 também definido neste mesmo arquivo de ligação, o que significa que a referência aponta para o bean de sessão cujo nome é S02.
    • A ligação de referência de recurso resolve a referência de recurso definida em java:comp/env/com.ejbs.BankAccountServiceBean/dataSource para o local JNDI jdbc/Default. A referência de recurso também poderia ter sido definida por uma injeção @Resource na classe com.ejbs.BankAccountServiceBean em uma variável de instância denominada "dataSource".
  3. São definidas ligações para um bean acionado por mensagens cujo ejb-name é M01. O MDB recebe mensagens de um destino JMS definido para o WebSphere Application Server, cujo nome da JNDI é jms/ServiceQueue, usando um adaptador JCA 1.5 cuja especificação de ativação JCA 1.5 foi definida para o WebSphere Application Server com o nome jms/InternalProviderSpec.
  4. Supõe-se que o bean de sessão cujo ejb-name é S04 tenha uma única interface de negócios ou visualização sem interface, ligada a ejb/session/S04, se remota, ou a ejblocal:ejb/session/S04, se local. Ele possui uma referência de recurso com nome, java:comp/env/ejbs/S04Bean/dataSource. Isso também pode ser a classe, ejbs.S04Bean, com uma injeção @Resource em uma variável nomeada, dataSource. Essa referência de recurso é resolvida para o local JNDI jdbc/Default. O resource-ref refere-se a uma conexão J2C e se conecta a esse recurso usando um alias de autenticação simples que é denominado defaultlogin definido no WebSphere Application Server.
  5. Uma ligação de interface de negócios é definida para a interface cujo nome de classe é com.ejbs.InventoryService implementado pelo bean de sessão com ejb-name de S05; supõe-se que a interface seja remota, já que ela não tem um prefixo "ejblocal:" e pode, assim, ser ligada a ejb/session/S05Inventory no contexto-raiz da JNDI do servidor no namespace clássico com escopo definido globalmente. Qualquer outra interface de negócios implementada por esse bean recebe ligações clássicas padrão. O bean possui uma referência de recurso com nome java:comp/env/ejbs.S05Bean/dataSource (ou uma injeção @Resource na classe ejbs.S05Bean na variável denominada "dataSource") que é resolvida para o local JNDI jdbc/Default. O resource-ref refere-se a uma conexão J2C e se conecta a esse recurso usando uma configuração de login customizada que inclui dois pares nome-valor.

Exemplo 3 do Arquivo de Ligação

Este exemplo demonstra como definir e resolver ligações de referência EJB para executar consultas do JNDI por meio de instâncias do servidor de aplicativos dentro da mesma célula WebSphere Application Server. Ele usa dois beans EJB: um bean chamado que define uma ligação explícita usando o atributo simple-binding-name e um bean executor da chamada, que executa uma injeção de @EJB e usa o elemento ejb-ref do arquivo de ligação associado para resolver a referência, para que esta aponte para o bean chamado, que reside em um processo diferente do servidor de aplicativos.

ibm-ejb-jar-bnd.xml (called bean)

<?xml version="1.0" encoding="UTF-8"?> 
<ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee" 
 "http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd" version="1.0"> 
 <session name="FacadeBean" simple-binding-name="ejb/session/FacadeBean"/> 
</ejb-jar-bnd>
Esse conteúdo de arquivo de ligação considera que o bean de sessão cujo ejb-name é "FacadeBean" implementa uma interface de negócios única e, portanto, o atributo simple-binding-name pode ser usado como alternativa ao subelemento <interface>. Nesse caso, FacadeBean implementa uma única interface de negócios remota, ligada a ejb/session/FacadeBean no contexto JNDI raiz do servidor de aplicativos onde FacadeBean reside.

Fragmento de código (bean de chamada)

@EJB(name="ejb/FacadeRemoteRef") 	
FacadeRemote remoteRef; 	
try {
     output = remoteRef.orderStatus(input);
} 
catch(Exception e){
     // Handle exception, etc.
} 
Esse fragmento de código executa uma injeção de recurso EJB na variável de instância denominada "remoteRef", que é do tipo FacadeRemote. A injeção substitui o parâmetro "name", configurando o nome de referência da referência ejb resultante como ejb/FacadeRemoteRef. O código chama um método de negócios na referência injetada.

ibm-ejb-jar-bnd.xml (calling bean)

<?xml version="1.0" encoding="UTF-8"?> 
<ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" 
 "xmlns:xsi="
 "http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee" 
 "http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd" version="1.0">
 <session name="CallingBean">     
  <ejb-ref name="ejb/FacadeRemoteRef" 
   binding-name="cell/nodes/S35NLA1/servers/S35serverA1/ejb/session/FacadeBean"/>   
 </session> 
</ejb-bnd-jar>  
Finalmente, este arquivo de ligação resolve a referência EJB com um nome ejb-ref de ejb/FacadeRemoteRef para apontar para o nome JNDI com escopo definido globalmente clássico de cell/nodes/S35NLA1/servers/S35serverA1/ejb/session/FacadeBean. Esse nome de JNDI clássico com escopo definido globalmente representa uma interface ligada a ejb/session/FacadeBean sob o contexto raiz do servidor de um servidor denominado "S35serverA1" no nó "S35NLA1" na célula WebSphere Application Server do bean de chamada. Para apontar para um local dentro de uma célula diferente do WebSphere Application Server, um nome com estilo CORBAName pode ser usado no lugar de um nome de JNDI padrão.

Instruções sobre como modificar o arquivo ibm-ejb-jar-bnd.xml podem ser localizadas no tópico, Maneiras de atualizar arquivos de aplicativos.

O Relacionamento entre Injeções e Referências

Existe uma correspondência um para um entre diretivas de injeção e declarações de referência - cada injeção define implicitamente uma referência de algum tipo e, de maneira oposta, cada referência tem a opção de também definir uma injeção. É possível pensar em uma anotação de injeção como um mecanismo para definir referências por meio de anotações em vez de defini-las no descritor de implementação XML.

Por padrão, uma injeção, define uma referência com um nome formado a partir do nome da classe qualificada do pacote do componente fazendo a injeção, uma barra (/) e o nome da variável ou propriedade sendo injetada. Por exemplo, uma injeção executada na classe com.ejbs.AccountService em uma variável ou propriedade denominada "depositService", resulta em uma referência denominada java:comp/env/com.ejbs.AccountService/depositService. Entretanto, especificar o parâmetro opcional "name" na diretiva de injeção substitui esse nome padrão e faz com que a referência seja nomeada de acordo com o valor do parâmetro "name".

Conhecendo-se essa regra, fica fácil ver como um arquivo de ligações pode ser utilizado não só para resolver destinos para referências declaradas em um descritor de implementação XML, mas também para resolver destinos para referências declaradas implicitamente por uma diretiva de injeção de anotação. Basta usar o valor do parâmetro "name" na anotação de injeção, ou o nome de referência padrão do nome de classe e o nome da variável/propriedade, se nenhum parâmetro "name" for especificado, como se fosse o nome da referência declarada em um descritor de implementação XML.

Resolução Padrão de Referências EJB e Injeções EJB: Os Recursos EJBLink e AutoLink

Os recursos EJBLink e AutoLink são dois mecanismos diferentes que resolvem referências para componentes EJB compactados no mesmo processo de aplicativo e de servidor de aplicativos que o componente de referência. Tanto EJBLink quanto AutoLink removem a necessidade de resolver explicitamente a referência EJB com informações sobre ligação. O recurso EJBLink é definido pela especificação EJB, enquanto que o recurso AutoLink é uma extensão do WebSphere Application Server.

Os recursos EJBLink e AutoLink usam diferentes critérios de procura para localizar o componente bean desejado. Procuras EJBLink para o componente de bean de destino usando o nome do bean especificado explicitamente. AutoLink procura pelo componente bean desejado usando a interface implementada pelo bean. Se nenhuma ligação explícita for fornecida, mas um nome de bean for fornecido, o recurso EJBLink será usado. Se nenhuma ligação explícita for fornecida, e nenhum nome de bean for fornecido, o recurso AutoLink será usado. Os recursos EJBLink e AutoLink nunca são usados juntos como parte do mesmo processo de procura.

Com exceção do critério de procura, os recursos EJBLink e AutoLink são semelhantes. Os dois recursos procuram um módulo específico primeiro e, em seguida, se necessário, voltam a procurar os outros módulos no mesmo processo de aplicativo e de servidor de aplicativos. Ambos exigem que os critérios de procura resolvam exatamente um componente de bean e consideram uma condição de erro quando resolvem múltiplos componentes de bean. Existe uma condição de erro porque o servidor de aplicativos não sabe qual dos diversos componentes de bean deve ser usado. Neste caso, ocorre a exceção com.ibm.websphere.ejbcontainer.AmbiguousEJBReferenceException. Esta exceção é emitida no tempo de execução quando o componente de referência tenta localizar o componente de bean desejado.

O recurso EJBLink suporta três formatos diferentes.
  • Especifique apenas o nome do componente do bean. Por exemplo, MyBean.
  • Especifique o nome do arquivo de módulo físico, incluindo a extensão, que contém o componente de bean destinado, seguido pelo caractere #, seguido pelo nome do componente do bean. Por exemplo, myModule.jar#MyBean
  • Especifique o nome lógico do módulo que contém o componente de bean destinado, o caractere barra (/), seguido pelo nome do componente do bean. Por exemplo, MyModule/MyBean.

Você pode especificar opcionalmente o nome lógico do módulo utilizando o elemento module-name no descritor de implementação EJB para um módulo ejb-jar, ou pode utilizar o elemento module-name no arquivo descritor de implementação da Web para um módulo WAR que contenha o conteúdo EJB. Para um módulo WAR que contenha o conteúdo EJB, o elemento module-name especificado no descritor de implementação EJB é ignorado, e o elemento module-name especificado no descritor de implementação da Web é processado. Quando nenhum valor module-name é especificado no descritor de implementação, um nome lógico padrão é designado ao módulo. O nome do módulo lógico padrão é o nome base do arquivo de módulo, menos a extensão. Por exemplo, o arquivo de módulo, MyModule.jar, possui o nome de módulo lógico padrão MyModule.

A especificação do nome do módulo físico ainda é suportada, mesmo quando o módulo tem um nome lógico. A especificação do nome lógico do módulo ainda é suportada, mesmo quando nenhum nome de módulo lógico é configurado no descritor de implementação. Neste caso, o nome base do módulo é usado como o nome lógico do módulo.

O contêiner EJB integrável suporta todos os formatos de EJBLink. Para suportar o formato de arquivo de módulo físico, o contêiner EJB integrável não permite iniciar diversos módulos com o mesmo nome base.

AutoLink é um recurso de valor agregado do WebSphere Application Server que elimina a necessidade de resolver explicitamente destinos de referência EJB em certos cenários de uso. No WebSphere Application Server V8, AutoLink é implementado nos limites de cada processo do WebSphere Application Server. O algoritmo do AutoLink funciona da seguinte forma.

Quando o contêiner EJB no produto encontra uma referência EJB em um determinado módulo EJB, ele verifica primeiro se você resolveu explicitamente o destino dessa referência por meio da inclusão de uma entrada no arquivo de ligação do módulo. Se ele não localizar nenhuma resolução explícita do destino no arquivo de ligação, o contêiner procurará no módulo de referência de um enterprise bean que implementa o tipo de interface ou a visualização sem interface definida na referência.

Se ele localizar exatamente um enterprise bean no módulo que implementa a visualização de interface ou sem interface, ele usará esse enterprise bean como o destino da referência EJB. Se o contêiner não puder localizar um enterprise bean desse tipo no módulo, ele expandirá o escopo de procura para o aplicativo do qual o módulo faz parte e procurará outros módulos dentro desse aplicativo que estejam designados para o mesmo servidor de aplicativos que referido módulo. Novamente, se o contêiner localizar exatamente um enterprise bean que implemente a visualização de interface ou sem interface de destino nos outros módulos do aplicativo designado ao mesmo servidor do módulo de referência, ele usará esse enterprise bean como o destino de referência.

O escopo do AutoLink é limitado ao aplicativo no qual a referência EJB aparece e ao servidor de aplicativos no qual o módulo de referência é designado. Referências a enterprise beans em um aplicativo diferente, enterprise beans em um módulo designado a um servidor de aplicativos diferente ou a enterprise beans que residem em um módulo que foi designado a um cluster WebSphere Application Server, devem ser explicitamente resolvidas usando-se ligações de destino de referência no arquivo ibm-ejb-jar-bnd.xml do módulo EJB ou arquivo ibm-web-bnd.xmi do módulo da Web.

É importante observar que o AutoLink só é suportado para referências EJB e nenhum outro tipo de referência, embora seja suportado no contêiner EJB, contêiner da Web e no contêiner de aplicativo cliente. Além disso, como o escopo da função AutoLink é limitado ao servidor ao qual o módulo de referência é designado ou, no caso do contêiner do cliente Java EE, ao servidor para o qual o contêiner do cliente é configurado como seu servidor de auto-inicialização JNDI, ele é útil principalmente em ambientes de desenvolvimento e outros cenários de uso de servidor único. Mesmo com essas limitações presentes, isso pode ter um valor significativo durante a experiência de desenvolvimento removendo-se a necessidade de resolver explicitamente referências EJB.

Resolução de injeções e referências de recurso e EJB: o recurso de consulta

O recurso de consulta é definido pela especificação EJB 3.1 como um mecanismo que resolve referências para EJBs ou recursos por um nome de JNDI explícito. É possível especificar o atributo lookup na anotação javax.ejb.EJB ou na anotação javax.annotation.Resource. O atributo XML correspondente no arquivo ejb-jar.xml é <lookup-name>, em um dos elementos a seguir: <ejb-ref>, <ejb-local-ref>, <env-entry>, <resource-ref>, <resource-env-ref> ou <message-destination-ref>. lookup ou <lookup-name> é um nome JNDI relativo ao contexto de nomenclatura java:comp/env.

Em uma referência EJB, lookup ou <lookup-name> não devem ser especificados com beanName ou com <ejb-link>. O console administrativo exibe lookup-name e ejb-link como somente leitura. Entretanto, se um nome JNDI for especificado na etapa de instalação do aplicativo "Mapeamento de Referências EJB para Beans", ele substituirá os valores lookup-name ou ejb-link.

Substituição de Entradas de Ambiente Definidas nos Aplicativos

Os aplicativos podem definir entradas de ambiente com valores adequados para o teste de unidade, mas não adequados ao teste da integração ou ao uso de produção. Caso deseje substituir o valor de uma entrada de ambiente, é possível incluir o seguinte elemento no arquivo de ligação correspondente:
<env-entry name="name" value="value"/>
em que name é o nome de env-entry conforme definido no aplicativo e value é o valor designado para o env-entry representado no formato de sequência. A sequência de value será analisada de acordo com o tipo de entrada de ambiente, como se o valor tivesse sido especificado no descritor de implementação usando env-entry-value. Por exemplo,
<env-entry name="java:module/env/taxYear" value="2010"/>
associa o env-entry chamado "java:module/env/taxYear" com um valor de "2010".
Alternativamente, é possível configurar um env-entry como referência para outro objeto que pode ser acessado por meio do JNDI. O objeto retornado pela consulta do JNDI é usado como o valor env-entry. O elemento dessa opção possui a seguinte forma:
<env-entry name="name" binding-name="lookupName"/>
em que name é o nome de env-entry conforme definido no aplicativo e lookupName é um nome JNDI que resolve, quando aplicado a uma consulta no contexto inicial padrão. Por exemplo,
<env-entry name="java:module/env/taxYear" binding-name="cell/persistent/MyApp/MyModule/taxYear"/>
associa o env-entry chamado "java:module/env/taxYear" com um valor retornado de uma operação de consulta de contexto inicial em "cell/persistent/MyApp/MyModule/taxYear". O usuário é responsável pela criação da ligação do objeto JNDI. A classe do objeto de ligação deve poder ser designada ao tipo de objeto do env-entry associado.

As entradas de ambiente podem ser definidas no nível do aplicativo e no EJB, na web e nos módulos do cliente. Estes níveis correspondem aos arquivos de ligação application-bnd.xml, ejb-jar-bnd.xml, web-app-bnd.xml e application-client-bnd.xml.

Substituindo Definições de Origens de Dados

Com o Java EE 6, é possível desenvolver aplicativos que definem origens de dados que usam a anotação @DataSourceDefinition ou a entrada do descritor de implementação <data-source>.

Os aplicativos devem procurar referências de recursos em vez de procurar definições de origens de dados diretamente. Se estiver instalando um aplicativo existente que contém consultas diretas a uma definição de origem de dados e desejar que ele use outra definição de origem de dados, é possível substituir a definição de origem de dados por uma ligação que resolva para um recurso gerenciado criado. Crie a ligação incluindo o seguinte elemento no arquivo de ligação:
<data-source name="name" binding-name="lookupName"/> 
em que name é o nome de env-entry conforme definido no aplicativo e lookupName é um nome JNDI que resolve, quando aplicado a uma consulta no contexto inicial padrão. Por exemplo,
<data-source name="java:module/env/myDS" binding-name="jdbc/DB2DS"/>
consultas de causa em "java:module/env/myDS" para resolver a origem de dados limitada com o nome "jdbc/DB2DS", relativa ao contexto inicial padrão. O limite da origem de dados em jdbc/DB2DS pode ser criado, por exemplo, por meio do console administrativo.

As origens de dados podem ser definidas no nível do aplicativo e no EJB, na web e nos módulos do cliente. Estes níveis correspondem aos arquivos de ligação application-bnd.xml, ejb-jar-bnd.xml, web-app-bnd.xml e application-client-bnd.xml.

Considerações sobre Nomenclatura em Ambientes em Cluster e de vários Servidores

As convenções de nomenclatura JNDI global clássicas nas seções anteriores se aplicam em ambientes não armazenados em cluster e quando o destino de consulta está dentro do mesmo cluster que a origem da consulta. Quando uma consulta é feita de fora de um cluster em uma ligação que está dentro de um determinado cluster, a cadeia de consulta deve estar qualificada para indicar o nome do cluster no qual o destino reside, de acordo com a seguinte convenção:
cell/clusters/<cluster-name>/<name-binding-location>   
Por exemplo, dado um local de ligação da interface EJB dentro do contexto raiz do servidor de aplicativos:
ejb/Department549/AccountProcessors/CheckingAccountReconciler  
Se o EJB implementando essa interface for designado a um servidor de aplicativos que é membro de um cluster denominado Cluster47, a cadeia de consulta externa para esse cluster será a seguinte:
cell/clusters/Cluster47/ejb/Department549/AccountProcessors/CheckingAccountReconciler
Quando uma consulta é feita através de processos do servidor de aplicativos, a cadeia de consulta deve estar qualificada para indicar o nome do nó no qual o destino reside, de acordo com a seguinte convenção:
cell/nodes/<node-name>/servers/<server-name>/<name binding location> 
Mais uma vez, dado um local de ligação da interface EJB dentro do contexto raiz do servidor de aplicativos:
ejb/Department549/AccountProcessors/CheckingAccountReconciler 
Se o enterprise bean que está implementando essa interface for designado a um servidor de aplicativos denominado Server47A1 que está localizado em um nó chamado S47NLA1, a cadeia de consulta de vários servidores será a seguinte:
cell/nodes/S47NLA1/servers/Server47A1/ejb/Department549/AccountProcessors/CheckingAccountReconciler 

Configurações de Extensões EJB Definidas pelo Usuário

Para casos em que você quer especificar valores para configurações de Extensão de EJB para WebSphere Application Server, é possível usar um arquivo de extensão de módulo EJB para designar essas configurações a tipos de EJB específicos dentro desse módulo. Especifique informações de configuração de extensão para módulos EJB 3.x colocando um dos, ou os dois, arquivos no diretório META-INF para o arquivo JAR EJB, dependendo do tipo de extensão sendo definido. Os nomes dos dois arquivos são ibm-ejb-jar-ext.xml e ibm-ejb-jar-ext-pme.xml.

Nota: O sufixo nesses arquivos são XML, não XMI como em versões anteriores do WebSphere Application Server.
Os arquivos ibm-ejb-jar-ext.xml e ibm-ejb-jar-ext-pme.xml são usados pelos módulos EJB 3.x em execução em WebSphere Application Server, enquanto os arquivos ibm-ejb-jar-ext.xmi e ibm-ejb-jar-ext-pme.xmi são usados para módulos EJB pré-3.0. O WebSphere Application Server Versão 8.0 usa um novo formato de arquivo de extensão baseado em XML em vez do formato de arquivo .xmi anterior pelos seguintes motivos:
  1. Ligações e extensões declaradas no formato do arquivo xmi dependem da presença de um arquivo do descritor de implementação ejb-jar.xml correspondente que se refira explicitamente aos números do ID exclusivo anexados aos elementos nesse arquivo. Esse sistema não é mais viável para módulos EJB 3.0 ou posteriores, já que não é mais um requisito que o módulo contenha um descritor de implementação ejb-jar.xml.
  2. O formato de arquivo xmi foi projetado para ser editado por máquina apenas pelas ferramentas de desenvolvimento do WebSphere e pelas funções de gerenciamento de sistemas; ele era efetivamente parte da implementação interna do WebSphere e a estrutura do arquivo nunca foi documentada externamente. Isso impossibilitou que os desenvolvedores criassem ou editassem manualmente os arquivos de ligação ou de extensão, ou os criassem como parte de um processo de construção independente do WebSphere, de maneira suportada.
  3. Em vez de se referir aos números de ID codificados no ejb-jar.xml, o formato de arquivo de extensão baseado em XML refere-se a componentes EJB por seu nome EJB. É garantido que cada componente EJB em um módulo tenha um nome EJB exclusivo, por padrão ou através da designação explícita feita pelo desenvolvedor, portanto, isso oferece uma forma ambígua de destinar ligações e extensões.
  4. Os novos arquivos de ligação e extensão são baseados em XML e arquivos XML Schema Definition (xsd) são fornecidos para documentar a estrutura externamente. Esses arquivos .xsd podem ser consumidos por vários editores de arquivo XML comuns para ajudar nas funções de verificação sintática e de conclusão de código. Como resultado, agora é possível para os desenvolvedores produzirem e editarem esses arquivos de ligação e extensão, independentemente da infraestrutura do WebSphere Application Server, usando um editor XML genérico ou sistema de script de sua escolha.

Extensões Definidas no META-INF/ibm-ejb-jar-ext.xml

As tabelas a seguir descrevem os elementos e atributos de extensão que devem ser colocados no arquivo META-INF/ibm-ejb-jar-ext.xml . A seção subsequente lista os elementos e atributos que aparecem em um arquivo separado, META-INF/ibm-ejb-jar-ext-pme.xml.
Tabela 4. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml
Elemento ou Atributo Descrição Exemplo: Notas sobre a Utilização
<session> Declara um grupo de configurações de extensão para um bean de sessão.
<session name="AccountServiceBean"/>
Requer o atributo name. Para obter algum efeito, inclua também pelo menos um subelemento de definição de configuração da extensão.
<message-driven> Declara um grupo de configurações de extensão para um bean acionado por mensagens.
<message-driven name="EventProcessorBean"/>
Requer o atributo name. Para obter algum efeito, inclua também pelo menos um subelemento de definição de configuração da extensão.
Tabela 5. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml
Elemento ou Atributo Descrição Exemplo: Notas sobre a Utilização
<time-out> Subelemento para o elemento <session> que, opcionalmente, declara o número de segundos entre chamadas de método após os quais um bean de sessão stateful pode não estar mais disponível.
<session
 name="ShoppingCartBean">
 <time-out value="600"/>
</session>
Requer o atributo value, um número inteiro positivo.
Nota: Aplicável somente a beans de sessão stateful; não deve ser usado em beans stateless.

Padrão de atributo: 300 (5 minutos)

<bean-cache> Subelemento do elemento <session> usado para declarar configurações de ativação/passivação de bean para beans de sessão stateful.
<session
 name="ShoppingCartBean">
 <bean-cache
  activation-policy="TRANSACTION"/>
</session>
Para que entre em vigor, inclua também o atributo activation-policy .
activation-policy Atributo do elemento <bean-cache> que declara as condições sob as quais a instância de bean pode ser ativada e passivada. Aplica-se a beans de sessão com preservação de estado. Os valores permitidos e seus significados são:
  • TRANSACTION: Indica que o bean é ativado no início de uma transação e passivado (é removido do cache de instância EJB ativo) no final da transação.
  • ONCE: Indica que o bean é ativado quando é acessado pela primeira vez no processo do servidor e passivado (é removido do cache de instância EJB ativo) a critério do contêiner, por exemplo, quando o cache fica cheio.
  • ACTIVITY_SESSION: Indica que um bean é ativo e passivo da seguinte forma:
    1. Em um limite do ActivitySession, se um contexto do ActivitySession estiver presente na ativação.
    2. Em um limite da transação, se um contexto da transação (mas nenhum contexto do ActivitySession) estiver presente na ativação, ou
    3. em um limite de chamada.
<session
 name="ShoppingCartBean">
 <bean-cache
  activation-policy="ONCE"/>
</session>
Padrão de atributo: ONCE para beans de sessão stateful.
Tabela 6. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml
Elemento ou Atributo Descrição Exemplo Notas sobre a Utilização
<global-transaction> Subelemento para os elementos <session> e <message-driven> que podem ser usados para declarar o tempo limite da transação (em segundos) a ser usado em transações iniciadas por este tipo específico de EJB (substituindo a configuração do servidor para tempo limite de transação global) e também pode declarar se o tipo de EJB propaga contexto de transação global recebido por meio de transações atômicas de serviço da web, em um ambiente de serviço da web heterogêneo.
<session
 name="AccountServiceBean"
 <global-transaction
  <global-transaction
 transaction-time-out="180" 
  send-wsat-context="FALSE"/>
</session>
Requer pelo menos um dos atributos transaction-time-out ou send-wsat-context.

Atributo padrão: Configuração de tempo limite de transação do servidor para transaction-time-out ; FALSE para send-wsat-context

<local-transaction> Subelemento dos elementos <session> e <message-driven> que pode ser usado para declarar configurações relacionadas a transações locais. Os atributos suportados são boundary, resolver e unresolved-action; esses atributos configuram, para o componente, o comportamento do ambiente local transaction containment (LTC) do contêiner que o contêiner estabelece sempre que não há uma transação global presente. O significado de cada atributo é o seguinte:

Limite

Essa configuração especifica o limite de contenção no qual todas as RMLTs (Resource Manager Local Transactions) contidas devem ser concluídas. Os valores possíveis são:
  • BEAN_METHOD: Esse é o valor padrão. Se você selecionar essa opção, RMLTs devem ser resolvidos dentro do mesmo método do bean no qual foram iniciados.
  • ACTIVITY_SESSION: RMLTs devem ser resolvidas dentro do escopo de qualquer ActivitySession em que foram iniciados ou, se nenhum contexto ActivitySession estiver presente, dentro do mesmo método do bean no qual foram iniciados.

Resolver

Essa configuração especifica o componente responsável por iniciar e finalizar RMLTs. Os valores possíveis são:
  • APPLICATION: Esse é o valor padrão. O aplicativo é responsável por iniciar RMLTs e concluí-las dentro do limite de LTC (contenção da transação local). Qualquer RMLT que não esteja concluída no final do limite de LTC será limpa pelo contêiner, de acordo com o valor do atributo Ação Não Resolvida.
  • CONTAINER_AT_BOUNDARY: O contêiner é responsável por iniciar RMLTs e concluí-los dentro do limite de LTC. O contêiner inicia uma RMLT quando uma conexão é utilizada primeiramente dentro do escopo de LTC e a conclui automaticamente no final do escopo de LTC. Se o atributo Limite estiver configurado como ActivitySession, as RMLTs serão inscritas como recursos ActivitySession e direcionadas para serem concluídas pela ActivitySession. Se o atributo Limite estiver configurado como BeanMethod, as RMLTs serão confirmadas no final do método por contêiner.

Unresolved Action

Essa configuração especifica a direção que o contêiner quer que seja seguida por RMLTs, caso essas transações não sejam resolvidas no final do escopo do limite do LTC e Resolver esteja configurado como Application. Os valores possíveis são:
  • ROLLBACK: Esse é o valor padrão. No final do escopo do limite de LTC, o contêiner instrui todas as RMLTs não resolvidas para serem recuperadas.
  • COMMIT: No final do escopo do limite do LTC, o contêiner instrui todas as RMLTs não resolvidas a consolidarem. O contêiner orienta que as RMLTs sejam confirmadas apenas na ausência de uma exceção não manipulada. Se o método de aplicativo que está sendo executado no contexto de transação local terminar com uma exceção, qualquer RMLT não resolvida será recuperada pelo contêiner. Esse é o mesmo comportamento das transações globais.
<session
 name>="AccountServiceBean">
 <local-transaction
  boundary="BEAN_METHOD" 
  resolver="APPLICATION" 
  unresolved-action="ROLLBACK"/>
</session>
Requer pelo menos um dos atributos boundary, resolver ou unresolved-action .
Padrão de atributo:
boundary="BEAN_METHOD";
resolver="APPLICATION";
unresolved-action=
"ROLLBACK"
Tabela 7. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml. Elementos e Atributos do Arquivo META-INF/ibm-ejb-jar-ext.xml
Elemento ou Atributo Descrição Exemplo Notas sobre a Utilização
<method> Subelemento para os elementos <method-session-attribute> e <run-as-mode> que é usado para especificar o nome do método, assinatura de método ou tipos de métodos aos quais uma determinada configuração pode se aplicar. Os atributos suportados são type, name e params. Cada atributo é descrito da seguinte forma:

type

  • UNSPECIFIED: A configuração se aplica a todos os métodos que correspondem aos atributos name e params, independentemente do tipo de interface.
  • REMOTE: A configuração aplica-se aos métodos de interface de negócios remota e de interface de componente remota correspondentes ao nome e aos atributos params.
  • LOCAL: A configuração aplica-se à interface de negócios local, aos métodos de interface de componente local e às visualizações sem interface que correspondem ao atributo de nome, atributo params ou ambos.
  • HOME: A configuração aplica-se aos métodos de interface inicial remota correspondentes aos atributos de nome e params correspondentes aos atributos de nome e parms.
  • LOCAL_HOME: A configuração aplica-se aos métodos de interface inicial local correspondentes aos atributos de nome e params.
  • SERVICE_ENDPOINT: A configuração aplica-se aos métodos na interface do terminal em serviço JAX-RPC correspondentes aos atributos de nome e params.

nome

O nome do método ao qual a configuração é aplicada, ou um asterisco (*), se a configuração tiver que ser aplicada a todos os métodos, independentemente do nome.

params

A assinatura do parâmetro do método ao qual a configuração é aplicada. Ela pode ser utilizada para qualificar exclusivamente um determinado método nos casos em que mais de um método utilizam o mesmo nome. A assinatura do parâmetro é uma lista separada por vírgula de tipos Java. Os tipos primitivos são especificados usando-se apenas seus nomes; os tipos não primitivos são especificados usando-se seus nomes de classe ou de interface completos, incluindo qualquer pacote Java, e as matrizes de tipos Java são especificadas pelo tipo do elemento de matriz seguido por um ou mais pares de colchetes quadrados (por exemplo, int[][]).

<session
 /name="AccountServiceBean">
 <method-session-attribute
  type="REQUIRES_NEW">
 <method
  type="LOCAL"
  name="debitAccount" 
  params="java.lang.String[], int,
     com.xyz.CustomerInfo"/>
 </method-session-attribute;>
</session>
 
<run-as-mode> Subelemento para os elementos <session> e <message-driven> que pode ser usado para declarar a identidade de segurança que um determinado método EJB usará ao chamar outro método. A identidade pode ser configurada para usar a identidade do responsável pela chamada (modo = CALLER_IDENTITY), a identidade do servidor EJB (modo = SYSTEM_IDENTITY) ou a identidade de uma função de segurança específica (modo = SPECIFIED_IDENTITY).
<session
 name="AccountServiceBean">
 <run-as-mode
   mode="SPECIFIED_IDENTITY">
 <specified-identity
   role="admin"/>
 <method type="UNSPECIFIED" 
   name="testRunAsRole"/>
 </run-as-mode>
</session>
Requer o atributo de modo e o subelemento <method>. Se o modo for SPECIFIED_IDENTITY, o subelemento <specified-identity também será necessário.
<start-at-app-start> Subelemento para os elementos <session> e <message-driven> que pode ser usado para informar o contêiner EJB que o tipo de EJB especificado pode ser inicializado no momento em que o aplicativo é iniciado a primeira vez, em vez do momento em que o tipo de EJB é usado a primeira vez pelo aplicativo.
<session
 name="AccountServiceBean">
 <start-at-app-startvalue="TRUE"/>
</session>
Requer atributos de valor.

Padrão de atributo: FALSE (inicializar tipo EJB quando o EJB é utilizado pela primeira vez pelo aplicativo) para beans que não sejam acionados por mensagens. Sempre TRUE para beans acionados por mensagens.

<resource-ref> Subelemento para os elementos <session> e <message-driven>, que pode ser usado para declarar configurações adicionais em uma referência de recurso Java EE, como um nível de isolamento a ser usado em transações orientadas por meio da conexão referida pela referência. Os atributos permitidos incluem isolation-level. Os atributos são definidos da seguinte maneira:
isolation-level
  • TRANSACTION_REPEATABLE_READ: Esse nível de isolamento proíbe leituras sujas e não repetíveis, mas permite leituras fictícias.
  • TRANSACTION_READ_COMMITTED: Esse nível de isolamento proíbe leituras sujas, mas permite leituras não repetíveis e leituras fictícias.
  • TRANSACTION_READ_UNCOMMITTED: Esse nível de isolamento permite leituras de alterações não consolidadas (dados alterados por uma transação diferente que ainda está em progresso). Também permite leituras sujas, não repetíveis e fictícias.
  • TRANSACTION_SERIALIZABLE: Esse nível de isolamento proíbe os seguintes tipos de leituras:
    1. Leituras sujas, em que uma transação lê uma linha do banco de dados contendo mudanças não confirmadas a partir de uma segunda transação.
    2. Leituras não repetidas, em que uma transação lê uma linha, uma segunda transação altera a mesma linha e a primeira transação lê novamente a linha e obtém um valor diferente, e
    3. Leituras fantasmas, em que uma transação todas as linhas que atendem a uma condição SQL WHERE, uma segunda transação insere uma linha que também atende à condição WHERE e a primeira transação aplica a mesma condição WHERE e obtém a linha inserida pela segunda transação.
  • TRANSACTION_NONE: Esse nível de isolamento indica que transações não são suportadas nesse tipo de recurso.
<session
 name="AccountServiceBean">
 <resource-ref
  name="jdbc/Default" 
  isolation-level="TRANSACTION_NONE">
</session>
Requer o atributo name. Para que entre em vigor, inclua também o atributo isolation-level.

Extensões definidas no arquivo META-INF/ibm-ejb-jar-ext-pme.xml

As tabelas a seguir listam os atributos e elementos de extensão que devem ser colocados no arquivo META-INF/ibm-ejb-jar-ext-pme.xml.
Tabela 8. Extensões Definidas no META-INF/ibm-ejb-jar-ext-pme.xml. Extensões Definidas no META-INF/ibm-ejb-jar-ext-pme.xml
Elemento ou Atributo Descrição Exemplo: Notas sobre a Utilização
<internationalization> Elemento que pode ser usado para declarar o código do idioma que poderá ser usado pelo tipo EJB (código do idioma do responsável pela chamada ou código do idioma do servidor).
<internationalization>
  <application>
   <ejb name="S01"/>
   <ejb name="S02"/>
  </application>
  <run-as-caller>
   <method type="LOCAL" name="getFoo" params="int">
     <ejb name="C01"/>
   </method>
  </run-as-caller>
  <run-as-server>
   <method type="LOCAL" name="getBar" params="int">
    <ejb name="C02"/>
   </method>
  </run-as-server>
  <run-as-specified name="North American English">
   <locale lang="en" country="US" variant="foo"/>
   <locale lang="en" country="CA" variant="bar" /> 
   <time-zone name="GMT"/> 
   <method type="LOCAL" name="getFoo" params="int"> 
    <ejb name="C03"/>
   </method>
  </run-as-specified>
  <run-as-specified name="North American French"> 
   <locale lang="fr" country="US" variant="foo"/>
   <locale lang="fr" country="US" variant="bar" /> 
   <time-zone name="GMT"  /> 
   <method type="LOCAL" name="getBar" params="int"> 
   <ejb name="C04"/>
   </method>
  </run-as-specified>
</internationalization>
Para obter informações sobre esta extensão, consulte Atributos de internacionalização do contêiner: WebSphere Application Server.

Devido à complexidade dessa função, talvez queira usar a ferramenta projetada para o WebSphere Application Server, como o Rational Application Developer, para produzir as sub-rotinas do arquivo de extensão desejadas e, em seguida, modificar o arquivo XML como desejar.

<activity-sessions> Elemento que, opcionalmente, declara o tipo de gerenciamento de sessões de atividade a ser utilizado em um bean de sessão designado (BEAN ou CONTÊINER) e, para sessões de atividade gerenciadas por contêiner, o tipo de comportamento de sessão de atividade a ser fornecido pelo contêiner.
<activity-sessions>
 <container-activity-session 
  name="Foo" type="NOT_SUPPORTED">
  <methodtype="HOME" name="findByPrimaryKey"
    params="int">
   <ejb name="C01"/>
  </method>
 </container-activity-session>
<./activity-sessions>
Para obter informações sobre esta extensão, consulte Configurando atributos de implementação ActivitySession do módulo EJB.

Devido à complexidade dessa função, talvez queira usar a ferramenta projetada para o WebSphere Application Server, como o Rational Application Developer.

<app-profiles> Elemento que, opcionalmente, declara as configurações de perfil do aplicativo para um ou mais arquivos EJB.
<app-profiles>
 <defined-access-intent-policy name="foo">
  <collection-scope type"SESSION"/>
  <optimistic-read/>
  <read-ahead-hint hint="foo.bar.baz"/>
 </defined-access-intent-policy>
 <run-as-task 
  name="TestEJB1.ejbs.C01LocalHome.createjava.lang.Integer" 
  type="RUN_AS_SPECIFIED_TASK">
  <task name=“/>
  <method type="LOCAL" name="getFoo" params="int">
   <ejb name="C01"/>
  </method>
 </run-as-task>
 <ejb-component-extension ejb="C01"> 
  <task name="SomeTask"/>
 </ejb-component-extension>
</app-profiles>
Devido à complexidade dessa função, talvez queira usar a ferramenta projetada para o WebSphere Application Server, como o Rational Application Developer, para produzir as sub-rotinas do arquivo de extensão desejadas e, em seguida, modificar o arquivo XML como desejar.

Ligações Legadas (XMI)

Módulos e aplicativos existentes podem continuar utilizando o suporte à ligação legada fornecido no produto, portanto, as ferramentas e os assistentes existentes podem ser utilizados para especificar informações de ligação e de extensão para aplicativos e módulos. O uso do suporte legado é limitado aos módulos e arquivos EAR utilizando-se descritores de implementação XML do estilo J2EE 1.4.

Módulos EJB que usam um esquema de descritor de implementação versão 3.x ou não têm um arquivo descritor de implementação XML devem usar ligações padronizadas e AutoLink ou arquivos de ligação XML especificados pelo usuário.

É necessário que beans de entidade CMP sejam sempre empacotados em um módulo com um esquema de descritor de implementação XML versão 2.1 para que ferramentas existentes possam ser utilizadas para fornecer suporte a mapeamentos, ligações e extensão.

Ligações XML Especificadas pelo Usuário

As ligações padrão para cada interface e resolução de referência de AutoLink para cada referência podem ser substituídas especificando-se ligações para o módulo EJB criando-se um arquivo META-INF/ibm-ejb-jar-bnd.xml.

Os arquivos de esquema que descrevem o formato estão localizados no diretório <WAS_HOME>/properties/schemas. Esse formato de especificação de ligações pode ser utilizado apenas para módulos não contendo um descritor de implementação XML ou um descritor de implementação EJB 3.x.
Nota: Não é necessário especificar todas as ligações. Qualquer referência ou nome de ligação que não estejam definidos utilizam o suporte padrão para ligações e AutoLink.
Ligações podem ser especificadas para os seguintes beans:
  • Os beans de sessão que usam o elemento <session>.
  • Os beans acionados por mensagem que usam o elemento <message-driven>
Os únicos atributos e subelementos suportados para o elemento <sessão> são:
  • Atributo id
  • Atributo name
  • Atributo simple-binding-name
  • Atributo component-id
  • Elemento ejb-ref
  • Elemento resource-ref e seus atributos
  • Elemento resource-env-ref e seus atributos
  • Elemento message-destination-ref e seus atributos
  • Elemento env-entry
  • Elemento data-source
Os únicos atributos e subelementos suportados para o elemento <message-driven> são:
  • Atributo id
  • Atributo name
  • Atributo jca-adapter
  • Elemento ejb-ref e seus atributos
  • Elemento resource-ref e seus atributos
  • Elemento resource-env-ref e seus atributos
  • Elemento message-destination-ref e seus atributos
  • Elemento env-entry
  • Elemento data-source

Ícone que indica o tipo de tópico Tópico de Conceito



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=cejb_bindingsejbfp
Nome do arquivo: cejb_bindingsejbfp.html