Criando suas próprias anotações em Java

artigo de Jonny Hackett 14 de julho de 2014 11h09 Se você programa em Java e usa qualquer um dos frameworks populares como Spring e Hibernate , então já está familiarizado com o uso de anotações. Ao trabalhar com uma estrutura existente, as anotações internas são suficientes. Mas e se você precisar criar suas próprias anotações? Não faz muito tempo, tive um motivo para criar minhas próprias anotações para um projeto que exigia a confirmação de informações comuns de vários bancos de dados. Cenário Uma empresa tinha vários bancos de dados que armazenavam as mesmas informações e atualizavam os dados de maneiras diferentes. Foi planejado combinar os dados em um banco de dados mestre para eliminar os problemas associados à obtenção de dados de diferentes fontes. Mas antes de iniciar o projeto, foi necessário descobrir o quão dessincronizados estavam os dados e fazer as alterações necessárias. O primeiro passo foi criar um relatório que mostrasse os mesmos dados em diferentes bases de dados e confirmasse os valores, ou destacasse os registros que não correspondiam, com base nas regras de reconciliação estabelecidas. Abaixo segue um trecho dos principais requisitos no momento do projeto: • Comparar dados em diversos bancos de dados para encontrar os mesmos dados, como nome do cliente, nome da empresa ou informações de diretório. • Por padrão, o valor deve ser exatamente o mesmo em todos os bancos de dados com base no tipo de dados. • Para alguns campos queríamos apenas mostrar que o valor foi encontrado, mas o valor não foi comparado. • Para outros campos, queríamos apenas comparar o valor com o que foi encontrado e confirmar os dados com os dados da fonte especificada. • Para os terceiros campos, queríamos fazer uma comparação complexa de dados que se baseasse no valor de outros campos do registro. • Para o quarto tipo de campo, queríamos formatar os dados, por exemplo, no formato de moeda $000.000,00. • O relatório deveria estar no formato MS Excel, cada linha deveria conter um valor de uma fonte separada. Qualquer linha cujo valor não corresponda às condições de confirmação dos dados deverá ser destacada em amarelo. Anotações Depois de lermos os requisitos e termos algumas ideias diferentes sobre o que era necessário, decidi usar anotações que acionariam a configuração de comparação de dados e o processo de geração de relatórios. Precisávamos de uma solução simples, mas flexível e extensível. Essas anotações estarão no nível do campo e gosto do fato de que a configuração não ficará oculta em um arquivo em algum lugar do caminho da classe. Em vez disso, poderei ver as anotações associadas ao campo para saber exatamente como ele será processado. Simplificando, uma anotação nada mais será do que um marcador, metadados que fornecerão informações, mas não afetarão diretamente o funcionamento do código em si. Se você já programou em Java antes, deve estar familiarizado com o uso de anotações, mas talvez nunca tenha precisado criar as suas próprias. Para fazer isso, você precisa criar um novo tipo que use o tipo Java @interface , que conterá elementos que por sua vez definirão os detalhes dos metadados. Aqui está um exemplo de projeto: 1@Target(ElementType.FIELD) 2@Retention(RetentionPolicy.RUNTIME) 3public @interface ReconField { 4 5 /** 6 * Значение, которое определяет из Howого источника сравниваются данные, or будет использоваться для 7 отображения значения or для ссылки на правило. 8 * 9 * @return Значение, если источники должны быть сравнены, по умолчанию true. 10 */ 11 boolean compareSources() default true; 12 13 /** 14 * Значение показывает формат, который используется для отображения значения в отчете. 15 * 16 * @return Установленный формам, по умолчанию native. 17 */ 18 ReconDisplayFormat displayFormat() default ReconDisplayFormat.NATIVE; 19 20 /** 21 * Значение, показывающее meaning ID используемого поля для одинаковых значений из источника до поля. 22 * 23 * @return ID поля. 24 */ 25 String id(); 26 27 /** 28 * Значение, показывающее ярлык, который будет отображается в отчете для поля. 29 * 30 * @return Значение ярлыка, по умолчанию пустая строка. 31 */ 32 String label() default ""; 33 34 /** 35 * Значение, показывающее источник, который должен быть сравнен на предмет различий. 36 * 37 * @return Список источников для сравнения. 38 */ 39 ReconSource[] sourcesToCompare() default {}; 40 } Esta é a anotação principal para iniciar o processo de comparação de dados. Ele contém os elementos básicos necessários, conforme necessário, para comparar dados de diferentes fontes de dados. @ReconField deve lidar com a maior parte do que precisamos, com exceção de comparações de dados mais complexas, sobre as quais falaremos mais tarde. A maioria desses elementos é explicada por comentários no código. Independentemente disso, algumas das principais anotações em nosso @ReconField precisam ser explicadas separadamente. • @Target – Esta anotação permitirá que você especifique os elementos java aos quais a anotação deve ser aplicada. Os tipos possíveis de usar são: ANNOTATION_TYPE, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER e TYPE. Em nossa anotação @ReconField para o nível FIELD. • @Retention – Esta anotação permitirá especificar quando a anotação estará disponível. Os valores possíveis são CLASS, RUNTIME e SOURCE. Como processaremos anotações em RUNTIME, devemos definir esses valores. O processo de validação de dados executará uma consulta em cada banco de dados e, em seguida, exibirá os resultados nos dados gerais, que são todos os campos de um tipo de registro específico. Uma anotação para cada campo nos dados compartilhados dirá ao processador como comparar os dados daquele campo específico, bem como o valor encontrado em cada banco de dados. Vejamos alguns exemplos de como essas anotações podem ser usadas para várias configurações de comparação de dados. Para confirmar se um valor existe e corresponde exatamente em cada fonte de dados, basta fornecer um ID de campo e um rótulo que aparecerá no campo do relatório. 1 @ReconField(id = CUSTOMER_ID, label = "Customer ID") 2 private String customerId; Para exibir os valores encontrados de cada fonte de dados, mas fazer comparações de dados, você precisa especificar um elemento compareSources e definir o valor como falso. 1 @ReconField(id = NAME, label = "NAME", compareSources = false) 2 private String name; Para confirmar se um valor foi encontrado em uma determinada fonte de dados, mas não em todas, você precisa usar o elemento sourcesToCompare . Isto exibirá todos os valores encontrados, mas qualquer comparação de dados nas fontes de dados será feita de acordo com a lista de elementos. Este é o caso se alguns dados não forem salvos em todas as fontes de dados. ReconSource é um enum no qual as fontes de dados estão disponíveis para comparação. 1 @ReconField(id = PRIVATE_PLACEMENT_FLAG, label = "PRIVATE PLACEMENT FLAG", sourcesToCompare ={ 2 ReconSource.LEGACY, ReconSource.PACE }) private String privatePlacementFlag; Agora que atendemos aos requisitos básicos, precisamos realizar comparações de dados mais complexas que sejam específicas de cada campo. Para isso criaremos uma segunda anotação que acionará o processamento das regras. 1 @Target(ElementType.FIELD) 2 @Retention(RetentionPolicy.RUNTIME) 3 public @interface ReconCustomRule { 4 5 /** 6 * Значение, указывающее используемые параметры, прописанные обработчику правила, meaning по умолчанию - 7 отсутствие параметров. 8 * 9 * @return The String[] параметры, прописанные обработчику правила 10 */ 11 String[] params() default {}; 12 13 /** 14 * Значение, указывающее класс обработчика правила, которое используется для сравнения значений из 15 каждого источника данных. 16 * 17 * @return Класс обработчика правила 18 */ 19 Class processor() default DefaultReconRule.class; 20 } Muito semelhante à anotação anterior, uma grande diferença é que em @ReconCustomRule especificamos uma classe que executará a comparação de dados quando o processo de reconhecimento for iniciado. Você só pode especificar a classe que será usada, para que seu manipulador atribua um valor e inicialize qualquer classe que você especificar. A classe especificada nesta anotação usará a interface de regra, que por sua vez será usada pelo manipulador para executar a regra. Vejamos alguns exemplos dessa anotação. Neste exemplo, estamos usando uma regra que verificará câmbios de moeda fora dos EUA e ignorará a comparação de dados neste caso. Para fazer isso, precisamos verificar o campo país no mesmo registro. 1 @ReconField(id = STREET_CUSIP, label = "STREET CUSIP", compareSources = false) 2 @ReconCustomRule(processor = SkipNonUSExchangeComparisonRule.class) 3 private String streetCusip; Aqui está um exemplo em que definimos os parâmetros da regra, neste caso o valor da tolerância. Para comparar nossos dados, o valor comparado não pode divergir mais de 1.000. Usar um parâmetro para especificar um valor de tolerância nos permitirá usar as mesmas regras para vários campos, com valores de tolerância diferentes. O único problema é que estes parâmetros são estáticos e não podem ser dinâmicos devido à natureza da anotação. 1 @ReconField(id = USD_MKT_CAP, label = "MARKET CAP USD", displayFormat = 2 ReconDisplayFormat.NUMERIC_WHOLE, sourcesToCompare = 3 { ReconSource.LEGACY, ReconSource.PACE, ReconSource.BOB_PRCM }) 4 @ReconCustomRule(processor = ToleranceAmountRule.class, params = { "10000" }) 5 private BigDecimal usdMktCap; Como você pode ver, adicionamos alguma flexibilidade ao processo de comparação de dados de diferentes bancos de dados usando duas anotações bastante simples. Para este caso específico, as anotações orientam o processo de comparação de dados, de modo que essencialmente avaliamos as anotações que encontramos nos dados compartilhados e as usamos para orientar o processamento. Conclusão Existem muitos artigos sobre anotações em Java, o que elas fazem e quais são as regras para usá-las. Neste artigo quis mostrar, através de exemplos, porque você deve utilizá-los e como pode se beneficiar com isso. Observe que este é apenas o começo. Depois de decidir criar anotações, você terá que descobrir como usá-las da maneira mais eficaz. Na Parte 2, mostrarei como processar anotações usando reflexão Java. - Jonny Hackett, artigo original asktheteam@keyholesoftware.com http://www.javacodegeeks.com/2014/07/creating-your-own-java-annotations.html