Download as
Browse Code »

Commit 6553561cb76af57ef5480c49e6205799c70cacdb

Authored by Dancovich
1 parent 6f022675
Exists in master

Completada primeira versão de documentação sobre mecanismo de 

monitoração e gerenciamento.
Showing 2 changed files with 93 additions and 117 deletions   Show diff stats
documentation/reference/pt-BR/gerenciamento.xml
  Diff comments   View file @6553561
... ... @@ -24,8 +24,6 @@
24 24 uso o desenvolvedor pode se despreocupar com detalhes de implementação de cada tecnologia individual e facilmente integrar tais tecnologias.</para>
25 25 </section>
26 26  
27   -
28   -
29 27 <section>
30 28 <title>Introdução ao mecanismo</title>
31 29  
... ... @@ -34,77 +32,18 @@
34 32 anotada com o estereótipo <code>@ManagementController</code>.</para>
35 33  
36 34 <programlisting role="JAVA"><![CDATA[
37   - @ManagementController
38   - public class GerenciadorUsuarios]]></programlisting>
  35 +@ManagementController
  36 +public class GerenciadorUsuarios]]></programlisting>
39 37  
40 38 <para>Essa anotação é suficiente para o mecanismo de gerenciamento descobrir sua classe e disponibiliza-la para ser monitorada e gerenciada.</para>
41 39  
42 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>
43   - 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>
  41 + não expõe nenhum aspecto seu. Para selecionar quais aspectos serão expostos usamos as anotações
  42 + <emphasis>@ManagedProperty</emphasis> e <emphasis>@ManagedOperation</emphasis>. Além disso outras anotações podem ser usadas para personalizar o funcionamento
  43 + de classes anotadas com <code>@ManagementController</code>.</para>
44 44  
45 45 <informaltable>
46   - <thead>
47   - <row>
48   - <entry>Anotação</entry>
49   - <entry>Descrição</entry>
50   - <entry>Atributos</entry>
51   - </row>
52   - </thead>
53   -
54   - <tbody>
55   - <row>
56   - <entry>
57   - <emphasis role="BOLD">@ManagedProperty</emphasis>
58   - </entry>
59   -
60   - <entry>
61   - <para>Marca um atributo na classe como uma propriedade gerenciada, significando que clientes externos podem ler e/ou escrever valores nesses atributos.</para>
62   - <para>Um atributo marcado pode estar disponível para leitura e/ou escrita. Por padrão, o que determina a visibilidade de um atributo
63   - marcado é a presença dos métodos <emphasis>getAtributo</emphasis> e <emphasis>setAtributo</emphasis>, respectivamente disponibilizando o atributo
64   - para leitura e escrita.</para>
65   - <para>Para sobrescrever esse comportamento existe na anotação <emphasis role="BOLD">@ManagedProperty</emphasis> o atributo <emphasis>accessLevel</emphasis>.
66   - 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>
67   - </entry>
68   -
69   - <entry>
70   - <itemizedlist>
71   - <listitem><emphasis role="BOLD">description</emphasis>: Um texto descritivo documentando o propósito da propriedade.</listitem>
72   - <listitem><emphasis role="BOLD">accessLevel</emphasis>: Sobrescreve o nível padrão de acesso de uma propriedade. Os valores possíveis são
73   - 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>
74   - </itemizedlist>
75   - </entry>
76   - </row>
77   -
78   - <row>
79   - <entry>
80   - <emphasis role="BOLD">@ManagedOperation</emphasis>
81   - </entry>
82   -
83   - <entry>
84   - <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>
85   - <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
86   - operação que, ao ser invocada, destrua todas as seções abertas no servidor e não utilizadas nos últimos 30 minutos.</para>
87   - </entry>
88   -
89   - <entry>
90   - <itemizedlist>
91   - <listitem><emphasis role="BOLD">description</emphasis>: Um texto descritivo documentando o propósito da operação.</listitem>
92   - <listitem><emphasis role="BOLD">type</emphasis>: Documenta o propósito da operação. <emphasis>ACTION</emphasis> informa que a operação modificará
93   - 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>
94   - informa que a operação modificará o sistema de alguma forma e retornará informações sobre o resultado. <emphasis>UNKNOWN</emphasis> é o padrão
95   - e significa que o resultado da execução da operação é desconhecido.</listitem>
96   - </itemizedlist>
97   - </entry>
98   - </row>
99   - </tbody>
100   - </informaltable>
101   -
102   - <section>
103   - <title>Personalizando operações gerenciadas</title>
104   -
105   - <para>Abaixo são apresentadas opções para personalizar ainda mais os atributos e operações marcados para gerenciamento da aplicação.</para>
106   -
107   - <informaltable>
  46 + <tgroup cols="3">
108 47 <thead>
109 48 <row>
110 49 <entry>Anotação</entry>
... ... @@ -112,15 +51,62 @@
112 51 <entry>Atributos</entry>
113 52 </row>
114 53 </thead>
115   -
  54 +
116 55 <tbody>
117 56 <row>
118 57 <entry>
  58 + <emphasis role="BOLD">@ManagedProperty</emphasis>
  59 + </entry>
  60 +
  61 + <entry>
  62 + <para>Marca um atributo na classe como uma propriedade gerenciada, significando que clientes externos podem ler e/ou escrever valores nesses atributos.</para>
  63 + <para>Um atributo marcado pode estar disponível para leitura e/ou escrita. Por padrão, o que determina a visibilidade de um atributo
  64 + marcado é a presença dos métodos <emphasis>getAtributo</emphasis> e <emphasis>setAtributo</emphasis>, respectivamente disponibilizando o atributo
  65 + para leitura e escrita.</para>
  66 + <para>Para sobrescrever esse comportamento existe na anotação <emphasis role="BOLD">@ManagedProperty</emphasis> o atributo <emphasis>accessLevel</emphasis>.
  67 + 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>
  68 + </entry>
  69 +
  70 + <entry>
  71 + <itemizedlist>
  72 + <listitem><emphasis role="BOLD">description</emphasis>: Um texto descritivo documentando o propósito da propriedade.</listitem>
  73 + <listitem><emphasis role="BOLD">accessLevel</emphasis>: Sobrescreve o nível padrão de acesso de uma propriedade. Os valores possíveis são
  74 + 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>
  75 + </itemizedlist>
  76 + </entry>
  77 + </row>
  78 +
  79 + <row>
  80 + <entry>
  81 + <emphasis role="BOLD">@ManagedOperation</emphasis>
  82 + </entry>
  83 +
  84 + <entry>
  85 + <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>
  86 + <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
  87 + operação que, ao ser invocada, destrua todas as seções abertas no servidor e não utilizadas nos últimos 30 minutos.</para>
  88 + </entry>
  89 +
  90 + <entry>
  91 + <itemizedlist>
  92 + <listitem><emphasis role="BOLD">description</emphasis>: Um texto descritivo documentando o propósito da operação.</listitem>
  93 + <listitem><emphasis role="BOLD">type</emphasis>: Documenta o propósito da operação. <emphasis>ACTION</emphasis> informa que a operação modificará
  94 + 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>
  95 + informa que a operação modificará o sistema de alguma forma e retornará informações sobre o resultado. <emphasis>UNKNOWN</emphasis> é o padrão
  96 + e significa que o resultado da execução da operação é desconhecido.</listitem>
  97 + </itemizedlist>
  98 + </entry>
  99 + </row>
  100 +
  101 + <row>
  102 + <entry>
119 103 <emphasis role="BOLD">@OperationParameter</emphasis>
120 104 </entry>
121 105  
122 106 <entry>
123   - <para>Esta anotação opcional permite detalhar melhor parâmetros em uma operação gerenciada. O efeito desta anotação é dependente da
  107 + <para>Esta anotação opcional pode ser usada para cada parâmetro de um método anotado com <emphasis role="BOLD">@ManagedOperation</emphasis>.</para>
  108 +
  109 + <para>Ele permite detalhar melhor parâmetros em uma operação gerenciada. O efeito desta anotação é dependente da
124 110 tecnologia utilizada para comunicação entre cliente e servidor. Na maioria das tecnologias, essa anotação meramente permite ao cliente
125 111 exibir informações sobre cada parâmetro: nome, tipo e descrição.</para>
126 112 </entry>
... ... @@ -133,8 +119,8 @@
133 119 </entry>
134 120 </row>
135 121 </tbody>
136   - </informaltable>
137   - </section>
  122 + </tgroup>
  123 + </informaltable>
138 124  
139 125 </section>
140 126  
... ... @@ -151,51 +137,43 @@
151 137 por expor o número de usuários que efetuaram login no sistema.</para>
152 138  
153 139 <programlisting role="JAVA"><![CDATA[
154   - @BusinessController
155   - public class ControleAcesso{
156   -
157   - @Inject
158   - private MonitorLogin monitorLogin;
159   -
160   - public boolean efetuarLogin(String usuario , String senha){
161   -
162   - // código de login
163   -
164   - monitorLogin.setContadorLogin( monitorLogin.getContadorLogin() + 1 );
165   -
166   - }
167   -
168   - }
169   - ]]></programlisting>
  140 +@BusinessController
  141 +public class ControleAcesso{
  142 +
  143 + @Inject
  144 + private MonitorLogin monitorLogin;
  145 +
  146 + public boolean efetuarLogin(String usuario , String senha){
  147 + // código de login
  148 + monitorLogin.setContadorLogin( monitorLogin.getContadorLogin() + 1 );
  149 + }
  150 +}]]></programlisting>
170 151  
171 152 <para>Como é possível ver, classes anotadas com <emphasis>@ManagementController</emphasis> podem ser injetadas em qualquer ponto do código. Valores definidos
172 153 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á
173 154 a quantidade de logins efetuados no momento da consulta.</para>
174 155 </section>
175 156  
176   -
177   -
178 157 <section>
179 158 <title>Conectando um cliente de monitoração</title>
180 159  
181   - <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
182   - para estabelecer uma conexão com um cliente de monitoração. Para isso utiliza-se extensões do framework.</para>
  160 + <para>O <emphasis>demoiselle-core</emphasis> contém as funcionalidades necessárias para marcar aspectos monitoráveis de sua aplicação,
  161 + mas não conta com nenhum mecanismo para estabelecer uma conexão com um cliente de monitoração. Para isso utiliza-se extensões do framework.</para>
183 162  
184   - <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
185   - 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
186   - 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
187   - da Oracle.</para>
  163 + <para>A extensão padrão do framework <emphasis>Demoiselle</emphasis> responsável pela tecnologia de monitoração é a <emphasis>demoiselle-jmx</emphasis>.
  164 + Essa extensão utiliza a especificação JMX (JSR 3) e permite registrar as classes marcadas para monitoração como <emphasis>MBeans</emphasis>.
  165 + Uma vez que as classes sejam registradas como <emphasis>MBeans</emphasis>, seus atributos e operações expostos para monitoração podem ser
  166 + acessados via JMX por um cliente adequado, como o <emphasis>JConsole</emphasis> que acompanha por padrão o JDK da Oracle.</para>
188 167  
189 168 <tip>
190 169 <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>
191 170  
192 171 <programlisting role="XML"><![CDATA[
193   - <dependency>
194   - <groupId>br.gov.frameworkdemoiselle</groupId>
195   - <artifactId>demoiselle-jmx</artifactId>
196   - <scope>compile</scope>
197   - </dependency>
198   - ]]></programlisting>
  172 +<dependency>
  173 + <groupId>br.gov.frameworkdemoiselle</groupId>
  174 + <artifactId>demoiselle-jmx</artifactId>
  175 + <scope>compile</scope>
  176 +</dependency>]]></programlisting>
199 177 </tip>
200 178  
201 179 <tip>
... ... @@ -206,27 +184,27 @@
206 184 <para>A figura <xref linkend="exemplo_jconsole"/> mostra como uma classe monitorada na aplicação <emphasis>Bookmark</emphasis> é exibida no <emphasis>JConsole</emphasis>.</para>
207 185  
208 186 <programlisting role="JAVA"><![CDATA[
209   - @ManagementController
210   - public class BookmarkMonitor {
211   -
212   - @Inject
213   - private BookmarkDAO bookmarkDAO;
214   -
215   - @ManagedOperation(type=OperationType.INFO , description="Informa quantos bookmarks estão salvos no sistema")
216   - public int countSavedBookmarks(){
217   - return bookmarkDAO.findAll().size();
218   - }
219   - }
220   - ]]></programlisting>
  187 +@ManagementController
  188 +public class BookmarkMonitor {
  189 +
  190 + @Inject
  191 + private BookmarkDAO bookmarkDAO;
  192 +
  193 + @ManagedOperation(type=OperationType.INFO , description="Informa quantos bookmarks estão salvos no sistema")
  194 + public int countSavedBookmarks(){
  195 + return bookmarkDAO.findAll().size();
  196 + }
  197 +}]]></programlisting>
221 198  
222 199 <figure id="exemplo_jconsole"><title>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></title>
223 200 <mediaobject>
224 201 <imageobject>
225   - <imagedata fileref="images/jmx-jconsole-example.png"/>
  202 + <imagedata fileref="images/jmx-jconsole-example.png" width="90%" />
226 203 </imageobject>
227 204 <textobject><phrase>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></phrase></textobject>
228 205 </mediaobject>
229 206 </figure>
230 207 </section>
  208 +
231 209  
232 210 </chapter>
233 211 \ No newline at end of file
... ...
documentation/reference/pt-BR/master.xml
  Diff comments   View file @6553561
... ... @@ -5,7 +5,6 @@
5 5  
6 6 <xi:include href="bookinfo.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
7 7  
8   - <!--
9 8 <preface>
10 9 <title>Sobre o Guia de Referência</title>
11 10 <para>
... ... @@ -39,9 +38,8 @@
39 38 <xi:include href="templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
40 39 <xi:include href="security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
41 40 <xi:include href="paginacao.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
42   - -->
43 41 <xi:include href="gerenciamento.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
44   - <!-- <xi:include href="properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
  42 + <xi:include href="properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
45 43  
46 44 <!-- parte 1 -->
47 45 <!-- TODO: dividir melhor os capítulos em seções -->
... ...