Ambiente Desenvolvimento e Produção

Ambiente e Versões Homologados

Unificação de Ambiente BIS2 e BIS10 A partir de 15/08/2024 comecei a unificar o ambiente em que o BIS2 e o BIS10 rodam para simplificar o desenvolvimento e a migração de classes e pacotes entre as versões.

As versões dos sistemas utilizados são:

• Eclipse IDE
  • Versão: Eclipse IDE 2023-06 R (4.28.0 / Build id: 20230608-1333) site da versão ou download direto do arquivo zip.

• MySQL Workbench
  • Versão: 8.0.18

• Versionamento do Código
  • Passamos a utilizar o Git, e hospedando o código em sua maioria em repositórios privados no GitHUb.

• Java
  • jdk-8u301 x64 - Por padrão para os módulos e aplicações WEB
  • jdk-8u301 x32 - Para alguns módulos e aplicações que exigem a versão 32 (como por exemplo o BISPDV que precisa acessar as bibliotecas DLL do SAT).
  • Página de Download do Java 1.8 (versões legadas):

• Servidor de Aplicações WildFly
  • Versão: wildfly-24.0.1.Final

Instalação do JDK

1. Baixe a versão do JDK homologada;
2. Execute e siga os passos do Wizard para completar a instalação. (Preferencialmente aceite as opções padrão de instalação)

Desabilitar Auto Update

Para evitar problemas de atualização automática, ou mesmo consumo de banda, vamos desligar a atualização automática do java no servidor. A atualização automática pode trocar a versão do Java por uma não homologada pelo BIS, fazendo com que funções importantes deixem de funcionar adequadamente. Por isso a atualização do JDK só é feita manualmente e na versão homologada.

Para desabilitar a atualização automática proceda da seguinte forma:

1. Abra o Painel de Controles > Java
2. Na Aba Atualizar, desmarque a caixa Verificar se Há Atualizações Automaticamente.
3. Ao desmarcar aparece um diálogo de confirmação, clique em Não Marcar
4. Confirme clicando em OK

Instalação do MySQL

Utilizando o Instalador para Windows

1. Execute o Instalador e escolha a opção de instalação apenas do Servidor.

Microsoft Visual C++ Redistributable Caso o sistema ainda não tenha instalado o componente da Microsoft, faça a instalação a partir do próprio instalador do MySQL

1. Ao fim da instalação o será iniciado o processo de configuração do Servidor, escolhas as seguintes opções:
   1. Standalone MySQL Server / Classic MySQL Replication, next;
   2. Config Type: Server Machine, next;
   3. Configure a senha do banco como biserp2003, não adicione nenhuma outra conta, next;
   4. Configure o serviço com o nome mysql, e deixe rodar como Standard Service Account, next;
   5. Em Plugins e Exceptions não há nada para alterar, next;
   6. Clique em Execute para configurar o servidor.

1. Finalize o Wizard principal de instalação.

Ambiente de Produção Verifique as configurações do serviço criado para ter certeza que o serviço foi configurado para ligar automaticamente com o Windows ao iniciar.

Utilizando o ZIP - Sem instalador

• Descompacte o conteúdo na pasta desejada. No windows, recomendável o próprio C:
• (Opcional) Renomeie a pasta para "MySQL", removendo a definição da versão da pasta. Caso necessário a versão pode ser obtida pelo comando:

mysql --version

• Crie um arquivo my.ini na pasta do mysql e cole o seguinte conteúdo corrigindo os caminhos:

[mysqld]
# set basedir to your installation path
basedir=c:\\mysql

# set datadir to the location of your data directory
datadir=c:\\mysql\\data

# set directory to export files on dump
#secure-file-priv=c:/Dumps

# Troca o padrão do SQL_MODE para que seja possível usar select com groupBy e colunas que não estejam agregadas, sem ter que usar a função any_value() em casa coluna do select.
# O valor definido aqui é o valor padrão do próprio MySQL removendo apenas o ONLY_FULL_GROUP_BY, acrescentado a partir da versão 5.7.x como padrão.
sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION

# Força que cada tabela do InnoDB tenha seu próprio arquivo, evitando que o mysql cresça sem limites os arquivos 'ibdata1' e 'ibdata?'
innodb_file_per_table=1

secure-file-priv Esse atributo deve ser definido caso haja a intenção de exportar o conteúdo das tabelas em arquivos de texto, como por exemplo usando o parâmetro --tab do mysqldump.exe. No entanto, se esse atributo for definido, a pasta deve existir! Caso contrário o MySQL não inicializa!

• O MySQL do ZIP não contem a pasta "data" criada com as tabelas iniciais do banco "mysql". Para cria-la utilize o comando:

mysqld --initialize-insecure

Note que este comando inicializará o banco com um usuário root sem senha, mas vamos configura-la na sessão seguinte.

• Para inicializar o servidor e verificar se tudo corre bem, utilize o seguinte comando:

mysqld --console

• Para instalar o MySQL como um serviço do windows utilize:

mysqld --install <servicename>

Nome do Serviço Opcional Caso o nome do serviço seja omitido, o serviço será instalado com o nome padrão 'mysql'. Só é necessário informar outro nome caso haja mais de uma versão do mysql instalada. Neste caso lembre-se de não permitir os serviços iniciando automaticamente para evitar conflito com a porta de conexão.

• Para inicializar o MySQL como um serviço utilize:

net start mysql

Configurar o MySQL

• Acesse o MySQL executando o comando abaixo:

c:\mysql\bin\mysql -uroot -p

Usuário Root Para conseguir se conectar no banco é obrigatório passar o parâmetro do usuário (-uroot) e o de senha (-p<seha>). Caso seja passado apena o "-p" sem informa a senha, ela será perguntada com um campo hidden, útil para não exibir a senha quando alguém estiver próximo.

• Caso não tenha definido uma senha para o root, é bom defini-la. Para definir a senha de um usuário utilize a sintaxe:

SET PASSWORD FOR 'root'@'localhost' = 'biserp2003';

• Cria uma nova base de dados com o nome "bis_kernel" para as tabelas compartilhadas do sistema e a "bis_bis" para base da primeira empresa (a própria BIS):

CREATE DATABASE bis_kernel;
CREATE DATABASE bis_bis;

• Muda para entre as bases de dados criadas com o comando:

USE bis_kernel;

ou

USE bis_bis;

• Importe o(s) script(s) base nesta base de dados com o comando abaixo. Comece pelo script do kernel, já que as tabelas das empresas tem FKs que dependem da base do kernel.

mysql -uroot -p bis_kernel <filename_path>\bis_kernel_10.0.0.sql;

e

mysql -uroot -p bis_bis <filename_path>\bis_bis_10.0.0.sql;

Escape Caracters Não se esqueça que o MySQL utiliza escape caracters na sua sintaxe, logo se o caminho para o script for e:\BISInstaKit\biscore_basescript.sql você deve usar e:\\BISInstaKit\\biscore_basescript.sql ao digitar o caminho no comando SOURCE.

Script Base Os scripts de base costumam ser versionados no projeto BISEAR em /etc/resources/dbbasescripts. Esses scripts não são armazenados junto com os scripts de atualização porque não são empacotados junto com a aplicação, eles fazem parte da configuração do ambiente.

Usuário Próprio Para o ambiente de produção é bom restringir o acesso a base de dados e não usar a conta root. Para isso vamos criar um usuário exclusivo para acesso ao banco de dados 'biserp' com o comando abaixo: CREATE USER 'bis'@'%' IDENTIFIED BY 'biserp2003'; Em seguida precisamos garantir acesso total deste novo usuário ao banco de dados. Precisamos dar acesso que inclua criar novos bancos de dados, uma vez que ele precisará criar quando o sistema cadastrar novas empresas no sistema: GRANT USAGE ON *.* TO 'bis'@'%'; GRANT ALL PRIVILEGES ON *.* TO 'bis'@'%' WITH GRANT OPTION; Por fim force o reload das permissões: FLUSH PRIVILEGES;

MySQL 8 No MySQL 8 o plugin de autenticação foi substituído. E a autenticação feita pelo Glassfish dará problema. Para corrigir o problema de autenticação, é necessário utilizar o seguinte comando para atualizar a senha do usuário que o Glassfish vai usar para o plugin antigo de autenticação: ALTER USER 'bis'@'%' IDENTIFIED WITH mysql_native_password BY 'biserp2003'; O problema foi detectado utilizando o GlassFish 4, com o MySQL Connector 5.1.43 e o MySQL 8.0.11.

Usuário Leitura Para cliente com usuários mais avançados, podemos permitir um acesso a nossa base de dados somente de leitura, permitindo que o cliente extraia dados diretamente da base de dados e gere seus próprios relatórios. CREATE USER 'cliente'@'%' IDENTIFIED BY 'cliente'; GRANT SELECT ON `bis_bis`.* TO 'cliente'@'%' identified by 'cliente'; Para efetivar o usuário execeute: FLUSH PRIVILEGES;

Instalação do WildFly

1. Faça o 'download' da versão homologada pelo BIS.
2. Descompacte o conteúdo em 'C:\'

Definindo o caminho do Java

Para garantir que o WildFly utilizará o Java homologado, e não o java padrão disponível no sistema, é preciso forçar o caminho do JAVA_HOME em suas configurações.

• No Windows
  • Edite o arquivo 'WILDFLY_HOME\bin\standalone.conf.bat'
  • Procure a linha 'rem set "JAVA_HOME=C:\opt\jdk1.6.0_23"', remova o 'rem' e a corrija para que aponte para o JDK homologado

• No Linux
  • Edite o arquivo 'WILDFLY_HOME\bin\standalone.conf'
  • Procure a linha '#JAVA_HOME="/opt/java/jdk"', remova o '#' e a corrija para que aponte para o JDK homologado

Módulo sunPKCS11

O BIS depende do módulo externo sunpkcs11.jar que é fornecido pela SUN dentro do java. No entanto, por padrão essa biblioteca fica inacessível por não ter suporte direto nem garantia de manutenção em versões futuras (como todos os pacotes sun.*). Para que o WildFly carregue esse pacote e disponibilize para as aplicações precisamos configurá-lo como um módulo adicional. Para isso é necessário criar o arquivo 'WILDFLY_HOME\modules\system\layers\base\sun\security\pkcs11\main\module.xml', com o seguinte conteúdo:

<module xmlns="urn:jboss:module:1.0" name="sun.security.pkcs11">
    <resources>
        <resource-root path="c:/Program Files/java/jdk1.8.0_301/jre/lib/ext/sunpkcs11.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.xml.bind.api"/>
    </dependencies>
</module>

Uma vez disponibilizado, é necessário garantir que o EAR contenha o arquivo solicitando esse módulo. Para isso o pacote EAR deve conter o arquivo 'META-INF\jboss-deployment-structure.xml', com o seguinte conteúdo:

<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="sun.security.pkcs11" export="true"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

Adicionando Usuário Administrador

1. Execute o comando WILDFLY_HOME\bin\add-user'
2. Escolha a opção 'Management User'
3. Crie o usuário 'bis'
4. Senha 'biserp2003'
5. Deixe em branco os grupos adicionais do usuário (apenas pressione ENTER)
6. Confirme com 'Yes' as próximas perguntas

Erro de JAVA no add-user Se tiver problemas relacionado a versão do Java provavelmente é por estar utilizando uma versão do Java não compatível com o WildFly. Para executar o script, ou troque sua versão padrão do java para executar esse script, ou edite o arquivo add-user.bat e inclua a linha: set "JAVA_HOME=c:\Program Files\Java\jdk-20" antes do código que testa o Java Home: if "x%JAVA_HOME%" == "x" (

Incluindo o Driver JDBC do MySQL

1. Baixe o JDBC homologado pelo BIS
   1. Para a versão 8.0.11: baixe com

      wget https://downloads.mysql.com/archives/get/p/3/file/mysql-connector-java-8.0.11.tar.gz

   2. Descompacte com

      sudo tar -xvf mysql-connector-java-8.0.11.tar.gz

2. Cria a pasta 'WILDFLY_HOME\modules\system\layers\base\com\mysql\main'
3. Copie o JAR do JDBC para esta pasta
4. Crie um arquivo 'module.xml' dentro da pasta com o seguinte conteúdo:

<?xml version="1.0" encoding="UTF-8"?>
<module name="com.mysql" xmlns="urn:jboss:module:1.9">
    <resources>
        <resource-root path="mysql-connector-java-8.0.11.jar" />
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

Iniciando o Servidor

Para iniciar o servidor execute o comando 'WILDFLY_HOME\bin\standalone'.

Standalone Vs. Domain Diferentemente da definição do Glassfish, o modo Domínio é utilizado para rodar múltiplas instâncias do WildFly distribuído em Cluster, Servidores, Etc. O BIS por enquanto não tem necessidade de rodar em um ambiente dividido em múltiplos servidores e domínios, por isso é executando no modo standalone tanto no ambiente de Homologação quanto de Produção.

Configuração do Datasource

Configuração do Driver JDBC

1. Com o servidor já em execução, acesse o 'Painel de Administração'.
2. Acesse 'Configuratoin -> Subsystem -> Datasources & Drivers -> JDBC Drivers'.
3. Clique no botão de '+' para adicionar uma nova configuração do Driver do MySQL

   

4. Complete os campos com as seguintes informações:
   1. Driver Name - MySQL
   2. Driver Module Name - com.mysql
   3. Driver Class Name - com.mysql.cj.jdbc.Driver
   4. Driver XA Datasource Class - com.mysql.cj.jdbc.MysqlXADataSource

   

Configuração do DataSource BIS10

1. Acesse 'Configuratoin -> Subsystem -> Datasources & Drivers -> Datasources'.
2. Clique no Botão '+' e escolha a opção 'Add Datasoruce para adicionar um novo DataSource. (Não seleciona a opção XA!)
3. Escolha a opção 'Custom'. Apesar de existir uma opção do MySQL, ela não permite as configurações necessárias.
4. Em Atributes preencha com:
   1. Name - BISDS
   2. JNDI Name - java:/jdbc/BISDS
5. Em JDBC Driver apenas escolha o driver que configuramos anteriormente MySQL
6. Em Connection complete com:
   1. Connectino URL - jdbc:mysql://localhost:3306?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=America%2FSao_Paulo
   2. User Name - Usuário do MySQL
   3. Password - Senha do MySQL
   4. Security Domain - deixar em branco
7. Teste a conexão e finalize a criação do DS

Configuração do DataSource BIS2

1. Acesse 'Configuratoin -> Subsystem -> Datasources & Drivers -> Datasources'.
2. Clique no Botão '+' e escolha a opção 'Add Datasoruce para adicionar um novo DataSource. (Não seleciona a opção XA!)
3. Escolha a opção 'Custom'. Apesar de existir uma opção do MySQL, ela não permite as configurações necessárias.
4. Em Atributes preencha com:
   1. Name - BISERPDS
   2. JNDI Name - java:/jdbc/BISERPDS
5. Em JDBC Driver apenas escolha o driver que configuramos anteriormente MySQL
6. Em Connection complete com:
   1. Connectino URL - jdbc:mysql://localhost:3306/biserp?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=America%2FSao_Paulo
   2. User Name - Usuário do MySQL
   3. Password - Senha do MySQL
   4. Security Domain - deixar em branco
7. Teste a conexão e finalize a criação do DS

Falha no Teste da Conexão Algumas vezes, por algum erro, a conexão com o banco de dados falha. Mesmo voltando, arrumando e tentando realizar um novo teste a conexão com o banco falha. Parece que o WildFly tem algum BUG neste sentido. Pois já tive casos de o teste da conexão falhar, e concluí a configuração - apertando finish - e depois que a conexão foi inserida e o servidor 'reloaded', o teste de conexão resultar em sucesso.

Configurações Adicionais Servidor Linux (Produção)

TimeZone

Embora a partir da versão 10 o BIS utilize o LocalDate, o sistema ainda apresenta alguns "pontos falhos" em que se utilizar do TimeZone do sistema. Por isso é necessário que o servidor esteja configurado para o TimeZone 'America/Sao_Paulo'.

Configurando o TimeSync Service no Amazon Linux

1. Exclua o NTP atual:

   sudo yum erase 'ntp*'

2. Instale o Chrony:

   sudo yum install chrony

3. Configure o NTP da Amazon (Talvez o mais recomendado seja instalar o NTP brasileiro, mas confiando que o da amazon terá os horários de verão configurados corretamente, mantive). Edite o arquivo /etc/chrony.conf. Se a linha não existir crie-a depois das instruções server ou pool. Caso exista, recomendo que passe para baixo de todas.

   sudo nano /etc/chrony.conf

   server 169.254.169.123 prefer iburst minpoll 4 maxpoll 4

4. Reinicie o serviço:

   sudo service chronyd restart

   Para visualizar se o server está sendo utilizado corretamente, utilize o comando:

   chronyc sources -v

   Ou as métricas de sincronização com:

   chronyc tracking

Configurando o TimeZone Para ver os TimeZones disponíveis navegue dentro da pasta /usr/share/zoneinfo. Neste tutorial já vamos configurar para America/Sao_Paulo.

1. Abra o arquivo /etc/sysconfig/clock

   sudo nano /etc/sysconfig/clock

2. Altere seu conteúdo conforme abaixo:

   ZONE="America/Sao_Paulo"

   UTC=true

3. Crie um symLink para o arquivo de TimeZone correspondente, conforme exemplo abaixo:

   sudo ln -sf /usr/share/zoneinfo/America/Sao_Paulo /etc/localtime

4. Reinicie a instância

   sudo reboot

5. Verifique a data com

   date

Eclipse

Instalação

• Descompacte o conteúdo de dentro do arquivo .zip

  Dentro do .zip há uma pasta chamada 'eclipse'. Se tiver mais versões do eclipse em sua máquina recomendo renomeá-la para 'eclipse-jee-2023-06-R', para ficar no mesmo padrão de nomes utilizado pelo instalador.

Versão Java Eclipse Apesar do BIS2 e BIS10 utilizarem a versão 1.8, a versão homologada do Eclipse já utiliza a versão 17 ou superior. No entanto o eclipse utiliza um java 'embedded' para executar, não é necessário instalar um java adicional na máquina só para a execução do Eclipse.

JAutoDoc

Este plugin permite que todo o javaDoc criado para um "field" (atributo da classe) seja replicado automaticamente nos métodos Get e Set ao pressionar a tecla de atalho 'CTRL+ALT+J'.

Instalação pelo MarketPlace

1. Vá em 'Help -> Eclipse Marketplace' e procure por 'JAutoDoc'.
2. Clique em Instalar siga os passos e Reinicie quando solicitado

Configuração do Módulo

1. Após a instalação vá no menu 'Windows > Preferences', no caminho 'Java > JAutoDoc' e clique no botão 'Import All...' para importar as configurações usadas no projeto BIS.
2. O arquivo com as opções salvas ficam no projeto 'RFW.Kernel' em 'etc\Eclipse Setup\Eclipse JAutoDoc.xml'.

Configurando o JDK e Bibliotecas no Eclipse

Ao carregar o pom.xml do Maven, o Eclipse configurará o projeto para utilizar o Execution Environment de acordo com a versão do JDK definida no arquivo. Por isso, é importante que o Execution Environment do Eclipse esteja apontando para o JDK homologado. Atualmente o Execution Environment é o JavaSE-1.8.

Versão x64 e x32 Embora o BIS esteja homologado para rodar na versão 64bits, alguns módulos e aplicações externas podem requerer a versão 32bits. Um exemplo é o BISPDV que por questões de compatibilidade com DLLs de SAT, Impressoras, PinPads e etc., precisam rodar em 32Bits. Para estes casos a cada vez que o Eclipse recarregar o pom.xml do Maven, é necessário configurar manualmente que desejamos que o projeto rode no JDK de 32bits homologado.

1. Vá em 'Windows -> Preferences -> Java -> Installed JREs'
2. Adicione a instalação do JDK homologado apontando para a pasta do JDK de 64 bits homologado.
3. Repita o passo anterior para a versão do JDK de 32 bits homologado.
4. Vá em 'Windows -> Preferences -> Java -> Installed JREs -> Execution Environment e em JavaSE-1.8 escolha o JDK 64bits homologado.

Maven Desde a adoção do Maven para controlar as bibliotecas de cada projeto não é mais necessário realizar configurações extras de bibliotecas no Eclipse

Configurando o WildFly

Antes de configurar o Servidor é necessário baixar o plugin do servidor.

1. Vá na aba 'Servidor e click para criar um novo servidor.
2. Na tela que se abre, escolha 'JBoss AS, WildFly, & EAP Server Tools' e clique em Next. Este passo pode demorar.

   

3. Termine os passos do Wizard até finalizar. Aguarde o fim da instalação e reinicie se for solicitado.
4. Após o término e reinicio do Eclipse, volte à aba 'Servers' e clique em adicionar um novo servidor novamente.
5. Desta vez escolha a opção 'WildFly24+', e deixe o Server Name como 'WildFly'.
6. Clique em 'Next.
7. Na próxima imagem escolha a opção 'Filesystem and shell pperations' para que o Eclipse controle o WildFly corretamente.

   * Para que o eclipse controle adequadamente o a instalação do WildFly precisa ser realizada como orientado nesta página.}}

   

8. Na definição de RunTime, selecione o ambiente conforme homologado.
9. Clique em Finish

Formatação do Código

É importante que todo desenvolvedor formate o código do mesmo modo para que o versionamento do código não passe a tratar as diferentes formatações de código como alterações no arquivo. Para facilitar as configurações o BIS utiliza as mesmas configurações definidas no RFW, e já tem um arquivo de formatação, para usa-lo basta seguir os seguintes passos:

Para configurar essas e outras definições de preferências do Eclipse é recomendado importar as preferências do Eclipse a partir do arquivo salvo no projeto RFW.Kernel na pasta etc\Eclipse Setup\Eclipse v2023_06 Preferences - Rodrigo.epf

1. Vá em 'Window -> Preferences'
2. Na parte inferior clique em importar preferência
3. Navegue até o arquivo e importe as configurações disponíveis.

Em caso de falha será necessário configurar o Eclipse manualmente conforme definições a seguir:

Organização dos Imports

Organizar os imports segue a mesma lógica da formatação de código, é obrigatória para evitar que o versionamento identifique a organização de imports como alteração do código.

Há um arquivo modelo disponível em RFW.Kernel\etc\Eclipse Setup que pode ser importado diretamente.

Em caso de falha, configure seu eclipse conforme imagem a seguir:

Organização de Imports no Eclipse

Automatizando as Formatações ao Salvar o Código

Algumas ações podem ser definidas no eclipse para que realize automaticamente ao salvar, automatizando algumas funções que acabam sendo esquecidas pelo desenvolvedor. Para isso vá no menu Window -> Preferences, em seguida escolha a configuração em Java -> Editor -> Save Actions e configure como a imagem abaixo:

Criando Templates de Códigos

Para facilitar e padronizar alguns códigos o eclipse pode ser configurado para gerar "templates de códigos" automaticamente. As orientações abaixo são uma sugestão de trabalho, não necessariamente uma obrigação.

Para criar esses e outros templates vá no menu Window -> Preferences e na configuração Java -> Editor -> Templates. Click em New e crie o template desejado.

JavaDOC de Classe

O Javadoc de classe tem a finalidade de fazer uma prévia da função da classe, identificar o autor e a data de sua criação.

• Nome: ccbis
• Descrição: Comentário/JavaDOC de Classe do BIS

Pattern /** * Description: ${cursor}.<br> * * @author Nome do Author * @since (${date}) */

1. Troque o nome do autor para o nome do desenvolvedor
2. Corrija o número da versão sempre que a versão em que estiver trabalho for alterada.

Eventualmente, quando um desenvolvedor "assume" a classe de outro desenvolvedor ou faz alguma alteração significativa durante o processo de alteração deve ser acrescida a tag abaixo logo a seguir da última @version ou abaixo da @since:

@version - X.X.X - Author - (...)

Onde:

• x.x.x - é a versão em que a alteração foi feita, e;
• (...) - é a descrição das alterações ou mudanças realizadas.

Configurando o Git para Trabalhar com o GitHub

Falha ao Autenticar com Usuário e Senha Antes de começar, tive diversos problemas para autenticar com usuário e senha utilizando o GitHub, não sei se é limitação do site ou do Eclipse. É possível fazer o checkout do código e navegar no repositório, mas no momento de fazer os Pushs o eclipse não autentica e segue perguntando usuário e senha. Por isso, sempre faça o checkout do código já utilizando chave SSH. No modelo que é sugerido configurar aqui.

Criando a Chave SSH

Se ainda não tiver uma chave SSH que queira utilizar, podemos cria-la utilizando o próprio Eclipse.

• Navegue em Window > Preferences > General | Network Connections | SSH2, na aba Key Management

Criação/Importação de Chave SSH

• Clique em Generate RSA Key ou Load Existing Key para criar ou importar suas chaves privadas.
• Configure o comentário desejado e uma senha para proteger sua chave.
• Copie todo o conteúdo da chave pública (Provavelmente começando com ssh-rsa
• Clique em Apply and Close

Configurando a Chave no GitHub

Agora, é preciso configurar o GitHub para aceitar sua chave de autenticação:

• Abra o site do Git Hub e se autentique.
• Clique na imagem do seu perfil e depois em Settings.
• Depois no menu SSH and GPG Keys
• Clique no botão New SSH key
• Dê um título para sua chave (só para sua referência), escolha Authentication Key e cole o conteúdo copiado da chave pública no campo Key.
• Pronto, sua chave será aceita pelo GitHub agora.

Fazendo Checkout do Código Existente

Para realizar o checkout do código:

• Utilize a função de importar projeto do eclipse, escolha Projects from Git.
• Escolha Clone URI.
• No GitHub, copie o link do código utilizando o SSH

Link do Repositório por SSH

• Cole no campo URI da tela Import Projects from Git

Checkout do Código por SSH no Git Hub

• Garanta que o protocolo ficou em ssh e deixe o usuário conforme sugerido git
• Termine a configurações como desejado, escolhendo o diretório de checkout, e no fim permita a importação do projeto no Eclipse.

Instalação do MetaObjectGenerator Plugin

Para gerar os MetaObjects do BIS (os objetos que espelham o VO e tem o mesmo no me do VO com o sufixo "VO_"), você deve instalar os plugins no seu eclipse. Os plugins ficam versionados junto com os projetos de EAR de aplicação, dentro da pasta etc\EclipsePlugins.

Para instalar você deve extrair o conteúdo do .zip dentro da pasta droppins que existe dentro da pasta do eclipse. A instalação ficará no caminho como a seguir:

%eclipseHome%\dropins\plugins\<plugin>.jar

Instalação no BIS10

O BIS10 utiliza o plugin MetaObjectGenerator_3.0.0.jar, que já é a versão atualizada e migrada para o RFW.

Para habilitar o plugin, clique com o botão direito do mouse no projeto em que o plugin precisa ser habilitado (projeto em que estão os VOs), e siga o menu: Configurações > Enable RFW VO_ Generator

Instalação no BIS2

O BIS2 utiliza o plugin mais antigo: BISMetaObjectGenerator_2.0.2.zip. E o nome do plugin no meu Configurações é Enable BIS MetaObject Generator

Ambos os Plugins Podem ser Instalados no Eclipse Simultaneamente Ambos os plugins podem estar instalados no Eclipse ao mesmo tempo, mas jamais não devem ser habilitados ao mesmo tempo no mesmo projeto.

MySQL Workbench

O MySQL Workbench é uma ferramenta oferecida pela própria MySQL para planejamento e gerenciamento do banco de dados. Os diagramas de banco de dados do BIS são feitas utilizando esta ferramenta. A instalação não tem nenhuma dificuldade, basta seguir os passos do Wizard se utilizada o instalador para windows, ou descompactar a pasta se usada a versão sem instalador.

Versão do Workbench A versão do MySQL Workbench deve ser a mesma utilizada por toda a equipe de desenvolvimento. Isso porque os arquivos salvos nas versões mais recentes da ferramenta não podem ser abertos nas anteriores. A atualização da versão deve ser conversada com toda a equipe.

Emulador do SAT

Desinstalar Versões Anteriores antes de Atualizar O instalador do emulador não suporta atualizações corretamente, por isso, caso tenha uma versão do emulador já instalado é recomendável realizar a desinstalação antes. Para isso utilize o Painel de Controle do Windows para desinstalar o "Emulador SAT". As demais instalações não geram entrada na tela de programas instalados, neste caso apague a pasta C:\Program Files (x86)\SAT-CFe e todo o seu conteúdo.

• Faça o Download do Emulador do SAT aqui. Na ocasião da escrita a versão do emulador é a 2.9.4.

Manual de Instalação Na mesma página de download, na seção de 'Manuais' é possível encontrar o manual de procedimentos para instalação do Emulador. Embora seguir aqui seja mais "rápido", alguma mudança na versão pode ter trocado os procedimentos e ser necessário a realização de outros procedimentos.

• Descompacte o conteúdo em uma pasta temporária.
• Instale os arquivos Setup-Emulador_OffLine_v2_9_4.exe e Setup-Ativacao_v2_2_5.exe, siga os passos da instalação.

  Não é necessário instalar o arquivo Setup-AC_v2_2_7.exe uma vez que ele só tem a função de substituir a Automação Comercial - o próprio BIS.

• Copie a Pasta SAT presente no zip para C:\SAT
• Na pasta “SAT” abra o arquivo configuracoes.xml. Modifique <versaoSchema> e <versaoLayoutCFe> de acordo com a versão da Especificação do SAT para a qual o Aplicativo Comercial será programado.
• O instalador do Emulador cria um atalho no Desktop "virado" direto para o jar executável. Normalmente ao executar pelo JAR o menu de configuração do Emulador não aparece (algum bug no emulador). Corrija o atalho para que ele não execute o jar diretamente, mas sim execute o java.exe. (Ex: C:\Windows\System32\java.exe -jar "C:\Program Files (x86)\SAT-CFe\Emulador\Emulador SAT-CFe.jar")

Ativação do Emulador do SAT

A ativação do emulador pode ser feita diretamente pelo BISSatHost. E vamos utiliza-lo aqui ao invés do aplicativo de Ativação que vêm com o emulador, assim já incluímos os passos de configuração do BISSatHost para funcionar com o emulador.

• Para funcionar com o Emulador, o BISSatHost deve ter a C:\SAT\SAT.dll dentro da pasta raiz do projeto do BISSatHost.

Maiúscula x Minuscula O Emulador envia a DLL com o SAT maiúsculo e a extensão minúscula, para o BIS encontrar a biblioteca corretamente o nome da DLL deve estar toda em minuscúlo.

• Abra o arquivo config.properties dentro da pasta raiz do BISSatHost e configure as seguintes propriedades para funcionar com o SAT Host:

bisserver.host=localhost
bisserver.port=2082
sat.codigoativacao=BynX53JHxvaj9Yb4TJP3lm8Jb7KBggQ9
sat.chaveassociacao=11111111111112222222222222211111111111111222222222222221111111111111122222222222222111111111111112222222222222211111111111111222222222222221111111111111122222222222222111111111111112222222222222211111111111111222222222222221111111111111122222222222222111111111111112222222222222211111111111111222222222222221111111111111122222222222222111111111
system.xmlbackupdir=./SAT/
system.logdir=./LOG/
socket.listen.port=2083
sat.cnpjContrib=11111111111111

Código de Ativação O código de ativação inicial do emulador é 12345678, no arquivo de properties o código de ativação fica criptografado.

• Inicie o BISERP e o programa BISSatHost. O BISERP deve estar ligado para garantir autenticação do usuário.
• Escolha a opção At para iniciar a ativação do SAT e faça a autenticação.
• Escolha o certificado 1 - AC-SAT/SEFAZ
• CNPJ do Contribuinte deve ser 11111111111111. O Emulador só aceita esse CNPJ para funcionar.
• No estado de ativação informe SP.

Associar Assinatura

• Para associar a assinatura escolha a opção As no BISSatHost.
• Autentique com um usuário que tenha permissão de configurar o SAT.
• Caso tenha o arquivo c:\debug.txt no computador, o BISSatHost detecta que é modo desenvolvedor e oferece para já configurar as opções para o emulador automaticamente. Escolha S.
• Confirme as opções com a opção S.
• O Emulador do SAT deve aceitar a associação e estar pronto para ser utilizado pela aplicação.

Android Studio

Desatualizado Este trecho da documentação foi migrado desde o BIS2 sem atualização. Está aqui somente por referência, mas provavelmente precisa de atualização.

Para desenvolvimento das aplicações para a plataforma Android e necessário preparar o Android Studio

Instalação do Android Studio

1. Faça o download do Android Studio aqui.
2. Siga os passos para completar a instalação conforme apresentados no wizard.

Instalação de Equipamento para Debug

Para realizar o debug do software em um equipamento com Android é necessário instalar o driver USB para depuração de acordo com o fabricante. Consulte o download aqui.

Depois que ele for reconhecido corretamente, é preciso liberar o aparelho para a realização de depuração via USB. Para isso siga os seguintes passos:

1. Abra as Configurações;
2. Selecione Sobre o dispositivo;
3. Pressione 7 vezes Número de Compilação / Versão Build / Número da versão;
4. Volte para as Configurações;
5. Escolha Opções do Desenvolvedor e ative-a, bem como extras;
6. Habilite Depuração de USB.

Configuração do SVN

Instalação do TortoiseSVN O Android Studio necessita de um cliente para realizar as funções de SVN, caso ainda não tenha instalado, execute a instalação do TortoiseSVN antes de continuar.

1. Vá em File > Settings > Version Control > Subversion e marque a opção Use command line cliente:

1. 1. Na instalação padrão o caminho seria c:\Program Files\TortoiseSVN\bin\svn.exe.
2. Abra o projeto feito o checkout pelo TortoiseSVN

Instalação do Glassfish

Usado para o BIS2!

1. Faça download da versão homologada pelo BIS do Glassfish.
2. Descompacte o conteúdo do .ZIP no drive 'C:\'

Configurando JDK Utilizado

A instalação o Glassfish tenta utilizar o "java" que estiver no path do sistema, isso é, ele simplesmente chama por "java" sem se preocupar com caminho para inicia-lo. Se o java padrão for o correto não é preciso fazer nada, embora seja recomendado definir exatamente o caminho a ser utilizado, assim, se no futuro alguma nova versão for instalada o Glassfish não passará a utilizar "outra versão" inadvertidamente.

Para configurar o glassfish edit o arquivo em <installdir>\glassfish\config\asenv.bat e acrescente a linha abaixo no final do arquivo para definir o home do JDK a ser utilizado:

set AS_JAVA=c:\Program Files\Java\jdk1.8.0_40

Domínio BISERP

Use o Domínio Padrão Para o ambiente de desenvolvimento o melhor é usar o domínio padrão do glassfish (chamado 'domain1'). Assim utilizando as portas padrões do GlassFish. Facilita a configuração e integração do Glassfish no Ecipse. Para o ambiente de desenvolvimento pule a etapa abaixo de criação, e nas etapas seguintes ao invés do domínio BISERP utilize domain1, ao invés da porta 9048 utilize a 4848 e da porta 9080 utilize a 8080.

Para separar a aplicação, ou mesmo permitir mais de uma aplicação na mesma máquina, podemos criar domínios separados para cada aplicação. Mesmo que ao iniciar o Glassfish crie um domínio padrão chamado 'domain1', para o ambiente de produção é recomendado criar um domínio diferente. Para o BISERP recomendamos criar um domínio nomeado 'BISERP'. Para isso utilize o comando:

c:\glassfish4\glassfish\bin\asadmin create-domain --portbase 9000 BISERP

Administrador do Domínio Ao criar o domínio, você será questionado sobre a criação de um usuário e senha. Esse senha serve para gerenciar esse domínio. O usuário e senha serão necessários para acessar a página de configurações. É recomendado definir o usuário 'bis' e a senha 'biserp2003' para proteger as configurações do domínio.

• portbase - é o número da porta base. A partir dessa porta todas as outras portas padrão serão somadas. Por exemplo, se passar como porta base "9000", as portas criadas serão 9080 para http, 9048 para a porta administração, e assim por diante. Para o BISERP recomendamos passar como parâmetro o valor: 9000.

Portas do Domínio As portas que serão criadas para cada domínio estão relacionadas a seguir. Lembre-se que os valores das portas serão adicionados ao valor passado em 'portbase', por isso recomendamos que cada domínio usa um 'portbase' múltiplo de 100, para que desta maneira cada domínio tenha um "prefixo" das suas portas, e o final das portas seja o mesmo para cada serviço de cada domínio. 48 for Admin. 80 for HTTP Instance. 76 for JMS. 37 for IIOP. 81 for HTTP_SSL. 38 for IIOP_SSL. 39 for IIOP_MUTUALAUTH. 86 for JMX_ADMIN. 66 for OSGI_SHELL. 09 for JAVA_DEBUGGER.

Permitir Acesso Remoto à tela Admin

O Glassfish 4 exige que o acesso remoto seja feito através de https na máquina local. Para permitir que o acesso possa ser feito de outra máquina temos de habilitar o login seguro no domínio. Antes de executar a configuração necessária precisamos primeiramente 'levantar' o domínio:

asadmin start-domain BISERP

Para realizar a liberação do acesso utilize:

asadmin --host localhost --port 9048 enable-secure-admin

• host: endereço da máquina onde está o glassfish, provavelmente localhost se feito da mesma máquina.
• port: porta do admin - domain1 = 4848; BISERP = 9048

Bibliotecas no Servidor de Aplicações

Devemos copiar as bibliotecas existentes no projeto BISERP na pasta etc/containerlibs para a pasta lib do domínio que será usado, pois são bibliotecas genéricas que precisamos que o GlassFish tenha em sua execução, como por exemplo as bibliotecas do JDBC do banco utilizado (atualmente MySQL). Se estiver com o domínio iniciado, reinicie-o para que ele carregue a nova biblioteca.

Configurar pool de conexões no banco de dados

Para que o BISERP funcione é necessário configurar um POOL de conexões com o banco de dados no Glassfish e depois um DataSource com o nome jdbc/BISERPDS.

1. Entre na tela de administração do GlassFish, se seguiu os passos deste manual é:
   1. Para o ambiente de desenvolvimento: http://localhost:4848
   2. Para o ambiente de produção: http://localhost:9048
2. Entre com o login criado durante a criação do domínio BISERP: pelos passos deste manual é biserp/biserp2003.
3. Abra a sessão Resources/JDBC/Connection Pools para criar o novo pool
   1. Clique em criar new
   2. Dê o nome "MySQLPool", por exemplo
   3. Em Resource Type defina javax.sql.ConnectionPoolDataSource
   4. Escolha o banco de dados MySQL e clique em avançar.
   5. Nesta tela deixe as opções padrão e nas propriedades devemos definir no mínimo as seguitnes:
      1. User: biserp (usuário criado no mysql para acessar o banco, para desenvolvimento pode acessar diretamente com a conta root)
      2. Password: biserp2003 Senha do usuário do banco de dados
      3. Port: 3306 (Ou outra caso tenha trocado a porta do banco de dados)
      4. DatabaseName: biserp (Ou outra base que queira usar para desenvolvimento/produção)
      5. Url e URL: jdbc:mysql://localhost:3306/biserp
      6. Click em Finalizar.
   6. Agora na sessão Resouces/JDBC/JDBC Resources vamos criar o data source da aplicação
      1. Clique em New
      2. Em JNDI Name complete com "jdbc/BISERPDS" este valor não pode ser alterado pois é o resource que a aplicação procura.
      3. Escolha o Pool que definimos no passo anterior e confirme.

Para confirmar se tudo funcionou bem, pode entrar no JDBC Connection Pool, clicar no Pool que criamos no primeiro passo e clicar em PING. Se não for bem sucedido o erro dará uma pista do que está errado.

Solução de Problemas Verifique a sessão final deste documento sobre a solução de problemas.

Instalando o Domínio BISERP como serviço do Windows

Para que o BIS levante-se automaticamente com o sistema é preciso configurar o domínio do glassfish como um serviço do Windows e configuração para iniciar automaticamente. Para criar o serviço execute o comando abaixo:

c:\glassfish4\glassfish\bin\asadmin create-service --name biserp biserp

Depois que o serviço for criado, é preciso garantir que está configurado para inicialização automática. Para isso:

1. Abra a janela de Serviços do Windows
2. Procure o serviço com o nome BISERP GlassFish Server e dê um duplo clique para abrir suas propriedades
3. Na opção Tipo de inicialização: garanta que esteja como Automático (Atraso na Inicialização)
4. Clique em OK para confirmar.

Porque inicializar com atraso? O Glassfish necessita que o MySQL já esteja em pé quando inicializar. Mesmo que normalmente o MySQL seja mais rápido que o Glassfish, é mais garantido se o Glassfish atrasar um pouco sua inicialização. Marcado para inicializar com atraso, o próprio windows se encarregará de só inicia-lo depois de iniciar os serviços marcados como Automático, como deve estar o MySQL.

Habilitar Debug Externo

Para fazer com que o servidor habilite o modo Debug ao inicializar, realize o seguinte procedimento:

1. Entre no console administrativo;
2. Abra o caminho Configurations > server-config > JVM Settings ou equivalente onde tenha sido feito o deploy da aplicação;
3. Marque a caixa Debug: Enabled;
4. Para especificar uma porta diferente para o Debug acrescente/altere a proriedade address=<port-number> na caixa "Debug Options" logo abaixo;

   É recomendável deixar na porta padrão, afinal o Debug só deve ser ligado em ambientes controlados!

Reinicio necessário! Para que esta alteração entre em vigor será necessário reiniciar o servidor. Este reinicio pode ser executado pelo próprio Admin Console na aba server. Ou, logo após a alteração de qualquer configuração que exija um reinício do servidor, o console exibirá um link Restart Required no cabeçalho da página. Ao clicar no link as alterações pendentes são exibidas junto com um botão de restart.

Fazendo o Deploy do BISERP

Agora que o Glassfish já foi configurado corretamente, precisamos colocar a aplicação BISERP para executar. Para isso siga os passos abaixo:

1. Entre na tela de administração do domínio BISERP, através do endereço http://localhost:9048, se você seguiu todos os passos deste manual.
2. Selecione no menu a opção "Aplications"
3. Click no Botão "Deploy"
4. Na tela que abrir, click em "selecionar o arquivo" e escolhar o EAR do BISERP
5. Após selecionar o arquivo, diversas novas opções aparecem, deixe todas nos seus valores padrão e click em OK. Esse passo pode demorar um pouco, entre subir o arquivo para o servidor e completar o deploy.

Neste ponto o BISERP já deve ser acessível através do endereço http://localhost:9080/BIS/.

Para fazer com que o site principal (raiz) do endereço a ser exibido seja a página do BIS, vá até no menu: "Configurations > server-config > VIrtual Servers > server" e na opção "Default Web Module" escolha a opção "<nome do deploy>#BISPresWAR.war".

Deploy em Ambiente de Desenvolvedor O deploy do BISERP feito desta maneira é só para ambiente de produção! Durante o desenvolvimento o Eclipse fará o deploy diretamente a cada vez publicamos o código pela IDE.

Aplicação WEB Principal

É possível configurar a aplicação para ser acessível da raiz do domínio, isto é, ao invés do endereço http://localhost:9080/BIS/ usar o endereço http://localhost:9080/.

Para isso precisamos configurar o domínio para assumir que o BISWAR da aplicação BISERP é a aplicação web padrão seguindo os seguintes passos:

1. Abra a administração do glassfish no endereço https://localhost:9048 e faça login
2. Abra o menu-árvore no caminho Configurations > server-config > Virtual Servers > server
3. Na tela de configuração que se abre do lado direito, no campo Default Web Module, escolha a opção do WAR padrão. A opção que terminar com BISWAR.war
4. Clique em save do lado superior direito

Troca de Versões Essa configuração precisa ser refeita toda vez que um novo arquivo for enviado para deploy, como por exemplo em uma troca de versão. Uma vez que um novo arquivo é enviado o Glassfish perde a informação do pacote "Default", e precisará ser indicado novamente.