Capítulo 3. Migre seu Aplicativo

1. Primeiro, busque pelo 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 não efetuar o log em registro, você precisará especificar as dependências de módulo corretas. Consulte a Seção 3.1.4.1, “Modificação das Dependências de Registro em Log” para maiores informações
3. Devido às alterações de carregamento de classe modular, você talvez precise alterar a estrutura do empacotamento de seu EAR ou WAR. 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 de Módulo

1. Compreendendo as dependências implícitas

   Os implantadores com o servidor implicitamente automatizado, adicionam algumas das dependências do módulo comumente usadas, como por exemplo javax.api e sun.jdk. Isto faz as classes visíveis à implantação no período de rodagem e libera o desenvolvedor da tarefa de adicionar explicitamente as dependências. Para maiores detalhes de como e quando essas dependências são adicionadas, refira-se ao Implicit Module Dependencies no capítulo nomeado Class Loading and Modules no Development Guide do JBoss Enterprise Application Plataform 6 no 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 ou as dependências faltantes resultam em erros de implantação ou do período de rodagem. Caso falte uma dependência, você verá traços ClassNotFoundExceptions ou NoClassDefFoundErrors no log do servidor. Caso mais de um módulo efetuar o carregamento ao mesmo JAR ou um módulo efetuar o carregamento numa classe que estende a classe com carregamento por um módulo diferente, você verá traços ClassCastExceptions no log do servidor. Para especificar as dependências, modifique o MANIFEST.MF ou crie um jboss-deployment-structure.xml do arquivo do descritor de implantação específico do JBoss. Para maiores informações sobre as dependências do módulo, refira-se ao Overview of Class Loading and Modules no capítulo chamado Class Loading and Module no Development Guide do JBoss Enterprise Application Plataform 6 no https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Procedimento 3.2. 

1. Caso esteja implantando um arquivo WAR, você deve empacotar essas propriedades na pasta WEB-INF/classes/ do WAR.

2. Caso deseje disponibilizar essas propriedades a todos os componentes num EAR, você deve empacotá-las à 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 Gerenciamento CLI.
        • Insira a seguinte linha de comando para o Linux:

          $ EAP_HOME/bin/jboss-cli.sh --connect
          $ Connected to standalone controller at localhost:9999
          

        • Insira a seguinte linha de comando para o Windows:

          C:\>EAP_HOME\bin\jboss-cli.bat --connect
          C:\> Connected to standalone controller at 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 da configuração do servidor.
     1. Interrompa o servidor e abra o arquivo de configuração do servidor num editor de texto. Caso você esteja executando um servidor autônomo, este é o arquivo EAP_HOME/standalone/configuration/standalone.xml ou caso esteja executando um storage domain, o arquivo é 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 Enterprise Application Plataform 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 no diretório META-INF/ ou diretório WEB-INF/, caso esteja implantando um WAR ou no diretório META-INF/, caso você esteja implantando um EAR.
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.
4. Implante seu aplicativo.

Procedimento 3.6. 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.7. Modificação do empacotamento do arquivo

1. Empacotamento do WAR

   O WAR é um módulo único e todas as classes no WAR são carregados com a 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 sub-implantação jar EJB com 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 sub-implantaçõ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 sub-implantações nem sempre possuem uma dependência automática para permiti-las acessar-se 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 sub-implantações vejam as classes pertencentes a demais sub-implantações com o EAR.
   Para maiores informações sobre o carregamento da classe, refira-se ao capítulo Class Loading and Modules no Development Guide para o JBoss Enterprise Application Plataform 6 no https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

1. Caso o seu aplicativo usar uma 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 usar JPA e empacotar o Hibernate JARs, consulte abaixo as opções de migração na Seção 3.1.6.4, “Configuração da Fonte de Dados para o Hibernate ou JPA”.
3. Caso o seu aplicativo usar um adaptador de recurso, consulte a Seção 3.1.6.5, “Atualização da Configuração do Adaptador de Recurso”.
4. Revise abaixo as informações de como configurar as alterações para segurança básica na Seção 3.1.7.1, “Configuração das Alterações de Segurança do Aplicativo”.

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

1. Instalação do JBBC Driver

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

      Esta é a maneira recomendada para instalar o driver. Quando o JDBC driver for instalado como uma implantação, ele é implantado como um JAR regular. Caso a instância do JBoss Enterprise Application Plataform estiver sendo executada como um servidor autônomo, copie o JDBC 4.0 compatível ao JAR no diretório EAP_HOME/standalone/deployments/. Caso o servidor estiver sendo executado num storage domain, copie o JAR ao diretório EAP_HOME/domain/deployments/.
      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 JDBC 4.0 é automaticamente reconhecido e instalado no sistema pelo nome e versão. Um JAR compatível com 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 implantação. Para uma instância do JBoss Enterprise Application Plataform 6 sendo executada como servidor autônomo, o arquivo deve ser posicionado aqui: EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver. Caso o servidor estiver num storage domain, o arquivo deve ser posicionado aqui: EAP_HOME/domain/deployments/META-INF/services/java.sql.Driver.
      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 storage 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 um JAR com licença independente ou JAR de localização, você não pode instalar o driver como uma implantação. Você deve instalar o JDBC driver 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 módulo core

      Para instalar um JDBC driver como um módulo core, você deve criar uma estrutura do caminho do arquivo sob o diretório EAP_HOME/modules/. 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 definir o 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 você NÃO possui espaço no início do arquivo module.xml ou você obterá um erro "New missing/unsatisfied dependencies" para este driver.
        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 licença JAR 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 você NÃO possui espaço no início do arquivo module.xml ou você obterá um erro "New missing/unsatisfied dependencies" para este driver.
        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 storage domain.

2. Configuração da fonte de dados

   1. Adição do 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. Criação da 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

      Você deve interromper o servidor antes de editar o arquivo de configuração do servidor para a sua alteração ser persistente na iniciação 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>
      
      

Procedimento 3.9. 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.10. Modificação das pesquisas JNDI

1. Leia mais a respeito deste assunto na Seção 3.1.8.2, “Sintaxe de Nomeação JNDI Portável”

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 (Espaço do Nome JNDI)”