ایجاد حاشیه نویسی در جاوا

مقاله توسط Jonny Hackett 14 ژوئیه 2014، 11:09 صبح اگر در جاوا برنامه نویسی می کنید و از هر یک از فریمورک های محبوب مانند Spring و Hibernate استفاده می کنید ، از قبل با استفاده از حاشیه نویسی آشنا هستید. هنگام کار با یک چارچوب موجود، حاشیه نویسی داخلی کاملاً کافی است. اما اگر بخواهید حاشیه نویسی خود را ایجاد کنید چه؟ چندی پیش دلیلی برای ایجاد حاشیه نویسی برای پروژه ای داشتم که نیاز به تایید اطلاعات مشترک از پایگاه های داده متعدد داشت. سناریو یک کسب و کار دارای پایگاه داده های متعددی بود که اطلاعات یکسانی را ذخیره می کردند و داده ها را به روش های مختلف به روز می کردند. برنامه ریزی شده بود که داده ها در یک پایگاه داده اصلی ترکیب شوند تا مشکلات مربوط به به دست آوردن داده ها از منابع مختلف برطرف شود. اما قبل از شروع پروژه می بایست از عدم همگام بودن داده ها مطلع شد و تغییرات لازم را انجام داد. اولین قدم ایجاد گزارشی بود که داده‌های یکسانی را در پایگاه‌های داده مختلف نشان می‌داد و مقادیر را تأیید می‌کرد، یا رکوردهایی را که مطابقت نداشتند، بر اساس قوانین تطبیق مشخص برجسته می‌کرد. در زیر گزیده ای از الزامات اصلی در زمان پروژه آورده شده است: • مقایسه داده ها در چندین پایگاه داده برای یافتن همان داده ها، مانند نام مشتری، نام شرکت یا اطلاعات دایرکتوری. • به طور پیش فرض، مقدار باید در تمام پایگاه های داده بر اساس نوع داده دقیقاً یکسان باشد. • برای برخی از فیلدها فقط می خواستیم نشان دهیم که مقدار پیدا شده است، اما مقدار مورد مقایسه قرار نگرفت. • برای سایر فیلدها فقط می خواستیم مقدار را با آنچه پیدا شده مقایسه کنیم و داده ها را با داده های منبع مشخص شده تأیید کنیم. • برای فیلدهای سوم، ما می خواستیم یک مقایسه داده پیچیده ای انجام دهیم که بر اساس ارزش سایر فیلدها در رکورد باشد. • برای نوع فیلد چهارم، می خواستیم داده ها را قالب بندی کنیم، به عنوان مثال در قالب ارز 000,000.00 دلار. • گزارش باید در قالب MS Excel باشد، هر ردیف باید حاوی مقداری از منبع جداگانه باشد. هر خطی که مقدار آن با شرایط تأیید داده مطابقت ندارد باید با رنگ زرد برجسته شود. حاشیه نویسی ها پس از اینکه الزامات را خواندیم و به چند ایده مختلف برای آنچه مورد نیاز بود رسیدیم، تصمیم گرفتم از حاشیه نویسی استفاده کنم که پیکربندی مقایسه داده ها و فرآیند گزارش دهی را آغاز کند. ما به یک راه حل ساده و در عین حال انعطاف پذیر و قابل توسعه نیاز داشتیم. این حاشیه‌نویسی‌ها در سطح فیلد خواهند بود و من دوست دارم که پیکربندی در یک فایل در جایی در مسیر کلاس پنهان نشود. در عوض، می‌توانم حاشیه‌نویسی‌های مرتبط با فیلد را ببینم تا دقیقا بدانم چگونه پردازش می‌شود. به بیان ساده، یک حاشیه نویسی چیزی بیش از یک نشانگر، فراداده ای نخواهد بود که اطلاعاتی را ارائه می دهد، اما مستقیماً بر عملکرد خود کد تأثیر نمی گذارد. اگر قبلاً در جاوا برنامه نویسی کرده اید، باید با استفاده از حاشیه نویسی آشنا باشید، اما ممکن است هرگز نیازی به ایجاد آن نداشته باشید. برای انجام این کار، باید نوع جدیدی ایجاد کنید که از نوع واسط @ Java استفاده می کند ، که حاوی عناصری است که به نوبه خود جزئیات فراداده را تعریف می کنند. در اینجا نمونه ای از یک پروژه آورده شده است: 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 } این حاشیه نویسی اصلی است که با آن فرآیند مقایسه داده ها را شروع می کنیم. این شامل عناصر اساسی مورد نیاز، در صورت لزوم، برای مقایسه داده ها از منابع داده های مختلف است. @ReconField باید بیشتر موارد مورد نیاز ما را انجام دهد، به استثنای مقایسه‌های پیچیده‌تر داده‌ها، که بعداً در مورد آن صحبت خواهیم کرد. بیشتر این عناصر با نظرات موجود در کد توضیح داده می شوند. صرف نظر از این، چند مورد از حاشیه نویسی های اصلی در @ReconField ما باید به طور جداگانه توضیح داده شوند. • @Target – این حاشیه نویسی به شما امکان می دهد آن عناصر جاوا را مشخص کنید که حاشیه نویسی باید روی آنها اعمال شود. انواع ممکن برای استفاده عبارتند از: ANNOTATION_TYPE، CONSTRUCTOR، FIELD، LOCAL_VARIABLE، METHOD، PACKAGE، PARAMETER و TYPE. در حاشیه نویسی @ReconField ما برای سطح FIELD. • @Retention – این حاشیه نویسی به شما امکان می دهد تعیین کنید که حاشیه نویسی چه زمانی در دسترس باشد. مقادیر ممکن CLASS، RUNTIME و SOURCE هستند. از آنجایی که در RUNTIME یادداشت ها را پردازش خواهیم کرد، باید این مقادیر را تنظیم کنیم. فرآیند اعتبار سنجی داده ها یک پرس و جو را در برابر هر پایگاه داده اجرا می کند و سپس نتایج را در داده های کلی نمایش می دهد که همه فیلدهای یک نوع رکورد خاص است. یک حاشیه نویسی برای هر فیلد در داده های به اشتراک گذاشته شده به پردازشگر می گوید که چگونه داده های آن فیلد خاص و همچنین مقدار یافت شده در هر پایگاه داده را مقایسه کند. بیایید به چند نمونه از نحوه استفاده از این حاشیه نویسی برای پیکربندی های مختلف مقایسه داده ها نگاه کنیم. برای تأیید اینکه یک مقدار وجود دارد و دقیقاً در هر منبع داده مطابقت دارد، فقط باید یک شناسه فیلد و یک برچسب ارائه کنید که در قسمت گزارش ظاهر می شود. 1 @ReconField(id = CUSTOMER_ID, label = "Customer ID") 2 private String customerId; برای نمایش مقادیر یافت شده از هر منبع داده، اما مقایسه داده ها، باید یک عنصر compareSources را مشخص کنید و مقدار را روی false قرار دهید. 1 @ReconField(id = NAME, label = "NAME", compareSources = false) 2 private String name; برای تأیید یافتن یک مقدار در یک منبع داده خاص، اما نه همه، باید از عنصر sourcesToCompare استفاده کنید . با این کار تمام مقادیر یافت شده نمایش داده می شود، اما هرگونه مقایسه داده در منابع داده طبق فهرست عناصر انجام می شود. این برای مواردی است که برخی از داده ها در همه منابع داده ذخیره نشده باشند. ReconSource فهرستی است که در آن منابع داده برای مقایسه در دسترس هستند. 1 @ReconField(id = PRIVATE_PLACEMENT_FLAG, label = "PRIVATE PLACEMENT FLAG", sourcesToCompare ={ 2 ReconSource.LEGACY, ReconSource.PACE }) private String privatePlacementFlag; اکنون که الزامات اساسی را برآورده کرده‌ایم، باید مقایسه‌های داده‌های پیچیده‌تری را انجام دهیم که مختص زمینه هستند. برای انجام این کار، حاشیه نویسی دوم ایجاد می کنیم که پردازش قوانین را آغاز می کند. 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 } بسیار شبیه به حاشیه نویسی قبلی، یک تفاوت بزرگ این است که در @ReconCustomRule کلاسی را مشخص می کنیم که مقایسه داده ها را با شروع فرآیند recon اجرا می کند. شما فقط می توانید کلاس مورد استفاده را مشخص کنید، به طوری که کنترل کننده شما یک مقدار را تعیین می کند و هر کلاسی را که شما مشخص می کنید مقداردهی اولیه می کند. کلاس مشخص شده در این حاشیه نویسی از رابط قانون استفاده می کند که به نوبه خود توسط handler برای اجرای قانون استفاده می شود. بیایید به چند نمونه از این حاشیه نگاه کنیم. در این مثال، ما از قانونی استفاده می کنیم که مبادلات ارزی غیر آمریکایی را بررسی می کند و در این مورد از مقایسه داده ها صرف نظر می کند. برای این کار باید فیلد کشور را در همان رکورد بررسی کنیم. 1 @ReconField(id = STREET_CUSIP, label = "STREET CUSIP", compareSources = false) 2 @ReconCustomRule(processor = SkipNonUSExchangeComparisonRule.class) 3 private String streetCusip; در اینجا یک مثال وجود دارد که در آن پارامترهای قانون، در این مورد مقدار تلورانس را تنظیم می کنیم. برای مقایسه داده های ما، مقدار مقایسه نمی تواند بیش از 1000 انحراف داشته باشد. استفاده از یک پارامتر برای تعیین مقدار تلورانس به ما این امکان را می دهد که از قوانین یکسانی برای چندین فیلد با مقادیر تلورانس متفاوت استفاده کنیم. تنها مشکل این است که این پارامترها ثابت هستند و به دلیل ماهیت حاشیه نویسی نمی توانند پویا باشند. 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; همانطور که می بینید، ما با استفاده از دو حاشیه نویسی نسبتاً ساده، مقداری انعطاف به فرآیند مقایسه داده ها از پایگاه های داده مختلف اضافه کرده ایم. برای این مورد خاص، حاشیه‌نویسی‌ها فرآیند مقایسه داده‌ها را هدایت می‌کنند، به طوری که اساساً یادداشت‌هایی را که در داده‌های به اشتراک گذاشته شده می‌یابیم ارزیابی می‌کنیم و از آنها برای هدایت پردازش استفاده می‌کنیم. نتیجه گیری مقالات زیادی در مورد حاشیه نویسی در جاوا، آنچه انجام می دهند و قوانین استفاده از آنها وجود دارد. در این مقاله می‌خواستم از طریق مثال‌هایی نشان دهم که چرا باید از آنها استفاده کنید و چه مزایایی می‌توانید از آن به دست آورید. لطفا توجه داشته باشید که این تازه شروع کار است. هنگامی که تصمیم به ایجاد حاشیه نویسی گرفتید، باید نحوه استفاده از آنها را به موثرترین راه بیابید. در قسمت 2، نحوه پردازش حاشیه نویسی با استفاده از بازتاب جاوا را به شما نشان خواهم داد. — جانی هکت، مقاله اصلی asktheteam@keyholesoftware.com http://www.javacodegeeks.com/2014/07/creating-your-own-java-annotations.html