Tworzenie własnych adnotacji w Javie

artykuł Jonny'ego Hacketta 14 lipca 2014 11:09 Jeśli programujesz w Javie i używasz któregoś z popularnych frameworków, takich jak Spring i Hibernate , to znasz już użycie adnotacji. Podczas pracy z istniejącym frameworkiem wystarczą wewnętrzne adnotacje. Ale co, jeśli chcesz stworzyć własne adnotacje? Niedawno miałem powód, aby stworzyć własne adnotacje do projektu, który wymagał potwierdzenia wspólnych informacji z kilku baz danych. Scenariusz Firma posiadała wiele baz danych, w których przechowywano te same informacje i aktualizowano je na różne sposoby. Planowano połączyć dane w jedną nadrzędną bazę danych, aby wyeliminować problemy związane z pozyskiwaniem danych z różnych źródeł. Jednak przed rozpoczęciem projektu konieczne było sprawdzenie, w jakim stopniu dane są niezsynchronizowane i dokonanie niezbędnych zmian. Pierwszym krokiem było stworzenie raportu, który pokazywałby te same dane w różnych bazach i potwierdzał wartości lub wyróżniał te rekordy, które nie pasowały, w oparciu o ustalone zasady uzgadniania. Poniżej znajduje się fragment głównych wymagań w momencie realizacji projektu: • Porównaj dane w kilku bazach danych, aby znaleźć te same dane, takie jak nazwa klienta, nazwa firmy lub informacje katalogowe. • Domyślnie wartość powinna być dokładnie taka sama we wszystkich bazach danych, w zależności od typu danych. • W przypadku niektórych pól chcieliśmy tylko pokazać, że wartość została znaleziona, ale wartość nie została porównana. • W przypadku pozostałych pól chcieliśmy jedynie porównać wartość ze znalezioną wartością i potwierdzić dane z danymi ze wskazanego źródła. • W przypadku trzeciego pola chcieliśmy dokonać złożonego porównania danych, które opierałoby się na wartościach innych pól w rekordzie. • W przypadku czwartego typu pola chcieliśmy sformatować dane, na przykład w formacie walutowym 000 000,00 USD. • Raport musiał być w formacie MS Excel, każdy wiersz powinien zawierać wartość z innego źródła. Linię, której wartość nie odpowiada warunkom potwierdzenia danych, należy podświetlić na żółto. Adnotacje Po przeczytaniu wymagań i wymyśleniu kilku różnych pomysłów na to, co jest wymagane, zdecydowałem się użyć adnotacji, które uruchomią proces konfiguracji porównania danych i raportowania. Potrzebowaliśmy prostego, a jednocześnie elastycznego i rozszerzalnego rozwiązania. Adnotacje te będą na poziomie pola i podoba mi się fakt, że konfiguracja nie będzie ukryta w pliku gdzieś na ścieżce klasy. Zamiast tego będę mógł zobaczyć adnotacje powiązane z polem, dzięki czemu będę dokładnie wiedział, jak zostanie ono przetworzone. Najprościej mówiąc, adnotacja będzie niczym innym jak znacznikiem, metadanymi, które dostarczą informacji, ale nie będą miały bezpośredniego wpływu na działanie samego kodu. Jeśli programowałeś już wcześniej w Javie, powinieneś być zaznajomiony z używaniem adnotacji, ale być może nigdy nie musiałeś tworzyć własnych. Aby to zrobić, musisz utworzyć nowy typ, który będzie korzystał z typu Java @interface , który będzie zawierał elementy definiujące szczegóły metadanych. Oto przykład projektu: 1@Target(ElementType.FIELD) 2@Retention(RetentionPolicy.RUNTIME) 3public @interface ReconField { 4 5 /** 6 * Значение, которое определяет из Jakого источника сравниваются данные, Lub будет использоваться для 7 отображения значения Lub для ссылки на правило. 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 * Значение, показывающее oznaczający 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 } Jest to główna adnotacja, od której należy rozpocząć proces porównywania danych. Zawiera podstawowe wymagane elementy, wymagane do porównywania danych z różnych źródeł danych. @ReconField powinien obsłużyć większość tego, czego potrzebujemy, z wyjątkiem bardziej złożonych porównań danych, o których porozmawiamy później. Większość tych elementów wyjaśniono komentarzami w kodzie. Niezależnie od tego, kilka głównych adnotacji w naszym @ReconField należy wyjaśnić osobno. • @Target – Ta adnotacja pozwala określić te elementy Java, do których należy zastosować adnotację. Możliwe typy do użycia to: ANNOTATION_TYPE, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METOD, PACKAGE, PARAMETER i TYPE. W naszej adnotacji @ReconField dla poziomu FIELD. • @Retention – Ta adnotacja pozwala określić, kiedy adnotacja będzie dostępna. Możliwe wartości to CLASS, RUNTIME i SOURCE. Ponieważ będziemy przetwarzać adnotacje w RUNTIME, musimy ustawić te wartości. Proces sprawdzania poprawności danych wykona jedno zapytanie do każdej bazy danych, a następnie wyświetli wyniki w danych ogólnych, czyli wszystkich polach dla określonego typu rekordu. Adnotacja dla każdego pola we współdzielonych danych poinformuje procesor, jak porównać dane dla tego konkretnego pola, a także wartość znalezioną w każdej bazie danych. Przyjrzyjmy się kilku przykładom wykorzystania tych adnotacji w różnych konfiguracjach porównywania danych. Aby potwierdzić, że wartość istnieje i jest dokładnie dopasowana w każdym źródle danych, wystarczy podać identyfikator pola i etykietę, która pojawi się w polu raportu. 1 @ReconField(id = CUSTOMER_ID, label = "Customer ID") 2 private String customerId; Aby wyświetlić znalezione wartości z każdego źródła danych, ale dokonać porównania danych, należy określić element CompareSources i ustawić wartość na false. 1 @ReconField(id = NAME, label = "NAME", compareSources = false) 2 private String name; Aby potwierdzić, że w określonym źródle danych, ale nie we wszystkich, została znaleziona wartość, należy skorzystać z elementu sourceToCompare . Spowoduje to wyświetlenie wszystkich znalezionych wartości, ale wszelkie porównania danych w źródłach danych zostaną wykonane zgodnie z listą elementów. Dzieje się tak w przypadku, gdy niektóre dane nie są zapisywane we wszystkich źródłach danych. ReconSource to wyliczenie, w którym dostępne są źródła danych do porównania. 1 @ReconField(id = PRIVATE_PLACEMENT_FLAG, label = "PRIVATE PLACEMENT FLAG", sourcesToCompare ={ 2 ReconSource.LEGACY, ReconSource.PACE }) private String privatePlacementFlag; Teraz, gdy spełniliśmy podstawowe wymagania, musimy przeprowadzić bardziej złożone porównania danych, które są specyficzne dla danej dziedziny. W tym celu utworzymy drugą adnotację, która uruchomi przetwarzanie reguł. 1 @Target(ElementType.FIELD) 2 @Retention(RetentionPolicy.RUNTIME) 3 public @interface ReconCustomRule { 4 5 /** 6 * Значение, указывающее используемые параметры, прописанные обработчику правила, oznaczający по умолчанию - 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 } Bardzo podobnie do poprzedniej adnotacji, jedną dużą różnicą jest to, że w @ReconCustomRule określamy klasę, która uruchomi porównanie danych po rozpoczęciu procesu rekonwalescencji. Możesz jedynie określić klasę, która będzie używana, dzięki czemu Twój program obsługi przypisze wartość i zainicjuje dowolną określoną klasę. Klasa określona w tej adnotacji będzie używać interfejsu reguł, który z kolei będzie używany przez procedurę obsługi do wykonania reguły. Spójrzmy na kilka przykładów tej adnotacji. W tym przykładzie używamy reguły, która sprawdzi, czy nie występują wymiany walut w USA i w tym przypadku pominie porównanie danych. Aby to zrobić musimy sprawdzić pole kraju w tym samym rekordzie. 1 @ReconField(id = STREET_CUSIP, label = "STREET CUSIP", compareSources = false) 2 @ReconCustomRule(processor = SkipNonUSExchangeComparisonRule.class) 3 private String streetCusip; Oto przykład, w którym ustalamy parametry reguły, w tym przypadku wartość tolerancji. Aby porównać nasze dane, porównywana wartość nie może różnić się o więcej niż 1000. Użycie parametru do określenia wartości tolerancji pozwoli nam zastosować te same zasady dla kilku pól, z różnymi wartościami tolerancji. Jedynym problemem jest to, że parametry te są statyczne i nie mogą być dynamiczne ze względu na charakter adnotacji. 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; Jak widać, dodaliśmy pewną elastyczność do procesu porównywania danych z różnych baz danych, używając dwóch dość prostych adnotacji. W tym konkretnym przypadku adnotacje kierują procesem porównywania danych, tak więc zasadniczo oceniamy adnotacje, które znajdziemy w udostępnionych danych i wykorzystujemy je do kierowania przetwarzaniem. Podsumowanie Istnieje wiele artykułów na temat adnotacji w Javie, ich działania i zasad korzystania z nich. W tym artykule chciałam pokazać na przykładach, dlaczego warto z nich korzystać i jakie korzyści można z tego wyciągnąć. Należy pamiętać, że to dopiero początek. Kiedy już zdecydujesz się na tworzenie adnotacji, będziesz musiał dowiedzieć się, jak z nich korzystać w najbardziej efektywny sposób. W części 2 pokażę, jak przetwarzać adnotacje za pomocą refleksji Java. — Jonny Hackett, Asktheteam@keyholesoftware.com oryginalny artykuł http://www.javacodegeeks.com/2014/07/creating-your-own-Java-annotations.html