Edição das 14h47min de 10 de junho de 2015

Introdução

Apresentamos neste documento a arquitetura de referência para o desenvolvimento do software Processo Judicial Eletrônico versão 2.0 (PJe 2.0) e suas evoluções futuras. As seções e subseções do documento explicarão os detalhes pertinentes da arquitetura.

Objetivo do documento

O objetivo principal é especificar a arquitetura de software de referência a ser utilizada como padrão para o desenvolvimento do PJe 2.0 e suas evoluções futuras. Nesta especificação está incluído: a estruturação do projeto do software, a organização das camadas do software, os componentes e arcabouços utilizados no software, a definição das principais tecnologias e ferramentas a serem utilizadas, os padrões de projeto, boas práticas de programação que devem ser utilizadas no desenvolvimento do software, entre outros assuntos relevantes.

Recomendamos que a leitura deste documento seja feita na ordem sequencial em que são apresentados os tópicos do sumário/índice do documento.

A metodologia de desenvolvimento do software definida será tratada em outro documento.

Termos, abreviações e convenções adotadas

Explicitamos nesta seção, uma tabela contendo os termos, abreviações e convenções adotadas no documento da arquitetura de referência do PJe 2.0. A leitura prévia desta seção é fortemente recomendada para compreensão das demais seções.

[TODO: citar as ref. bib. nos termos necessários]

Restrições da arquitetura

TODO: verificar se existem restrições impostas que foram obedecidas.

Justificativas arquiteturais

Nesta seção, explicitamos o conjunto de memorandos (técnicos, gerenciais, institucionais) que justificam as decisões arquiteturais da arquitetura de referência do PJe 2.0. Esses memorandos são resumos das discussões e estudos os quais balizam este trabalho.

Requisitos do projeto PJe 2.0.

O conjunto completo de premissas e requisitos (funcionais e não funcionais) consta no Plano Geral do Projeto PJe 2.0 ( [TODO: colocar link para o plano, se for desejado]). A saber, explicitamos apenas um resumo desse conjunto:

• Isolamento dos módulos de negócio (ou seja, módulos responsáveis pela lógica de negócio do software PJe) a fim de evitar efeitos colaterais indesejáveis provenientes das modificações no código-fonte.
• Permitir que o desenvolvimento dos módulos de negócio seja realizado isoladamente, inclusive com equipes distribuídas.
• Permitir que a implementação de um módulo de negócio qualquer seja totalmente substituída por nova implementação, sem prejudicar o funcionamento dos demais módulos.
• Isolamento das camadas lógicas do software, para evitar ao máximo o embaralhamento da lógica de negócio do software PJe e a dificuldade de leitura e compreensão do código-fonte
• Permitir que os módulos mais exigentes, quanto ao consumo de recursos de infraestrutura, possam ser "instalados" (deploy) mais de uma vez.

Experiências prévias.

Foram consideradas as seguintes experiências:

• Experiência prévia da equipe de arquitetos servidores do Poder Judiciário.
• Foram analisadas arquiteturas de referência de outras instituições (TCU, STF, SERPRO, TJRO, TJPE).
• Estudos diversos foram realizados pela equipe de arquitetos na primeira Sprint do projeto.

Tecnologias adotadas.

As tecnologias e/ou ferramentas adotadas para a implementação foram selecionadas a partir da análise dos requisitos do projeto PJe 2.0:

• Java Enterprise Edition Platform specification (JEE): a escolha pela plataforma JEE foi um consenso dada a notória posição de destaque dessa plataforma na construção de aplicações corporativas com grande volume de acesso e necessidade de escalabilidade, de robustez, de segurança, de controle de transação e de processamento em batch, entre outras necessidades. Além disso, a plataforma JEE traz um conjunto expressivo de APIs que aumentam a produtividade da construção do software, encapsulam parte da complexidade inerente às funções que as APIs implementam, promovem a definição de padrões de desenvolvimento, contemplando independência de servidor de aplicações.
• Apache Maven: a escolha pela ferramenta Maven foi norteada pela necessidade de modularização do software e pela adoção da plataforma JEE, como também pelo consenso, na comunidade de desenvolvedores Java, de que a ferramenta Maven é a melhor ferramenta para gerenciamento de builds e dependências na atualidade.
• Git: a escolha pela ferramenta Git (um software de controle de versões de código-fonte) se deu pela complexidade do ambiente de desenvolvimento do software PJe no qual é desejável que várias equipes, em diferentes localidades (Tribunais de Justiça), estejam trabalhando, paralelamente, no desenvolvimento de diferentes módulos do software PJe e, também, na manutenção dos módulos já implementados.
• JBoss Enterprise Application Platform (JBoss): a escolha pelo servidor de aplicações Red Hat JBoss é justificada pela reconhecida posição de destaque, entre a comunidade de desenvolvedores JEE, deste servidor de aplicação que oferece a completa implementação das APIs da plataforma JEE. Além disso, a versão do JBoss denominada EAP (Enterprise Application Platform), em particular, foi a escolhida porque permite a contratação do serviço de suporte da empresa Red Hat. É importante destacar que, o uso do servidor de aplicações JBoss é adotado como o servidor de aplicação padrão do projeto e, para o uso de outro servidor de aplicação diferente, explicaremos em outra seção deste documento as diretrizes de configuração que precisarão ser feitas.
• PostgreSQL: a escolha do SGBD PostgreSQL deve-se pelo fato deste SGBD ser de uso gratuito e open source (ou seja, é um software cujo código-fonte está aberto para comunidade), implementar o padrão objeto-relacional com a robustez desejada pelo projeto. Além de, ser um SGBD amplamente utilizado pela comunidade de desenvolvedores de diversas linguagens de programação. É importante destacar que, o uso do SGBD PostgreSQL é adotado como o SGBD padrão do projeto e, para o uso de outro SGBD diferente, explicaremos em outra seção deste documento as diretrizes de configuração que precisarão ser feitas.

Definição da arquitetura de referência

Esta seção descrevemos a arquitetura de referência definida para o desenvolvimento do software PJe 2.0 e suas evoluções futuras. Dentre os assuntos que serão tratados, podemos destacar: a forma como a arquitetura foi estruturada/organizada e as responsabilidades da arquitetura. Vale informar que, a arquitetura também poderá ser reutilizada para outros projetos cujo domínio do negócio seja diferente do PJe.

A arquitetura é formada por 5 "camadas" lógicas relacionadas entre si e, além das camadas, é possível agruparmos logicamente elementos da arquitetura por meio de "módulos". Vejamos o significado desses dois conceitos:

• Camada: representa uma associação abstrata de elementos que atendem a um conjunto bem definido de responsabilidades dentro do contexto do software.
• Módulo: são blocos de implementação (código-fonte, arquivos de configuração, arquivos de propriedades, arquivos de templates (ou modelos) de janelas gráficas, scripts de banco de dados, etc.) responsáveis por um ou mais serviços ofertados pelo software. Um módulo é classificado, conceitualmente, por um dos seguintes tipos assim definidos:
  • Tipo 1: é um módulo que representa abstrações do modelo de negócio inerente ao software, em outras palavras, um módulo do tipo 1 agrupa classes Java que representam conceitos do domínio do negócio. Também o chamaremos de módulo de negócio. Um módulo do tipo 1 não pode conhecer um outro módulo do tipo 1, caso contrário, será violado a independência entre esses módulos. Todo módulo tipo 1 deve ter uma única interface Java, local e/ou remota, e, também, a classe Java que implementa os serviços ofertados por essa interface.
  • Tipo 2: é um módulo que representa abstrações da própria arquitetura do software, em outras palavras, um módulo do tipo 2 agrupa classes Java e um conjunto de arquivos que fazem parte da arquitetura. Exemplo desse conjunto de arquivos: XHTML, CSS, Javascript, HTML, XML, etc. Um módulo do tipo 2 pode conhecer um outro módulo do tipo 2.

Concretamente, cada módulo tornar-se-á um projeto específico gerenciado pelo aplicativo Maven. Dessa forma, garantiremos o isolamento dos módulos do software. Além de ser gerenciado pelo Maven, cada módulo é construído separadamente, com repositório próprio no aplicativo Git e com versionamento exclusivo, permitindo o isolamento do código-fonte e a especialização das equipes de desenvolvimento, contribuindo com o objetivo de facilitar a manutenção do software e minimizar os impactos de efeitos colaterais das diversas manutenções do software. A nomenclatura do projeto específico no Maven obedecerá o padrão pje-<modulo>, em 'modulo' deve conter o nome do módulo correspondente.

Explicaremos nas próximas subseções mais detalhes da arquitetura por meio de visões gráficas arquiteturais.

Visão geral das camadas da arquitetura

A primeira visão da arquitetura de referência é exibida na Figura 1 e a denominamos de Visão Geral das Camadas da Arquitetura.
TODO: desenhar Figura 1 conforme Rascunho 1 e incluir aqui. Deve-se explicar 'qual camada conhece qual camada' na Figura 1
Figura 1. Visão Geral das Camadas da Arquitetura. Figura 1. Visão Geral das Camadas da Arquitetura.

Conforme pode ser visto na Figura 1, há 5 camadas lógicas e a definição de cada uma dessas camadas é apresentada seguir:

1. Camada de Apresentação: encapsula toda a lógica de interação com usuários, desde a exibição de informações, passando pela captura de dados informados pelos usuários por meio das janelas gráficas do software, até o reconhecimento de ações realizadas nessas janelas gráficas.
2. Camada de APIs: encapsula o acesso aos módulos ofertados pelo software. Normalmente, nesta camada terão módulos do tipo 2.
3. Camada de Negócio: encapsula toda a lógica do domínio de negócio do software, ou seja, as regras de manipulação dos dados e informações controlados pelo software.
4. Camada de Domínio: encapsula as representações dos dados e informações inerentes ao domínio de negócio do software, em outras palavras, esta camada é responsável pela realização do mapeamento objeto-relacional.
5. Camada de Serviços: encapsula toda a lógica de acesso ao software, servindo como porta de entrada de requisições dos diversos clientes do software, por exemplo: requisições de usuários por meio de janelas gráficas; requisições de outros softwares por meio de webservices.

TODO: citar as tecnologias predominantes que serão usadas em cada camada

Visão modular da arquitetura

A segunda visão da arquitetura de referência é exibida na Figura 2 e a denominamos de Visão Modular da Arquitetura.
Figura 2. Visão Modular da Arquitetura.
Na Figura 2 apresentamos uma visão da arquitetura contemplando os conceitos já explicados: camadas e módulos. Nessa visão também demonstramos um exemplo de uso da arquitetura. Observando a Figura 2 no sentido 'cima para baixo', explicaremos, a seguir, a estrutura da arquitetura de referência:

1. Um módulo tipo 2 que denominamos de módulo web. Esse módulo no aplicativo Maven é denominado pje-web. Nesse módulo inclui-se:
   1. Uma pasta denominada recursos que contém um conjunto de arquivos. Exemplos desses arquivos: XHTML, CSS, Javascript, imagens, entre outros.
   2. Um pacote denominado controlador que contém classes Java que realizam o trabalho definido pela Camada de Apresentação do software. Somente as classes desse pacote têm acesso ao conjunto de arquivos da pasta recursos. Essas classes também têm acesso às interfaces Java do módulo orquestrador. Também podem ter acesso às interfaces Java de módulos do negócio do tipo 1 que existirem no software, por exemplo: na Figura 2, a classe Java 'MinhaEntidadeAOperacaoCtrl' acessa o módulo 'Meu negócio A' por meio de sua interface Java.
2. Um módulo tipo 2 que denominamos de módulo orquestrador. Esse módulo no aplicativo Maven é denominado pje-service. Nesse módulo inclui-se:
   1. Um pacote denominado api que contém interfaces Java que representam o trabalho definido pela Camada de APIs do software.
   2. Um pacote denominado impl que contém classes Java que implementam o trabalho definido pela Camada de Serviços do software. Em outras palavras, uma classe Java do pacote impl implementa os serviços ofertados por uma interface Java do pacote api correspondente.
      Uma classe do pacote impl não, necessariamente, implementa por completo um determinado serviço o qual ela é responsável. Logo, é possível que essa classe obtenha o resultado de 'partes desse serviço' por meio de um outro módulo da arquitetura do software. Um exemplo: na Figura 2 temos um ou mais serviços da classe 'MeuServicoSrv' fazendo uso de serviços disponíveis nas interfaces Java 'IMeuNegocioASrv' do módulo 'Meu negócio A' e 'IMeuNegocioBSrv' do módulo 'Meu negócio B'.
3. 'Meu Negócio A' é exemplo de como pode ser estruturado um módulo tipo 1 no software. Nesse exemplo, inclui-se:
   1. Uma interface Java denominada 'IMeuNegocioASrv'; essa interface representa o trabalho definido pela Camada de APIs do módulo 'Meu Negócio A'.
   2. Uma classe Java denominada 'MeuNegocioASrv'; essa classe implementa os serviços ofertados pela Camada de Serviços do módulo 'Meu Negócio A'. Em outras palavras, a classe 'MeuNegocioASrv' implementa os serviços ofertados pela interface Java 'IMeuNegocioASrv'.
   3. Uma ou mais classes Java que implementam o trabalho definido pela Camada de Negócio do módulo 'Meu Negócio A'. Exemplos: na Figura 2 temos as classes 'MinhaEntidadeAManager' e 'MinhaEntidadeCManager' e as suas classes DAO correspondentes.
4. 'Meu Negócio B' é exemplo de como pode ser estruturado um módulo tipo 1 no software. Nesse exemplo, inclui-se:
   1. Uma interface Java denominada 'IMeuNegocioBSrv'; essa interface representa o trabalho definido pela Camada de APIs do módulo 'Meu Negócio B'.
   2. Uma classe Java denominada 'MeuNegocioBSrv'; essa classe implementa os serviços ofertados pela Camada de Serviços do módulo 'Meu Negócio B'. Em outras palavras, a classe 'MeuNegocioBSrv' implementa os serviços ofertados pela interface Java 'IMeuNegocioBSrv'.
   3. Uma ou mais classes Java que implementam o trabalho definido pela Camada de Negócio do módulo 'Meu Negócio B'. Exemplos: na Figura 2 temos as classes 'MinhaEntidadeBManager' e sua classe DAO correspondente.
5. Um módulo tipo 2 que denominamos de módulo modelo. Esse módulo no aplicativo Maven é denominado pje-modelo. Nesse módulo inclui-se:
   1. Um pacote denominado modelo que contém classes Java que realizam o trabalho definido pela Camada de Domínio do software. Por exemplo: na Figura 2 temos as classes 'MinhaEntidadeA', 'MinhaEntidadeB' e 'MinhaEntidadeC'. Todos os módulos do software (tanto módulo do tipo quanto do tipo 2) têm acesso às classes do pacote modelo.

É importante destacar que:

• O módulo de negócio 'Meu Negócio A' não conhece o módulo de negócio 'Meu Negócio B', logo, está consistente com a definição de módulo tipo 1.
• Uma classe Java pertencente à Camada de Negócio pode acessar uma outra classe da Camada de Negócio desde que, ambas classes, pertençam ao mesmo módulo de negócio.
• Classes Java da Camada de Negócio podem ser acessadas por classes Java da Camada de Serviços somente dentro de um mesmo módulo de negócio.

Organização dos projetos no Maven

Nesta subseção, apresentamos a organização dos projetos no aplicativo Maven, consolidando os módulos citados no decorrer da explicação da Figura 2 e outros módulos necessários para estruturação da arquitetura.

• pje-pom: projeto que contém as dependências que são comuns entre todos os demais projetos. Não deve conter código-fonte, apenas as configurações dessas dependências. O aplicativo Maven exige a presença do arquivo POM (Project Object Model).
• pje-modelo: projeto que contém todas as entidades de domínio do negócio mapeadas de acordo com o padrão JPA-Java Persistence API.
• pje-comum: projeto que contém todas as classes Java utilitárias do software. Também é classificado como um módulo tipo 2. Exemplos de classes Java desse projeto: classes que implementam os registros de auditoria das operações do software (também chamado de registro de log), classes que implementam o controle de acesso, o tratamento de exceções, entre outras classes responsáveis pela infraestrutura do software.
• pje-service: projeto que contém as classes do módulo orquestrador das funcionalidades que envolvam mais de um módulo de negócio.
• pje-web: projeto que contém todo o código-fonte associado à Camada de Apresentação, exemplos: classes controladoras (também conhecidas por back-beans), arquivos HTML, XHTML, CSS e scripts JavaScript.

Os projetos no Maven serão empacotados em arquivos com extensão jar (Java ARchive), com exceção do projeto "pje-web", que será empacotado em um arquivo com extensão war (Web application ARchive).

Cada módulo dará origem a três arquivos extensão jar:

1. pje-modulo-X.Y.Z.jar: este arquivo contém todas as classes Java do módulo e será utilizado no momento da instalação (deploy) do módulo.
2. pje-modulo-X.Y.Z-api.jar: este arquivo contém apenas as interfaces Java do respectivo módulo e será utilizado como dependência na implementação dos módulos "pje-web" e "pje-service". Lembrando que, os módulos "pje-web" e "pje-service" somente terão acesso à Camada de APIs do módulo em questão.
3. pje-modulo-X.Y.Z-sources.jar: este arquivo contém o código-fonte do módulo e será utilizado para fins de depuração do código-fonte (ou debug).

Padrões e boas práticas

Esta seção tem o objetivo de apresentar os padrões estabelecidos e algumas boas práticas de programação, ambos em consonância com os propósitos da arquitetura de referência. As explicações serão divididas nas subseções desta seção.

Padrões de nomenclatura e codificação

• Padrões de nomenclatura para classes Java:
  • Controladores (back-beans): <Entidade><operação>Ctrl.java
  • Interfaces Java dos orquestradores: I<Serviço>Srv.java
  • Implementações dos orquestradores: <Serviço>Srv.java
  • Interfaces Java dos módulos: I<Módulo>Srv.java
  • Implementações dos módulos: <Módulo>Srv.java
  • Classes de negócio: <Entidade>Manager.java
  • Classes de acesso aos dados: <Entidade>DAO.java
  • Entidades: <Entidade>.java

• Padrões de nomenclatura para pacotes Java:
  • br.jus.cnj.pje.web.controlador: todos os controladores do software devem pertencer a este pacote.
  • br.jus.cnj.pje.service.api: todas as interfaces Java dos orquestradores do software devem pertencer a este pacote.
  • br.jus.cnj.pje.service.impl: todas as implementações das interfaces Java dos orquestradores devem pertencer a este pacote.
  • br.jus.cnj.pje.<negócio>.api: a interface Java do módulo deve pertencer a este pacote. Entende-se por <negócio> o nome do módulo de negócio.
  • br.jus.cnj.pje.<negócio>.impl: a implementação da interface Java do módulo deve pertencer a este pacote. Entende-se por <negócio> o nome do módulo de negócio.
  • br.jus.cnj.pje.<negócio>.manager: todas as classes de negócio do módulo de negócio devem pertencer a este pacote. Entende-se por <negócio> o nome do módulo de negócio.
  • br.jus.cnj.pje.<negócio>.dao: todas as classes de acesso aos dados inerentes ao módulo de negócio devem pertencer a este pacote. Entende-se por <negócio> o nome do módulo de negócio.
  • br.jus.cnj.pje.modelo: todas as classes das entidades mapeadas no padrão JPA devem pertencer a este pacote.

• Padrões de nomenclatura para arquivos XHTML:
  • <entidade><operação>.xhtml: entende-se por <entidade> o nome da principal da entidade manipulada pela janela gráfica (ou tela), e por <operação> a principal manipulação que se deseja realizar a partir desta tela (visualizar, excluir, alterar, desativar, cadastrar, etc).

É importante ressaltar que, os padrões apresentados no decorrer da explicação da Figura 2 também foram considerados.

Além dos padrões definidos nesta subseção, recomendamos a adoção do padrão de codificação Java, disponível no endereço http://www.oracle.com/technetwork/java/codeconvtoc-136057.html.

Problemas conhecidos e preocupações

[TODO: citar e explicar problemas conhecidos e preocupações futuras, caso tenham ]

Instruções de montagem do ambiente de desenvolvimento

TODO: - Incluir as diretrizes de configuração que precisarão ser feitas caso use um servidor de aplicação diferente do JBoss - Incluir as diretrizes de configuração que precisarão ser feitas caso use um SGBD diferente do PostgreSQL - Iincluir todas as diretrizes de configuração necessárias.

Referências bibliográficas

1. World Wide Web Consortium (W3C) disponível em http://www.w3.org/, último acesso em 26/05/2015.
2. Maven – Welcome to Apache Maven disponível em https://maven.apache.org/, último acesso em 28/05/2015.
3. Code Conventions disponível em http://www.oracle.com/technetwork/java/codeconvtoc-136057.html (último acesso em 02/06/2015).