ObjectScript Class Explorer - Explorando Classes ObjectScript na Notação UML

Olá!

Este artigo é uma pequena visão geral de uma ferramenta que ajuda a entender classes e sua estrutura dentro dos produtos InterSystems: do IRIS ao Caché, Ensemble e HealthShare.

Em resumo, ela visualiza uma classe ou um pacote inteiro, mostra as relações entre as classes e fornece todas as informações possíveis para desenvolvedores e líderes de equipe sem fazê-los ir ao Studio e examinar o código lá.

Se você está aprendendo os produtos InterSystems, revisando muitos projetos ou apenas interessado em algo novo nas soluções de tecnologia InterSystems - você é mais do que bem-vindo para ler a visão geral do ObjectScript Class Explorer!

Introdução aos Produtos InterSystems

O IRIS (anteriormente conhecido como Caché) é um SGBD( Sistema Gerenciador de Banco de Dados)  multi-modelo. Você pode acessá-lo usando consultas SQL ou interagir com objetos e procedimentos armazenados por meio de interfaces disponíveis para várias linguagens de programação. Mas a primeira opção é sempre desenvolver aplicativos na linguagem nativa e integrada do SGBD - ObjectScript (COS).

O Caché suporta classes no nível do SGBD. Existem dois tipos principais de classes: Persistentes (podem ser armazenadas no banco de dados) e Registradas (não são armazenadas no banco de dados e desempenham o papel de programas e manipuladores). Existem também vários tipos de classes especiais: Serial (classes que podem ser integradas em classes Persistentes para criar tipos de dados complexos, como endereços), DataType (para criar tipos de dados definidos pelo usuário), Index, View e Stream.

Apresentando o Class Explorer

O Caché Class Explorer é uma ferramenta que visualiza a estrutura das classes Caché como um diagrama, mostra as dependências entre as classes e todas as informações relevantes, incluindo o código dos métodos, consultas, blocos xData, comentários, documentação e palavras-chave de vários elementos da classe.

Funcionalidade

O Class Explorer usa uma versão estendida da notação UML para visualização, já que o Caché possui um conjunto adicional de entidades que não são suportadas no UML padrão, mas são importantes para o Caché: consultas, blocos xData, muitas palavras-chave para métodos e propriedades (como System, ZenMethod, Hidden, ProcedureBlock e outros), relações pai-filho e um-para-muitos, tipos de classe e assim por diante. 

O Caché Class Explorer (versão 1.14.3) permite que você faça o seguinte:

• Exiba a hierarquia de pacotes, um diagrama de classes ou um pacote inteiro;
• Edite a aparência de um diagrama depois que ele for exibido;
• Salve a imagem atual de um diagrama de classes;
• Salve a aparência atual de um diagrama e restaure-a no futuro;
• Pesquise por quaisquer palavras-chave mostradas em um diagrama ou em uma árvore de classes;
• Use dicas de ferramentas (tooltips) para obter informações completas sobre classes, suas propriedades, métodos, parâmetros, consultas e blocos xData;
• Visualize o código de métodos, consultas ou blocos xData;
• Habilite ou desabilite a exibição de quaisquer elementos do diagrama, incluindo ícones gráficos. 

Para melhor compreensão de tudo o que se segue neste artigo, veja como as classes são visualizadas no Class Explorer. Como exemplo, vamos exibir o pacote "Cinema" do namespace "SAMPLES":

Visão geral de detalhes e recursos

A barra lateral esquerda contém uma árvore de pacotes. Posicione o cursor sobre o nome do pacote e clique em um botão que aparece à sua direita para exibir o pacote inteiro. Selecione a classe na árvore de pacotes para renderizá-la juntamente com suas classes vinculadas.

O Class Explorer pode exibir vários tipos de dependências entre classes:

1. Herança: É mostrada com uma seta preenchida com cor branca apontando na direção da classe herdada;
2. "Associação" ou relação entre classes: Se um campo de uma das classes contiver um tipo de outra classe, o construtor de diagramas mostrará isso como uma relação de associação;
3. Relação Pai-Filho e Um-Para-Muitos: As regras de manutenção da integridade dos dados.

Se você apontar o cursor sobre a relação, as propriedades que criam essa relação serão destacadas:

Deve-se notar que o Class Explorer não se aprofundará e não desenhará dependências para classes fora do pacote atual. Ele mostrará apenas as classes no pacote atual e, se você precisar limitar a profundidade com que o Class Explorer deve procurar as classes, use a configuração "Nível de dependência":

A própria classe é exibida como um retângulo dividido em seis seções:

1. Nome da classe: Se você apontar o cursor para o nome da classe, poderá saber quando ela foi criada e modificada, visualizar o comentário e todas as palavras-chave atribuídas à classe. Um clique duplo no cabeçalho da classe abrirá sua documentação;
2. Parâmetros da classe: Todos os parâmetros atribuídos com tipos, palavras-chave e comentários. Parâmetros em itálico, assim como quaisquer propriedades, possuem dicas de ferramentas e podem ser focalizados (hover);
3. Propriedades da classe: São semelhantes aos parâmetros;
4. Métodos: Qualquer método pode ser clicado para visualizar seu código-fonte. A sintaxe COS será destacada;
5. Consultas (Queries): São como métodos - clique neles para visualizar o código-fonte;
6. Blocos xData: Blocos que contêm principalmente dados XML. Clicar neles mostrará o código-fonte formatado no bloco.

Por padrão, cada classe é exibida com um número de ícones gráficos. O significado de cada ícone pode ser esclarecido clicando no botão Ajuda no canto superior direito da tela. Se você precisar de uma notação UML mais ou menos estrita que é exibida por padrão, bem como a exibição de quaisquer seções de classe, isso pode ser desativado na seção de configurações.

Se um diagrama for muito grande e desconhecido para você, você pode usar uma função de pesquisa rápida de diagrama. A classe contendo qualquer parte da palavra-chave que você inseriu será destacada. Para pular para a próxima correspondência, basta pressionar Enter ou clicar no botão de pesquisa novamente:

Finalmente, depois que todas as edições no diagrama forem feitas, todas as relações desnecessárias forem removidas e os elementos forem colocados em suas posições para atingir a aparência desejada, você pode salvá-lo clicando no botão Download no canto inferior esquerdo: 

Quando você ativa um botão de alfinete (pin) , a posição dos elementos no diagrama do conjunto atual de classes (ou um pacote) será salva. Por exemplo, se você selecionar as classes A e B e, em seguida, salvar a visualização com o botão de alfinete, você verá exatamente a mesma visualização ao escolher as classes A e B novamente, mesmo após reiniciar o navegador ou a máquina. Mas se você escolher apenas a classe A, o layout será o padrão.

Instalação

Para instalar o Caché Class Explorer, você só precisará importar o pacote xml da versão mais recente  para qualquer namespace. Assim que a importação for concluída, você poderá notar que o novo aplicativo web chamado hostname/ClassExplorer/ (a barra no final é obrigatória) apareceu.

Instruções de instalação detalhadas

1. Baixe o arquivo com a versão mais recente do Caché Class Explorer;
2. Extraia o arquivo XML chamado Cache/CacheClassExplorer-vX.X.X.xml;
3. Importe o pacote para qualquer namespace usando uma das seguintes maneiras:
   1. Basta arrastar o arquivo XML para o Studio;
   2. Usando o Portal de Gerenciamento do Sistema: Explorador de Sistema -> Classes -> Importar e especifique o caminho para o arquivo local;
   3. Usando o comando do terminal: do ##class(%Installer.Installer).InstallFromCommandLine(“Path/Installer.cls.xml”);
4. Leia o log de importação — se tudo estiver OK, você poderá abrir o aplicativo web em http://hostname/ClassExplorer/. Se algo der errado, verifique o seguinte:
   1. Se você tem direitos suficientes para importar classes para este namespace;
   2. Se o usuário do aplicativo web tem privilégios suficientes para acessar diferentes namespaces;
   3. Se você receber o erro 404, basta verificar se adicionou uma barra no final da URL.

Algumas outras capturas de tela.

[Captura de tela 1] Pacote DSVRDemo, passando o mouse sobre o nome de uma classe.

[Captura de tela 2] Pacote DataMining, pesquisando pela palavra-chave "TreeInput" no diagrama.

[Captura de tela 3] Visualização do código do método na classe JavaDemo.JavaListSample.

[Captura de tela 4] Visualizando o conteúdo do bloco XData na classe ClassExplorer.Router.

Você pode experimentar como o Class Explorer funciona no namespace padrão SAMPLES:  demo. . E aqui está uma resenha em vídeo do projeto.

Quaisquer comentários, sugestões e observações são bem-vindos - por favor, deixe-os aqui ou no repositório do GitHub. Aproveite!