RFWBundle

RFWBundle

Introdução

Visão Geral

O RFWBundle é uma classe estática que centraliza a gestão de mensagens no sistema, permitindo a recuperação de mensagens configuráveis a partir de arquivos de propriedades, conhecidos como bundles. Essas mensagens são amplamente utilizadas para fornecer feedback ao usuário, registrar logs, e suportar a internacionalização da aplicação. O RFWBundle facilita a substituição de parâmetros dinâmicos nas mensagens, tornando-as adaptáveis a diferentes contextos e necessidades.

Contexto de Uso

O RFWBundle é utilizado em diversos pontos do sistema onde é necessário recuperar mensagens de forma consistente e centralizada. Situações típicas de uso incluem:

• Internacionalização: Suporte a múltiplos idiomas através da recuperação de mensagens configuradas em arquivos de propriedades específicos para cada idioma.
• Gestão de Erros e Logs: Recuperação de mensagens de erro e avisos a partir de chaves definidas, com a capacidade de personalizar a mensagem com parâmetros específicos.
• Flexibilidade de Configuração: Permite que as mensagens do sistema sejam alteradas sem modificar o código-fonte, bastando atualizar os arquivos de bundle, o que facilita a manutenção e a adaptação do sistema a diferentes ambientes e requisitos.

A classe RFWBundle é essencial para sistemas que necessitam de uma camada de apresentação de mensagens flexível e facilmente configurável, garantindo que as informações exibidas ou registradas sejam coerentes e adaptadas ao contexto de uso.

Estrutura e Componentes

Métodos Principais

loadBundle

O método loadBundle é responsável por carregar os arquivos de propriedades (bundles) que contêm as mensagens utilizadas pelo sistema. Ele deve ser chamado com um nome de arquivo específico. Se o bundle já estiver carregado uma exceção crítica (`RFWCriticalException`) será lançada. Este método garante que as mensagens estejam disponíveis para recuperação por outros métodos da classe.

get(String key, String... params)

O método get é utilizado para recuperar uma mensagem associada a uma chave específica do bundle. Além disso, ele permite a substituição de parâmetros dinâmicos dentro da mensagem, utilizando placeholders como `${0}`, `${1}`, etc. Isso torna as mensagens adaptáveis a diferentes contextos ao inserir informações específicas em tempo de execução.

get(Throwable t)

O método get sobrecarregado com um parâmetro do tipo `Throwable` é usado para recuperar e formatar mensagens baseadas em exceções, especialmente aquelas que herdam de RFWException. Ele percorre a cadeia de causas da exceção para identificar a raiz do problema e formata a mensagem correspondente, incluindo detalhes como a classe da exceção e os parâmetros associados.

Tratamento Específico para RFWValidationException Se a exceção recebida for uma instância de `RFWValidationException`, o método realiza substituições adicionais na mensagem além dos parâmetros padrão `${0}`, `${1}`, etc. As variáveis suportadas incluem: `${fieldname}`: Substituído pelos nomes dos campos da classe que causaram a validação a falhar. `${classname}`: Substituído pelo nome da classe onde ocorreu a falha de validação. `${cause}`: Substituído pelo nome da classe da causa original da exceção. Essas substituições permitem que a mensagem seja mais informativa e específica ao contexto da validação que falhou. Os valores dessas variáveis podem ser definidos nos construtores da RFWValidationException.

get(Enum<?> value)

O método get com um parâmetro `Enum` é projetado para recuperar mensagens associadas a valores de enumerações. Ele constrói a chave do bundle a partir do valor da enumeração e tenta recuperar a mensagem correspondente. Se a chave não for encontrada no bundle, um aviso é registrado usando o RFWLogger.

get(MeasureUnit measureUnit)

O método get com um parâmetro MeasureUnit lida com a recuperação de mensagens associadas a unidades de medida. Ele trata instâncias de CustomMeasureUnit de maneira especial, formatando a mensagem com o símbolo e o nome da unidade. Para outras unidades de medida, ele delega a recuperação ao método que lida com enums.

replaceParameters

O método replaceParameters é responsável por substituir placeholders na mensagem recuperada pelo bundle com os valores fornecidos em um array de strings. Placeholders têm o formato `${0}`, `${1}`, e assim por diante, onde o número representa o índice do array de parâmetros.

• Funcionamento:
  • O método percorre a mensagem original, identificando os placeholders e substituindo-os pelos valores correspondentes do array.
  • Se um parâmetro for nulo, ele é substituído pela string `"<null>"` para evitar que o placeholder permaneça inalterado na mensagem final.

• Uso Interno:
  • Esse método é utilizado internamente pelos métodos `get(String key, String... params)` e `get(Throwable t)` para personalizar as mensagens retornadas, garantindo que elas contenham informações específicas do contexto de uso.

• Exemplo de Substituição:
  • Dada uma mensagem original `"Erro ao processar a transação ${0} na conta ${1}"` e os parâmetros `{"12345", "67890"}`, o método retornaria `"Erro ao processar a transação 12345 na conta 67890"`.

Carregamento e Configuração do Bundle

Processo de Carregamento

O carregamento do bundle é uma etapa crucial para o funcionamento do RFWBundle. Isso é realizado pelo método loadBundle, que carrega os arquivos de propriedades (bundles) que contêm as mensagens utilizadas em todo o sistema.

• Funcionamento:
  • O método tenta carregar o bundle especificado pelo nome do arquivo passado como parâmetro.
  • O bundle é carregado na primeira vez que o método é chamado e armazenado no atributo estático `bundle`. Isso garante que o arquivo de propriedades esteja disponível para futuras chamadas de recuperação de mensagens sem a necessidade de recarregá-lo.

• Recarregamento:
  • Se o bundle já estiver carregado e um novo nome de arquivo for passado para o método, ele tenta carregar o novo bundle e mesclar as propriedades, preservando as já existentes.
  • No entanto, se o bundle já estiver carregado e o nome do arquivo não for especificado, uma exceção crítica (RFWCriticalException) será lançada para evitar a inconsistência no carregamento das propriedades.

Bundles Padrão

Por padrão, o RFWBundle carrega seus arquivos de propriedades básicos, que contém os bundles do próprio módulo RFW.

Esses bundles são automaticamente carregados na primeira chamada do método loadBundle, garantindo que as mensagens essenciais do sistema estejam disponíveis desde o início. Se sua aplicação requer bundles adicionais, você pode chamar o método com o nome do arquivo necessário logo após a inicialização.

Erro ao Carregar Bundles

O método loadBundle lida com possíveis erros durante o carregamento do arquivo de propriedades, como falhas ao localizar o arquivo ou problemas de I/O.

• Tratamento de Exceções:
  • Se ocorrer uma exceção de I/O durante o carregamento, o método lançará uma RFWCriticalException com uma mensagem apropriada e a chave do bundle que causou o erro.
  • Esse tratamento garante que qualquer falha no carregamento do bundle seja imediatamente identificada e registrada, permitindo ações corretivas rápidas e evitando comportamentos inesperados no sistema.

O processo de carregamento e configuração do bundle é projetado para ser robusto e flexível, garantindo que as mensagens estejam disponíveis e prontas para uso logo no início da execução do sistema.

Recuperação de Mensagens

Chaves e Substituição de Parâmetros

A recuperação de mensagens no RFWBundle é realizada principalmente pelo método get(String key, String... params). Esse método permite recuperar uma mensagem associada a uma chave específica no bundle e, se necessário, substituir parâmetros dinâmicos na mensagem.

• Funcionamento:
  • O método aceita uma chave como argumento, que é usada para localizar a mensagem correspondente no bundle.
  • Parâmetros adicionais podem ser passados como strings, que substituem os placeholders na mensagem recuperada. Esses placeholders têm o formato `${0}`, `${1}`, etc., onde o número corresponde à posição do parâmetro no array.

• Exemplo de Uso:
  • Considere que o bundle contém a seguinte entrada: `ERRO_TRANSACAO=Erro ao processar a transação ${0} na conta ${1}`. Ao chamar `get("ERRO_TRANSACAO", "12345", "67890")`, o método retornará a mensagem `"Erro ao processar a transação 12345 na conta 67890"`.

Esse método é amplamente utilizado em todo o sistema para garantir que as mensagens sejam claras e adaptadas ao contexto específico, substituindo dinamicamente os valores necessários.

Mensagens Baseadas em Exceções

Além da recuperação de mensagens com base em chaves, o RFWBundle também oferece suporte para a recuperação de mensagens diretamente associadas a exceções, através do método get(Throwable t).

• Funcionamento:
  • O método percorre a cadeia de causas da exceção recebida, identificando a raiz do problema. Se a exceção for uma instância de `RFWException`, o método tentará recuperar a mensagem correspondente ao código de exceção.
  • Parâmetros específicos da exceção, como detalhes da classe onde ocorreu o erro e a mensagem da exceção, são substituídos na mensagem recuperada.

• Tratamento Específico para RFWValidationException:
  • Se a exceção for uma `RFWValidationException`, o método também substitui placeholders adicionais, como `${fieldname}`, que representa os nomes dos campos que falharam na validação, e `${classname}`, que substitui o nome da classe onde a validação falhou.

• Exemplo de Uso:
  • Se uma exceção `RFWValidationException` for lançada devido a um erro de validação no campo "username" da classe "User", e o bundle contiver a entrada `VALIDATION_ERROR=Erro de validação nos campos: ${fieldname} da classe ${classname}`, o método `get(Throwable t)` retornará a mensagem `"Erro de validação nos campos: username da classe User"`.

Tratamento de Enums

O método get(Enum<?> value) é utilizado para recuperar mensagens associadas a valores de enumerações. Esse método constrói a chave do bundle com base no CanonicalName da enumeração e tenta recuperar a mensagem correspondente.

• Funcionamento:
  • O método gera uma chave usando o CanonicalName da enumeração e tenta encontrar uma mensagem correspondente no bundle.
  • Se a chave não for encontrada, o método retorna o nome completo da enumeração como fallback e registra um aviso no log utilizando o RFWLogger.

• Exemplo de Uso:
  • Para uma enumeração `Status`, declarada em uma classe cujo CanonicalName seja 'com.example.Document' com valores como `PENDING`, o método `get(Status.PENDING)` tentará recuperar a mensagem correspondente à chave `com.example.Document.Status.PENDING`. Se não encontrar a chave ela será retornada como valor.

Unidades de Medida

O método get(MeasureUnit measureUnit) lida com a recuperação de mensagens associadas a unidades de medida do componente [MeasureUnit]], incluindo o suporte para instâncias de `CustomMeasureUnit`.

• Funcionamento:
  • Se o parâmetro passado for uma instância de `CustomMeasureUnit`, o método formatará a mensagem usando o símbolo e o nome da unidade. Caso contrário, ele delegará a recuperação ao método de enumerações, já que `MeasureUnit` geralmente funciona como uma enumeração.

Conteúdo Anterior

O RFWBundle é um serviço de Bundle oferecido pelo RFW. A classe estática RFWBundle ao ser inicializada já carrega os bundles do próprio RFW, trazendo as mensagens para as exceptions e Enumarations do próprio framework.

Carregando Arquivos de Bundles

Para incluir um arquivo de properties dentro do RFWBundle, deve ser chamado o método loadBundle(...) e passar o novo arquivo de bundle. Também é possível realizar a operação ao inicializar o framework, pelo método initializeBundle(...) da classe RFW.

	Carregando Arquivo de Bundle
	RFWBundle.loadBundle("bundlefile.properties");

Obtendo o Bundle

Para obter o Bundle o RFWBundle oferece os métodos get(...). Dependendo do objeto passado o módulo é capaz de extrair a chave e procurar nos arquivos de bundle automaticamente. Veja os detalhes de cada método a seguir:

get(Enum<?>)

Este método recebe como um argumento um objeto de Enumeração. O objeto de enumeração é procurado no arquivo de bundle pelo CanonicalName da sua Classe + Name da Enmeration. Por exemplo, imagine a Enumeration CASE_INSENSITIVE_ORDER da classe java.lang.String, será convertida na chave java.lang.String.CASE_INSENSITIVE_ORDER, para procurar entre os arquivos de bundle.

Neste caso, o arquivo de bundle deve ter uma entrada similar a esta:

java.lang.String.CASE_INSENSITIVE_ORDER=Ordem sem sensibilidade de caixa alta.

RUString.getEnumKey() A classe [RUString] contém um método getEnumKey(Enum<?>) que retorna exatamente a chave do Enumeration passado, mesmo método utilizado pelo RFWVBundle.

get(String, String...)

Recupera os bundles dos arquivos e substitui propriedades dentro deles. Este método procura por bundles que tenham o texto ${i}, onde i é o índice do array recebido para substituir seu conteúdo.

Por exemplo, o bundle seja:

warnmsg=Mensagem de erro (${0}): ${1}

E código executado seja:

	Obtendo o conteúdo do Bundle
	String v = RFWBundle.get("warnmsg", "500", "Erro Crítico");

O conteúdo da variável v será "Mensagem de Erro (500): Erro Crítico".

get(MeasureUnit)

Similar o método de Enumeration, ele recebe um objeto da interface MeasureUnit e se resolve para tentar descobrir o enumeration correto. Para mais informações sobre esta classe veja mais sobre o MeasureRuler.

get(Throwable)

É um método criado para tentar obter o bundle diretamente dos erros (Throwables). Esta método considera que está em uso o padrão de Exceções & Tratamento do RFW.

O método funciona na seguinte cascata para obter o bundle:

• O Throwable é instância de RFWException?
  • Sim: Tem um 'ExceptionCode' definido no padrão "[A-Z0-9_]+"?
    • Sim: Busca a mensagem de Bundle pelo 'ExceptionCode' e tenta substituir os parâmetros na mensagem.
  • Não: Retornará CanonicalName + Message (se Existir) + " at " + StackTrace()[0]

Parâmetros das Exceptions Note que os parâmetros que são substituídos no bundle são os mesmos passados na RFWException, seguindo a mesma lógica do método get(String, String...).

No caso de ser a exception de validação RFWValidationException, o RFW ainda tem algumas variáveis adicionais que podem ser utilizadas no bundle:

• ${fieldname} - substitui pelo nome do campo em que ocorreu o problema de validação (veja atributos ClassName e FieldName da classe RFWValidationException)
• ${classname} - substitui pele nome da classe em que a falha de validação ocorreu
• ${cause} - substitui pelo CannonicalName da exception que causou a validação. Note que não é da própria RFWValidationException, mas sim da Throwable passada dentro dela como causa.