MeasureRuler

O MeasureRuler é, pela própria tradução, uma régua de medidas. Essa régua de medidas tem a intenção de oferecer aos sistemas a facilidade para converter unidades de medidas da mesma dimensão, ou até mesmo entre dimensões diferentes quando estabelecida a regra de conversão.

Definições:

• Dimensão - tipo de medida utiliza, como "Comprimento", "Área", "Volume", "Massa (Peso)", etc. Embora estas hoje sejam as dimensões que o BIS suporta, nada impede de se criar dimensões menos usuais como "Energia", "Luminosidade", "Torque", etc..
• Unidade de Medida - Unidade de medida utilizada para medir a Dimensão desejada. Por exemplo, comprimento pode ser medido em "Metros", "Centimetros", "Pés", "Polegadas", etc. "Massa" pode ser medida em "Arrobas", "Kilos", "Pounds", etc.

A classe MeasureRuler apresenta diversos métodos para conversão de forma. Para mais informações sobre eles consulte o JavaDoc da classe.

MeasureUnit

O MeasureRuler suporta várias dimensões de medidas. Cada dimensão pode conter várias unidades de medidas. A dimensão é definida pela enumeration MeasureDimension. Já as unidades de cada unidade de medida são definidas pela sua própria enumeration que estendem a interface MeasureUnit. Por exemplo:

• Volume - VolumeUnit
• Comprimento - LengthUnit
• Área - AreaUnit
• Massa (peso) - WeightUnit
• Unidades - UnitUnit

Interface MeasureUnit

Cada dimensão tem suas unidades de medidas em enumerations próprias. Assim, quando precisamos representar qualquer uma das unidades de medida utilizamos essa interface. Um exemplo: ao cadastrar um produto no sistema, a "unidade básica de estoque" dele pode ser tanto Unidades, quando Metros, Kilos, Metros Quadrados, etc.. Assim, a melhor maneira de definir este atributo no VO é através desta interface.

A interface MeasureUnit apresenta métodos como getDimension(), que retorna a enumeration de MeasureDimension para indicar que Dimensão de Medida esta Unidade pertence.

Persistência da Interface MeasureUnit

MeasureUnitDAOConverter (RFWDAO)

Por tratar-se de uma enumeration, o padrão do FrameWork é que no banco seja um campo do tipo varchar(50) (O limite recomendado de enums no RFW é de 50 chars). Mas, uma vez que a MeasureUnit é uma interface, o RFWDAO não sabe como proceder para persisti-la e reconstruir o VO com os dados do banco. Para isso temos de utilizar uma RFWDAOConverter. E para simplificar, o MeasureRuler já oferece uma implementação pronta para isso a MeasureUnitDAOConverter.

Classe Disponível no RFW.DAO Apesar do Measure ser disponibilizado no RFW.Kernel, as classes de persistência e conversão estão disponibilizadas apenas no módulo RFW.DAO, afinal essas classes só fazem sentido em conjunto com o RFW.

Para definir um atributo no VO que seja do tipo MeasureUnit devemos ter algo como:

	Exemplos de Declaração
	@BISDAOConverter(converterClass = MeasureUnitDAOConverter.class) @BISMetaGenericField(caption = "Unidade de Medida", required = true) private MeasureUnit measureUnit = null;

Sempre que o RFWDAO ler a String no banco de dados que representa a unidade de medida, o Converter conseguirá descobrir de qual enumeration devemos realizar o "valueOf(...)".

Persistindo sem o RFWDAO

Ao persistir o RFWVO sem o RFWDAO, será necessário identificar como o seu sistema salva as enumerações. Embora existam diversas maneiras de se resolver, se seguir o método do RFWDAO, em que as enumerations são salvas somente pelos seus nomes, ao recuperar o nome do banco de dados e utilizar o ".valueOf()" a operação falhará, já que não sabemos de qual enumeration a unidade pertence.

Para resolver isso o MeasureRuler tem o seguinte método:

MeasureRuler.valueOf(...);

Este método identifica a unidade pelo nome, entre todas as dimensões existentes no MeasureRuler.

Unidades de Medidas Iguais Por conta de termos várias unidades de medidas de dimensões diferentes representadas em enumerations diferentes, o Java permitirá que tenhamos uma unidade de medida "X" tanto em VolumeUnit quanto em AreaUnit. Embora o Java não tenha problemas para compilar esse código, ao ser persistido no banco de dados (salvo apenas o NAME da enumeration), a recuperação do objeto é baseada apenas no nome da enumeration. Isso fará com que seja sempre retornada pela primeira enumeration que o código procura. Para evitar esse problemas as unidades de medidas devem sempre ter nomes diferentes mesmo que em dimensões distintas. Embora não conheça nenhuma unidade de medida que tenha o mesmo o nome e represente coisas diferentes, é bom que o DEV tenha ciência dessa situação.

Unidades de Medidas Personalizadas

O MeasureRuler permite que o usuário crie suas próprias unidades de medidas bastando apenas definir um nome e um símbolo. Em uma classe que estenda a interface MeasureUnit. Para que a unidade de medida se torne funcional será ainda necessário estabelecer uma régua de equivalências, explicado no tópico de utilização.

Persistência de Unidades de Medidas Personalizadas Vale ressaltar que as unidades de medidas personalizadas não podem ser persistidas com o MeasureUnitDAOConverter. Esses objetos devem ser persistidos em atributos separados como um objeto do sistema, ou o desenvolvedor deve implementar seu próprio converter para o determinado atributo.

Estabelecendo Paridade de Conversão - MeasureRulerEquivalenceIntercade

Embora o MeasureRuler já seja capaz de converter unidades de medidas dentro da mesma dimensão, é possível estabelecer equivalências entre as unidades de medidas. Como, por exemplo, estabelecer que 1 unidade tem 50g, e depois disso pedir que a régua converta 1 Dúzia em Kilos.

Essas paridades são definidas apenas implementando a interface MeasureRulerEquivalenceInterface. Nela há apenas um método que deve retornar uma Hash<MeasureUnit, BigDecimal>. A chave da hash é qualquer unidade de medida, e seu valor é um BigDecimal que estabelece o peso da unidade de medida. Exemplos:

• 1 Unidade = 50g = 30ml - Devemos ter os seguintes objetos na Hash:
  • hash.put(UnitUnit.UNIT, BigDecimal.ONE);
  • hash.put(WeightUnit.GRAM, new BigDecimal("50");
  • hash.put(VolumeUnit.MILILITER, new BigDecimal("30");

Informações Redundantes Só devemos ter uma unidade de medida de cada dimensão. Incluir na Hash múltiplas informações da mesma dimensão é desnecessário, e podem resultar em resultados "aleatórios" se elas não forem coerentes. Exemplos: Incluir 1Kg, 1000g e 50Unidades - A hash aceitará a unidade de medida KILOGRAM e GRAM, mas a informação é redundante, mas não causará nenhum problema. Incluir 1Kg, 500g e 50Unidades - Informar que 1Kg é equivalente à 500g é uma informação incoerente. Ao procurar as equivalências para converter Unidades em Massa, o MeasureRuler pode hora utilizar a informação de 1Kg - 50 Unidades, hora utilizar 500g - 50Unidades. Dependendo da informação que encontrar primeiro na Hash o resultado será diferente.

Com esses três objetos estabelecemos a referência entre as dimensões Unidades, Massa e Volume. Podendo converter de Toneladas para Centimetros Cúbicos, por exemplo. Para estabelecer, uma referência com uma unidade de medida personalizada basta colocar na Hash a instância da unidade de media personalizada na Hash e estabelecer o seu peso em comparação as demais unidades presentes na Hash.

Validação da MeasureRulerEquivalenceInterface

A classe MeasureRuller contém um método de validação para garantir que as informações da Hash de equivalências não estão redundantes ou incoerentes.