Download as
Browse Code »

Commit 1c9e25ba604e0f3bf07bf977d7f75b72b51fc72e

Authored by Dancovich
1 parent 90e73ed6
Exists in master

Escrevendo documentação de módulo de monitoração do Demoiselle

Showing 3 changed files with 172 additions and 6 deletions   Show diff stats
documentation/reference/pt-BR/gerenciamento.xml
  Diff comments   View file @1c9e25b
1 1 <?xml version='1.0' encoding="utf-8"?>
2 2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
4   -<chapter id="mensagem">
  4 +<chapter id="gerenciamento">
5 5  
6 6 <title>Monitoração e Gerenciamento de Recursos</title>
7 7  
... ... @@ -38,24 +38,189 @@
38 38 <para>Essa anotação é suficiente para o mecanismo de gerenciamento descobrir sua classe e disponibiliza-la para ser monitorada e gerenciada.</para>
39 39  
40 40 <para>Contudo, a simples anotação acima não informa ao mecanismo quais aspectos da classe serão expostos. Por padrão, um <emphasis>Management Controller</emphasis>
41   - não expõe nenhum aspecto seu. Para selecionais quais aspectos serão expostos usamos as anotações <code>@ManagedProperty</code> e <code>@ManagedOperation</code>.</para>
  41 + não expõe nenhum aspecto seu. Para selecionar quais aspectos serão expostos usamos as anotações <emphasis>@ManagedProperty</emphasis> e <emphasis>@ManagedOperation</emphasis>.</para>
  42 +
  43 + <informaltable>
  44 + <thead>
  45 + <row>
  46 + <entry>Anotação</entry>
  47 + <entry>Descrição</entry>
  48 + <entry>Atributos</entry>
  49 + </row>
  50 + </thead>
42 51  
43   - <table>
44 52 <tbody>
45 53 <row>
46 54 <entry>
47 55 <emphasis role="BOLD">@ManagedProperty</emphasis>
48 56 </entry>
  57 +
  58 + <entry>
  59 + <para>Marca um atributo na classe como uma propriedade gerenciada, significando que clientes externos podem ler e/ou escrever valores nesses atributos.</para>
  60 + <para>Um atributo marcado pode estar disponível para leitura e/ou escrita. Por padrão, o que determina a visibilidade de um atributo
  61 + marcado é a presença dos métodos <emphasis>getAtributo</emphasis> e <emphasis>setAtributo</emphasis>, respectivamente disponibilizando o atributo
  62 + para leitura e escrita.</para>
  63 + <para>Para sobrescrever esse comportamento existe na anotação <emphasis role="BOLD">@ManagedProperty</emphasis> o atributo <emphasis>accessLevel</emphasis>.
  64 + Com ele é possível criar um atributo apenas para leitura, mas que contenha um método <emphasis>set</emphasis>. O contrário também é possível.</para>
  65 + </entry>
  66 +
  67 + <entry>
  68 + <itemizedlist>
  69 + <listitem><emphasis role="BOLD">description</emphasis>: Um texto descritivo documentando o propósito da propriedade.</listitem>
  70 + <listitem><emphasis role="BOLD">accessLevel</emphasis>: Sobrescreve o nível padrão de acesso de uma propriedade. Os valores possíveis são
  71 + READ_ONLY, WRITE_ONLY e DEFAULT, que significa que a presença de métodos <emphasis>get</emphasis> e <emphasis>set</emphasis> vai determinar o nível de acesso.</listitem>
  72 + </itemizedlist>
  73 + </entry>
49 74 </row>
50 75  
51 76 <row>
52 77 <entry>
53   - <para>Marca um atributo na classe como uma propriedade gerenciada, significando que clientes externos podem ler e/ou escrever valores nesses atributos.</para>
54   - <para>Um</para>
  78 + <emphasis role="BOLD">@ManagedOperation</emphasis>
  79 + </entry>
  80 +
  81 + <entry>
  82 + <para>Marca um método da classe gerenciada como uma operação, o que significa que clientes externos podem invocar esse método remotamente.</para>
  83 + <para>Operações gerenciadas normalmente são criadas para executar intervenções em um sistema já em execução. Por exemplo, é possível criar uma
  84 + operação que, ao ser invocada, destrua todas as seções abertas no servidor e não utilizadas nos últimos 30 minutos.</para>
  85 + </entry>
  86 +
  87 + <entry>
  88 + <itemizedlist>
  89 + <listitem><emphasis role="BOLD">description</emphasis>: Um texto descritivo documentando o propósito da operação.</listitem>
  90 + <listitem><emphasis role="BOLD">type</emphasis>: Documenta o propósito da operação. <emphasis>ACTION</emphasis> informa que a operação modificará
  91 + o sistema de alguma forma. <emphasis>INFO</emphasis> diz que a operação coletará e retornará informações sobre o sistema. <emphasis>ACTION_INFO</emphasis>
  92 + informa que a operação modificará o sistema de alguma forma e retornará informações sobre o resultado. <emphasis>UNKNOWN</emphasis> é o padrão
  93 + e significa que o resultado da execução da operação é desconhecido.</listitem>
  94 + </itemizedlist>
55 95 </entry>
56 96 </row>
57 97 </tbody>
58   - </table>
  98 + </informaltable>
  99 +
  100 + <section>
  101 + <title>Personalizando operações gerenciadas</title>
  102 +
  103 + <para>Abaixo são apresentadas opções para personalizar ainda mais os atributos e operações marcados para gerenciamento da aplicação.</para>
  104 +
  105 + <informaltable>
  106 + <thead>
  107 + <row>
  108 + <entry>Anotação</entry>
  109 + <entry>Descrição</entry>
  110 + <entry>Atributos</entry>
  111 + </row>
  112 + </thead>
  113 +
  114 + <tbody>
  115 + <row>
  116 + <entry>
  117 + <emphasis role="BOLD">@OperationParameter</emphasis>
  118 + </entry>
  119 +
  120 + <entry>
  121 + <para>Esta anotação opcional permite detalhar melhor parâmetros em uma operação gerenciada. O efeito desta anotação é dependente da
  122 + tecnologia utilizada para comunicação entre cliente e servidor. Na maioria das tecnologias, essa anotação meramente permite ao cliente
  123 + exibir informações sobre cada parâmetro: nome, tipo e descrição.</para>
  124 + </entry>
  125 +
  126 + <entry>
  127 + <itemizedlist>
  128 + <listitem><emphasis role="BOLD">name</emphasis>: O nome do parâmetro quando exibido para clientes.</listitem>
  129 + <listitem><emphasis role="BOLD">description</emphasis>: Um texto descritivo documentando o propósito do parâmetro.</listitem>
  130 + </itemizedlist>
  131 + </entry>
  132 + </row>
  133 + </tbody>
  134 + </informaltable>
  135 + </section>
  136 +
  137 + </section>
  138 +
  139 + <section>
  140 + <title>Expondo aspectos de sua aplicação para monitoração</title>
  141 +
  142 + <para>Uma vez que uma classe esteja anotada com <emphasis>@ManagementController</emphasis> e seus atributos e operações estejam expostos, a classe está pronta para
  143 + ser monitorada.</para>
  144 +
  145 + <para>Suponha que a aplicação deseje expor o número de usuários que efetuaram login. A operação de <emphasis>login</emphasis> será processada em
  146 + uma classe de negócio <emphasis>ControleAcesso</emphasis>. Vamos supor também que existe uma classe chamada <emphasis>MonitorLogin</emphasis> responsável
  147 + por expor o número de usuários que efetuaram login no sistema.</para>
  148 +
  149 + <programlisting role="JAVA"><![CDATA[
  150 + @BusinessController
  151 + public class ControleAcesso{
  152 +
  153 + @Inject
  154 + private MonitorLogin monitorLogin;
  155 +
  156 + public boolean efetuarLogin(String usuario , String senha){
  157 +
  158 + // código de login
  159 +
  160 + monitorLogin.setContadorLogin( monitorLogin.getContadorLogin() + 1 );
  161 +
  162 + }
  163 +
  164 + }
  165 + ]]></programlisting>
  166 +
  167 + <para>Como é possível ver, classes anotadas com <emphasis>@ManagementController</emphasis> podem ser injetadas em qualquer ponto do código. Valores definidos
  168 + para seus atributos retêm seu estado, então um cliente que acesse remotamente o sistema e monitore o valor do atributo <emphasis>contadorLogin</emphasis> verá
  169 + a quantidade de logins efetuados no momento da consulta.</para>
  170 + </section>
  171 +
  172 + <section>
  173 + <title>Conectando um cliente de monitoração</title>
  174 +
  175 + <para>O <emphasis>demoiselle-core</emphasis> contém as funcionalidades necessárias para marcar aspectos monitoráveis de sua aplicação, mas não conta com nenhum mecanismo
  176 + para estabelecer uma conexão com um cliente de monitoração. Para isso utiliza-se extensões do framework.</para>
  177 +
  178 + <para>A extensão padrão do framework <emphasis>Demoiselle</emphasis> é a <emphasis>demoiselle-jmx</emphasis>. Essa extensão utiliza a especificação JMX e
  179 + permite registrar as classes marcadas para monitoração como <emphasis>MBeans</emphasis>. Uma vez que as classes sejam registradas como <emphasis>MBeans</emphasis>, seus atributos
  180 + e operações expostos para monitoração podem ser acessados via JMX por um cliente adequado, como o <emphasis>JConsole</emphasis> que acompanha por padrão o JDK
  181 + da Oracle.</para>
  182 +
  183 + <tip>
  184 + <para>Para acrescentar a extensão <emphasis>demoiselle-jmx</emphasis> em um projeto Maven, adicione a dependência abaixo no arquivo <emphasis>pom.xml</emphasis>.</para>
  185 +
  186 + <programlisting role="XML"><![CDATA[
  187 + <dependency>
  188 + <groupId>br.gov.frameworkdemoiselle</groupId>
  189 + <artifactId>demoiselle-jmx</artifactId>
  190 + <scope>compile</scope>
  191 + </dependency>
  192 + ]]></programlisting>
  193 + </tip>
  194 +
  195 + <tip>
  196 + <para>A API de monitoração é compatível com o uso de múltiplas extensões simultãneas. Adicione em seu projeto a dependência às extensões desejadas e configure-as
  197 + individualmente, as classes monitoradas serão então expostas para todas as extensões escolhidas.</para>
  198 + </tip>
  199 +
  200 + <para>A imagem abaixo mostra como uma classe monitorada na aplicação <emphasis>Bookmark</emphasis> é exibida no <emphasis>JConsole</emphasis>.</para>
  201 +
  202 + <programlisting role="JAVA"><![CDATA[
  203 + @ManagementController
  204 + public class BookmarkMonitor {
  205 +
  206 + @Inject
  207 + private BookmarkDAO bookmarkDAO;
  208 +
  209 + @ManagedOperation(type=OperationType.INFO , description="Informa quantos bookmarks estão salvos no sistema")
  210 + public int countSavedBookmarks(){
  211 + return bookmarkDAO.findAll().size();
  212 + }
  213 + }
  214 + ]]></programlisting>
  215 +
  216 + <figure>
  217 + <title>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></title>
  218 + <mediaobject>
  219 + <imageobject>
  220 + <imagedata fileref="jmx-console-example.jpg" align="center"/>
  221 + </imageobject>
  222 + </mediaobject>
  223 + </figure>
59 224  
60 225 </section>
61 226  
... ...
documentation/reference/pt-BR/jmx-jconsole-example.jpg 0 → 100644
View file @1c9e25b

95.5 KB
documentation/reference/pt-BR/master.xml
  Diff comments   View file @1c9e25b
... ... @@ -38,6 +38,7 @@
38 38 <xi:include href="templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
39 39 <xi:include href="security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
40 40 <xi:include href="paginacao.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
  41 + <xi:include href="gerenciamento.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
41 42 <xi:include href="properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
42 43  
43 44 <!-- parte 1 -->
... ...