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,8 +24,6 @@
24 uso o desenvolvedor pode se despreocupar com detalhes de implementação de cada tecnologia individual e facilmente integrar tais tecnologias.</para> 24 uso o desenvolvedor pode se despreocupar com detalhes de implementação de cada tecnologia individual e facilmente integrar tais tecnologias.</para>
25 </section> 25 </section>
26 26
27 -  
28 -  
29 <section> 27 <section>
30 <title>Introdução ao mecanismo</title> 28 <title>Introdução ao mecanismo</title>
31 29
@@ -34,77 +32,18 @@ @@ -34,77 +32,18 @@
34 anotada com o estereótipo <code>@ManagementController</code>.</para> 32 anotada com o estereótipo <code>@ManagementController</code>.</para>
35 33
36 <programlisting role="JAVA"><![CDATA[ 34 <programlisting role="JAVA"><![CDATA[
37 - @ManagementController  
38 - public class GerenciadorUsuarios]]></programlisting> 35 +@ManagementController
  36 +public class GerenciadorUsuarios]]></programlisting>
39 37
40 <para>Essa anotação é suficiente para o mecanismo de gerenciamento descobrir sua classe e disponibiliza-la para ser monitorada e gerenciada.</para> 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 <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> 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 <informaltable> 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 <thead> 47 <thead>
109 <row> 48 <row>
110 <entry>Anotação</entry> 49 <entry>Anotação</entry>
@@ -112,15 +51,62 @@ @@ -112,15 +51,62 @@
112 <entry>Atributos</entry> 51 <entry>Atributos</entry>
113 </row> 52 </row>
114 </thead> 53 </thead>
115 - 54 +
116 <tbody> 55 <tbody>
117 <row> 56 <row>
118 <entry> 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 <emphasis role="BOLD">@OperationParameter</emphasis> 103 <emphasis role="BOLD">@OperationParameter</emphasis>
120 </entry> 104 </entry>
121 105
122 <entry> 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 tecnologia utilizada para comunicação entre cliente e servidor. Na maioria das tecnologias, essa anotação meramente permite ao cliente 110 tecnologia utilizada para comunicação entre cliente e servidor. Na maioria das tecnologias, essa anotação meramente permite ao cliente
125 exibir informações sobre cada parâmetro: nome, tipo e descrição.</para> 111 exibir informações sobre cada parâmetro: nome, tipo e descrição.</para>
126 </entry> 112 </entry>
@@ -133,8 +119,8 @@ @@ -133,8 +119,8 @@
133 </entry> 119 </entry>
134 </row> 120 </row>
135 </tbody> 121 </tbody>
136 - </informaltable>  
137 - </section> 122 + </tgroup>
  123 + </informaltable>
138 124
139 </section> 125 </section>
140 126
@@ -151,51 +137,43 @@ @@ -151,51 +137,43 @@
151 por expor o número de usuários que efetuaram login no sistema.</para> 137 por expor o número de usuários que efetuaram login no sistema.</para>
152 138
153 <programlisting role="JAVA"><![CDATA[ 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 <para>Como é possível ver, classes anotadas com <emphasis>@ManagementController</emphasis> podem ser injetadas em qualquer ponto do código. Valores definidos 152 <para>Como é possível ver, classes anotadas com <emphasis>@ManagementController</emphasis> podem ser injetadas em qualquer ponto do código. Valores definidos
172 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á 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 a quantidade de logins efetuados no momento da consulta.</para> 154 a quantidade de logins efetuados no momento da consulta.</para>
174 </section> 155 </section>
175 156
176 -  
177 -  
178 <section> 157 <section>
179 <title>Conectando um cliente de monitoração</title> 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 <tip> 168 <tip>
190 <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> 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 <programlisting role="XML"><![CDATA[ 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 </tip> 177 </tip>
200 178
201 <tip> 179 <tip>
@@ -206,27 +184,27 @@ @@ -206,27 +184,27 @@
206 <para>A figura <xref linkend="exemplo_jconsole"/> mostra como uma classe monitorada na aplicação <emphasis>Bookmark</emphasis> é exibida no <emphasis>JConsole</emphasis>.</para> 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 <programlisting role="JAVA"><![CDATA[ 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 <figure id="exemplo_jconsole"><title>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></title> 199 <figure id="exemplo_jconsole"><title>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></title>
223 <mediaobject> 200 <mediaobject>
224 <imageobject> 201 <imageobject>
225 - <imagedata fileref="images/jmx-jconsole-example.png"/> 202 + <imagedata fileref="images/jmx-jconsole-example.png" width="90%" />
226 </imageobject> 203 </imageobject>
227 <textobject><phrase>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></phrase></textobject> 204 <textobject><phrase>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></phrase></textobject>
228 </mediaobject> 205 </mediaobject>
229 </figure> 206 </figure>
230 </section> 207 </section>
  208 +
231 209
232 </chapter> 210 </chapter>
233 \ No newline at end of file 211 \ No newline at end of file
documentation/reference/pt-BR/master.xml
  Diff comments   View file @6553561
@@ -5,7 +5,6 @@ @@ -5,7 +5,6 @@
5 5
6 <xi:include href="bookinfo.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> 6 <xi:include href="bookinfo.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
7 7
8 - <!--  
9 <preface> 8 <preface>
10 <title>Sobre o Guia de Referência</title> 9 <title>Sobre o Guia de Referência</title>
11 <para> 10 <para>
@@ -39,9 +38,8 @@ @@ -39,9 +38,8 @@
39 <xi:include href="templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> 38 <xi:include href="templates.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
40 <xi:include href="security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> 39 <xi:include href="security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
41 <xi:include href="paginacao.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> 40 <xi:include href="paginacao.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
42 - -->  
43 <xi:include href="gerenciamento.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> 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 <!-- parte 1 --> 44 <!-- parte 1 -->
47 <!-- TODO: dividir melhor os capítulos em seções --> 45 <!-- TODO: dividir melhor os capítulos em seções -->