3. Sobre a estrutura do projeto

Data	Versão	Realizada por	Modificações
31/01/2018	1.0	Yury Alencar	Criação da estrutura do documento
01/02/2018	1.0	Yury Alencar	Preenchimento de toda a estrutura

Estrutura do projeto

O projeto com a finalidade de criar um plugin com regras personalizadas para a ferramenta SonarQube possui a seguinte estrutura básica:

• java-custom-rules
  • src
    • main
      • java
      • resources
    • test
      • files
      • java
  • pom.xml

Onde:

• java-custom-rules: É o diretório raiz do projeto.
• src: É a pasta onde se encontra todo o código desenvolvido.
• main: Diretório no qual se encontra a implementação real do plugin sem a inclusão dos arquivos de teste.
• java: Diretório no qual se localiza os arquivos com extensão .java referentes tanto as regras, quanto aos arquivos padrões de manipulação da mesma para a criação do arquivo executável (.jar)
• resources: Diretório no qual se encontra arquivos de metadados como JSON e HTML, que são utilizados pela ferramenta para ilustrar os problemas encontrados na ferramenta, o .json e o .html são criados automaticamente durante a compilação, mas podem ser criados e personalizados para melhorar o entendimento do desenvolvedor que irá utilizar o plugin.
• test: Diretório no qual se encontram os arquivos relacionados aos testes do projeto.
• files: Diretório no qual se localiza arquivos .java personalizados com a finalidade de servirem como exemplos para os testes, um exemplo de arquivo de testes pode ser localizado em: Exemplo de arquivo de testes
• java: Diretório no qual se encontram os testes relacionados tanto as classes de manipulação das regras quanto a de cada regra.
• pom.xml: Arquivo XML com a função de configurar a compilação, sincronização de dependências e criação do arquivo executável .jar.

Significado das classes e arquivos padrões do projeto

Classes

• MyJavaRulesPlugin.java: Classe que serve como ponto de entrada para o plugin na ferramenta SonarQube, a mesma contém um método nomeado "define" que recebe como parâmetro um objeto do tipo "Context", que possui dados e permissão para modificar dados relacionados ao contexto no qual a ferramenta se encontra. Assim se torna possível a adição das extensões referentes ao plugin implementado. Estas extensões possuem dois tipos sendo eles:

  • Extensões do servidor que são instanciadas durante o início do servidor que estão contidos na classe MyJavaRulesDefinition.class
  • Extensões que são instanciadas em lote, e são utilizadas no momento a análise que se encontram na classe MyJavaFileCheckRegistrar.class

• MyJavaFileCheckRegistrar.java: É a classe responsável por fornecer as classes de verificações, ou seja, as classes nas quais as regras personalidades foram implementadas. Nas quais são utilizadas durante a análise do código, sendo esta referente a extensão de lote. A classe possui um método público "register", que tem como objetivo registrar quais classes serão instanciadas durante a análise do projeto. Este método recebe como parâmetro um objeto do tipo RegistrarContext, que torna possível o registro de classes naquele contexto específico(análise do projeto), para isto é necessário fornecer a senha do repositório no qual se encontra as regras, uma lista contendo as respectivas regras e outra lista contendo os testes realizados em cima das regras fornecidas.

• MyJavaRulesDefinition.java: É uma classe que tem como objetivo declarar os metadados relacionados às regras no repositório do sistema, por causa da mesma é possível listar as especificações implementadas na aba "Rules", sendo isto relacionada a etapa de inicialização do software, por este motivo a classe é utilizada como extensão de servidor. A classe é composta por seis métodos e duas outras classes internas. A seguir contém os métodos e suas respectivas funções dentro do projeto:

  • define: O método em questão recebe como parâmetro um objeto do tipo "Context", que diz respeito ao estado do sistema atual (inicialização), e partindo disto é criado um repositório neste contexto específico, inserindo o nome e senha do mesmo. Posteriormente o método carrega todas as verificações implementadas juntamente com seus respectivos arquivos de testes. Depois disto as regras criadas são adicionadas ao repositório criado, após esta etapa toda a lista é percorrida com o objetivo de criação dos metadados e validação das verificações inseridas. O método finaliza com o fechamento do repositório criado.
  • newRule: O método recebe como parâmetro o novo repositório criado e uma classe desconhecida, partindo disto é verificado se esta classe possui o annotation presente na implementação de uma regra. Caso possua sua chave é extraída, para que assim posteriormente seja realizada uma pesquisa dentro do repositório. Se a respectiva regra for encontrada pela sua chave, são criados os metadados para que esta apareça na aba "Rules" da ferramenta. O método é finalizado adicionando a regra um template a ser seguido. Obs.: Este método contém várias verificações e pode lançar várias exceções.
  • ruleMetadata: Método que recebe como parâmetro uma classe desconhecida e uma nova regra. Este método extrai a chave da regra presente no repositório, posteriormente utiliza essa classe para a retirada dos dados presente no annotation relacionado à regra. Caso não possua dados na anotação, é definido um novo valor default, com a finalidade de modificar a chave interna da regra. Posteriormente é criado adicionado a um diretório um arquivo HTML, e um JSON referentes à regra, para que possa ser visualizado através do sistema, e retorna a chave relacionada ao metadado.
  • addMetadata: Método que recebe como parâmetro a nova regra e a chave do metadado. É o método responsável pela criação de um arquivo JSON, com metadados referentes à regra implementada. Através da regra é extraído todos os dados necessários para que o arquivo possa ser criado. A chave é utilizada juntamente com o nome do arquivo, assim garantindo que o arquivo criado conterá um nome único dentro do diretório especificado.
  • addHtmlDescription: Método que recebe como parâmetro a nova regra e a chave do metadado. Possui funcionamento semelhante ao anterior, utilizando os dados para a criação de um arquivo HTML ao invés de um JSON dentro do mesmo diretório do método anterior.
  • readResource: Método que recebe a URL da pasta "resource", e a partir do mesmo retorna os dados no formato UTF-8.

  As duas classes internas presentes são estáticas e são referentes aos metadados da regra, contendo somente atributos relacionados à mesma assim facilitando na criação dos arquivos de metadados.

• RulesList.java: É a classe que contém a lista de todas as regras e testes que foram implementadas no plugin, e tem função crucial no fornecimento destas para as classes de extensões tanto as de servidor quanto as de lote. A classe possui três métodos, sendo um que fornece uma lista somente das verificações e outro somente os testes ambos são utilizados pela extensão em lote, já o último método é utilizado pela extensão de servidor que fornece ambas informações somente em um única lista.

• MyJavaRulesDefinitionTest.java: É a uma classe de testes que tem com objetivo garantir o funcionamento da criação do plugin em modo geral, através da mesma é possível verificar as regras, se os parâmetros foram devidamente incluídos no repositório. Garantindo uma maior qualidade para o plugin confeccionado.

• LoggerDebug.java (Opcional) : Classe responsável pela criação de um arquivo de Logger na pasta do projeto, com a finalidade de saber alguns dados relacionados as regras implementadas, podendo assim visualizar detalhes relevantes relacionados a criação e funcionamento do plugin. A classe possui um único método estático, que tem como finalidade inicializar o Logger e para isto recebe como parâmetro o nome do arquivo de log.

Arquivos

• pom.xml: Arquivo que é utilizado pela tecnologia Maven, e o mesmo contém dados referentes ao artefato que será gerado, ou seja, o executavel .jar. Através deste arquivo o Maven consegue realizar o gerenciamento de dependências que são utilizadas no projeto, além de ter um papel importante na compilação do projeto, definindo inclusive em qual etapa usar quais dependências, assim permitindo uma personalização desta etapa.

Exemplo do arquivo de testes

A seguir contém um exemplo de arquivos de testes localizado na pasta "$PATH\java-custom-rules\tests\files", e é utilizado pelas classes de testes. Nas respectivas linhas preenchidas com "Noncompliant" significa que as mesmas apresentam incoerências com a respectiva regra. Neste caso em específico apresenta uma exemplo na qual um método que recebe um e somente um parâmetro de entrada não pode possuir retorno do mesmo tipo do parâmetro de entrada.

class MyClass {
    MyClass(MyClass mc) { }
 
    int     foo1() { return 0; }
    void    foo2(int value) { }
    int     foo3(int value) { return 0; } // Noncompliant
    Object  foo4(int value) { return null; }
    MyClass foo5(MyClass value) {return null; } // Noncompliant
 
    int     foo6(int value, String name) { return 0; }
    int     foo7(int ... values) { return 0;}
}