Capítulo 3. Migre seu Aplicativo

1. Primeiro, observe o empacotamento de seu aplicativo e suas dependências. Consulte a: Seção 3.1.2.3, “Atualização das Dependências do Aplicativo devido às Alterações do Carregamento da Classe” para maiores informações.
2. Caso o seu aplicativo realize o logon, será necessário especificar corretamente as dependências do módulo. Consulte a: Seção 3.1.4.1, “Modificação das Dependências de Registro em Log” para maiores informações.
3. A estrutura do empacotamento de seu EAR ou WAR talvez precise ser alterada devido às alterações de carregamento de classe modular. Consulte a: Seção 3.1.5.1, “Modificação do Empacotamento dos EARS e WARs” para maiores informações.

Procedimento 3.1. Compreendendo as Dependências do Módulo

1. Compreendendo as dependências implícitas

   Os implantadores com o servidor adicionam automaticamente, e de forma implícita, algumas dependências de módulo comumente usadas como o javax.api e sun.jdk. Isto permite que as classes sejam visíveis à implantação no período de execução reduzindo a tarefa do desenvolvedor de adicionar explicitamente dependências. Consulte as Dependências de Módulo Implícitas no capítulo nomeado Carregamento de Carga e Módulo no Guia de Desenvolvimento para o JBoss EAP 6 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/ para maiores informações.

2. Compreendendo as dependências explícitas

   Os módulos devem ser especificados explicitamente para outras classes, do contrário as dependências ausentes resultarão em implantação ou erros do período de execução. Caso falte uma dependência, traços ClassNotFoundExceptions ou NoClassDefFoundErrors poderão ser observados no log do servidor. Caso mais de um módulo carregar o mesmo JAR ou um módulo carregar uma classe que estende uma classe carregada por um módulo diferente, traços ClassCastExceptions poderão ser vistos no servidor do log. Modifique o MANIFEST.MF ou crie um arquivo do descritor de implantação específico do JBoss jboss-deployment-structure.xml para especificação explícita de dependências. Refira-se à Visão Geral do Carregamento de Classe e Módulos no capítulo nomeado Carregamento de Classe e Módulo no Guia de Desenvolvimento para o JBoss EAP 6 no https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Procedimento 3.2. Altere a Localização das Propriedades ResourceBundle

1. Caso esteja implantando um arquivo WAR, essas propriedades devem ser empacotadas na pasta WEB-INF/classes/ do WAR.
2. Caso deseje disponibilizar essas propriedades a todos os componentes num EAR, elas devem ser empacotadas à raiz do JAR na pasta lib/ do EAR.

Procedimento 3.3. Criação de um Módulo Personalizado

1. Crie e preencha a estrutura do diretório module/.
   1. Crie uma estrutura de diretório sob o diretório EAP_HOME/module para conter os arquivos e JARs. Por exemplo:

      $ cd EAP_HOME/modules/ 
      $ mkdir -p myorg-conf/main/properties

   2. Mova os arquivos de propriedades ao diretório EAP_HOME/modules/myorg-conf/main/properties/ criado na etapa anterior.
   3. Crie um arquivo module.xml no diretório EAP_HOME/modules/myorg-conf/main/ contendo o seguinte XML:

      <module xmlns="urn:jboss:module:1.1" name="myorg-conf">
          <resources>
              <resource-root path="properties"/>
          </resources>
      </module>
      
      

2. Modifique o subsistema ee no arquivo de configuração do servidor. Você pode usar o JBoss CLI ou pode editar manualmente o arquivo.
   • Siga as seguintes etapas para modificar o arquivo de configuração do servidor usando o JBoss CLI.
     1. Inicie o servidor e conecte-se ao Management CLI.
        • Insira a seguinte linha de comando para o Linux:

          $ EAP_HOME/bin/jboss-cli.sh --connect
          

        • Insira a seguinte linha de comando para o Windows:

          C:\>EAP_HOME\bin\jboss-cli.bat --connect
          

        Você deverá observar a seguinte resposta:

        Conectado ao controlador autônomo no localhost:9999

     2. Digite o seguinte na linha de comando para criar o elemento myorg-conf <global-modules> no subsistema ee:

        /subsystem=ee:write-attribute(name=global-modules, value=[{"name"=>"myorg-conf","slot"=>"main"}])
        

        Você deverá ver o seguinte resultado:

        {"outcome" => "success"}
        

   • Siga essas etapas caso prefira editar manualmente o arquivo da configuração do servidor.
     1. Interrompa o servidor e abra o arquivo de configuração do servidor num editor de texto. Caso esteja executando um servidor autônomo, o arquivo será o EAP_HOME/standalone/configuration/standalone.xml ou caso esteja executando um managed domain, o arquivo será o EAP_HOME/domain/configuration/domain.xml.
     2. Encontre o subsistema ee e adicione o módulo global para myorg-conf. Segue abaixo uma amostra do elemento do subsistema ee modificado para inclusão do elemento myorg-conf:

        <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
            <global-modules>
                <module name="myorg-conf" slot="main" />            
            </global-modules>
        </subsystem>
        
        

3. Assumindo que você copiou um arquivo nomeado my.properties à localização de módulo correta, você poderá agora carregar os arquivos de propriedades usando o código similar ao seguinte:

   Thread.currentThread().getContextClassLoader().getResource("my.properties");
   

Procedimento 3.4. Atualização do código de registro de log do aplicativo

1. Seção 3.1.4.2, “Atualização do Código do Aplicativo para Frameworks de Registro de Log de Terceiros”
2. Seção 3.1.4.3, “Modificação do Código para Uso do Novo Framework de Registro de Log do JBoss”

Procedimento 3.5. Configuração do JBoss EAP 6 para uso de um arquivo log4j.properties ou log4j.xml

1. Criação de um jboss-deployment-structure.xml com o seguinte conteúdo:

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
       </deployment>
   </jboss-deployment-structure>
   
   

2. Posicione o arquivo jboss-deployment-structure.xml, tanto em seu diretório META-INF/ ou no diretório WEB-INF/, caso esteja implantando um WAR. Do contrário, posicione-o no diretório META-INF/ caso esteja implantando um EAR. Caso a sua implantação incluir implantações filho dependente, o módulo deve ser também excluído para cada subimplantação.
3. Adicione o arquivo log4j.properties ou log4j.xml no diretório lib/ de seu EAR ou no diretório WEB-INF/classes/ de sua implantação WAR. Caso deseje posicionar o arquivo no diretório lib/ de seu WAR, o caminho <resource-root> deve ser especificado no arquivo jboss-deployment-structure.xml.

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
           <resources>
               <resource-root path="lib" />
           </resources>
       </deployment>
   </jboss-deployment-structure>
   
   

4. Inicie o servidor do JBoss EAP 6 com o seguinte argumento para evitar que um ClassCastException apareça no console no momento de implantação de seu aplicativo:

   -Dorg.jboss.as.logging.per-deployment=false

5. Implante seu aplicativo.

Procedimento 3.6. Configuração das Dependências de Logon para o JBoss EAP 6.3 ou versões mais recentes

1. Inicie o servidor do JBoss EAP 6 com o seguinte argumento para evitar que um ClassCastException apareça no console no momento de implantação de seu aplicativo:

   -Dorg.jboss.as.logging.per-deployment=false

2. Abra um terminal e conecte-se ao Management CLI.
   • Insira a seguinte linha de comando para o Linux:

     $ EAP_HOME/bin/jboss-cli.sh --connect
     

   • Insira a seguinte linha de comando para o Windows:

     C:\>EAP_HOME\bin\jboss-cli.bat --connect
     

3. Modifique o atributo add-logging-api-dependencies no subsistema de logon.
   Este atributo controla se o contêiner adiciona implicitamente as dependências API de logon as suas implantações.

   • Caso determinado para true, que é o default, todas as dependências API de logon implícitas serão adicionadas.
   • Caso determinado para false, as dependências não são adicionadas as suas implantações.
   Este atributo deve ser determinado para false usando o seguinte comando, com o objetivo de excluir as dependências do framework de logon de terceiros:

   /subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

   Este comando adiciona o elemento <add-logging-api-dependencies> ao subsistema logging do arquivo de configuração standalone.xml.

   <subsystem xmlns="urn:jboss:domain:logging:1.4">
       <add-logging-api-dependencies value="false"/>
       ....
   </subsystem>
   
   

4. Implante seu aplicativo.

Procedimento 3.7. Modifique o Código e Dependências para Uso do JBoss logging Framework

1. Alteração de suas importações e código de registro em log

   Segue abaixo uma amostra do código que usa o novo framework do JBoss Logging:

   import org.jboss.logging.Level;
   import org.jboss.logging.Logger;
   
   private static final Logger logger = Logger.getLogger(MyClass.class.toString());
   
   if(logger.isTraceEnabled()) {
       logger.tracef("Starting...", subsystem);
   }
   

2. Adição de dependência de registro em log

   O JAR contendo as classes do JBoss Logging está localizado no módulo nomeado org.jboss.logging. O seu arquivo MANIFEST-MF deve parecer com o seguinte:

   Manifest-Version: 1.0
   Dependencies: org.jboss.logging
   

   Por favor consulte a Seção 3.1.2.3, “Atualização das Dependências do Aplicativo devido às Alterações do Carregamento da Classe” e a Seção 4.2.1, “Depuração e Solução dos Problemas de Migração” para maiores informações sobre como encontrar a dependência do módulo.

Procedimento 3.8. Modificação do empacotamento do arquivo

1. Empacotamento do WAR

   O WAR é um módulo único e todas as classes no WAR são carregadas com o mesmo carregador de classe. Isto significa que as classes empacotadas no diretório WEB-INF/lib/ são tratadas da mesma forma que as classes no diretório WEB-INF/classes.

2. Empacotamento de um EAR

   Um EAR consiste de módulos múltiplos. O diretório EAR/lib/ é um módulo único e cada WAR ou subimplantação EJB jar no EAR é um módulo separado. As classes não possuem acesso às classes em outros módulos com o EAR, a não ser que as dependências tenham sido definidas. As subimplantações sempre possuem uma dependência automática no módulo pai que as fornecem acesso às classes no diretório EAR/lib/. No entanto, as subimplantações nem sempre possuem uma dependência automática para permitir que se acessassem entre si. Este comportamento é controlado pela configuração do elemento <ear-subdeployments-isolated> na configuração do subsistema ee, conforme abaixo:

   <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
     <ear-subdeployments-isolated>false</ear-subdeployments-isolated>
   </subsystem>
   

   Por default, isto é configurado para falso, permitindo que as subimplantações vejam as classes pertencentes às demais subimplantações com o EAR.
   Refira-se ao capítulo nomeado no carregamento da classe ao capítulo nomeado Carregamento de Classe e Módulos no Guia de Desenvolvimento para o JBoss EAP 6 no https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

1. Caso seu aplicativo use a fonte de dados, consulte a: Seção 3.1.6.2, “Atualização da Configuração da Fonte de Dados”.
2. Caso o seu aplicativo use o JPA e empacote os Hibernate JARs, consulte a: Seção 3.1.6.4, “Configuração da Fonte de Dados para o Hibernate ou JPA” para opções de migração.
3. Caso seu aplicativo use um adaptador de recurso, consulte a: Seção 3.1.6.5, “Atualização da Configuração do Adaptador de Recurso”.
4. Revise a seguinte informação de como configurar as alterações para a segurança básica na: Seção 3.1.7.1, “Configuração das Alterações de Segurança do Aplicativo”.

Procedimento 3.9. Instalação e Configuração do JDBC Driver

1. Instale o JDBC Driver.

   1. Instale o JDBC Driver como uma implantação.

      Esta é a maneira recomendada de instalação do driver. Quando o JDBC driver for instalado como uma implantação, ele é implantado como um JAR regular. Caso a instância do JBoss EAP 6 estiver sendo executada como um servidor autônomo, copie o JDBC 4.0 compatível com o diretório EAP_HOME/standalone/deployments/. Para um managed domain, o Management Console ou Management CLI deve ser usado para implantar o JAR aos grupos do servidor.
      Segue abaixo uma amostra de um MySQL JDBC driver instalado como implantação ao servidor autônomo:

      $cp mysql-connector-java-5.1.15.jar EAP_HOME/standalone/deployments/

      Qualquer driver compatível com o JDBC 4.0 é automaticamente reconhecido e instalado no sistema pelo nome e versão. Um JAR compatível com o JDBC 4.0 contém um texto com arquivo nomeado META-INF/services/java.sql.Driver que especifica o(s) nome(s) da classe do driver. Caso o driver não for compatível com o JDBC 4.0, ele pode ser implantável em uma das seguintes maneiras:

      • Crie e adicione o arquivo java.sql.Driver ao JAR sob o caminho META-INF/services/. Esse arquivo deve conter o nome de classe do driver, por exemplo:

        com.mysql.jdbc.Driver

      • Crie um arquivo java.sql.Driver no diretório de implementação. Para uma instância do JBoss EAP 6 executando como um servidor autônomo, o arquivo deve ser posicionado no: EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver. Caso o servidor estiver num managed domain, o uso do Management Console ou do Managment CLI deve ser aplicado para implantar o arquivo.
      Os aspectos positivos desta abordagem são:

      • Este é o método mais simples uma vez que não há necessidade de definir um módulo.
      • Quando o servidor estiver executando num managed domain, as implantações que usam esta abordagem são propagadas automaticamente a todos os servidores no domain. Isto significa que o administrador não precisa distribuir o driver JAR manualmente.

      Os aspectos negativos desta abordagem são:

      • Caso o JDBC driver consistir de mais de um JAR, por exemplo o driver JAR mais o JAR da licença de dependência JAR ou JAR de localização, o driver não pode ser instalado como implantação. O JDBC deve ser instalado como um módulo core.
      • Caso o driver não for compatível com o JDBC 4.0, um arquivo deve ser criado contendo o(s) nome(s) da classe do driver e deve ser importado num JAR ou sobreposto no diretório deployments/.

   2. Instale o JDBC Driver como um módulo core.

      Para instalar um JDBC driver como um módulo core, uma estrutura do caminho do arquivo sob o diretório EAP_HOME/modules/ deve ser criada. Esta estrutura contém o JDBC driver JAR, qualquer licença do fornecedor adicional ou JARs de localização e um arquivo module.xml para definição do módulo.

      • Instale o MySQL JDBC Driver como módulo core

        1. Crie uma estrutura de diretório EAP_HOME/modules/com/mysql/main/
        2. No subdiretório main/, crie um arquivo module.xml contendo a seguinte definição do módulo para o MySQL JDBC driver:

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.0" name="com.mysql">
           <resources>
               <resource-root path="mysql-connector-java-5.1.15.jar"/>
           </resources>
           <dependencies>
               <module name="javax.api"/>
           </dependencies>
           </module>
           
           
           

           O nome do módulo, "com.mysql", coincide com a estrutura do diretório para esse módulo. O elemento <dependencies> é usado para especificar as dependências do módulo em outros módulos. Neste caso, como é o caso em todas as fontes de dados JDBC, isto é dependente do Java JDBC APIs que é definido em outro módulo nomeado javax.api. Este módulo está localizado sob o diretório modules/system/layers/base/javax/api/main/.

           Nota

           Certifique-se de que NÃO possui espaço no início do arquivo module.xml ou um erro "Novas dependências ausentes/não satisfatórias" para este driver será obtido.
        3. Copie o MySQL JDBC driver JAR ao diretório EAP_HOME/modules/com/mysql/main/:

           $ cp mysql-connector-java-5.1.15.jar EAP_HOME/modules/com/mysql/main/

      • Instale o IBM DB2 JDBC driver e JAR de licença como um módulo core.

        Esta amostra é fornecida para apenas demonstrar como implantar drivers que requerem JARs além do JDBC Driver JAR.
        1. Crie a estrutura do diretório EAP_HOME/modules/com/ibm/db2/main/.
        2. No subdiretório main/ crie um arquivo module.xml contendo a seguinte definição do módulo para o IBM DB2 JDBC driver e licença:

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.1" name="com.ibm.db2">
             <resources>
               <resource-root path="db2jcc.jar"/>
               <resource-root path="db2jcc_license_cisuz.jar"/>
             </resources>
             <dependencies>
               <module name="javax.api"/>
               <module name="javax.transaction.api"/>
             </dependencies>
           </module>
           
           

           Nota

           Certifique-se de que NÃO possui espaço no início do arquivo module.xml ou um erro "Novas dependências ausentes/não satisfatórias" para este driver será obtido.
        3. Copie o JDBC driver e a licença JAR ao diretório EAP_HOME/modules/com/ibm/db2/main/.

           $ cp db2jcc.jar EAP_HOME/modules/com/ibm/db2/main/
           $ cp db2jcc_license_cisuz.jar EAP_HOME/modules/com/ibm/db2/main/

      Os aspectos positivos desta abordagem são:

      • Esta é a única abordagem que funciona quando o JDBC driver consiste de mais de um JAR.
      • Com esta abordagem, os drivers que não são compatíveis com o JDBC 4.0 podem ser instalados sem modificar o driver JAR ou criando uma sobreposição de arquivo.

      Os aspectos negativos desta abordagem são:

      • É mais difícil configurar um módulo.
      • O módulo deve ser manualmente copiado para cada servidor executando num managed domain.

2. Configure a fonte de dados.

   1. Adicione o driver do banco de dados.

      Adicione o elemento <driver> ao elemento <drivers> de mesmo arquivo. Isto contém algumas das informações que foram definidas anteriormente no arquivo *-ds.xml.
      Primeiro determine se o driver JAR é compatível com o JDBC 4.0. Um JAR que é compatível com o JDBC 4.0 contém um arquivo META-INF/services/java.sql.Driver que especifica o nome de classe do driver. O servidor usa este arquivo para encontrar o nome da(s) classe(s) de driver no JAR. Um driver que é compatível com o JDBC 4.0 não requer um elemento <driver-class>, uma vez que ele já está especificado no JAR. Esta é uma amostra do elemento do driver para um JDBC 4.0 compatível com o driver MySQL:

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql"/>
      

      Um driver que não seja compatível com o JDBC 4.0 requer um atributo <driver-class> para identificar a classe do driver desde que não haja um arquivo META-INF/services/java.sql.Driver que especifique o nome da classe do driver. Segue abaixo uma amostra do elemento driver para o driver não compatível com o JDBC 4.0:

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql">
      <driver-class>com.mysql.jdbc.Driver</driver-class></driver>
      

   2. Crie a fonte de dados.

      Crie um elemento <datasource> na seção <datasources> do arquivo standalone.xml. Este arquivo contém bastante informações da fonte de dados anteriormente definida no arquivo *-ds.xml.

      Importante

      O servidor deve ser interrompido antes de editar o arquivo de configuração do servidor para que sua alteração seja efetivada no reinício do servidor.
      Segue abaixo uma amostra de um elemento de fonte de dados MySQL no arquivo standalone.xml:

      <datasource jndi-name="java:/YourDatasourceName" pool-name="YourDatasourceName">
        <connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url>
        <driver>mysql-connector-java-5.1.15.jar</driver>
        <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
        <pool>
          <min-pool-size>100</min-pool-size>
          <max-pool-size>200</max-pool-size>
        </pool>
        <security>
          <user-name>USERID</user-name>
          <password>PASSWORD</password>
        </security>
        <statement>
          <prepared-statement-cache-size>100</prepared-statement-cache-size>
          <share-prepared-statements/>
        </statement>
      </datasource>
      
      

3. Atualize as referências JNDI no código do aplicativo.

   Os nomes de pesquisa JNDI antigos no código fonte do aplicativo devem ser substituídos para uso dos nomes da fonte de dados padronizados do JNDI definidos anteriormente. Consulte a Seção 3.1.8.4, “Modificação do Aplicativo para Seguir as Novas Regras do JNDI Namespace” para maiores informações.
   Quaisquer anotações @Resource existentes devem ser também substituídas, das quais acessam a fonte de dados para uso do novo nome JNDI. Por exemplo:

   @Resource(name = "java:/YourDatasourceName").
   

Procedimento 3.10. Remoção do pacote Hibernate

1. Remova o Hibernate JARs de suas pastas da biblioteca do aplicativo.
2. Remova ou comente o elemento <hibernate.transaction.manager_lookup_class> em seu arquivo persistence.xml, uma vez que este elemento não é necessário.

Procedimento 3.11. Desabilitação das Verificações de Autorização Adicional

• As verificações de autorização adicional podem ser desabilitadas e continuarem usando as implantações PicktLink existentes, pelo uso de um dos seguintes métodos.

  • Determinação da Propriedade em todo o Sistema

    As verificações de autorização adicional podem ser desabilitadas ao nível do servidor pela determinação do valor do sistema de propriedade org.jboss.ws.cxf.disableHandlerAuthChecks para true. Este método afeta qualquer implantação realizada ao servidor do aplicativo.
    Consulte o tópico nomeado Configuração das Propriedades de Sistema usando o Management CLI no Guia de Configuração e Administração do JBoss EAP para maiores informações sobre como determinar uma propriedade de sistema.

  • Criação de uma Propriedade no Arquivo do Descritor do Web Services de Implantação

    As verificações de autorização no nível de implantação podem ser desabilitadas pela configuração do valor da propriedade org.jboss.ws.cxf.disableHandlerAuthChecks para true no arquivo jboss-webservices.xml.
    1. Crie um arquivo jboss-webservices.xml no diretório META-INF/ da implantação pela qual deseja desabilitar as verificações da autorização.
    2. Adicione o seguinte conteúdo:

       <?xml version="1.1" encoding="UTF-8"?>
       <webservices xmlns="http://www.jboss.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">
         <property>
           <name>org.jboss.ws.cxf.disableHandlerAuthChecks</name>
           <value>true</value>
         </property>
       </webservices>
       

Procedimento 3.12. Modificação das pesquisas JNDI

1. Leia mais a respeito deste assunto na Seção 3.1.8.2, “Nomes do EJB JNDI Portátil ”
2. Seção 3.1.8.3, “Revisão das Regras JNDI Namespace”
3. Seção 3.1.8.4, “Modificação do Aplicativo para Seguir as Novas Regras do JNDI Namespace”