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 291648c4
Showing 5 changed files with 93 additions and 42 deletions Show diff stats
documentation/reference/pt-BR/configuracao.xml
impl/core/src/main/java/br/gov/frameworkdemoiselle/internal/implementation/ConfigurationEnumValueExtractor.java
impl/core/src/test/java/configuration/field/enumeration/AbstractEnumValueConfig.java
impl/core/src/test/java/configuration/field/enumeration/ConfigurationEnumValueTest.java
impl/core/src/test/resources/configuration/field/enumeration/demoiselle.properties
@@ -160,15 +160,15 @@ public class BookmarkConfig {
 	<section>
 		<title>Especificando os parâmetros</title>
 		<para>
-			Atualmente são suportados nativamente pelo <emphasis>Demoiselle Framework</emphasis> parâmetros de cinco tipos 
-			diferentes, são eles: <emphasis>primitivo</emphasis>, <emphasis>wrapped</emphasis>, <emphasis>String</emphasis>,
-			<emphasis>class</emphasis>, <emphasis>map</emphasis> e <emphasis>array</emphasis>, sendo que os três últimos
-			são suportados a partir da versão 2.4.0. A seguir vamos explicar e exemplificar como utilizar cada um desses 
+			Atualmente são suportados nativamente pelo <emphasis>Demoiselle Framework</emphasis> parâmetros de sete categorias 
+			diferentes. São eles: tipos primitivos (<emphasis>int, float, boolean, etc</emphasis>), classes <emphasis>wrapper</emphasis> (<emphasis>Integer, Float, Boolean, etc.</emphasis>)
+			, <emphasis>String</emphasis>, <emphasis>Class</emphasis>, <emphasis>Map</emphasis>, <emphasis>Array</emphasis> e instâncias de <emphasis>Enum</emphasis>.
+			A seguir vamos explicar e exemplificar como utilizar cada um desses 
 			tipos, e alertar para as possíveis exceções que poderão ser lançadas para sua aplicação.
 		</para>
 		<caution>
 			<para>
-				A partir da versão 2.4.0 não são mais reconhecidas as convenções. Os parâmetros serão procurados exatamente
+				A partir da versão 2.4.0 não são mais reconhecidas as convenções de substituição de nomes. Os parâmetros serão procurados exatamente
 				como foram definidos na classe de configuração.
 			</para>
 		</caution>
@@ -332,58 +332,42 @@ untypedClass=package.MyOtherClass
 						<entry>
 							<para>
 								Para utilizar parâmetros do tipo <emphasis>Map</emphasis>, o arquivo de configurações deve usar a seguinte 
-								estrutura na formação da chave: <emphasis>prefixo+chavedomap+nomedoatributo</emphasis>. Vejamos um exemplo.
+								estrutura na formação da chave: <emphasis>prefixo+nomedoatributo+chavedomap</emphasis>. Vejamos um exemplo.
 								Se temos em nossa aplicação uma classe de configuração como a mostrada abaixo: 
 							</para>	 
 								<programlisting role="JAVA"><![CDATA[
 @Configuration
 public class BookmarkConfig {
  
-	private Map<String, String> url;
+	private Map<String, String> connectionConfiguration;
  
-	private Map<String, String> driverClass;
-
-	public Map<String, String> getUrl() {
-		return url;
-	}
-	
-	public Map<String, String> DriverClass() {
-		return driverClass;
+	public Map<String, String> getConnectionConfiguration() {
+		return connectionConfiguration;
 	}
 }
 								]]></programlisting> 
 								<para>
-									O arquivo de configuração deverá ser preenchido no formato seguinte (se for do tipo <emphasis>properties</emphasis>):
+									O arquivo de configuração deverá ser preenchido no seguinte formato (se for do tipo <emphasis>properties</emphasis>):
 								</para>
-								<programlisting role="PROPERTIES"><![CDATA[
-mapkey1.url=jdbc:postgresql://localhost:5432/app
-mapkey2.url=jdbc:mysql://localhost:3306/app
-mapkey1.driverClass=org.postgresql.Driver
-mapkey2.driverClass=com.mysql.Driver
-								]]></programlisting>
+								<programlisting role="PROPERTIES"><![CDATA[connectionConfiguration.ip=192.168.0.120
+connectionConfiguration.gateway=192.168.0.1
+connectionConfiguration.dns1=200.10.128.99
+connectionConfiguration.dns2=200.10.128.88]]></programlisting>
 							<para>
-								Dessa forma, ao fazer a chamada <emphasis>url.get("mapkey2");</emphasis>por exemplo, o valor retornado será 
-								<emphasis>jdbc:mysql://localhost:3306/app</emphasis>.
+								Dessa forma, ao fazer a chamada <emphasis>connectionConfiguration.get("gateway");</emphasis> por exemplo, o valor retornado será 
+								<emphasis>192.168.0.1</emphasis>.
 							</para>
-							<note>
-								<para>
-									O ponto entre a chave do <emphasis>Map</emphasis> e o nome do parâmetro é adicionado automaticamente pelo 
-									framework. 
-								</para>
-							</note>
+
 							<tip>
 								<para>
 									Você pode utilizar a chave do Map com nome "default" para indicar que, no arquivo de configuração, a chave é formada
-									apenas pela junção do prefixo com o atributo, sem utilizar a própria chave do Map. Por exemplo, se na sua classe 
-									existir um comando como este:
-								</para> 
-					    		<programlisting role="JAVA"><![CDATA[
-									myMap.get("default");
-								]]></programlisting>
-								<para>o framework irá procurar no arquivo de configuração uma linha como esta:</para>
-								<programlisting role="JAVA"><![CDATA[
-									prefix.myMap=Default Value
-								]]></programlisting>
+									apenas pela junção do prefixo com o atributo, sem utilizar a própria chave do Map. Por exemplo, se o seu arquivo de propriedades
+									contiver uma chave:
+								</para>
+								<programlisting role="JAVA"><![CDATA[prefix.myMap=Default Value]]></programlisting>
+								<para>então seu código poderá ter um comando:</para>
+					    		<programlisting role="JAVA"><![CDATA[String value = myMap.get("default");]]></programlisting>
+					    		<para>e o valor de <emphasis>value</emphasis> será <emphasis>"Default Value"</emphasis>.</para>
 							</tip>
 							<para>
 								Caso a classe de configuração não esteja associada a um arquivo que contenha a chave de um de seus parâmetros
@@ -427,7 +411,66 @@ integerArray=1
 					</row>
 				</tbody>
 			</tgroup>
-		</informaltable>		
+		</informaltable>
+		
+		<informaltable>
+			<tgroup cols="1">
+				<colspec colwidth="100*" />
+				<tbody>
+					<row>
+						<entry>
+							<emphasis role="bold">Enum</emphasis>
+						</entry>
+					</row>
+					<row>
+						<entry>
+							<para>
+								É possível criar uma lista de constantes do tipo <emphasis>Enum</emphasis> e carregar um valor de constante
+								através de um arquivo de configuração. Por exemplo, caso exista o seguinte <emphasis>Enum</emphasis>
+							</para>
+							
+							<programlisting role="JAVA"><![CDATA[public enum ConfigurationType {
+	
+	PROPERTIES , XML , SYSTEM;
+
+}]]></programlisting>
+
+							<para>e ele seja usado no seguinte arquivo de configuração</para>
+							
+							<programlisting role="JAVA"><![CDATA[@Configuration
+public class ConfigurationLoader {
+	
+	private ConfigurationType loadedConfigurationType;
+	
+	public ConfigurationType getLoadedConfigurationType(){
+		return loadedConfigurationType;
+	}
+}]]></programlisting>
+							
+							<para>O arquivo do tipo <emphasis>properties</emphasis> pode ser criado assim:</para>
+							
+							<programlisting role="PROPERTIES"><![CDATA[loadedConfigurationType=SYSTEM]]></programlisting>
+							
+							<note>
+								<para>
+									O valor definido no arquivo de configuração para atributos do tipo <emphasis>Enum</emphasis> deve
+									ser idêntico ao nome da constante definida no <emphasis>Enum</emphasis>, inclusive casando letras maiúsculas e
+									minúsculas. De fato, o valor da propriedade deve casar com o valor retornado no código:
+									<emphasis>Enum.name()</emphasis>.
+								</para>
+								
+								<para>
+									Caso o valor definido no arquivo de configuração não case com nenhuma constante definida no <emphasis>Enum</emphasis>,
+									uma exceção de tipo <emphasis>ConfigurationException</emphasis> de causa <emphasis>ConversionException</emphasis>
+									será lançada. Já se à propriedade for atribuido um valor vazio, o atributo do tipo <emphasis>Enum</emphasis> receberá
+									o valor <emphasis>null</emphasis>. 
+								</para>
+							</note>
+						</entry>
+					</row>
+				</tbody>
+			</tgroup>
+		</informaltable>
  
 	</section>
  
@@ -58,7 +58,7 @@ public class ConfigurationEnumValueExtractor implements ConfigurationValueExtrac
 	public Object getValue(String prefix, String key, Field field, Configuration configuration) throws Exception {
 		String value = configuration.getString(prefix + key);
  
-		if (value!=null){
+		if (value!=null && !value.trim().equals("")){
 			Object enums[] = field.getType().getEnumConstants();
  
 			for (int i=0; i<enums.length; i++){
@@ -46,6 +46,8 @@ public abstract class AbstractEnumValueConfig implements Serializable {
  
 	private ListOfEnum anotherValue;
  
+	private ListOfEnum emptyValue;
+	
 	public ListOfEnum getEnumValue() {
 		return enumValue;
 	}
@@ -53,4 +55,8 @@ public abstract class AbstractEnumValueConfig implements Serializable {
 	public ListOfEnum getAnotherValue() {
 		return anotherValue;
 	}
+
+	public ListOfEnum getEmptyValue() {
+		return emptyValue;
+	}
 }
@@ -74,6 +74,7 @@ public class ConfigurationEnumValueTest {
 	public void loadEnumConfig(){
 		Assert.assertEquals(ListOfEnum.VALUE_2, propertiesEnumConfig.getEnumValue());
 		Assert.assertEquals(ListOfEnum.VALUE_2, xmlEnumConfig.getEnumValue());
+		Assert.assertNull(propertiesEnumConfig.getEmptyValue());
 	}
  
 	@Test(expected=ConfigurationException.class)
@@ -34,4 +34,5 @@
 # 51 Franklin St, Fifth Floor, Boston, MA 02111-1301, USA.
  
 prefix1.enumValue=VALUE_2
+prefix1.emptyValue=
 prefix2.anotherValue=value_2
...	...	@@ -160,15 +160,15 @@ public class BookmarkConfig {
160	160	<section>
161	161	<title>Especificando os parâmetros</title>
162	162	<para>
163		- Atualmente são suportados nativamente pelo <emphasis>Demoiselle Framework</emphasis> parâmetros de cinco tipos
164		- diferentes, são eles: <emphasis>primitivo</emphasis>, <emphasis>wrapped</emphasis>, <emphasis>String</emphasis>,
165		- <emphasis>class</emphasis>, <emphasis>map</emphasis> e <emphasis>array</emphasis>, sendo que os três últimos
166		- são suportados a partir da versão 2.4.0. A seguir vamos explicar e exemplificar como utilizar cada um desses
	163	+ Atualmente são suportados nativamente pelo <emphasis>Demoiselle Framework</emphasis> parâmetros de sete categorias
	164	+ diferentes. São eles: tipos primitivos (<emphasis>int, float, boolean, etc</emphasis>), classes <emphasis>wrapper</emphasis> (<emphasis>Integer, Float, Boolean, etc.</emphasis>)
	165	+ , <emphasis>String</emphasis>, <emphasis>Class</emphasis>, <emphasis>Map</emphasis>, <emphasis>Array</emphasis> e instâncias de <emphasis>Enum</emphasis>.
	166	+ A seguir vamos explicar e exemplificar como utilizar cada um desses
167	167	tipos, e alertar para as possíveis exceções que poderão ser lançadas para sua aplicação.
168	168	</para>
169	169	<caution>
170	170	<para>
171		- A partir da versão 2.4.0 não são mais reconhecidas as convenções. Os parâmetros serão procurados exatamente
	171	+ A partir da versão 2.4.0 não são mais reconhecidas as convenções de substituição de nomes. Os parâmetros serão procurados exatamente
172	172	como foram definidos na classe de configuração.
173	173	</para>
174	174	</caution>
...	...	@@ -332,58 +332,42 @@ untypedClass=package.MyOtherClass
332	332	<entry>
333	333	<para>
334	334	Para utilizar parâmetros do tipo <emphasis>Map</emphasis>, o arquivo de configurações deve usar a seguinte
335		- estrutura na formação da chave: <emphasis>prefixo+chavedomap+nomedoatributo</emphasis>. Vejamos um exemplo.
	335	+ estrutura na formação da chave: <emphasis>prefixo+nomedoatributo+chavedomap</emphasis>. Vejamos um exemplo.
336	336	Se temos em nossa aplicação uma classe de configuração como a mostrada abaixo:
337	337	</para>
338	338	<programlisting role="JAVA"><![CDATA[
339	339	@Configuration
340	340	public class BookmarkConfig {
341	341
342		- private Map<String, String> url;
	342	+ private Map<String, String> connectionConfiguration;
343	343
344		- private Map<String, String> driverClass;
345		-
346		- public Map<String, String> getUrl() {
347		- return url;
348		- }
349		-
350		- public Map<String, String> DriverClass() {
351		- return driverClass;
	344	+ public Map<String, String> getConnectionConfiguration() {
	345	+ return connectionConfiguration;
352	346	}
353	347	}
354	348	]]></programlisting>
355	349	<para>
356		- O arquivo de configuração deverá ser preenchido no formato seguinte (se for do tipo <emphasis>properties</emphasis>):
	350	+ O arquivo de configuração deverá ser preenchido no seguinte formato (se for do tipo <emphasis>properties</emphasis>):
357	351	</para>
358		- <programlisting role="PROPERTIES"><![CDATA[
359		-mapkey1.url=jdbc:postgresql://localhost:5432/app
360		-mapkey2.url=jdbc:mysql://localhost:3306/app
361		-mapkey1.driverClass=org.postgresql.Driver
362		-mapkey2.driverClass=com.mysql.Driver
363		- ]]></programlisting>
	352	+ <programlisting role="PROPERTIES"><![CDATA[connectionConfiguration.ip=192.168.0.120
	353	+connectionConfiguration.gateway=192.168.0.1
	354	+connectionConfiguration.dns1=200.10.128.99
	355	+connectionConfiguration.dns2=200.10.128.88]]></programlisting>
364	356	<para>
365		- Dessa forma, ao fazer a chamada <emphasis>url.get("mapkey2");</emphasis>por exemplo, o valor retornado será
366		- <emphasis>jdbc:mysql://localhost:3306/app</emphasis>.
	357	+ Dessa forma, ao fazer a chamada <emphasis>connectionConfiguration.get("gateway");</emphasis> por exemplo, o valor retornado será
	358	+ <emphasis>192.168.0.1</emphasis>.
367	359	</para>
368		- <note>
369		- <para>
370		- O ponto entre a chave do <emphasis>Map</emphasis> e o nome do parâmetro é adicionado automaticamente pelo
371		- framework.
372		- </para>
373		- </note>
	360	+
374	361	<tip>
375	362	<para>
376	363	Você pode utilizar a chave do Map com nome "default" para indicar que, no arquivo de configuração, a chave é formada
377		- apenas pela junção do prefixo com o atributo, sem utilizar a própria chave do Map. Por exemplo, se na sua classe
378		- existir um comando como este:
379		- </para>
380		- <programlisting role="JAVA"><![CDATA[
381		- myMap.get("default");
382		- ]]></programlisting>
383		- <para>o framework irá procurar no arquivo de configuração uma linha como esta:</para>
384		- <programlisting role="JAVA"><![CDATA[
385		- prefix.myMap=Default Value
386		- ]]></programlisting>
	364	+ apenas pela junção do prefixo com o atributo, sem utilizar a própria chave do Map. Por exemplo, se o seu arquivo de propriedades
	365	+ contiver uma chave:
	366	+ </para>
	367	+ <programlisting role="JAVA"><![CDATA[prefix.myMap=Default Value]]></programlisting>
	368	+ <para>então seu código poderá ter um comando:</para>
	369	+ <programlisting role="JAVA"><![CDATA[String value = myMap.get("default");]]></programlisting>
	370	+ <para>e o valor de <emphasis>value</emphasis> será <emphasis>"Default Value"</emphasis>.</para>
387	371	</tip>
388	372	<para>
389	373	Caso a classe de configuração não esteja associada a um arquivo que contenha a chave de um de seus parâmetros
...	...	@@ -427,7 +411,66 @@ integerArray=1
427	411	</row>
428	412	</tbody>
429	413	</tgroup>
430		- </informaltable>
	414	+ </informaltable>
	415	+
	416	+ <informaltable>
	417	+ <tgroup cols="1">
	418	+ <colspec colwidth="100*" />
	419	+ <tbody>
	420	+ <row>
	421	+ <entry>
	422	+ <emphasis role="bold">Enum</emphasis>
	423	+ </entry>
	424	+ </row>
	425	+ <row>
	426	+ <entry>
	427	+ <para>
	428	+ É possível criar uma lista de constantes do tipo <emphasis>Enum</emphasis> e carregar um valor de constante
	429	+ através de um arquivo de configuração. Por exemplo, caso exista o seguinte <emphasis>Enum</emphasis>
	430	+ </para>
	431	+
	432	+ <programlisting role="JAVA"><![CDATA[public enum ConfigurationType {
	433	+
	434	+ PROPERTIES , XML , SYSTEM;
	435	+
	436	+}]]></programlisting>
	437	+
	438	+ <para>e ele seja usado no seguinte arquivo de configuração</para>
	439	+
	440	+ <programlisting role="JAVA"><![CDATA[@Configuration
	441	+public class ConfigurationLoader {
	442	+
	443	+ private ConfigurationType loadedConfigurationType;
	444	+
	445	+ public ConfigurationType getLoadedConfigurationType(){
	446	+ return loadedConfigurationType;
	447	+ }
	448	+}]]></programlisting>
	449	+
	450	+ <para>O arquivo do tipo <emphasis>properties</emphasis> pode ser criado assim:</para>
	451	+
	452	+ <programlisting role="PROPERTIES"><![CDATA[loadedConfigurationType=SYSTEM]]></programlisting>
	453	+
	454	+ <note>
	455	+ <para>
	456	+ O valor definido no arquivo de configuração para atributos do tipo <emphasis>Enum</emphasis> deve
	457	+ ser idêntico ao nome da constante definida no <emphasis>Enum</emphasis>, inclusive casando letras maiúsculas e
	458	+ minúsculas. De fato, o valor da propriedade deve casar com o valor retornado no código:
	459	+ <emphasis>Enum.name()</emphasis>.
	460	+ </para>
	461	+
	462	+ <para>
	463	+ Caso o valor definido no arquivo de configuração não case com nenhuma constante definida no <emphasis>Enum</emphasis>,
	464	+ uma exceção de tipo <emphasis>ConfigurationException</emphasis> de causa <emphasis>ConversionException</emphasis>
	465	+ será lançada. Já se à propriedade for atribuido um valor vazio, o atributo do tipo <emphasis>Enum</emphasis> receberá
	466	+ o valor <emphasis>null</emphasis>.
	467	+ </para>
	468	+ </note>
	469	+ </entry>
	470	+ </row>
	471	+ </tbody>
	472	+ </tgroup>
	473	+ </informaltable>
431	474
432	475	</section>
433	476
...	...
...	...	@@ -58,7 +58,7 @@ public class ConfigurationEnumValueExtractor implements ConfigurationValueExtrac
58	58	public Object getValue(String prefix, String key, Field field, Configuration configuration) throws Exception {
59	59	String value = configuration.getString(prefix + key);
60	60
61		- if (value!=null){
	61	+ if (value!=null && !value.trim().equals("")){
62	62	Object enums[] = field.getType().getEnumConstants();
63	63
64	64	for (int i=0; i<enums.length; i++){
...	...
...	...	@@ -46,6 +46,8 @@ public abstract class AbstractEnumValueConfig implements Serializable {
46	46
47	47	private ListOfEnum anotherValue;
48	48
	49	+ private ListOfEnum emptyValue;
	50	+
49	51	public ListOfEnum getEnumValue() {
50	52	return enumValue;
51	53	}
...	...	@@ -53,4 +55,8 @@ public abstract class AbstractEnumValueConfig implements Serializable {
53	55	public ListOfEnum getAnotherValue() {
54	56	return anotherValue;
55	57	}
	58	+
	59	+ public ListOfEnum getEmptyValue() {
	60	+ return emptyValue;
	61	+ }
56	62	}
...	...
...	...	@@ -74,6 +74,7 @@ public class ConfigurationEnumValueTest {
74	74	public void loadEnumConfig(){
75	75	Assert.assertEquals(ListOfEnum.VALUE_2, propertiesEnumConfig.getEnumValue());
76	76	Assert.assertEquals(ListOfEnum.VALUE_2, xmlEnumConfig.getEnumValue());
	77	+ Assert.assertNull(propertiesEnumConfig.getEmptyValue());
77	78	}
78	79
79	80	@Test(expected=ConfigurationException.class)
...	...
...	...	@@ -34,4 +34,5 @@
34	34	# 51 Franklin St, Fifth Floor, Boston, MA 02111-1301, USA.
35	35
36	36	prefix1.enumValue=VALUE_2
	37	+prefix1.emptyValue=
37	38	prefix2.anotherValue=value_2
...	...