Capítulo 5. Alterações na migração dos aplicativos

A API Java para RPC baseado em XML(JAX-RPC) foi preterida no Java EE 6 e é opcional no Java EE 7. Ela não está mais disponível ou suportada no JBoss EAP 7. Aplicativos que utilizam JAX-RPC devem ser migrados para utilizar JAX-WS, que é a atual framework de serviços web padrões Java EE.

A utilização dos serviços web JAX-RPC pode ser identificada em qualquer uma das seguintes maneiras:

Em versões prévias do JBoss EAP, você podia personalizar a integração do JBossWS e Apache CXF ao incluir um arquivo de configuração jbossws-cxf.xml com o arquivo de implementação de ponto de extremidade. Um caso de utilização para isto era configurar correntes de interceptores para cliente de serviço web e pontos de extremidades de servidores no barramento Apache CXF. Esta integração exigia a implantação de Spring no servidor JBoss EAP.

A integração do Spring não é mais suportada no JBoss EAP 7. Qualquer aplicativo que contiver um arquivo de configuração de descritor jbossws-cxf.xml deve ser modificado para substituir a configuração personalizada definida naquele arquivo. Embora ainda seja possível acessar diretamente a API Apache CXF, fique ciente de que o aplicativo não será portátil.

A abordagem sugerida é para substituir configurações personalizadas de Spring com as novas opções de configuração de descritor JBossWS quando possível. A abordagem baseada em descritor JBossWS fornece funcionalidade similar sem exigir modificação do código de ponto de extremidade do cliente. Em alguns casos, você pode substituir Spring por Context Dependency Injection (CDI).

Interceptores Apache CXF

O descritor JBossWS fornece novas opções de configurações que permitem a você declarar os interceptores sem modificar o código de ponto de extremidade do cliente. Alternativamente, você declara interceptores dentro de clientes pré-definidos e configurações de pontos de extremidade ao especificar uma lista de nomes de classe de interceptor para as propriedades cxf.interceptors.in e cxf.interceptors.out.

Segue um exemplo de um arquivo jaxws-endpoint-config.xml que declara interceptores usando estas propriedades.

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

Recursos Apache CXF

O descritor JBossWS permite que você declare recursos dentro do cliente pré-definido e configurações de ponto de extremidade ao especificar uma lista de nomes de classe de recursos para a propriedade cxf.features.

Segue um exemplo de um arquivo jaxws-endpoint-config.xml que declara um recurso usando esta propriedade.

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

Apache CXF HTTP Transport

Em Apache CXF, a configuração do transporte HTTP é alcançada ao especificar opções org.apache.cxf.transport.http.HTTPConduit. A Integração JBossWS permite que conduits sejam modificados programaticamente usando a API Apache CXF como segue.

import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.transports.http.configuration.HTTPClientPolicy;

// Set chunking threshold before using a JAX-WS port client
...
HTTPConduit conduit = (HTTPConduit)ClientProxy.getClient(port).getConduit();
HTTPClientPolicy client = conduit.getClient();

client.setChunkingThreshold(8192);
...

Você pode também controlar e substituir os valores padrão Apache CXF HTTPConduit ao definir as propriedades de sistema.

Os Jars cxf-api e cxf-rt-core foram agrupados em um JAR cxf-core. Como consequência, o módulo org.apache.cxf no JBoss EAP agora contém o JAR cxf-core e expõe mais classes que o lançamento anterior.

Se você quiser usar criptografia AES com Galois/Counter Mode (GCM) para criptografia simétrica em XML/WS-Security, você precisa do provedor de segurança BouncyCastle.

JBoss EAP 7 envia com módulo org.bouncycastle e JBossWS agora pode confiar em seus carregadores de classes para obter e usar o provedor de segurança BouncyCastle. Portanto, não é mais necessário instalar estaticamente BouncyCastle em JVM atual. Para aplicativos executando fora do contêiner, o fornecedor de segurança pode ser disponibilizado para JBossWS ao adicionar uma biblioteca BouncyCastle ao caminho da classe.

Você pode desativar este comportamento ao configurar o valor de propriedade org.jboss.ws.cxf.noLocalBC para true no arquivo descritor de implementação jaxws-endpoint-config.xml para o servidor ou no arquivo do descritor jaxws-client-config.xmlpara clientes.

Se você quiser uma versão diferente daquela que é enviada com o JBoss EAP, você ainda pode instalar estaticamente o BouncyCastle para a JVM. Neste caso, o provedor de segurança BouncyCastle é escolhido entre o provedor presente no caminho da classe. Para evitar quaisquer problemas, você deve usar BouncyCastle 1.49, 1.51 ou versão superior.

A estratégia de seleção do barramento padrão para clientes executando dentro de contêiner mudou de THREAD_BUS para TCCL_BUS. Para clientes executando fora de contêiner, a estratégia padrão ainda é THREAD_BUS. Você pode restaurar o comportamento para o lançamento anterior ao utilizar um dos seguintes métodos.

Contêiner deve usar construtores de estilo JAX-WS 2.2, usando a classeWebServiceFeature para compilar clientes que são injetados nas referências do web service. Isto significa que as classes de serviço fornecidas por usuários injetadas pelo contêiner devem implementar JAX-WS 2.2 ou versão superior.

Em lançamentos prévios, você podia desativar a verificação do nome de host de URL HTTPS com o nome comum (CN - Common Name) do serviço fornecido em seu certificado ao definir a propriedade de sistema org.jboss.security.ignoreHttpsHost para true. Este nome de propriedade de sistema foi substituído por cxf.tls-client.disableCNCheck.

As a consequence of enabling injections into service endpoint and service client handlers, it is no longer possible to automatically load handler classes from the org.jboss.as.webservices.server.integration JBoss module. If your application depends on a given predefined configuration, you might need to explicitly define new module dependencies for your deployment. For more information, see Migrate Explicit Module Dependencies

O mecanismo de substituição de standards endossados Java https://docs.oracle.com/javase/8/docs/technotes/guides/standards/ foi descontinuado no JDK 1.8_40 com a intenção de removê-lo no JDK 9. Este mecanismo permite desenvolvedores disponibilizar bibliotecas para todos os aplicativos implantados ao colocar JARs em um diretório endossado dentro do JRE.

Se seu aplicativo utiliza implementações JBossWS de Apache CXF, o JBoss EAP 7 assegura que as dependências necessárias sejam adicionadas na ordem correta e esta alteração não deve causar impacto para você. Se seu aplicativo acessa Apache CXF diretamente, você deve fornecer agora as dependências Apache CXF depois das dependências JBossWS como parte da implantação de seu aplicativo.

Em lançamentos prévios do JBoss EAP, era possível configurar o arquivo de descritor de implantação jboss-webservices.xml para implantações de servidor web EJB no diretório META-INF/ dos arquivos JAR ou no diretório WEB-INF/ para implantações de serviço web POJO e pontos de extremidades de serviço web EJB agrupados em arquivos WAR.

Agora no JBoss EAP 7, você pode configurar o arquivo de descritor de implantação jboss-webservices.xml no diretório META-INF/ de um arquivo EAR. Caso um arquivo jboss-webservices.xml for encontrado em ambos os arquivos EAR e o JAR ou arquivo WAR, os dados de configuração no arquivo jboss-webservices.xml para o JAR ou WAR substitui os dados correspondentes no arquivo descritor EAR.

Os arquivos de descritores de implantação de recursos JMS proprietários identificados pelo modelo de nomenclatura -jms.xml são obsoletos no JBoss EAP 7. Segue um exemplo de um arquivo de descritor de implantação de recurso JMS no JBoss EAP 6.

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
  <hornetq-server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </hornetq-server>
</messaging-deployment>

Se você usou descritores de implantação JMS -jms.xml em seu aplicativo em lançamentos prévios, você pode converter seu aplicativo para usar o descritor de implantação Java EE 7 padrão, conforme especificado na seção EE.5.18 da especificação Java EE 7, ou você pode atualizar o descritor de implantação para usar o subsistema messaging-activemq no JBoss EAP 7.

Se você escolher atualizar o descritor, você precisa fazer as seguintes modificações.

O arquivo modificado deve parecer com o exemplo que segue.

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-activemq-deployment:1.0">
  <server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </server>
</messaging-deployment>

Para informação sobre alterações de configuração de servidor relacionadas a mensagens, consulte Alterações de configuração de servidor de mensagens.

JBoss EAP 7 ainda suporta API JMS 1.1, assim você não precisa modificar seu código.

O conector remoto padrão e porta foram alterados no JBoss EAP 7. Para detalhes sobre esta mudança, consulte Atualize o conector URL remoto e porta.

Se você migrar sua configuração de servidor usando a operação migrate, as configurações antigas são preservadas e você não precisa atualizar seu PROVIDER_URL. Porém, se você executar com a configuração padrão nova do JBoss EAP 7, você deve alterar o PROVIDER_URL no código do cliente para usar a nova configuração http-remoting://localhost:8080. Para mais informações, consulte Migrar a designação de código de cliente remoto.

Se você planeja migrar seu código para usar a API JMS 2.0, consulte o início rápido helloworld-jms para um exemplo prático.

O JBoss EAP 6 incluía o módulo org.hornetq, que permitia que você usasse API HornetQ no código de fonte de seu aplicativo.

Apache ActiveMQ Artemis substitui HornetQ no JBoss EAP 7, por isso você deve migrar qualquer código que utilizava API HornetQ para utilizar API Apache ActiveMQ Artemis . As bibliotecas para esta API estão incluídas no módulo org.apache.activemq.artemis.

ActiveMQ Artemis é uma evolução do HornetQ, por isso muitos conceitos ainda são válidos.

Classes de corpo de mensagem e interceptores

JSR 311: JAX-RS: A API Java™ para RESTful Web Services não incluía uma framework de interceptor, por isso RESTEasy 2 forneceu uma. JSR 339: JAX-RS 2.0: A API Java para RESTful Web Services introduziu um interceptor oficial e frameworkd de filtro, por isso a framework do interceptor incluída no RESTEasy 2 está agora preterida e foi substituída pelo interceptor compatível JAX-RS 2.0 no RESTEasy 3.x. As interfaces relevantes estão definidas no pacote javax.ws.rs.ext do módulo jaxrs-api.

For more information about interceptors, see RESTEasy Interceptors in Developing Web Services Applications for JBoss EAP.

Para mais informações sobre a nova API de substituição, consulte RESTEasy JAX-RS 3.0.13.Final API ou mais recente.

API Cliente

A framework do cliente RESTEasy de resteasy-jaxrs foi substituída pelo módulo resteasy-client compatível a JAX-RS 2.0. Sendo assim, algumas classes e métodos de API do cliente RESTEasy são preteridos.

StringConverter

A classe org.jboss.resteasy.spi.StringConverter está preterida em RESTEasy 3.x. Esta funcionalidade pode ser substituída usando a classe JAX-RS 2.0 jax.ws.rs.ext.ParamConverterProvider.

Métodos de adição de ResteasyProviderFactory

A maior parte de métodos org.jboss.resteasy.spi.ResteasyProviderFactory add() foi removida ou protegida do RESTEasy 3.0. Por exemplo, os métodos addBuiltInMessageBodyReader() e addBuiltInMessageBodyWriter() foram removidos e os métodos addMessageBodyReader() e addMessageBodyWriter() foram protegidos.

Agora, você deve usar os métodos registerProvider() e registerProviderInstance().

Classes suplementares removidas do RESTEasy 3

A anotação @org.jboss.resteasy.annotations.cache.ServerCached, que especificava a resposta para o método JAX-RS deve ser memorizada no servidor, foi removida do RESTEasy 3 e deve ser removida do código do aplicativo.

SignedInput e SignedOuput

Filtros de segurança

Os filtros de segurança para @RolesAllowed, @PermitAll e @DenyAll agora retornam "403 Forbidden" ao invés de "401 Unauthorized".

Filtros do lado do cliente

Os novos filtros JAX-RS 2.0 lado cliente não serão limitados e executarão quando você estiver usando a API de cliente RESTEasy a partir de um lançamento prévio.

Suporte HTTP assíncrono

Because the JAX-RS 2.0 specification adds asynchronous HTTP support using the @Suspended annotation and the AsynResponse interface, the RESTEasy proprietary API for asynchronous HTTP has been deprecated and might be removed as soon as RESTEasy 3.1. The asynchronous Tomcat and asynchronous JBoss Web modules have also been removed from the server installation. If you are not using the Servlet 3.0 container or higher, asynchronous HTTP server-side processing will be simulated and run synchronously in same request thread.

Cache do lado do servidor

A configuração da cache do lado do servidor foi alterada. Por favor, consulte a Documentação RESTEasy para mais informações.

Exceções SPI

Todas exceções de falhas SPI foram preteridas e não são mais utilizadas internamente. Elas foram substituídas com a exceção JAX-RS 2.0 correspondente.

InjectorFactory e Registro

As SPIs InjectorFactory e Registry foram alteradas. Isto não deve ser um problema se você usar RESTEasy conforme documentado e suportado.

A versão de Jackson incluída no JBoss EAP foi alterada. A versão anterior do JBoss EAP incluía Jackson 1.9.9. O JBoss EAP 7 inclui agora Jackson 2.6.3 ou superior. Como resultado, o provedor Jackson foi alterado de resteasy-jackson-provider para resteasy-jackson2-provider

A atualização para o resteasy-jackson2-provider requer algumas alterações de pacotes. Por exemplo, o pacote de anotações Jackson foi alterado de org.codehaus.jackson.annotate para com.fasterxml.jackson.annotation.

To switch your application to use the default provider that was included in the previous release of JBoss EAP, see Switching the Default Jackson Provider in Developing Web Services Applications for JBoss EAP.

A framework de Spring 4.0 introduziu suporte para Java 8. Se você planeja usar integração RESTEasy 3.x com Spring, certifique-se que especificou 4.2.x como a versão mínima para Spring em sua implantação pois esta é a versão estável mais recente suportada pelo JBoss EAP 7.

O fornecedor RESTEasy Jettison JSON é preterido no JBoss EAP 7 e não é mais adicionado às implantações por padrão. Aconselhamos que troque para o fornecedor recomendado RESTEasy Jackson. Se preferir continuar a utilizar o fornecedor Jettison, você deve definir uma dependência explicita para ele no arquivo jboss-deployment-descriptor.xml como demonstrado no seguinte exemplo.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

For more information about how to define explicit dependencies, see Add an Explicit Module Dependency to a Deployment in the JBoss EAP Development Guide.

As classes de integração que facilitaram a utilização do Hibernate ORM 3 em lançamentos prévios foram removidas do JBoss EAP 7. Se seu aplicativo ainda utiliza bibliotecas do Hibernate ORM 3, é altamente recomendável que você migre seu aplicativo para utilizar Hibernate ORM 5 pois Hibernate ORM 3 não funcionará mais em JBoss EAP facilmente. Se você não pode migrar para Hibernate ORM 5, você deve definir um módulo JBoss personalizado para os JARs de Hibernate ORM 3 e excluir as classes de Hibernate ORM 5 de seu aplicativo.

Caso seu aplicativo necessite que o cache de segundo nível seja ativado, você deve migrar para Hibernate ORM 5.0, que é integrado com Infinispan 8.x.

Aplicativos escritos com Hibernate ORM 4.x ainda podem usar Hibernate 4.x. Você deve definir um módulo JBoss personalizado para os JARs Hibernate 4.x e excluir as classes Hibernate 5 de seu aplicativo. Contudo, é altamente recomendável que você reescreva o código de seu aplicativo para usar Hibernate 5. Para information sobre como migrar para Hibernate ORM 5, consulte Migrating to Hibernate ORM 5.

Caso seu aplicativo contiver um arquivo persistence.xml ou o código usa anotações @PersistenceContext ou @PersistenceUnit, JBoss EAP 7 detecta isto durante a implantação e presume que o aplicativo usa JPA. As bibliotecas Hibernate ORM 5.O são implicitamente adicionadas, assim como algumas outras dependências, ao caminho de classe de seu aplicativo e estas bibliotecas são usadas por padrão.

Esta seção destaca as alterações que você precisa fazer quando migrar do Hbernate ORM versão 4.3 para versão 5. Para mais informações sobe as alterações implementadas entre o Hibernate ORM 4 e Hibernate ORM 5, consulte o Guia de migração Hibernate ORM 5.0.

Classes preteridas e excluídas

The following deprecated classes were removed from Hibernate ORM 5.

Outras alterações às classes e pacotes

Type Handling

Gerenciamento de transação.

Outra alteração Hibernate ORM 5

Modifique o valor de porta da conexão remota de 4447 para 8080 no arquivo jboss-ejb-client.properties.

Os exemplos seguintes são de um arquivo jboss-ejb-client.properties na versão antiga e na atual.

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=4447
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=8080
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

Se você esta executando com a nova configuração de JBoss EAP 7, o conector padrão foi modificado de remote para http-remoting. Esta alteração impacta clientes que utilizam bibliotecas de uma versão de JBoss EAP para conectar-se ao servidor em uma versão diferente.

Se você está executando com a nova configuração padrão JBoss EAP 7, você deve modificar seu código cliente para usar a nova porta remota padrão e conector.

O exemplo seguinte é de como propriedades de nomeação remota foram especificadas no código cliente no JBoss EAP 6.

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=remote://localhost:4447

O exemplo seguinte é de como especificar as propriedades de nomeação remota no código cliente no JBoss EAP 7.

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

As válvulas do autenticador devem ser substituídas manualmente usando o mecanismo de autenticação interno Undertow. Consulte as seções seguintes para informações sobre como migrar válvulas do autenticador.

For information about the changes required for SSO with SAML v2 configuration, see Changes from Previous Versions of JBoss EAP in How to Set Up SSO with SAML v2 for JBoss EAP.

For information about the differences in SSO configuration with Kerberos, see Differences from Configuring Previous Versions JBoss EAP in How to Set Up SSO with Kerberos for JBoss EAP.

A lista seguinte descreve algumas das novas funcionalidades de clusterização para considerar quando fizer a migração de seu aplicativo do JBoss EAP 6 para JBoss EAP 7.

The remainder of this section describes how clustering changes might impact the migration of your applications to JBoss EAP 7.

O JBoss EAP 7 introduz uma nova implementação em web session clustering. Ela substitui a implementação anterior, que era acoplada rigidamente ao código-fonte do subsistema JBoss Web herdado.

A nova implementação Web Session Clustering impacta em como o aplicativo é configurado no arquivo descritor XML do aplicativo web proprietário jboss-web.xml do JBoss. Segue os únicos elementos de configuração de clustering que permaneceram neste arquivo.

<jboss-web>
  ...
  <max-active-sessions>...</max-active-sessions>
  ...
  <replication-config>
    <replication-granularity>...</replication-granularity>
    <cache-name>...</cache-name>
  </replication-config>
  ...
</jboss-web>

A tabela seguinte descreve como conseguir um comportamento similar para elementos no arquivojboss-web.xml que são obsoletos agora.

Esta nova implementação também suporta armazenamentos de cache de gravação, bem como armazenamentos de cache somente de passivação. Normalmente, armazenamentos de cache de gravação é usado em conjunto com um cache de invalidação. A implementação de cluster de sessões web no JBoss EAP 6 não funcionou corretamente quando usada com um cache de invalidação.

No JBoss EAP 6, era exigido que você habilitasse o comportamento do clustering para stateful session beans (SFSBs) em uma das seguintes maneiras.

O JBoss EAP 7 não exige mais que você habilite o comportamento do clustering. Por padrão, se o servidor for iniciado utilizando um perfil HA, o estado de SFSBs será replicado automaticamente.

Você pode desabilitar este comportamento padrão com uma das seguintes maneiras.

No JBoss EAP 6, as APIs para serviços de clustering estavam em módulos privados e não eram suportadas.

O JBoss EAP 7 introduz uma API de serviço de clustering público para ser utilizada pelos aplicativos. Os novos serviços são projetados para serem leves, facilmente injetáveis e não necessitar de dependências externas.

Estes serviços substituem APIs similares que estavam disponíveis em versões prévias, isto é, HAPartition do JBoss EAP 5 e GroupCommunicationService, GroupMembershipNotifier e GroupRpcDispatcher do JBoss EAP 6.

For more information, see Public API for Clustering Services in the JBoss EAP Development Guide.

No JBoss EAP 6, não havia API pública disponível para o serviço global de cluster HA singleton. Se você utilizava as classes privadas org.jboss.as.clustering.singleton.*, você deve alterar seu código para utilizar os novos pacotes públicos org.wildfly.clustering.singleton.* quando você migar seu aplicativo para JBoss EAP 7.

For more information about how to implement an HA singleton, see HA Singleton Service in the Development Guide for JBoss EAP.