WebSphere Message Broker, Versão 8.0.0.5 Sistemas operacionais: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

Consulte as informações sobre a versão mais recente do produto em IBM Integration Bus, Versão 9.0

DatabaseRetrieve

Utilize o nó DatabaseRetrieve para assegurar que as informações em uma mensagem estejam atualizadas.

Este tópico contém as seguintes seções:

Propósito

Utilize o nó DatabaseRetrieve para modificar a mensagem utilizando informações de um banco de dados. Por exemplo, você pode incluir informações em uma mensagem utilizando uma chave que está contida em uma mensagem; a chave pode ser um número de conta.

O nó DatabaseRetrieve está contido no repositório do Banco de Dados da paleta do nó do fluxo de mensagens e é representado no WebSphere® Message Broker Toolkit pelo seguinte ícone:

Ícone do nó DatabaseRetrieve

Utilizando Este Nó em um Fluxo de Mensagens

Examine a amostra a seguir para ver como utilizar esse nó:

Você só pode visualizar informações sobre amostras quando usa o centro de informações que está integrado ao WebSphere Message Broker Toolkit ou o centro de informações on-line. Você só poderá executar amostras quando usar o centro de informações que está integrado ao WebSphere Message Broker Toolkit.

Os valores dos parâmetros de entrada que são necessários de elementos de mensagens na mensagem de entrada são suportados para inserção nas instruções preparadas que são utilizadas por esse nó. Esses valores são adquiridos de elementos nome, valor e nome-valor na mensagem de entrada analisada que chega. Os elementos são adquiridos inicialmente no formato de um objeto com.ibm.broker.plugin.MbElement, portanto, o intervalo de tipos de objetos Java™ suportados que os valores podem assumir é gerido pela interface desse objeto. Quando valores estão no formato de tipos primitivos Java ou Objetos, eles são convertidos em seus tipos de dados JDBC equivalentes, conforme mostrado na tabela a seguir.
Componente JDBC
Número Inteiro INTEGER
Longo BIGINT
Double DOUBLE
BigDecimal NUMERIC
Boolean BIT
byte[] VARBINARY ou LONGVARBINARY
BitSet VARBINARY ou LONGVARBINARY
Cadeia VARCHAR ou LONGVARCHAR
MbTime java.sql.Time
MbTimestamp java.sql.Timestamp
MbDate java.sql.Date
Os valores são utilizados de um elemento somente se o elemento for de um tipo conhecido e o estado do valor for válido, caso contrário, uma exceção é emitida. Os valores da coluna Saída que são adquiridos no conjunto de resultados de consultas SQL que são realizadas por esse nó são convertidas primeiro para tipos Java correspondentes, em seguida, em tipos de valores internos de elementos da mensagem, conforme mostrado na tabela a seguir.
JDBC Java Tipo ESQL
SMALLINT Inteiro INTEGER
INTEGER Número Inteiro INTEGER
BIGINT Longo DECIMAL
DOUBLE Dupla FLOAT
REAL Dupla FLOAT
FLOAT Double FLOAT
NUMERIC BigDecimal DECIMAL
DECIMAL BigDecimal DECIMAL
BIT Booleana BOOLEAN
BOOLEAN Boolean BOOLEAN
BINARY byte[] BLOB
VARBINARY byte[] BLOB
LONGVARBINARY byte[] BLOB
CHAR String CHARACTER
VARCHAR String CHARACTER
LONGVARCHAR Cadeia CHARACTER
TINYINT byte[1] BLOB
TIME java.util.Date TIME
TIMESTAMP java.util.Date TIMESTAMP
DATE java.util.Date DATE
É possível rotear uma mensagem para o mesmo local, se uma consulta for bem sucedida com relação ao banco de dados especificado, conectando ambos os terminais de saída que não são de falhas ao mesmo local de saída.

Se for localizado um erro na expressão XPath de um padrão, ele será relatado durante a validação no WebSphere Message Broker Toolkit. A mensagem de erro relatada pode incluir a cadeia da expressão incorreta e seu nome de terminal estático ou dinâmico exclusivo associado ou a cadeia pode ser marcada como um broker na tabela.

O nó DatabaseRetrieve consulta valores de um banco de dados e os armazena como elementos nas árvores de montagem de mensagem de saída. O tipo de informação que é obtido do banco de dados no formulário de valores de coluna de saída, que é adquirido e transmitido de volta no conjunto de resultados das consultas SQL, é convertido primeiro em um tipo Java correspondente, em seguida, em um tipo de valor de elemento de mensagem interno quando ele é finalmente armazenado em um local em uma árvore de montagem de mensagem de saída. Se um elemento de mensagem já existir na árvore de mensagens de saída, o novo valor grava o valor antigo. Se o elemento de destino não existir, é criado e o valor é armazenado.

O nó precisa consultar informações que são utilizadas para formar uma consulta SQL select, que pode acessar diversas tabelas de um banco de dados utilizando diversas condições de teste. Às vezes, nem todas as informações que deseja recuperar em um conjunto de resultados está em uma única tabela de banco de dados. Para obter os valores de coluna que você deseja, você pode precisar recuperá-los de duas ou mais tabelas. Esse nó suporta a utilização de instruções SELECT que facilitam a obtenção de colunas de uma ou mais tabelas em um único conjunto de resultados. A sintaxe de junção normal que é suportada também é referida como uma junção interna.

As informações da junção interna que são coletadas para formar uma consulta incluem uma lista de valores de coluna qualificados da tabela a serem recuperados e uma lista de condições de teste, que formam a cláusula WHERE da instrução SELECT. Os valores de coluna qualificados da tabela podem formar o operando esquerdo em uma condição de teste. Escolha um operador de comparação a aplicar a esse operando e, opcionalmente, especifique um operando à direita para completar a condição de teste. O operador pode ser um teste de comparação nulo, caso no qual um operando à direita não é necessário. O valor do operando à direita pode ser um tipo de banco de dados (como Inteiro, Booleano ou Longo), outra coluna qualificada da tabela ou um valor que seja adquirido de um elemento na mensagem de entrada, conforme expresso através da expressão geral XPath 1.0.

O aplicativo da expressão deve resultar em um único elemento, double, Boolean ou sendo retornado, caso contrário, uma exceção ocorrerá. Se a consulta retornar diversas linhas, a primeira linha é escolhida e as restantes são ignoradas, a menos que a opção Diversas Linhas esteja selecionada. Nesse caso, todas as linhas são processadas e os valores dessas linhas são utilizados para atualizar as árvores de montagem da mensagem de saída.

Pode ser útil combinar um nó DatabaseRetrieve com outros nós do fluxo de mensagens. Por exemplo, você pode utilizar um nó XSLTransform para manipular dados antes ou após a chamada do nó DatabaseRetrieve.

O nó DatabaseRetrieve possui um terminal de entrada (In) e três terminais de saída (Out, KeyNotFound e Failure). Se a mensagem for modificada com êxito, ela será roteada para o terminal Out. Se a mensagem não for modificada com êxito ou uma falha for detectada durante o processamento, a mensagem é roteada para o terminal Failure. Se nenhuma linha for retornada no conjunto de resultados após a execução de uma consulta de seleção SQL especificada, a mensagem original será roteada para ao terminal KeyNotFound.

Disponibilizando o Serviço do Provedor JDBC para o Nó DatabaseRetrieve

O nó DatabaseRetrieve constrói suas conexões JDBC utilizando detalhes da conexão que estão armazenados no registro do broker como um serviço configurável. Os serviços configuráveis do JDBCProvider são fornecidos para todos os bancos de dados suportados.

Use o WebSphere Message Broker Explorer para modificar ou criar o serviço fornecido; consulte Usando o WebSphere Message Broker Explorer para Trabalhar com Serviços Configuráveis para obter informações adicionais.

Também é possível usar o comando mqsichangeproperties para modificar as configurações do serviço fornecido do banco de dados escolhido ou criar um novo serviço usando o comando mqsicreateconfigurableservice. Consulte Configurando um Provedor JDBC para Conexões Tipo 4 para obter informações e assistência adicional sobre como trabalhar com serviços do JDBCProvider. Você deve configurar um serviço de JDBCProvider diferente para cada banco de dados ao qual você deseja se conectar.

Nota: A propriedade maxConnectionPoolSize não se aplica às conexões JDBC usadas pelos nós DatabaseRetrieve ou DatabaseRoute.

Quando você tiver definido o serviço, configure a propriedade Nome da Origem de Dados deste nó com o nome do serviço JDBCProvider; os atributos do serviço são utilizados para estabelecer conexões para o nó DatabaseRetrieve.

Você deve parar e reiniciar o broker para que suas alterações tenham efeito, a menos que tenha a intenção de criar um novo grupo de execução no broker para o qual implementará o fluxo de mensagens que contém esse nó.

Usando a Visualização Data Source Explorer para Consultar Origens de Dados

Use a visualização Data Source Explorer para descobrir os nomes das tabelas em um banco de dados de destino e os nomes de quaisquer colunas dessas tabelas. Você deve importar definições de banco de dados de seus bancos de dados para o WebSphere Message Broker Toolkit antes de visualizá-las na visualização Data Source Explorer.
  1. Alterne para o Perspectiva do Desenvolvimento de Aplicativos do Intermediário.
  2. Na visualização Data Source Explorer, expanda Conexões. As conexões com o banco de dados são listadas.
  3. Expanda uma conexão com o banco de dados para listar os bancos de dados, em seguida, expanda o banco de dados apropriado.
  4. Expanda Esquemas para listar os esquemas, em seguida, expanda o esquema apropriado.
  5. Expanda Tabelas para listar todas as tabelas.
  6. Clique em uma tabela para mostrar suas propriedades na visualização Propriedades.
  7. Na visualização Propriedades, clique na guia Colunas para visualizar os nomes de colunas.

Configurando o Nó DatabaseRetrieve

Quando tiver colocado uma instância do nó DatabaseRetrieve em um fluxo de mensagens, você poderá configurá-lo. Para obter informações adicionais, consulte Configurando um Nó do Fluxo de Mensagens. As propriedades do nó são exibidas na visualização Propriedades.

Todas as propriedades obrigatórias para as quais é necessário digitar um valor (aquelas que não têm um valor padrão definido) são marcadas com um asterisco.

Exemplo

O exemplo a seguir inclui novos elementos (nome de família e salário) na estrutura da mensagem de entrada. Este exemplo utiliza uma tabela de banco de dados chamada Employee.
EmployeeNumber FamilyName FirstName Salary
00001 Smith John 20000
00002 Jones Harry 26000
00003 Doe Jane 31000
Para fazer uma cópia da mensagem que chega, selecione Copiar Mensagem. Quando essa propriedade é selecionada, o nós sempre cria uma montagem de mensagem de saída que é baseada na montagem da mensagem que chega e essas árvores da nova montagem de mensagem de saída são modificadas e propagadas para o terminal Out do nó. Esse comportamento permite a modificação da própria árvore de mensagens de saída ($OutputRoot), além das outras árvores lógicas da montagem da mensagem: $OutputLocalEnvironment, $OutputDestinationList, $OutputExceptionList e $Environment. Se as árvores lógicas apenas na montagem da mensagem precisarem ser modificadas por este nó, por motivos de desempenho não selecione Copiar Mensagem. Quando essa propriedade não for selecionada, o nó sempre funciona em relação à montagem da mensagem que chega original e espera que nenhuma atualização seja tentada na árvore de mensagens. Se uma expressão XPath na tabela Elementos de Dados tentar atualizar esta árvore de mensagens através de uma referência para $OutputRoot, ocorrerá uma MbReadOnlyMessageException. A mensagem que chega é:
<EmployeeRecord>
	<EmployeeNumber>00001</EmployeeNumber>
</EmployeeRecord>
A seguir há um exemplo da tabela Elementos da Consulta.
Nome da tabela Nome da Coluna Operador Tipo do Valor Valor
Employee FamilyName      
Employee Salary      
Employee EmployeeNumber = Elemento $InputRoot/XMLNSC/EmployeeRecord/EmployeeNumber
A seguir há um exemplo da tabela Elementos de Dados.
Nome da Coluna Elemento de Mensagem
Employee.FamilyName $OutputRoot/XMLNSC/EmployeeRecord/FamilyName
Employee.Salary $OutputRoot/XMLNSC/EmployeeRecord/Wage
O nó DatabaseRetrieve conecta a tabela de banco de dados Employee e extrai o valor a ser comparado de cada mensagem que chega. A expressão XPath utilizada para navegar para o corpo da mensagem é $InputBody/EmployeeRecord/EmployeeNumber. A consulta SQL é:
SELECT Employee.FamilyName, Employee.Salary
FROM Employee
WHERE EmployeeNumber=?
ORDER BY Employee.FamilyName ASC, Employee.Salary ASC
em que ? é o valor recuperado a partir da mensagem que chega, que é localizado através da propriedade Valor na terceira linha da tabela de elementos da Consulta, que possui um Tipo de Valor igual a Elemento.
  • Se o valor neste local for 00001, as informações para John Smith serão recuperadas. A primeira linha do elemento de dados indica obter o valor da coluna FamilyName que é retornado da consulta e inseri-lo em um novo elemento denominado "FamilyName" em EmployeeRecord. A segunda linha do elemento de dados indica obter o valor da coluna Salary retornada da consulta e inseri-lo em um novo elemento denominado "Wage" sob EmployeeRecord. A mensagem de saída resultante é:
    <EmployeeRecord>
    	<EmployeeNumber>00001</EmployeeNumber>
    	<FamilyName>Smith</FamilyName>
    	<Wage>20000</Wage>
    </EmployeeRecord>
  • Se o valor neste local for 00002, as informações para Harry Jones serão recuperadas. A mensagem de saída resultante é:
    <EmployeeRecord>
    	<EmployeeNumber>00002</EmployeeNumber>
    	<FamilyName>Jones</FamilyName>
    	<Wage>26000</Wage>
    </EmployeeRecord>
Se você selecionar a propriedade Várias Linhas e os detalhes de ambos os funcionários forem retornados a partir de uma consulta no formato de duas linhas no conjunto de resultados, a mensagem de saída resultante será:
<EmployeeRecord>
	<EmployeeNumber>00001</EmployeeNumber>
	<FamilyName>Smith</FamilyName>
	<Wage>20000</Wage>
	<EmployeeNumber>00002</EmployeeNumber>
	<FamilyName>Jones</FamilyName>
	<Wage>26000</Wage>
</EmployeeRecord>

Validando Mensagens

Configure as propriedades de Validação para definir como a mensagem que é produzida pelo nó DatabaseRetrieve deve ser validada. Essas propriedades não fazem com que a mensagem de entrada seja validada. É esperado que, se tal validação for requerida, ela já tenha sido executada pelo nó input ou por um nó de validação anterior.

Para obter detalhes adicionais, consulte Validando Mensagens e Propriedades de Validação.

Terminais e Propriedades

Os terminais do nó DatabaseRetrieve são descritos na tabela a seguir.

Terminal Descrição
Entrada O terminal de entrada que aceita a mensagem para processamento pelo nó.
Out O terminal de saída para o qual a mensagem de saída será roteada quando tiver sido modificada com êxito.
KeyNotFound O terminal de saída para o qual a mensagem original é roteada, inalterada, quando o conjunto de resultados está vazio.
Falha O terminal de saída para o qual a mensagem será roteada se for detectado um defeito durante o processamento.

As tabelas a seguir descrevem as propriedades do nó. A coluna com cabeçalho M indica se a propriedade é obrigatória (marcada com um asterisco caso seja necessário digitar um valor quando nenhum padrão for definido); a coluna com cabeçalho C indica se a propriedade é configurável (você poderá alterar o valor quando incluir o fluxo de mensagens ao arquivo BAR para implementá-lo).

As propriedades Descrição do nó DatabaseRetrieve são descritas na tabela a seguir.
Propriedade M P Default Descrição
Nome do Nó Não Não DatabaseRetrieve O nome do nó.
Descrição curta Não Não   Uma breve descrição do nó.
Descrição Longa Não Não   Texto que descreve a finalidade do nó no fluxo de mensagens.
As propriedades Básicas do nó DatabaseRetrieve são descritas na tabela a seguir.
Propriedade M P Default Descrição Propriedade do Comando mqsiapplybaroverride
Nome da origem de dados Sim Sim DB2 O alias que é utilizado para localizar a definição do serviço de JDBCProvider que está armazenado no registro do broker. O alias é utilizado para localizar e construir a URL da conexão JDBC utilizada para conectar-se a um DBMS. A URL de conexão é específica do driver, mas inclui o nome do banco de dados ao qual se conectar.

Se a conexão com o banco de dados for feita por uma conta e senha de login, o nó também utilizará esta propriedade como uma chave de consulta, por meio da qual estes valores podem ser adquiridos de uma entrada DNS do registro do broker correspondente esperada.

Se o DBMS for protegido por senha, defina o parâmetro -n no comando mqsisetdbparms para a chave de segurança JDBC antes de implementar o fluxo de mensagens que contém este nó DatabaseRetrieve.

dataSource
Copiar mensagem Não Sim Desmarcada Essa propriedade indica se uma cópia da mensagem de entrada original é necessária, porque a árvore de mensagens deve ser atualizada, possivelmente em adição às árvores lógicas na montagem da mensagem. Por padrão, essa caixa de opções é limpa. Por motivos de desempenho, selecione esta propriedade somente se a mensagem de entrada for aumentada.  
Linhas múltiplas Não Sim Desmarcada Essa propriedade indica se todas as linhas são processadas quando uma consulta retorna diversas linhas. se você selecionar Diversas Linhas, todas as linhas são processadas e os valores dessas linhas são utilizados para atualizar as árvores de montagem da mensagem de saída. Se você não selecionar essa propriedade, a primeira linha é escolhida e as restantes são ignoradas.  
Consultar elementos Sim Não   Uma tabela de elementos de consulta que são utilizados para compor uma única instrução SQL select. A tabela consiste em cinco colunas e uma ou mais linhas. As colunas são Nome da Tabela, Nome da Coluna, Operador, Tipo de Valor e Valor. Essas cinco propriedades descrevem um elemento de consulta, indicando um valor de coluna qualificado da tabela a ser recuperado de um banco de dados. Nesse caso, o elemento forma parte das cláusulas SELECT e ORDER BY na consulta gerada. Caso contrário, o elemento da consulta age como uma condição de teste que forma um predicado na cláusula WHERE na consulta gerada.  
Nome da tabela Sim Não   O nome de uma tabela de banco de dados que forma parte da instrução SQL select, incluindo o nome do esquema; por exemplo, myschema.mytable.  
Nome da Coluna Sim Não   O nome da coluna na tabela de banco de dados a ser recuperada no conjunto de resultados, conforme qualificado pelo valor da propriedade Nome da Tabela property. Essa cláusula SELECT pode se referir a esse nome como um valor da coluna a retornar de uma consulta ou a ser referenciada em uma condição de teste na cláusula WHERE.  
Operador Sim Não   Um operador de comparação a aplicar a um operando à esquerda (a coluna da tabela que é especificada nas primeiras duas colunas da linha) e opcionalmente um valor a aplicar a um operando à direita. Se você especificar um valor de operador Ascendente 'ASC' ou Descendente 'DESC' para essa propriedade, essa linha significa a declaração de uma coluna qualificada de tabela que forma parte das cláusulas SELECT e ORDER BY na consulta gerada e, opcionalmente, pode ser referenciada em linhas futuras como um valor para um operando à direita.  
Tipo do Valor Sim Não   Um valor configurado para Nenhum ou que indique o tipo de valor que é expressado na última coluna dessa linha. Se essa propriedade não estiver configurada para Nenhum, ela refere-se a uma linha que descreve uma condição de teste na cláusula WHERE da instrução SQL select.  
Valor Sim Não   Um valor que é configurado como Nenhum ou que especifica um de um conjunto especificado de tipos de propriedades conforme expresso pela propriedade Tipo de Valor. Por exemplo, se a propriedade Tipo de Valor estiver definida como Elemento, a propriedade Valor coleta uma expressão XPath 1.0 geral. O valor que é retornado da expressão quando é aplicada à mensagem de entrada do nó é usado como valor do operando à direita a ser comparado nesse predicado. O valor comparado do operando à direita deve corresponder ao tipo que é recuperado para a coluna da tabela que é comparada em relação ao operando à esquerda. Expressões complexas são possíveis, quando zero ou mais valores podem ser adquiridos da mensagem que chega e manipulados para formarem um único valor de comparação. Por exemplo, a soma de diversos valores de campos na mensagem de entrada pode ser calculada por uma expressão geral apresentada para um tipo de valor Elemento.  
As propriedades da tabela Elementos de Dados nó do DatabaseRetrieve são descritas na tabela a seguir.
Propriedade M P Default Descrição
Elementos de dados Sim Não   Uma lista de elementos de dados. Um elemento de dados é descrito pelas propriedades Nome da Coluna e Elemento de Mensagem.
Nome da Coluna Sim Não   O nome da coluna do banco de dados da qual obter o valor do elemento. A lista de nomes é atualizada dinamicamente com base nas entradas de coluna que são inseridas na tabela de elementos de Consulta.
Elemento de Mensagem Sim Não   Uma expressão XPath 1.0 de caminho de leitura/gravação que descreve o local do caminho de um elemento de mensagem. O elemento de mensagem é onde o valor do banco de dados está armazenado. A expressão XPath deve ser avaliada como um único elemento na mensagem.

As propriedades Validação do nó DatabaseRetrieve são descritas na tabela a seguir.

Para obter uma descrição completa dessas propriedades, consulte Propriedades de Validação.
Propriedade M P Default Descrição
Validar Não Sim Nenhum(a) Essa propriedade controla se a validação ocorre. Os valores válidos são Nenhum, Conteúdo e Valor, Conteúdo e Herdar.
Ação de falha Não Não Exceção Essa propriedade controla o que acontecerá se uma falha de validação ocorrer. Você poderá configurar esta propriedade apenas se Validar estiver configurado como Conteúdo ou Conteúdo e Valor. Os valores válidos são Rastreio do Usuário, Registro de Erros Local, Exceção e Lista de Exceções.
As propriedades Monitoramento do nó são descritas na tabela a seguir.
Propriedade M P Default Descrição
Eventos Não Não Nenhum Eventos definidos para o nó são exibidos nesta guia. Por padrão, nenhum evento de monitoramento é definido em um nó do fluxo de mensagens. Utilize Incluir, Editar, e Excluir para criar, alterar ou excluir eventos de monitoração no nó; consulte Configurando fontes de eventos de monitoramento utilizando propriedades de monitoramento para detalhes.

É possível ativar e desativar eventos mostrados aqui selecionando ou desmarcando a caixa de opções Ativado.

Avisos | Marcas Registradas | Downloads | Biblioteca | Suporte | Feedback

Copyright IBM Corporation 1999, 2014Copyright IBM Corporation 1999, 2014.

        
        Última atualização:
        
        Última atualização: 2015-02-28 18:28:39


Tópico de ReferênciaTópico de Referência | Versão 8.0.0.5 | ac37390_