Capítulo 3. Migre su aplicación

1. Primero mire el empaque de su aplicación y sus dependencias. Para mayores detalles consulte: Sección 3.1.2.3, “Actualizar las dependencias de la aplicación debido a los cambios en la carga de clases”
2. Si su aplicación realiza registros entonces necesita especificar las dependencias correctas de los módulos. Para obtener mayor información consulte: Sección 3.1.4.1, “Modificar las dependencias de registros”
3. Debido a los cambios en la carga modular de clases es posible que tenga que cambiar la estructura de empaque de su EAR o WAR. Para obtener mayor información consulte: Sección 3.1.5.1, “Modificación del empaque de EARs y WARs”

Procedimiento 3.1. Dependencias de módulos

1. Dependencias implícitas

   Los implementadores dentro del servidor implícitamente agregan de manera automática algunas dependencias de módulos utilizadas comúnmente como javax.api y sun.jdk. Esto hace que las clases sean visibles para la implementación en el tiempo de ejecución y libera al desarrollador de la tarea de agregar explícitamente las dependencias. Para obtener detalles sobre la manera en que estas dependencias implícitas se agregan, consulte Dependencias de módulos implícitos en el capítulo titulado Carga de clases y módulos en la Guía de desarrollo para JBoss EAP 6 en https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

2. Dependencias explícitas

   Para otras clases, los módulos se deben especificar explícitamente o de otra manera las dependencias que faltan generan errores en la implementación o en el tiempo de ejecución. Si una dependencia falta entonces verá rastros de ClassNotFoundExceptions o NoClassDefFoundErrors en el registro del servidor. Si más de un módulo carga la misma JAR o un módulo carga una clase que extienda una clase cargada por un módulo diferente podrá ver los rastros de ClassCastExceptions en el registro del servidor. Para especificar dependencias de manera explícita, modifique el MANIFEST.MF o cree un archivo descriptor de implementación jboss-deployment-structure.xml específico para JBoss. Para mayor información sobre dependencias de módulos consulte la Sinopsis de carga de clases y módulos en el capítulo titulado Carga de clases y módulos en la Guía de desarrollo para JBoss EAP 6 en https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Procedimiento 3.2. Cambiar la ubicación de las propiedades ResourceBundle

1. Si está implementando un archivador WAR tiene que empacar esas propiedades en la carpeta WEB-INF/classes/ del WAR.
2. Si quiere que esas propiedades sean accequibles para todos los componentes en un EAR entonces debe empacarlos en la raíz de una JAR y luego poner la JAR en la carpeta lib/ del EAR.

Procedimiento 3.3. Crear un módulo personalizado

1. Crear y poblar la estructura del directorio module/.
   1. Crear una estructura de directorio bajo el directorio EAP_HOME/module para que contenga los archivos y JARs. Por ejemplo:

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

   2. Mueva el archivo de propiedades al directorio EAP_HOME/modules/myorg-conf/main/properties/ que creó en el paso anterior.
   3. Cree un archivo module.xml en el directorio EAP_HOME/modules/myorg-conf/main/ conteniendo el siguiente XML:

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

2. Modifique el subsistema ee en el archivo de configuración del servidor. Puede utilizar el CLI JBoss o puede modificar manualmente el archivo.
   • Siga estos pasos para modificar el archivo de configuración usando el CLI JBoss.
     1. Inicie el servidor y conéctese al CLI de administración.
        • Para Linux, ingrese lo siguiente en la línea de comandos:

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

        • Para Windows, ingrese lo siguiente en la línea de comandos:

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

        Debe ver la siguiente respuesta:

        Conectado a un controlador autónomo en localhost:9999

     2. Para crear el elemento myorg-conf <global-modules> en el subsistema ee escriba lo siguiente en la línea de comandos:

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

        Debe ver el siguiente resultado:

        {"outcome" => "success"}
        

   • Siga estos pasos si prefiere modificar manualmente el archivo de configuración del servidor.
     1. Detenga el servidor y abra el archivo de configuración del servidor en un editor de texto. Si está ejecutando un servidor autónomo este es el archivo EAP_HOME/standalone/configuration/standalone.xml o el archivo EAP_HOME/domain/configuration/domain.xml si está ejecutando un dominio administrado.
     2. Identifique el subsistema ee y agregue el módulo global para myorg-conf. El siguiente es un ejemplo del elemento subsistema ee modificado para incluir el elemento myorg-conf:

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

3. Asumiendo que copió un archivo llamado my.properties en la ubicación correcta del módulo ahora puede cargar archivos de propiedades usando código similar al siguiente:

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

Procedimiento 3.4. Actualización del código de registros de la aplicación

1. Sección 3.1.4.2, “Actualización del código de aplicación para marcos de trabajo de registros de terceros”
2. Sección 3.1.4.3, “Modificar el código para utilizar el nuevo marco de trabajo de inicio de sesión JBoss”

Procedimiento 3.5. Configuración de JBoss EAP 6 para utilizar un archivo log4j.properties o log4j.xml

1. Cree un jboss-deployment-structure.xml con el siguiente contenido:

   <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. Ponga el archivo jboss-deployment-structure.xml en el directorio META-INF/ o en el directorio WEB-INF/ si está implementando un WAR o en el directorio META-INF/ si está implementando un EAR. Si su implementación incluye implementaciones dependientes hijas también debe excluir el módulo para cada subimplementación.
3. Incluya el archivo log4j.properties o log4j.xml en el directorio lib/ de su EAR o el directorio WEB-INF/classes/ de su implementación WAR. Si prefiere poner el archivo en el directorio lib/ de su WAR, debe especificar la ruta <resource-root> en el archivo 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 el servidor JBoss EAP 6 con el siguiente argumento de tiempo de ejecución para prevenir que se presente una ClassCastException en la consola cuando implementa la aplicación:

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

5. Implemente su aplicación.

Procedimiento 3.6. Configuración de las dependencias de registro para JBoss EAP 6.3 o posteriores

1. Inicie el servidor JBoss EAP 6 con el siguiente argumento de tiempo de ejecución para prevenir que se presente una ClassCastException en la consola cuando implementa la aplicación:

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

2. Abra una terminal y conéctese al CLI de administración.
   • Para Linux, ingrese lo siguiente en la línea de comandos:

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

   • Para Windows, ingrese lo siguiente en la línea de comandos:

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

3. Modifique el atributo add-logging-api-dependencies en el subsistema de registro.
   Este atributo controla si el contenedor debe agregar dependencias implícitas API de registro a sus implementaciones.

   • Si se configura como true, el cual es el valor predeterminado entonces se agregan todas las dependencias API de registro implícitas.
   • Si se configura como false entonces las dependencias no se agregan a sus implementaciones.
   Para excluir las dependencias del marco de trabajo de registro de terceros debe establecer este atributo como false utilizando el siguiente comando:

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

   Este comando agrega el elemento <add-logging-api-dependencies> al subsistema logging del archivo de configuración standalone.xml.

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

4. Implemente su aplicación.

Procedimiento 3.7. Modificar el código y las dependencias para utilizar el marco de trabajo de inicio de sesión JBoss

1. Cambie sus importaciones y su código de inicio de sesión

   El siguiente es un ejemplo del código que utiliza el nuevo marco de trabajo de inicio de sesión 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. Agregue la dependencia de inicio de sesión

   La JAR que contiene las clases de inicio de sesión de JBoss se encuentra en el módulo llamado org.jboss.logging. Su archivo MANIFEST-MF se debe ver así:

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

   Para mayor información sobre cómo encontrar la dependencia del módulo consulte Sección 3.1.2.3, “Actualizar las dependencias de la aplicación debido a los cambios en la carga de clases” and Sección 4.2.1, “Depurar y resolver problemas de migración”.

Procedimiento 3.8. Modificación del empaque de archivadores

1. Empaque de un WAR

   Un WAR es un solo módulo y todas las clases en el WAR se cargan con el mismo cargador de clases. Esto significa que las clases empacadas en el directorio WEB-INF/lib/ se tratan de igual manera que las clases en el directorio WEB-INF/classes.

2. Empaque de un EAR

   Un EAR consiste de múltiples módulos. El directorio EAR/lib/ es un solo módulo y toda subimplementación EJB jar o WAR dentro del EAR es un módulo separado. Las clases no tienen acceso a las clases en otros módulos dentro del EAR a menos de que se hayan definido dependencias explícitas. Las subimplementaciones siempre tienen una dependencia automática en el módulo padre el cual les proporciona acceso a las clases en el directorio EAR/lib/. Sin embargo, las subimplementaciones no siempre tienen una dependencia automática para permitirles el acceso entre ellas. Este comportamiento se controla configurando el elemento <ear-subdeployments-isolated> en la configuración del subsistema ee así:

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

   Por defecto esto se configura como falso, lo cual permite que las subimplementaciones vean las clases que pertenecen a otras subimplementaciones dentro del EAR.
   Para mayor información sobre la carga de clases consulte el capítulo titulado Módulos y carga de clases en la Guía de desarrollo para JBoss EAP 6 en https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

1. Si su aplicación usa una fuente de datos consulte: Sección 3.1.6.2, “Actualización de la configuración de la fuente de datos”.
2. Si su aplicación usa JPA y actualmente une las JARs Hibernate consulte lo siguiente para ver sus opciones de migración: Sección 3.1.6.4, “Configuración de la fuente de datos para Hibernate o JPA”.
3. Si su aplicación usa un adaptador de recursos consulte: Sección 3.1.6.5, “Actualización de la configuración del adaptador de recursos”.
4. Revise lo siguiente para obtener mayor información sobre cómo configurar los cambios para la seguridad básica: Sección 3.1.7.1, “Configuración de los cambios de seguridad de la aplicación”.

Procedimiento 3.9. Instalación y configuración del controlador JDBC

1. Instale el controlador JDBC.

   1. Instale el controlador JDBC como implementación.

      Esta es la manera recomendada de instalar el controlador. Cuando el controlador JDBC se instala como una implementación, se implementa como una JAR normal. Si la instancia de JBoss EAP 6 está ejecutando como un servidor autónomo, copie la JAR que cumple con los requerimientos de JDBC 4.0 en el directorio EAP_HOME/standalone/deployments/. Para un dominio administrado tiene que utilizar la consola de administración o el CLI de administración para implementar la JAR en los grupos de servidores.
      El siguiente es un ejemplo de un controlador MySQL JDBC instalado como una implementación en un servidor autónomo:

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

      Cualquier controlador que cumple con los requerimientos de JDBC 4.0 es reconocido automáticamente y se instala en el sistema por nombre y versión. Una JAR que cumple con los requerimientos de JDBC 4.0 contiene un archivo de texto llamado META-INF/services/java.sql.Driver, el cual especifica los nombres de las clases controladoras. Si el controlador no cumple con los requerimientos de JDBC 4.0 entonces se puede hacer que se implemente de una de las siguientes maneras:

      • Cree y agregue un archivo java.sql.Driver a la JAR bajo la ruta META-INF/services/. Este archivo debe contener el nombre de la clase del controlador, por ejemplo:

        com.mysql.jdbc.Driver

      • Cree un archivo java.sql.Driver en el directorio de implementaciones. Para una instancia de JBoss EAP 6 ejecutando como un servidor autónomo, el archivo se debe poner aquí: EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver. Si el servidor está en un dominio administrado entonces debe utilizar la consola de administración o el CLI de administración para implementar el archivo.
      Las ventajas de este enfoque son:

      • Este es el método más fácil ya que no hay necesidad de definir un módulo.
      • Cuando el servidor está ejecutando en un dominio administrado, las implementaciones que usan este enfoque se propagan de manera automática en todos los servidores en el dominio. Esto significa que el administrador no necesita distribuir el controlador JAR manualmente.

      Las desventajas de este enfoque son:

      • Si el controlador JDBC consiste de mas de una JAR, por ejemplo el controlador JAR más una licencia JAR dependiente o una JAR de localización, no puede instalar el controlador como una implementación. Tiene que instalar el controlador JDBC como un módulo núcleo.
      • Si el controlador no cumple con los requerimientos de JDBC 4.0 entonces se debe crear un archivo que contenga los nombres de las clases controladoras y tiene que ser importado en la JAR o superpuesto en el directorio deployments/.

   2. Instalación del controlador JDBC como módulo central .

      Para instalar un controlador JDBC como un módulo núcleo, tiene que crear una estructura de ruta de archivos bajo el directorio EAP_HOME/modules/. Esta estructura contiene la JAR del controlador JDBC, las JARS de localización o las licencias adicionales del vendedor y un archivo module.xml para definir el módulo.

      • Instale el controlador MySQL JDBC como módulo núcleo

        1. Cree la estructura del directorio EAP_HOME/modules/com/mysql/main/
        2. En el subdirectorio main/, cree un archivo module.xml que contenga la siguiente definición de módulo para el controlador 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>
           
           

           El nombre del módulo, "com.mysql", coincide con la estructura del directorio para este módulo. El elemento <dependencies> se usa para especificar las dependencias de este módulo en otros módulos. En este caso, tal como los es con todas las fuentes de datos JDBC, depende de las APIs JDBC Java que se definen en otro módulo llamado javax.api. Ese módulo se encuentra bajo el directorio modules/system/layers/base/javax/api/main/.

           Nota

           Asegúrese de NO tener un espacio al principio del archivo module.xml de otra manera obtendrá un error "New missing/unsatisfied dependencies" para este controlador.
        3. Copie la JAR del controlador MySQL JDBC en el directorio EAP_HOME/modules/com/mysql/main/:

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

      • Instalación del controlador IBM DB2 JDBC y la JAR licencia como un módulo núcleo.

        Este ejemplo se proporciona sólo para demostrar la manera de implementar controladores que requieren JARs además de la JAR del controlador JDBC.
        1. Cree la estructura del directorio EAP_HOME/modules/com/ibm/db2/main/.
        2. En el subdirectorio main/, cree un archivo module.xml que contenga la siguiente definición de módulo para el controlador IBM DB2 JDBC y licencia:

           <?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

           Asegúrese de NO tener un espacio al principio del archivo module.xml de otra manera obtendrá un error "New missing/unsatisfied dependencies" para este controlador.
        3. Copie el controlador JDBC y la JAR de lincencia en el directorio 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/

      Las ventajas de este enfoque son:

      • Este es el único enfoque que funciona cuando el controlador JDBC consiste de más de una JAR.
      • Con este enfoque, los controladores que no cumplen con los requerimientos de JDBC 4.0 se pueden instalar sin modificar la JAR del controlador o creando una superposición de archivos.

      Las desventajas de este enfoque son:

      • Es más dificil configurar un módulo.
      • El módulo se debe copiar manualmente en todos los servidores ejecutando en un dominio administrado.

2. Configure la fuente de datos.

   1. Agregue el controlador de la base de datos.

      Agregar el elemento <driver> al elemento <drivers> del mismo archivo. Nuevamente esto contiene alguna de la misma información de la fuente de datos que se definió previamente en el archivo *-ds.xml.
      Primero determine si la JAR controladora cumple con los requerimientos de JDBC 4.0. Una JAR que cumple con los requerimientos de JDBC 4.0 contiene un archivo META-INF/services/java.sql.Driver que especifica el nombre de la clase controladora. El servidor usa este archivo para encontrar el nombre de las clases controladoras en la JAR. Un controlador que cumpla con los requerimientos de JDBC 4.0 no requiere un elemento <driver-class> ya que ya se especifica en la JAR. Este es un ejemplo del elemento controlador para un controlador MySQL que cumple con los requerimientos de JDBC 4.0:

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

      Un controlador que no cumple con los requerimientos de JDBC 4.0 requiere un atributo <driver-class> para identificar la clase del controlador ya que no hay un archivo META-INF/services/java.sql.Driver que especifique el nombre de la clase controladora. Este es un ejemplo del elemento controlador para el controlador que no cumpla con los requerimientos de 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. Creación de la fuente de datos.

      Cree un elemento <datasource> en la sección <datasources> del archivo standalone.xml. Este archivo contiene mucha de las misma información de la fuente de datos que se definió anteriormente en el archivo *-ds.xml.

      Importante

      Tiene que detener el servidor antes de modificar el archivo de configuración del servidor para que su cambio persista al reiniciar el servidor.
      El siguiente es un ejemplo de un elemento de la fuente de datos MySQL en el archivo 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. Actualización de las referencias JNDI en el código de la aplicación.

   Debe reemplazar los nombres de las búsquedas JNDI que estén desactualizados en el código fuente de la aplicación para utilizar los nuevos nombres de la fuente de datos estándar JNDI que haya definido. Para obtener mayor información, consulte: Sección 3.1.8.4, “Modifique la aplicación a seguir las nuevas reglas de los espacios de nombre JNDI”.
   También debe reemplazar cualquier anotación @Resource existente que acceda la fuente de datos para utilizar el nuevo nombre JNDI. Por ejemplo:

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

Procedimiento 3.10. Borre el paquete Hibernate

1. Borre las JARs Hibernate de sus carpetas de la biblioteca de su aplicación.
2. Borre o comente el elemento <hibernate.transaction.manager_lookup_class> en su archivo persistence.xml ya que este elemento no se necesita.

Procedimiento 3.11. Desactivación de chequeos adicionales de autorización

• Puede desactivar los chequeos adicionales de autorización y seguir utilizando las implementaciones PicketLink existentes utilizando uno de los siguientes métodos.

  • Configuración de una propiedad a nivel del sistema

    Puede desactivar chequeos adicionales de autorización a nivel del servidor configurando el valor de la propiedad del sistema org.jboss.ws.cxf.disableHandlerAuthChecks como true. Este método afecta cualquier implementación realizada en el servidor de aplicaciones.
    Para obtener mayor información sobre cómo configurar una propiedad del sistema consulte la sección titulada Configuración de propiedades del sistema utilizando el CLI de administración en la Guía de configuración y administración para JBoss EAP.

  • Creación de una propiedad en el archivo descriptor de servicios web de la implementación

    Puede desactivar chequeos adicionales de autorización a nivel de la implementación configurando el valor de la propiedad org.jboss.ws.cxf.disableHandlerAuthChecks como true en el archivo jboss-webservices.xml. Este método tiene impacto solo en la implementación especifica.
    1. Cree un archivo jboss-webservices.xml en el directorio META-INF/ de la implementación en la que quiere desactivar los chequeos adicionales de autorización.
    2. Agregue el siguiente contenido:

       <?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>

Procedimiento 3.12. Modificar búsquedas JNDI

1. Mayor información sobre Sección 3.1.8.2, “Nombres JNDI EJB portátiles”
2. Sección 3.1.8.3, “Revisión de las reglas del espacio de nombres de JNDI”
3. Sección 3.1.8.4, “Modifique la aplicación a seguir las nuevas reglas de los espacios de nombre JNDI”