Configuração de Drivers JDBC no JBoss AS 7

Há alguns anos atrás, quando comecei meus primeiros estudos na plataforma J2EE 5, perdi algumas semanas quebrando a cabeça para configurar datasources no servidor de aplicação JBoss AS (versão 5.1 na época). A última versão deste servidor (JBoss AS 7) mudou consideravelmente a forma de realizar esta configuração. Agora é possível fazer praticamente tudo em um único arquivo (standalone.xml) e as bibliotecas podem ser adicionadas como módulos, o que é uma das razões pela grande melhoria na velocidade de inicialização do servidor.

Nesta primeira postagem pretendo apenas demonstrar como devemos configurar o driver do banco de dados (abordarei a configuração para os SGBDs Oracle, PostgreSQL e MySQL).

A partir do JBoss Application Server na versão 7 há dois meios para configurar um driver JDBC. O primeiro é fazendo o deploy do driver (arquivo com a extensão .jar) no servidor e a outra é configurá-lo como módulo.

Adicionando o Driver JDBC como deployment

Por meio do primeiro método, recomendado pela documentação oficial do JBoss AS, é necessário apenas copiar o driver para o sub-diretório /standalone/deployments, assim como quando adicionávamos o driver no diretório common/lib nas versões anteriores (JBoss AS 5 e 6).

A vantagem dessa solução é que ela é a mais simples e que no modo domain (i.e., em ambientes clusterizados) você faz o deploy do driver e o mesmo é automaticamente propagado para todas as instâncias do servidor sem nenhum trabalho adicional.

A limitação é que ele funciona apenas para drivers compatíveis com o JDBC 4, sendo porém possível modificar drivers JDBC 3 de modo que funcionem por meio do deploy e, além disso, exige que seja especificada em toda xa-datasource a classe do driver. O driver também não pode ser adicionado como módulo caso ele consista em mais de um JAR. Nesse caso ele deve ser necessariamente ser instalado como deployment.

É importante destacar que no caso do servidor em modo domain não há um diretório em que você possa simplesmente colocar o JAR do driver e esperar que ele seja implantado automaticamente. Nesse caso é necessário utilizar as ferramentas de gerenciamento do JBoss (pretendo abordar essas ferramentas em um novo artigo).

Adicionando o Driver JDBC como módulo

O segundo método, que é recomendado por Francesco Marchioni [1], é adicionar o driver JDBC como um módulo do servidor, que é inicializado apenas quando especificado explicitamente no standalone.xml (ou domain.xml).

A configuração do driver JDBC como módulo no JBoss AS 7 é similar para qualquer SGBD, entretando há algumas particularidades. Primeiramente a estrutura de diretório depende da estrutura de empacotamento do driver JDBC e, além disso, esta estrutura deve estar descrita em um arquivo denominado module.xml. Esta diferenciação estará mais explícita conforme é demonstrada a configuração para cada um dos três SGBDs abordados neste post.

Configuração para o Oracle

O driver JDBC do Oracle pode ser obtido aqui e os seguintes passos devem ser seguidos para criar a estrutura de diretórios requerida pelo JBoss AS:

1. Vá ao diretório [JBoss_AS_Home]/modules/com
2. Crie o diretório ojdbc6 e dentro dele outra pasta chamada main
3. Coloque o driver JDBC (ojdbc6.jar) dentro do diretório main e dentro desta mesma pasta crie o arquivo module.xml que conterá a definição do módulo.

Ao final, a estrutura dos diretórios deverá ser a seguinte:

• [JBoss_AS_Home]/
• modules
• com
• oracle
• ojdbc6
• main
• module.xml
• ojdbc6.jar

O arquivo module.xml deverá ter o seguinte conteúdo:

<module xmlns="urn:jboss:module:1.0" name="com.oracle.ojdbc6">
 <resources>
   <resource-root path="ojdbc6.jar"/>
 </resources>
 <dependencies>
   <module name="javax.api"/>
 </dependencies>
</module>

Configuração para o PostgreSQL

Primeiramente é necessário baixar o driver JDBC do PostgreSQL que pode ser encontrado aqui. A versão do driver durante a edição deste post é a 9.1-901.jdbc4.

Os passos são similares aos descritos no tópico anterior sobre a configuração para o Oracle, porém no caso do Postgres a estrutura de diretório deve ficar assim:

• [JBoss_AS_Home]/
• modules
• org
• postgres
• main
• module.xml
• postgresql-9.1-901.jdbc4.jar

O arquivo modules.xml para o Postgres deve ser o seguinte:

<module xmlns="urn:jboss:module:1.0" name="org.postgres">
  <resources>
    <resource-root path="postgresql-9.0-801.jdbc4.jar"/>
  </resources>
   <dependencies>
     <module name="javax.api"/>
   </dependencies>
</module>

Configuração para o MySQL

O driver JDBC do MySQL pode ser baixado aqui e, novamente, os passos são similares aos dois drivers anteriores e a estrutura de diretório para o MySQL deve ser como abaixo:

• [JBoss_AS_Home]/
• modules
• com
• mysql
• main
• module.xml
• mysql-connector.jar

E este é o modules.xml para o MySQL:

<module xmlns="urn:jboss:module:1.0" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.1.17-bin.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
  </dependencies>
</module>

Datasources Transacionais

Caso sua aplicação precise utilizar datasources transacionais (xa-datasources) é necessário adicionar a dependência adicional javax.transaction.api no arquivo module.xml como no seguinte exemplo.

<module xmlns="urn:jboss:module:1.0" name="com.oracle.ojdbc6">
  <resources>
    <resource-root path="ojdbc6.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

A adição desta dependência para o driver dos outros SBGDs é equivalente à configuração exibida acima para o Oracle.

Declaração do Driver JDBC

Após a definição do driver JDBC como módulo é ainda necessário declará-lo no arquivo standalone.xml no subsystem "urn:jboss:domain:datasources:1.0", dentro das tags datasources e drivers como no exemplo abaixo:

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
    <datasources>
        <drivers>
            
            
        </drivers>
    </datasources>
</subsystem>

Abaixo estão representadas as declarações para cada SGBD abordado neste artigo.

Oracle

<driver name="oracle" module="com.oracle.ojdbc6">
  <xa-datasource-class>
    oracle.jdbc.OracleDriver
  </xa-datasource-class>
</driver>

PostgreSQL

<driver name="postgresql" module="org.postgresql">
  <xa-datasource-class>
    org.postgresql.xa.PGXADataSource
  </xa-datasource-class>
</driver>

MySQL

<driver name="mysql-xa" module="com.mysql">
  <xa-datasource-class>
    com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
  </xa-datasource-class>
</driver>

Conclusão

Seguidos os passos acima, será necessário reiniciar o servidor (caso ele esteja iniciado) e o driver estará adequadamente configurado e disponível para ser utilizado pelas datasources configuradas no JBoss AS.

Fica a seu critério decidir o método de inclusão do driver de seu SGBD no JBoss AS 7 de acordo com as vantagens e limitações de cada alternativa. O intuito deste artigo foi simplesmente o de mostrar como realizar a configuração necessária independente de sua escolha.

Demonstrei como fazer o JBoss AS reconhecer o driver e, em breve (provavelmente até a semana que vem), publicarei outro artigo entrando em detalhes na configuração das datasources e xa-datasources.

Referências Úteis:

[1] Livro JBoss AS 7 Configuration, Deployment and Administration
[2] Documentação de Referência do JBoss AS 7 - Datasource Configuration