JBoss Enterprise Application Platform 6

Este tópico descreve como o Lumis Portal deve ser instalado no servidor JBoss Enterprise Application Platform 6.

Nessa documentação, assume-se que a instalação do portal está situada em um caminho que a partir desse momento é simplesmente citado como $LUMIS_HOME. Também assume-se que a instalação do JBoss está situada em $JBOSS_HOME.

Instalação e atualização de módulos

Em $LUMIS_HOME/lib/jboss6/modules há os módulos que devem ser instalados no JBoss. Ele é composto de um módulo Lumis Shared (lumis/shared), módulos de drivers JDBC (lumis/jdbc).

Para instalar estes módulos, deve-se copiar o diretório $LUMIS_HOME/lib/jboss6/modules para $JBOSS_HOME/modules. Durante uma atualização, deve-se primeiro excluir o diretório antigo destes módulos (lumis/shared e lumis/jdbc em $JBOSS_HOME/modules) e depois instalá-los.

Configuração do perfil

A configuração do perfil dar-se-á de acordo com a arquitetura escolhida para a solução. Normalmente será em um dos arquivos standalone.xml, domain.xml ou host.xml (para maiores informações consultar a documentação do JBoss).

Na configuração, deve-se incluir as propriedades de sistema abaixo. Para isso inclua as propriedades como o exemplo abaixo. Caso não exista o elemento system-properties, adicione-o após </extensions>.

<system-properties> <property name="org.xml.sax.driver" value="com.sun.org.apache.xerces.internal.parsers.SAXParser"/> <property name="javax.xml.parsers.SAXParserFactory" value="com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl"/> <property name="javax.xml.parsers.DocumentBuilderFactory" value="com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl"/> <property name="javax.xml.transform.TransformerFactory" value="com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl"/> </system-properties>

Na configuração, deve-se incluir o módulo Lumis no subsystem jboss:domain:ee. Para isso, basta criar um nó de módulo global como a seguir:

<subsystem xmlns="urn:jboss:domain:ee:1.2"> <global-modules> <module name="lumis.shared" slot="main"></module> </global-modules> </subsystem>

Também deve-se aumentar o timeout de deployment para que o deploy do portal possa ser completo. Para isso, basta incluir (ou alterar de acordo) o atributo deployment-timeout do nó deployment-scanner no subsystem jboss:domain:deployment-scanner . Esse tempo é medido em segundos e deve ser ajustado para as características do ambiente.

Também é necessária a inclusão de um security-domain no subsystem jboss:domain:security. Para isso, basta adicionar um novo nó como a seguir:

<security-domain name="LumisPortal" cache-type="default"> <authentication> <login-module code="lumis.portal.authentication.LumisLoginModule" flag="sufficient"></login-module> </authentication> </security-domain>

É necessário que as variáveis target-vm e source-vm sejam configuradas para utilizar Java 8. Assim, basta acrescentar o seguinte nó no jboss:domain:web:2.2

<subsystem xmlns="urn:jboss:domain:web:2.2"> ... <configuration> <jsp-configuration source-vm="1.8" target-vm="1.8" /> </configuration> ... </subsystem>

Para permitir o uso de websocket pelo portal, no subsystem jboss:domain:web:2.2 o attributo protocol do connector deve ser modificado para:

1. Caso o Apache Portability Runtime (APR) esteja sendo usado: org.apache.coyote.http11.Http11AprProtocol; ou
2. Caso contrário: org.apache.coyote.http11.Http11NioProtocol

   Exemplo:

   <subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false"> <configuration> <jsp-configuration source-vm="1.8" target-vm="1.8" /> </configuration> <connector name="http" protocol="org.apache.coyote.http11.Http11NioProtocol" scheme="http" socket-binding="http"></connector> <virtual-server name="default-host" enable-welcome-root="true"> <alias name="localhost"></alias> <alias name="example.com"></alias> </virtual-server> </subsystem>

Ajuste na aplicação do portal

Deve-se remover o arquivo $LUMIS_HOME/www/WEB-INF/jboss-all.xml. Este arquivo é para estar presente apenas em ambientes com versões mais recentes do JBoss EAP.

Efetuar o deploy do portal

• Em modo standalone:

  Copiar a pasta $LUMIS_HOME/www para a pasta de deploy da configuração standalone no JBoss ($JBOSS_HOME/standalone/deployments). A pasta copiada deve ser renomeada para <nome do contexto>.war (exemplo: portal.war , se o contexto é portal ). Também deve ser criado um arquivo em branco com o mesmo nome da pasta com a terminação .dodeploy (seguindo o exemplo, seria portal.war.dodeploy ).

• Em modo domain:

  Gerar um arquivo de aplicação web ("WAR") a partir da pasta $LUMIS_HOME/www e efetuar a instalação do WAR via console administrativa do servidor de aplicação.

Criação e configuração do datasource

Este item descreve como configurar o Lumis Portal para utilizar um datasource no JBoss. Estes passos só são necessários se for desejado utilizar datasource.

Para o uso correto de datasource no portal, o módulo do driver JDBC correspondente ao banco de dados utilizado deve ser instalado no servidor de aplicação, assim como o módulo Lumis Shared. O local de origem do módulo será:

• para Oracle: $LUMIS_HOME/lib/jboss6/modules/lumis/jdbc/driver/oracle;
• para SQL Server: $LUMIS_HOME/lib/jboss6/modules/lumis/jdbc/driver/sqlserver;
• para MySQL: $LUMIS_HOME/lib/jboss6/modules/lumis/jdbc/driver/mysql

O módulo correspondente deve ser copiado para $JBOSS_HOME/modules (por exemplo, se o banco de dados utilizado for o Oracle, a estrutura de pastas deve ficar $JBOSS_HOME/modules/lumis/jdbc/driver/oracle/main).

O módulo também deve ser referenciado no arquivo de configuração, como no caso do módulo Lumis Shared. Para isso, basta inserir sua referência nos módulos globais, como destacado a seguir:

<subsystem xmlns="urn:jboss:domain:ee:1.0"> <global-modules> <module name="lumis.shared" slot="main"></module> <module name="lumis.jdbc.driver.oracle" slot="main"></module> </global-modules> </subsystem>

Depois de feito isso, o datasource pode ser criado no subsystem jboss:domain:datasources , como o exemplo a seguir:

<subsystem xmlns="urn:jboss:domain:datasources:1.0"> <datasources> <datasource jndi-name="java:jboss/datasources/PortalDS" pool-name="PortalDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url> jdbc:oracle:thin:@localhost:1521:ora11g </connection-url> <driver> ojdbc14 </driver> <security> <user-name>USUÁRIO</user-name> <password>SENHA</password> </security> </datasource> <drivers> <driver name="ojdbc14" module="lumis.jdbc.driver.oracle"> <driver-class> oracle.jdbc.driver.OracleDriver </driver-class> </driver> </drivers> </datasources> </subsystem>

Dentro do nó datasources dois nós devem ser criados. Um nó driver, dentro do nó drivers, para definir o driver a ser utilizado e um nó datasource para a criação do datasource em si.

No nó de driver é importante definir:

• O nome do driver: vai ser o nome que o datasource vai referenciar como driver (no exemplo o nome usado é ojdbc14);
• O módulo que contém o driver: qual módulo possui esse driver (lumis.jdbc.driver.<tipo de banco de dados>, no exemplo é lumis.jdbc.driver.oracle);
• Classe do driver:
  • para Oracle: oracle.jdbc.driver.OracleDriver;
  • para SQL Server: net.sourceforge.jtds.jdbc.Driver;
  • para MySQL: com.mysql.jdbc.Driver

No nó do datasource, definir:

• Nome JNDI: é o nome a ser referenciado no lumishibernate.cfg.xml;
• URL de conexão: a URL utilizada para a conexão;
• Driver: o nome do driver utilizado (utilizar o mesmo nome definido no nó de driver);
• Usuário e Senha: login de acesso à base de dados.

Passo extra para usuários de MySQL:

O driver do MySQL baixado descrito no tópico MySQL deve ser copiado para a pasta $JBOSS_HOME/modules/lumis/jdbc/driver/mysql/main e o arquivo module.xml (residente ao mesmo diretório) deve ser ajustado de acordo como o exemplo a seguir (exemplo para o driver mysql-connector-java-8.0.11.jar, o nome deve ser ajustado conforme o arquivo do driver que será utilizado):

<?xml version="1.0" encoding="UTF-8"?> <!-- $Revision: 18096 $ $Date: 2015-12-10 14:20:20 -0200 (qui, 10 dez 2015) $ --> <module xmlns="urn:jboss:module:1.0" name="lumis.jdbc.driver.mysql"> <resources> <resource-root path="mysql-connector-java-8.0.11.jar" ></resource> </resources> <dependencies> <module name="javax.api"></module> </dependencies> </module>

Caso desejado, a senha do datasource pode permanecer criptografada. Para isso, deve-se gerá-la executando o seguinte comando no diretório $JBOSS_HOME:

java -cp modules\org\picketbox\main\picketbox-4.0.1.jar;modules\org\jboss\logging\main\jboss-logging-3.0.1.GA.jar org.picketbox.datasource.security.SecureIdentityLoginModule [SENHA]

Também é necessária a inclusão de um security-domain no subsystem jboss:domain:security para armazenagem do usuário do datasource e da senha criptografada. Para isso, basta adicionar um novo nó como a seguir:

<security-domain name="portal-ds" cache-type="default"> <authentication> <login-module code="SecureIdentity" flag="required"> <module-option name="username" value="USUÁRIO"></module-option> <module-option name="password" value="[SENHA CRIPTOGRAFADA]"></module-option> </login-module> </authentication> </security-domain>

Nesse security domain, deve-se definir: usuário (no exemplo, USUÁRIO), senha criptografada (no exemplo, [SENHA CRIPTOGRAFADA]) e nome do security domain (no exemplo, portal-ds).

Após isso, deve-se alterar o nó security do datasource, removendo os nós user-name e password e adicionando um novo nó security-domain referenciando o security domain criado anteriormente, como a seguir:

<subsystem xmlns="urn:jboss:domain:datasources:1.0"> <datasources> <datasource jndi-name="java:jboss/datasources/PortalDS" pool-name="PortalDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url> jdbc:oracle:thin:@localhost:1521:ora11g </connection-url> <driver> ojdbc14 </driver> <security> <security-domain> portal-ds </security-domain> </security> </datasource> <drivers> <driver name="ojdbc14" module="lumis.jdbc.driver.oracle"> <driver-class> oracle.jdbc.driver.OracleDriver </driver-class> </driver> </drivers> </datasources> </subsystem>

Maiores informações sobre a configuração de datasources em https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/chap-Datasource_Management.html.

Configuração da codificação de URIs

É necessário que a codificação de URIs seja configurada para UTF-8. Para isto, acrescente no elemento system-properties uma propriedade de sistema igual o exemplo abaixo:

<system-properties> ... <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"></property> </system-properties>