Capítulo 3. Migração do seu Aplicativo

1. Primeiro, veja o empacotamento do seu aplicativo e as suas dependências. Para mais informações, consulte: Seção 3.1.2.3, “Atualização das Dependências do Aplicativo Devido às Alterações de Carregamento de Classe”
2. Caso o seu aplicativo realize o registro em log, será necessário especificar corretamente as dependências do módulo. Para mais informações, consulte: Seção 3.1.4.1, “Modificação das Dependências de Registro em Log”
3. Devido às alterações do carregamento de classe modular, pode ser que seja necessário alterar a estrutura do empacotamento do seu EAR ou WAR. Para mais informações, consulte: Seção 3.1.5.1, “Modificação do Empacotamento de EARS e WARs”

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

1. Compreendendo as dependências implícitas

   Os implantadores dentro do servidor adicionam automaticamente e de forma implícita algumas dependências de módulo comumente usadas, como javax.api e sun.jdk. Isto permite que as classes sejam visíveis à implantação durante o tempo de execução e reduz a tarefa do desenvolvedor de adicionar explicitamente as dependências. Para obter mais detalhes sobre como e quando essas dependências implícitas são adicionadas, consulte Implicit Module Dependencies no capítulo entitulado Class Loading and Modules no guia Development Guide para o JBoss EAP 6 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

2. Compreendendo as dependências explícitas

   Para outras classes, os módulos devem ser especificados explicitamente, caso contrário as dependências ausentes resultarão em erros de implantação ou de tempo de execução. Caso esteja faltando uma dependência, você encontrará rastreios como ClassNotFoundExceptions ou NoClassDefFoundErrors no log do servidor. Caso mais de um módulo carregue o mesmo JAR ou um módulo carregue uma classe que estenda uma classe carregada por um módulo diferente, você encontrará rastreios como ClassCastExceptions no servidor do log. Para especificar as dependências explicitamente, modifique o MANIFEST.MF ou crie um arquivo de descritor de implantação específico do JBoss jboss-deployment-structure.xml. Para mais informações sobre as dependências de módulos, consulte Overview of Class Loading and Modules no capítulo entitulado Class Loading and Module no guia Development Guide para o JBoss EAP 6 em https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Procedimento 3.2. Alteração da 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 queira que essas propriedades fiquem acessíveis a todos os componentes em um EAR, elas devem ser empacotadas na raiz de um JAR e, então, o JAR deve ser colocado 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 para o 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 Gerenciamento CLI.
        • Para o Linux, insira o seguinte na linha de comando:

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

        • Para o Windows, insira o seguinte na linha de comando:

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

        Você deverá ver a seguinte resposta:

        Conectado ao controlador autônomo em localhost:9999

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

        /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 de configuração do servidor.
     1. Interrompa o servidor e abra o arquivo de configuração do servidor em um editor de texto. Caso esteja executando um servidor autônomo, o arquivo será EAP_HOME/standalone/configuration/standalone.xml ou, caso esteja executando um domínio gerenciado, o arquivo será EAP_HOME/domain/configuration/domain.xml.
     2. Encontre o subsistema ee e adicione o módulo global para myorg-conf. Segue um exemplo do elemento do subsistema ee modificado para a inclusão do elemento myorg-conf:

        Exemplo 3.1. elemento myorg-conf

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

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

   Exemplo 3.2. Carregue o arquivo de propriedades

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

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

1. Seção 3.1.4.2, “Atualização do Código de Aplicativo para Estruturas de Registro em Log de Terceiros”
2. Seção 3.1.4.3, “Modificação do Código para Uso da Nova Estrutura de Registro do JBoss”

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

1. Crie 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 no 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. Se a sua implantação incluir componentes dependentes, o módulo também deve ser removido 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 prefira posicionar o arquivo no diretório lib/ de seu WAR, você deve especificar o caminho <resource-root> 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 de tempo de execução para evitar que um ClassCastException apareça no console no momento de implantação do aplicativo:

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

5. Implante seu aplicativo.

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

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

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

2. Abra um terminal e conecte-se ao Gerenciamento CLI.
   • Para o Linux, insira a seguinte linha de comando:

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

   • Para o Windows, insira a seguinte linha de comando:

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

3. Modifique o atributo add-logging-api-dependencies no subsistema de registro.
   Este atributo controla se o contêiner deve adicionar ou não as dependências API implícitas de registro às suas implantações.

   • Se definido como true, que é o padrão, todas as dependências API implícitas de registro serão adicionadas.
   • Se definido como false, as dependências não serão adicionadas às suas implantações.
   Para remover as dependências de estrutura de registro em log de terceiros, você deve definir este atributo como false usando o seguinte comando:

   /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. Modificação do Código e das Dependências para Uso da Estrutura de Registro do JBoss

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

   Segue abaixo um exemplo do código que usa a nova estrutura de registro do JBoss:

   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 da dependência de registro

   O JAR contendo as classes de registro do JBoss 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 Seção 3.1.2.3, “Atualização das Dependências do Aplicativo Devido às Alterações de Carregamento de Classe” e Seção 4.2.1, “Depuração e Solução de Problemas de Migração” para mais informações sobre como encontrar a dependência do módulo.

Procedimento 3.8. Modificação do empacotamento de arquivos

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 dentro do EAR é um módulo separado. As classes não possuem acesso às classes em outros módulos dentro do EAR, a não ser que as dependências explícitas tenham sido definidas. As subimplantações sempre possuem uma dependência automática no módulo pai que fornece-as acesso às classes no diretório EAR/lib/. No entanto, as subimplantações nem sempre possuem uma dependência automática para permití-las acessar umas às outras. 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 padrão, isto é configurado como falso, permitindo que as subimplantações vejam as classes pertencentes às outras subimplantações dentro do EAR.
   Para mais informações sobre o carregamento de classe, consulte o capítulo entitulado Class Loading and Modules no guia Development Guide para o JBoss EAP 6 em https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

1. Se seu aplicativo usa uma fonte de dados, consulte : Seção 3.1.6.2, “Atualização da Configuração da DataSource”.
2. Se o seu aplicativo usa JPA e atualmente agrupa JARs Hibernate, consulte: Seção 3.1.6.4, “Configuração da Fonte de Dados para o Hibernate ou JPA” para opções de migração.
3. Se o seu aplicativo usa um adaptador de recursos, consulte: Seção 3.1.6.5, “Atualização da Configuração do Adaptador de Recurso”.
4. Revise as informações a seguir sobre como configurar as alterações para segurança básica: 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 Driver JDBC

1. Instalação do Driver JDBC.

   1. Instalação do Driver JDBC como uma implantação.

      Esta é a maneira recomendada de instalar o driver. Quando o driver JDBC é instalado como uma implantação, ele é implantado como um JAR regular. Caso a instância do JBoss EAP 6 esteja sendo executada como um servidor autônomo, copie o JAR compatível com o JDBC 4.0 no diretório EAP_HOME/standalone/deployments/. Para um domínio gerenciado, você deve usar o Console de Gerenciamento ou Gerenciamento CLI para implantar o JAR nos grupos do servidor.
      Segue um exemplo de um driver MySQL JDBC instalado como uma implantação no 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 por nome e versão. Um JAR compatível com o JDBC 4.0 contém um arquivo de texto nomeado META-INF/services/java.sql.Driver que especifica o(s) nome(s) da classe do driver. Caso o driver não seja 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 implantação. Para uma instância do JBoss EAP 6 executando como um servidor autônomo, o arquivo deve ser posicionado aqui: EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver. Caso o servidor esteja em um domínio gerenciado, você deve usar o Console de Gerenciamento ou o Gerenciamento CLI para implantar o arquivo.
      Os aspectos positivos desta abordagem são:

      • Este é o método mais simples já que não há necessidade de definir um módulo.
      • Quando o servidor executa em um domínio gerenciado, as implantações que usam esta abordagem são propagadas automaticamente a todos os servidores no domínio. Isto significa que o administrador não precisa distribuir o driver JAR manualmente.

      Os aspectos negativos desta abordagem são:

      • Se o driver JDBC consiste em mais de um JAR, por exemplo o driver JAR mais um JAR de licença dependente ou um JAR de localização, você não pode instalar o driver como uma implantação. O JDBC deve ser instalado como um módulo principal.
      • Caso o driver não seja 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 para um JAR ou sobreposto no diretório deployments/.

   2. Instalação do Driver JDBC como um módulo principal.

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

      • Instalação do Driver MySQL JDBC como um módulo principal

        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 driver MySQL JDBC:

           <?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 no caso de todas as fonte de dados JDBC, ele é 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 você NÃO possua espaço no início do arquivo module.xml ou obterá um erro "Novas dependências ausentes/não satisfatórias" para este driver.
        3. Copie MySQL JDBC driver JAR no diretório EAP_HOME/modules/com/mysql/main/:

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

      • Instalação do driver IBM DB2 JDBC e do JAR de licença como um módulo principal.

        Este exemplo é fornecido apenas para demonstrar a implantação de drivers que requerem JARs além do JAR do Driver JDBC.
        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 a licença e o driver IBM DB2 JDBC:

           <?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 você NÃO possua espaço no início do arquivo module.xml ou obterá um erro "Novas dependências ausentes/não satisfatórias" para este driver.
        3. Copie o driver JDBC e o JAR de licença no 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 driver JDBC consiste em 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 criar 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 em execução em um domínio gerenciado.

2. Configuração da fonte de dados.

   1. Adição do driver do banco de dados.

      Adicione o elemento <driver> ao elemento <drivers> do mesmo arquivo. Mais uma vez, isto contém algumas das mesmas informações sobre a fonte de dados 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) do driver no JAR. Um driver que é compatível com o JDBC 4.0 não requer um elemento <driver-class>, desde que ele já esteja especificado no JAR. Segue um exemplo do elemento do driver para um driver MySQL compatível com o JDBC 4.0:

      <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 já que não há um arquivo META-INF/services/java.sql.Driver que especifique o nome da classe do driver. Segue um exemplo do elemento do driver para um 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. Criação da fonte de dados.

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

      Importante

      Você deve interromper o servidor antes de editar o arquivo de configuração do servidor para que a sua alteração seja efetivada ao reiniciar o servidor.
      Segue um exemplo de um elemento da 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. Atualização das referências JNDI no código do aplicativo.

   Você deve substituir os antigos nomes de pesquisa JNDI no código fonte do aplicativo para usar os novos nomes padronizados da fonte de dados JNDI que você definiu anteriormente. Consulte Seção 3.1.8.4, “Modificação do Aplicativo para Seguir as Novas Regras do Namespace JNDI” para mais informações.
   Você deve substituir também quaisquer anotações @Resource existentes que acessam a fonte de dados para utilizar o novo nome JNDI. Por exemplo:

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

Procedimento 3.10. Remoção do pacote Hibernate

1. Remova os JARs Hibernate das pastas da biblioteca do seu aplicativo.
2. Remova ou converta em comentário o elemento <hibernate.transaction.manager_lookup_class> no seu arquivo persistence.xml, já que este elemento não é necessário.

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

• Você pode desabilitar as verificações de autorização adicionais e continuar usando as implantações PicktLink existentes usando um dos seguintes métodos.

  • Definição de uma Propriedade em Todo o Sistema

    As verificações de autorização adicionais podem ser desabilitadas ao nível do servidor definindo o valor da propriedade do sistema org.jboss.ws.cxf.disableHandlerAuthChecks para true. Este método afeta qualquer implantação realizada ao servidor do aplicativo.
    Consulte o tópico entitulado Configure System Properties Using the Management CLI no guia Administration and Configuration Guide do JBoss EAP para mais informações sobre como definir uma propriedade de sistema.

  • Criação de uma Propriedade no Arquivo de Descritor de Serviços Web da Implantação

    As verificações de autorização adicionais podem ser desabilitadas ao nível da implantação definindo o valor da propriedade org.jboss.ws.cxf.disableHandlerAuthChecks para true no arquivo jboss-webservices.xml. Este método impacta somente a implantação específica.
    1. Crie um arquivo jboss-webservices.xml no diretório META-INF/ da implantação que deseja desabilitar as verificações da autorização adicionais.
    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. Saiba mais Seção 3.1.8.2, “Nomes JNDI EJB Portáteis ”
2. Seção 3.1.8.3, “Revisão das Regras do Namespace JNDI”
3. Seção 3.1.8.4, “Modificação do Aplicativo para Seguir as Novas Regras do Namespace JNDI”