IN PROGRESS - issue FWK-123: Revisar e atualizar documentação do

Framework 2.4.0 https://demoiselle.atlassian.net/browse/FWK-123

IN PROGRESS - issue FWK-123: Revisar e atualizar documentação do
Framework 2.4.0 https://demoiselle.atlassian.net/browse/FWK-123
Dancovich
1 parent 605c06cd
Showing 2 changed files with 70 additions and 11 deletions Show diff stats
documentation/reference/pt-BR/gerenciamento.xml
documentation/reference/pt-BR/images/jmx-jconsole-example.png
@@ -171,6 +171,50 @@ public class MonitorLogin{
 		<para>Como é possível ver, classes anotadas com <emphasis>@ManagementController</emphasis> podem ser injetadas em qualquer ponto do código. Valores definidos
 		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á
 		a quantidade de logins efetuados no momento da consulta.</para>
+		
+		<section>
+			<title>Enviando notificações da aplicação</title>
+			
+			<para>
+				É comum que aplicações monitoradas permaneçam em estado de espera - é função do cliente de monitoração acessar a aplicação e obter
+				as informações necessárias.
+			</para>
+			
+			<para>
+				No entanto existem casos onde é necessário que a aplicação comunique clientes de eventos ocorridos no sistema. Um exemplo é um monitor
+				de espaço em disco que envia um alerta quando esse espaço for menor que 20% do total. 
+			</para>
+			
+			<para>
+				Para essa funcionalidade o <emphasis>Demoiselle Framework</emphasis> disponibiliza o utilitário <emphasis>NotificationManager</emphasis>, que
+				pode ser injetado em sua aplicação a qualquer momento para notificar clientes externos de eventos importantes. 
+			</para>
+			
+			<para>Considere o exemplo abaixo:</para>
+			
+			<programlisting role="JAVA"><![CDATA[
+public class DiskWritter{
+
+  @Inject
+  private NotificationManager notificationManager;
+
+  public void writeFile(byte[] data , File fileToWrite){
+    // ... implementação da escrita de arquivo
+    
+    if (fileToWrite.getUsableSpace() / (float)fileToWrite.getTotalSpace() <= 0.2f){
+    	Notification notification = new GenericNotification("O espaço disponível no disco é inferior a 20% do total");
+    	notificationManager.sendNotification( notification );
+    }
+  }
+}]]></programlisting>
+
+			<para>
+				Nesse exemplo podemos ver como enviar uma notificação em decorrência de um evento gerado pela aplicação. Dessa forma
+				a aplicação pode comunicar a um agente de monitoração sobre o espaço disponível no disco, ao invés de aguardar que o agente
+				conecte-se à aplicação para solicitar essa informação explicitamente.
+			</para>
+		</section>
+		
 	</section>
  
 	<section>
@@ -200,22 +244,22 @@ public class MonitorLogin{
 			individualmente, as classes monitoradas serão então expostas para todas as extensões escolhidas.</para>
 		</tip>
  
-		<para>A figura <xref linkend="exemplo_jconsole" /> mostra como uma classe monitorada na aplicação <emphasis>Bookmark</emphasis> é exibida no <emphasis>JConsole</emphasis>.</para>
+		<para>A figura <xref linkend="exemplo_jconsole" /> mostra como uma classe monitorada é exibida no <emphasis>JConsole</emphasis>.</para>
  
-		<programlisting role="JAVA"><![CDATA[
-@ManagementController
-public class BookmarkMonitor {
+		<programlisting role="JAVA"><![CDATA[@ManagementController
+public class HelloWorldManager {
+	
+	@Inject
+	private HelloWorld helloWorld;
  
-  @Inject
-  private BookmarkDAO bookmarkDAO;
+	@ManagedOperation(type=OperationType.ACTION)
+	public void saySomething(String whatToSay){
+		helloWorld.say(whatToSay);
+	}
  
-  @ManagedOperation(type=OperationType.INFO , description="Informa quantos bookmarks estao salvos no sistema")
-  public int countSavedBookmarks(){
-      return bookmarkDAO.findAll().size();
-  }
 }]]></programlisting>
  
-		<figure id="exemplo_jconsole"><title>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></title>
+		<figure id="exemplo_jconsole"><title>JConsole acessando uma aplicação monitorada</title>
 			<mediaobject>
 				<imageobject>
 					<imagedata fileref="images/jmx-jconsole-example.png" width="90%" />
@@ -223,6 +267,21 @@ public class BookmarkMonitor {
 				<textobject><phrase>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></phrase></textobject>
 			</mediaobject>
 		</figure>
+		
+		<para>
+			É possível perceber os seguintes elementos nessa imagem:
+			<itemizedlist>
+				<listitem>Uma classe gerenciada <emphasis>HelloWorldManager</emphasis> com uma operação chamada <emphasis>saySomething</emphasis></listitem>
+				<listitem>Uma classe geradora de notificações <emphasis>NotificationBroadcaster</emphasis> responsável por converter as notificações para a API JMX</listitem>
+			</itemizedlist>
+		</para>
+		
+		<para>
+			Através do <emphasis>JConsole</emphasis> é possível invocar comandos e acessar atributos em todas as classes anotadas com <emphasis>@ManagementController</emphasis>
+			em aplicações que usam o <emphasis>demoiselle-jmx</emphasis>. Também é possível inscrever-se às notificações enviadas por <emphasis>NotificationBroadcaster</emphasis>
+			e receber todas as notificações enviadas pela aplicação.
+		</para>
+		
 	</section>
...	...	@@ -171,6 +171,50 @@ public class MonitorLogin{
171	171	<para>Como é possível ver, classes anotadas com <emphasis>@ManagementController</emphasis> podem ser injetadas em qualquer ponto do código. Valores definidos
172	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á
173	173	a quantidade de logins efetuados no momento da consulta.</para>
	174	+
	175	+ <section>
	176	+ <title>Enviando notificações da aplicação</title>
	177	+
	178	+ <para>
	179	+ É comum que aplicações monitoradas permaneçam em estado de espera - é função do cliente de monitoração acessar a aplicação e obter
	180	+ as informações necessárias.
	181	+ </para>
	182	+
	183	+ <para>
	184	+ No entanto existem casos onde é necessário que a aplicação comunique clientes de eventos ocorridos no sistema. Um exemplo é um monitor
	185	+ de espaço em disco que envia um alerta quando esse espaço for menor que 20% do total.
	186	+ </para>
	187	+
	188	+ <para>
	189	+ Para essa funcionalidade o <emphasis>Demoiselle Framework</emphasis> disponibiliza o utilitário <emphasis>NotificationManager</emphasis>, que
	190	+ pode ser injetado em sua aplicação a qualquer momento para notificar clientes externos de eventos importantes.
	191	+ </para>
	192	+
	193	+ <para>Considere o exemplo abaixo:</para>
	194	+
	195	+ <programlisting role="JAVA"><![CDATA[
	196	+public class DiskWritter{
	197	+
	198	+ @Inject
	199	+ private NotificationManager notificationManager;
	200	+
	201	+ public void writeFile(byte[] data , File fileToWrite){
	202	+ // ... implementação da escrita de arquivo
	203	+
	204	+ if (fileToWrite.getUsableSpace() / (float)fileToWrite.getTotalSpace() <= 0.2f){
	205	+ Notification notification = new GenericNotification("O espaço disponível no disco é inferior a 20% do total");
	206	+ notificationManager.sendNotification( notification );
	207	+ }
	208	+ }
	209	+}]]></programlisting>
	210	+
	211	+ <para>
	212	+ Nesse exemplo podemos ver como enviar uma notificação em decorrência de um evento gerado pela aplicação. Dessa forma
	213	+ a aplicação pode comunicar a um agente de monitoração sobre o espaço disponível no disco, ao invés de aguardar que o agente
	214	+ conecte-se à aplicação para solicitar essa informação explicitamente.
	215	+ </para>
	216	+ </section>
	217	+
174	218	</section>
175	219
176	220	<section>
...	...	@@ -200,22 +244,22 @@ public class MonitorLogin{
200	244	individualmente, as classes monitoradas serão então expostas para todas as extensões escolhidas.</para>
201	245	</tip>
202	246
203		- <para>A figura <xref linkend="exemplo_jconsole" /> mostra como uma classe monitorada na aplicação <emphasis>Bookmark</emphasis> é exibida no <emphasis>JConsole</emphasis>.</para>
	247	+ <para>A figura <xref linkend="exemplo_jconsole" /> mostra como uma classe monitorada é exibida no <emphasis>JConsole</emphasis>.</para>
204	248
205		- <programlisting role="JAVA"><![CDATA[
206		-@ManagementController
207		-public class BookmarkMonitor {
	249	+ <programlisting role="JAVA"><![CDATA[@ManagementController
	250	+public class HelloWorldManager {
	251	+
	252	+ @Inject
	253	+ private HelloWorld helloWorld;
208	254
209		- @Inject
210		- private BookmarkDAO bookmarkDAO;
	255	+ @ManagedOperation(type=OperationType.ACTION)
	256	+ public void saySomething(String whatToSay){
	257	+ helloWorld.say(whatToSay);
	258	+ }
211	259
212		- @ManagedOperation(type=OperationType.INFO , description="Informa quantos bookmarks estao salvos no sistema")
213		- public int countSavedBookmarks(){
214		- return bookmarkDAO.findAll().size();
215		- }
216	260	}]]></programlisting>
217	261
218		- <figure id="exemplo_jconsole"><title>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></title>
	262	+ <figure id="exemplo_jconsole"><title>JConsole acessando uma aplicação monitorada</title>
219	263	<mediaobject>
220	264	<imageobject>
221	265	<imagedata fileref="images/jmx-jconsole-example.png" width="90%" />
...	...	@@ -223,6 +267,21 @@ public class BookmarkMonitor {
223	267	<textobject><phrase>JConsole acessando a aplicação <emphasis>Bookmark</emphasis></phrase></textobject>
224	268	</mediaobject>
225	269	</figure>
	270	+
	271	+ <para>
	272	+ É possível perceber os seguintes elementos nessa imagem:
	273	+ <itemizedlist>
	274	+ <listitem>Uma classe gerenciada <emphasis>HelloWorldManager</emphasis> com uma operação chamada <emphasis>saySomething</emphasis></listitem>
	275	+ <listitem>Uma classe geradora de notificações <emphasis>NotificationBroadcaster</emphasis> responsável por converter as notificações para a API JMX</listitem>
	276	+ </itemizedlist>
	277	+ </para>
	278	+
	279	+ <para>
	280	+ Através do <emphasis>JConsole</emphasis> é possível invocar comandos e acessar atributos em todas as classes anotadas com <emphasis>@ManagementController</emphasis>
	281	+ em aplicações que usam o <emphasis>demoiselle-jmx</emphasis>. Também é possível inscrever-se às notificações enviadas por <emphasis>NotificationBroadcaster</emphasis>
	282	+ e receber todas as notificações enviadas pela aplicação.
	283	+ </para>
	284	+
226	285	</section>
227	286
228	287
...	...