luciano silva

Na primeira parte, preparamos os arquivos de fault policy e a classe Java que irá receber as informações de falha para tratativa. Agora queremos adicionar os XMLs de fault ao MDS do SOA para facilitar a localização e manutenção destes arquivos, que poderão ser utilizados por todos os projetos SOA que forem tratar exceções.

Bem, uma vez que os arquivos de Fault Policy estejam concluídos (fault-policies.xml e fault-bindings.xml) você deverá empacotá-los em um arquivo Jar.

Crie um diretório qualquer chamado Fault_Policy_Arquivos, neste diretório iremos montar a estrutura que irá ser armazenada no MDS Database, então crie os sub-diretórios na estrutura abaixo:



No prompt de comando/terminal, vá até o diretório raiz e execute o comando para criação do arquivo Jar.

jar -cf blog-faultpolicy-MDS.jar ./apps/blog/fault/*.xml

Pronto, agora vamos fazer o deploy do arquivo blog-faultpolicy-MDS.jar com as estrutura do Fault Policy no MDS.
Acesse o Enterprise Manager do servidor, clique com o botão direito em soa-infra e depois vá para Administração e por fim clique em Configuração de MDS.

Na tela de Configuração de MDS, em Importar documentos de metadados de um arquivo, selecione o blog-faultpolicy-MDS.jar que acabamos de criar e clique no botão Importar. That’s all! Não é necessário reiniciar o Weblogic!

Para utilizar o fault policy no seu projeto SOA, edite o arquivo composite.xml e adicione os comandos baixo antes da tab component.

  <property name="oracle.composite.faultPolicyFile">oramds:/apps/blog/fault/fault-policies.xml</property>
  <property name="oracle.composite.faultBindingFile">oramds:/apps/blog/fault/fault-bindings.xml</property>

Isto é o suficiente para que seu projeto utilize o fault policy com Java Class Action, configurada no MDS.

Arquivos para Download:
Projeto Jdev (Exemplo de BPEL)
Estrutura de Diretórios para o MDS
Arquivo JAR para o MDS

Este exemplo esta dividido em duas partes, nessa primeira parte vou demonstrar como configurar os arquivos de Fault Policy chamando uma Java Class Custom como Action para o fault. Já na segunda parte vamos ver como adicionar a configuração ao MDS do SOA, facilitando o acesso e manutenção ao fault policy.

1. Definindo o Fault Policy

Vamos começar com o exemplo de configuração dos arquivos para o Fault Policy, veja a construção dos arquivos fault-policies.xml e fault-bindings.xml

Exemplo para o arquivo fault-policies.xml.

...
<Conditions>
      <faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
                 name="bpelx:remoteFault">
        <condition>
          <action ref="ora-custom-retry"/>
        </condition>
      </faultName>
      <faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
                 name="bpelx:bindingFault">
        <condition>
          <action ref="ora-custom-retry"/>
        </condition>
      </faultName>
    </Conditions>
    <Actions>
      <Action id="ora-custom-retry">
        <javaAction className="com.lucianosilva.lab.soa.CompositeFaultHandler"
                    defaultAction="ora-human-intervention">
            <returnValue value="ERROR" ref="ora-terminate"/>
            <returnValue value="ABORT" ref="ora-terminate"/>
            <returnValue value="RETRY" ref="ora-retry"/>
            <returnValue value="MANUAL" ref="ora-human-intervention"/>
        </javaAction>
      </Action>
            <Action id="ora-retry">
          <retry>
              <retryCount>2</retryCount>
              <retryInterval>3</retryInterval>
              <exponentialBackoff/>
          </retry>
      </Action>
      <Action id="ora-replay-scope">
          <replayScope/>
      </Action>
      <Action id="ora-rethrow-fault">
          <rethrowFault/>
      </Action>
      <Action id="ora-human-intervention">
          <humanIntervention/>
      </Action>
      <Action id="ora-terminate">
          <abort/>
      </Action>
    </Actions>
...

Definição do arquivo fault-bindings.xml.

<?xml version="1.0" encoding="UTF-8" ?>
<faultPolicyBindings version="2.0.1" xmlns="http://schemas.oracle.com/bpel/faultpolicy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <composite faultPolicy="fault-policies"/>
</faultPolicyBindings>

2. Java Action Class

Agora, com os arquivos de policy definidos, vamos construir a classe que irá receber a exception ocorrida no BPEL. No seu projeto adicione as duas classes orabpel.jar e fabric-runtime.jar, se você utiliza o JDeveloper configure-o como a imagem abaixo.

package com.lucianosilva.lab.soa;

import java.util.Collection;
import java.util.Map;

import oracle.integration.platform.faultpolicy.IFaultRecoveryContext;
import oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass;
import com.collaxa.cube.engine.fp.BPELFaultRecoveryContext;

/**
 * @author luciano silva
 *
 */
public class CompositeFaultHandler implements IFaultRecoveryJavaClass {

    private static final String RETURN_ERROR  = "ERROR";
    private static final String RETURN_MANUAL = "MANUAL";
    private static final String RETURN_RETRY  = "RETRY";

    /**
     *
     */
    public CompositeFaultHandler() {
        super();
    }

    /**
     *
     * @param iFaultRecoveryContext
     * @return
     */
    public String handleFault( IFaultRecoveryContext iFaultRecoveryContext ) {

        // print all fault details
        System.out.println("==========");
        System.out.println("Fault Policy Id : " + iFaultRecoveryContext.getPolicyId());
        System.out.println("Fault Type      : " + iFaultRecoveryContext.getType());
        System.out.println("Partnerlink     : " + iFaultRecoveryContext.getReferenceName());
        System.out.println("Port Type       : " + iFaultRecoveryContext.getPortType());

        if( iFaultRecoveryContext instanceof BPELFaultRecoveryContext ){
            //
            BPELFaultRecoveryContext bctx = (BPELFaultRecoveryContext) iFaultRecoveryContext;

            System.out.println("BPEL ActionId       : " + bctx.getActionId() );
            System.out.println("BPEL ActivityId     : " + bctx.getActivityId() );
            System.out.println("BPEL ActivityName   : " + bctx.getActivityName() );
            System.out.println("BPEL ActivityType   : " + bctx.getActivityType() );
            System.out.println("BPEL CorrelationId  : " + bctx.getCorrelationId() );
            System.out.println("BPEL PartnerLinkName: " + bctx.getPartnerLinkName() );
            System.out.println("BPEL Fault  : " + bctx.getFault().getFaultName() );
            System.out.println( bctx.getFault().getMessage() );
        }

        if( iFaultRecoveryContext.getProperties() != null ){

          System.out.println("Properties found in propertySet:");
          // print all properties defined in the fault-policy file
          Map props = iFaultRecoveryContext.getProperties();
          Collection list = props.values();
          for (String value : list) {
              System.out.println( value );
          }//

        }

        System.out.println("==========");

        return RETURN_MANUAL;
    }

    /**
     *
     * @param iFaultRecoveryContext
     */
    public void handleRetrySuccess( IFaultRecoveryContext iFaultRecoveryContext ) {
        System.out.println("SUCCESS.");
    }
}

Após compilar a classe acima, vamos empacotar em um arquivo .jar, faça isso:

 jar -cf fault-policy-javaaction.jar ./com/lucianosilva/lab/soa/*.class

Lembre-se, de usar \ se estiver no windows.

3. Adicionando Java Class (Jar) ao classpath do Weblogic

Você precisará que seu Jar seja adicionado ao classpath do Weblogic, para que em runtime a classe seja reconhecida pelo contexto e o Faut Policy funcione. O Apache Ant deve estar obrigatóriamente configurado no servidor.

O processo é muito simples, faça shutdown do servidor Weblogic, depois copie o arquivo .Jar para o diretório do servidor Weblogic $ORACLE_MIDDLEWARE_HOME/soa/modules/oracle.soa.ext_11.1.1/classes. Vá para no diretório oracle.soa.ext_11.1.1, aqui temos o build.xml, por fim, execute o Ant.

Pronto, está concluída a configuração de um exemplo para Fault Policy.
Para que as falhas do seu BPEL seja manipulada pela classe Java, as policies devem ser adicionadas ao arquivo composite.xml.

Veja na próxima parte deste post, como adicionar os XMLs de configuração do Fault Policy ao MDS e um BPEL utilizando esta configuração.

Download
Arquivos XML do Fault Policy
Projeto Java

Referências
http://docs.oracle.com/cd/E12839_01/integration.1111/e10224/bp_faults.htm
http://ant.apache.org/

A solução da Oracle para o conceito de arquitetura de serviços SOA, conhecida como Oracle SOA Suite disponibiliza um pacote com diversos recursos para organização, orquestração, segurança e integração. Para este último posso destacar o Business Process Execution Language, BPEL, que integrado ao JDeveloper é uma excelente ferramenta de trabalho, fácil, simples e com alguns recursos (adapters) pré-compilados que auxiliam o desenvolvimento.

O BPEL é uma linguagem descrita em XML que básicamente é utilizada para desenhar processo de negócio seguindo como base o BPM, destaca-se pela simplicidade da criação de um processo e pela amigável interface, proporcionando uma sensação agradável no momento do design. O utilizador de BPEL não necessita de conhecimentos em linguagem de programação, porém, o programador poderá obter mais recursos da ferramenta.

Para apresentar o BPEL escolhi algo um pouco mais além do famoso “Hello Word”, vamos trabalhar em um cenário de integração de softwares, aonde o legado irá disponibilizar um arquivo TXT no padrão CVS posicional diáriamente, o processo deverá interpretar o conteúdo deste arquivo e gravar no banco.

Pré-Requisitos

JDeveloper 10.1.3.4 (com suporte a SOA).

SOA Suite 10.1.3.1.0 (Com Windows Vista, talvez vc tenha problemas, baixe o patch).

MySQL.

Parte 1 – Criando o Projeto

Crie um projeto do tipo BPEL Project em File -> New -> Projects -> BPEL Process Project (certifique-se de que está filtrando por todas as tecnologias). Em seguida, dê um nome ao projeto e na opção template opte por Empty BPEL Process.

Parte 2 – Usando o Adapter File

O Adapter File é um recurso do BPEL para manipulação de arquivos, oferece três opções Leitura, Escrita e Sincronização (Read, Writer e Synchronous Read), além dele existe o Adapter FTP (autoexplicativo), porém iremos falar sobre ele depois. Continuando com nosso projeto, vamos utiliza a opção Read para o arquivo texto que estará disponível no diretório c:\interface_dir, haverá um pooling a cada 1 minuto, obviamente que isto é apenas para testes você deve adequar o intervalo de tempo de acordo com sua necessidade, veja a seguir o passo-a-passo do Adapter File.

Veja aqui os screenshot do passo-a-passo para configurar o File Adapter.

Até este passo fizemos apenas configurações básicas da funcionalidade do Adapter, porém, agora é necessário definir um o mapeamento das colunas posicional (fixo), utililzando um Schema XSD, veja a seguir como é simples:

Screenshots para criar o Schema XSD.

Parte 3 – Criando o Adapter Database

Crie um banco de dados no MySQL ou em qualquer outro SGDB, em seguida crie a tabela pais que irá receber os dados contidos no arquivo texto. Antes de utilizar o Adapter Database certifique-se que sua conexão com o banco está feita pelo JDeveloper, ela será necessária para os passos a seguir, portando vá até a aba Connection, se não existir crie-a.

Com a tabela criada e a conexão feita, agora vamos utilizar o componente Database Adapter que será o responsável por executar instruções SQL. Os passos aqui são tão simples quanto a criação da conexão, porém, é importante destacar que no Passo 4 escolha a opção Execute Custom SQL, e no quinto e último passo coloque a instrução de inserção da tabela pais, não se preocupe com o XSD ele será criado automáticamente, veja como fica:

Passo 4 – While e Variáveis

Para cada campo do arquivo TXT, mapeado pelo Schema XSD, devemos criar uma variável que irá armazenar o valor dos campos, então vá até a aba Structure e crie as variáveis.

Depois de todas as variáveis criadas precisamos associa-las aos campos do XSD e inicializa-las, mas para isto devo esclarecer uma coisa, sabemos que o arquivo texto poderá ter uma ou mais linhas de registro, portanto é necessária uma instrução de repetição. Utilizaremos o componente WHILE, a partir de uma variável contadora (índice).

O While cria um novo escopo aonde devemos arrastar os componentes de assinatura das variáveis e chamada da procedure, ou seja, para cada registro iremos fazer a inicialização da variáveis e a chamada da procedure para gravar no banco de dados, finalizando o nosso processo BPEL.

O processo é simples mas o dominio do ambiente BPEL é excencial, saber criar as variáveis, inicializá-las, passagem de valores, etc. Abaixo está disponível o fonte do projeto criado no JDeveloper.

Clique aqui para baixar o fonte.