If you\u2019ve been programming in Java and using any one of the popular frameworks\u00a0like\u00a0Spring and Hibernate, you should be very familiar with using annotations. When working with an existing framework, its annotations typically suffice. But, have you ever found a need to create your own annotations?<\/p>\n
Not too long ago, I found a reason to create my\u00a0own annotations for a project that involved verifying common data stored in multiple databases.
\n
\n
\n
\n <\/p>\n
The business had multiple databases that were storing the same information and had various means of keeping the data up to date. The business had planned a project to consolidate the data into a master database to alleviate some of the issues involved with having multiple sources of data.<\/p>\n
Before the project could begin however, the business needed to know how far out of sync the data was and make any necessary corrections to get in back in sync. The first step required creating a report that showed common data that belonged in multiple databases and validated the values, highlighting any records that didn\u2019t match according to the reconciliation rules defined. Here\u2019s a short summary of the requirements at the time:<\/p>\n
After going over the requirements and knocking around a few ideas, I decided to use annotations to drive the configuration for the data comparison and reporting process. We needed something that was somewhat simple, yet highly flexible and extensible. These annotations will be at the field level and I like the fact that the configuration won\u2019t be hidden away in a file somewhere on the classpath. Instead you\u2019ll be able to look at the annotation associated with a field to know exactly how it will be processed.<\/p>\n
In the simplest terms, an annotation is nothing more than a marker, metadata that provides information but has no direct effect on the operation of the code itself. If you\u2019ve been doing Java programming for a while now you should be pretty familiar with their use, but maybe you\u2019ve never had a need to create your own. To do that you\u2019ll need to create a new type that uses the Java type @interface<\/strong> that will contain the elements that specify the details of the metadata.<\/p>\n Here\u2019s an example from the project:<\/p>\n This is the main annotation that will drive how the data comparison process will work. It contains the basic elements required to fulfill most of the requirements for comparing the data amongst the different data sources. The @ReconField<\/strong> should handle most of what we need except for the requirement of more complex data comparison, which we\u2019ll go over a little bit later. Most of these elements are explained by the comments associated with each one in the code listing, however there are a couple of key annotations on our @ReconField that need to be pointed out. This data verification process will run one query for each database and then map the results to a common data bean that represents all of the fields for that particular type of business record. The annotations on each field of this mapped data bean tell the processor how to perform the data comparison for that particular field and its value found on each database. So let\u2019s look at a few examples of how these annotations would be used for various data comparison configurations.<\/p>\n To verify that the value exists and matches exactly in each data source, you would only need to provide the field ID and the label that should be displayed for the field on the report.<\/p>\n To display the values found in each data source, but not do any data comparisons, you would need to specify the element compareSources<\/strong> and set its value to false.<\/p>\n To verify the values found in specific data sources but not all of them, you would use the element sourcesToCompare<\/strong>. Using this would display all of the values found, but only perform any data comparisons on the data sources listed in the element. The handles the case in which some data is not stored in every data source. ReconSource<\/strong> is an enum that contains the data sources available for comparison.<\/p>\n Now that we\u2019ve covered our basic requirements, we need to address the ability to run complex data comparisons that are specific to the field in question. To do that, we\u2019ll create a second annotation that will drive the processing of custom rules.<\/p>\n Very similar to the previous annotation, the biggest difference in the @ReconCustomRule<\/strong> annotation is that we are specifying a class that will execute the data comparison when the recon process executes. You can only define the class that will be used, so your processor will have to instantiate and initialize any class that you specify. The class that is specified in this annotation will need to implement a custom rule interface, which will be used by the rule processor to execute the rule.<\/p>\n Now let\u2019s take a look at a couple of examples of this annotation.<\/p>\n In this example, we\u2019re using a custom rule that will check to see if the stock exchange is not the United States and skip the data comparison if that\u2019s the case. To do this, the rule will need to check the exchange country field on the same record.<\/p>\n Here\u2019s an example where we are specifying a parameter for the custom rule, in this case it\u2019s a tolerance amount. For this specific data comparison, the values being compared cannot be off by more than 1,000. By using a parameter to specify the tolerance amount, this allows us to use the same custom rule on multiple fields with different tolerance amounts. The only drawback is that these parameters are static and can\u2019t be dynamic due to the nature of annotations.<\/p>\n As you can see, we\u2019ve designed quite of bit of flexibility into a data verification report for multiple databases by just using a couple of fairly simple annotations. For this particular case, the annotations are driving the data comparison processing so we\u2019re actually evaluating the annotations that we find on the mapped data bean and using those to direct the processing.<\/p>\n There are numerous articles out there already about Java annotations, what they do, and the rules for using them. I wanted this article to focus more on an example of why you might want to consider using them and see the benefit directly.<\/p>\n Keep in mind that this is only the starting point, once you have decided on creating annotations you\u2019ll still need to figure out how to process them to really take full advantage of them. In part two, I\u2019ll show you how to process these annotations using Java reflection. Until then, here are a couple of good resources to learn more about Java annotations:<\/p>\n@Target(ElementType.FIELD)\r\n@Retention(RetentionPolicy.RUNTIME)\r\npublic @interface ReconField {\r\n\r\n \/**\r\n * Value indicates whether or not the values from the specified sources should be compared or will be used to display values or reference within a rule.\r\n *\r\n * @return The value if sources should be compared, defaults to true.\r\n *\/\r\n boolean compareSources() default true;\r\n\r\n \/**\r\n * Value indicates the format that should be used to display the value in the report.\r\n *\r\n * @return The format specified, defaulting to native.\r\n *\/\r\n ReconDisplayFormat displayFormat() default ReconDisplayFormat.NATIVE;\r\n\r\n \/**\r\n * Value indicates the ID value of the field used for matching source values up to the field.\r\n *\r\n * @return The ID of the field.\r\n *\/\r\n String id();\r\n\r\n \/**\r\n * Value indicates the label that should be displayed in the report for the field.\r\n *\r\n * @return The label value specified, defaults to an empty string.\r\n *\/\r\n String label() default \"\";\r\n\r\n \/**\r\n * Value that indicates the sources that should be compared for differences.\r\n *\r\n * @return The list of sources for comparison.\r\n *\/\r\n ReconSource[] sourcesToCompare() default {};\r\n\r\n}<\/pre>\n\n
@ReconField(id = CUSTOMER_ID, label = \"Customer ID\")\r\nprivate String customerId;<\/pre>\n
@ReconField(id = NAME, label = \"NAME\", compareSources = false)\r\nprivate String name;<\/pre>\n
@ReconField(id = PRIVATE_PLACEMENT_FLAG, label = \"PRIVATE PLACEMENT FLAG\", sourcesToCompare ={ ReconSource.LEGACY, ReconSource.PACE })\r\nprivate String privatePlacementFlag;<\/pre>\n@Target(ElementType.FIELD)\r\n@Retention(RetentionPolicy.RUNTIME)\r\npublic @interface ReconCustomRule {\r\n\r\n\/**\r\n* Value indicates the parameters used to instantiate a custom rule processor, the default value is no parameters.\r\n*\r\n* @return The String[] of parameters to instantiate a custom rule processor.\r\n*\/\r\nString[] params() default {};\r\n\r\n\/**\r\n* Value indicates the class of the custom rule processor to be used in comparing the values from each source.\r\n*\r\n* @return The class of the custom rule processor.\r\n*\/\r\nClass<?> processor() default DefaultReconRule.class;\r\n\r\n}<\/pre>\n@ReconField(id = STREET_CUSIP, label = \"STREET CUSIP\", compareSources = false)\r\n@ReconCustomRule(processor = SkipNonUSExchangeComparisonRule.class)\r\nprivate String streetCusip;<\/pre>\n
@ReconField(id = USD_MKT_CAP, label = \"MARKET CAP USD\", displayFormat = ReconDisplayFormat.NUMERIC_WHOLE, sourcesToCompare =\r\n{ ReconSource.LEGACY, ReconSource.PACE, ReconSource.BOB_PRCM })\r\n@ReconCustomRule(processor = ToleranceAmountRule.class, params =\t{ \"10000\" })\r\nprivate BigDecimal usdMktCap;<\/pre>\nConclusion<\/h2>\n
\n