إنشاء التعليقات التوضيحية الخاصة بك في جافا

مقال بقلم جوني هاكيت 14 يوليو، 2014 الساعة 11:09 صباحًا إذا كنت تقوم بالبرمجة بلغة Java وتستخدم أيًا من أطر العمل الشائعة مثل Spring و Hbernate ، فأنت بالفعل على دراية باستخدام التعليقات التوضيحية. عند العمل مع إطار موجود، تكون التعليقات التوضيحية الداخلية كافية تمامًا. ولكن ماذا لو كنت بحاجة إلى إنشاء التعليقات التوضيحية الخاصة بك؟ منذ وقت ليس ببعيد كان لدي سبب لإنشاء التعليقات التوضيحية الخاصة بي لمشروع يتطلب تأكيد المعلومات الشائعة من قواعد بيانات متعددة. السيناريو كان لدى الشركة قواعد بيانات متعددة تقوم بتخزين نفس المعلومات وتحديث البيانات بطرق مختلفة. وتم التخطيط لدمج البيانات في قاعدة بيانات رئيسية واحدة للتخلص من المشاكل المرتبطة بالحصول على البيانات من مصادر مختلفة. ولكن قبل البدء بالمشروع، كان من الضروري معرفة مدى عدم مزامنة البيانات وإجراء التغييرات اللازمة. كانت الخطوة الأولى هي إنشاء تقرير يعرض نفس البيانات في قواعد بيانات مختلفة ويؤكد القيم، أو يسلط الضوء على السجلات التي لم تتطابق، بناءً على قواعد التسوية المعمول بها. وفيما يلي مقتطف من المتطلبات الرئيسية في وقت المشروع: • مقارنة البيانات في عدة قواعد بيانات للعثور على نفس البيانات، مثل اسم العميل أو اسم الشركة أو معلومات الدليل. • بشكل افتراضي، يجب أن تكون القيمة هي نفسها تمامًا عبر كافة قواعد البيانات استنادًا إلى نوع البيانات. • بالنسبة لبعض الحقول، أردنا فقط إظهار أنه تم العثور على القيمة، ولكن لم تتم مقارنة القيمة. • بالنسبة للحقول الأخرى، أردنا فقط مقارنة القيمة بما تم العثور عليه وتأكيد البيانات بالبيانات من المصدر المحدد. • بالنسبة للحقول الثالثة، أردنا إجراء مقارنة معقدة للبيانات تعتمد على قيمة الحقول الأخرى داخل السجل. • بالنسبة لنوع الحقل الرابع، أردنا تنسيق البيانات، على سبيل المثال بتنسيق العملة $000,000.00. • يجب أن يكون التقرير بصيغة MS Excel، ويجب أن يحتوي كل صف على قيمة من مصدر منفصل. يجب تمييز أي سطر لا تتطابق قيمته مع شروط تأكيد البيانات باللون الأصفر. التعليقات التوضيحية بعد أن قرأنا المتطلبات وتوصلنا إلى بعض الأفكار المختلفة لما هو مطلوب، قررت استخدام التعليقات التوضيحية التي من شأنها تشغيل تكوين مقارنة البيانات وعملية إعداد التقارير. كنا بحاجة إلى حل بسيط ولكنه مرن وقابل للتوسيع. ستكون هذه التعليقات التوضيحية على مستوى الحقل وأحب حقيقة أن التكوين لن يكون مخفيًا في ملف في مكان ما على مسار الفصل. وبدلاً من ذلك، سأكون قادرًا على رؤية التعليقات التوضيحية المرتبطة بالحقل حتى أعرف بالضبط كيف ستتم معالجتها. ببساطة، لن يكون التعليق التوضيحي أكثر من مجرد علامة، وبيانات وصفية توفر معلومات، ولكنها لن تؤثر بشكل مباشر على تشغيل الكود نفسه. إذا كنت قد قمت بالبرمجة بلغة Java من قبل، فمن المفترض أن تكون على دراية باستخدام التعليقات التوضيحية، ولكن ربما لم تكن بحاجة إلى إنشاء تعليقات توضيحية خاصة بك. للقيام بذلك، تحتاج إلى إنشاء نوع جديد يستخدم نوع Java @interface ، والذي سيحتوي على عناصر تحدد بدورها تفاصيل البيانات التعريفية. فيما يلي مثال لمشروع: 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 – سيسمح لك هذا التعليق التوضيحي بتحديد عناصر Java التي يجب تطبيق التعليق التوضيحي عليها. الأنواع التي يمكن استخدامها هي: 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; لعرض القيم التي تم العثور عليها من كل مصدر بيانات، مع إجراء مقارنات البيانات، تحتاج إلى تحديد عنصر مقارنة المصادر وتعيين القيمة إلى خطأ. 1 @ReconField(id = NAME, label = "NAME", compareSources = false) 2 private String name; للتأكد من العثور على قيمة في مصدر بيانات معين، ولكن ليس كله، تحتاج إلى استخدام العنصر sourceToCompare . سيؤدي هذا إلى عرض جميع القيم التي تم العثور عليها، ولكن سيتم إجراء أي مقارنة للبيانات في مصادر البيانات وفقًا لقائمة العناصر. وهذا هو الحال إذا لم يتم حفظ بعض البيانات في كافة مصادر البيانات. 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 نحدد فئة ستقوم بتشغيل مقارنة البيانات عند بدء عملية إعادة التكوين. يمكنك فقط تحديد الفئة التي سيتم استخدامها، بحيث يقوم المعالج الخاص بك بتعيين قيمة وتهيئة أي فئة تحددها. ستستخدم الفئة المحددة في هذا التعليق التوضيحي واجهة القاعدة، والتي بدورها سيستخدمها المعالج لتنفيذ القاعدة. دعونا نلقي نظرة على بضعة أمثلة على هذا الشرح. في هذا المثال، نستخدم قاعدة ستتحقق من عمليات تبادل العملات غير الأمريكية وستتخطى مقارنة البيانات في هذه الحالة. للقيام بذلك، نحتاج إلى التحقق من حقل البلد في نفس السجل. 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; كما ترون، أضفنا بعض المرونة إلى عملية مقارنة البيانات من قواعد بيانات مختلفة باستخدام تعليقين توضيحيين بسيطين إلى حد ما. في هذه الحالة بالذات، تقود التعليقات التوضيحية عملية مقارنة البيانات، بحيث نقوم بشكل أساسي بتقييم التعليقات التوضيحية التي نجدها في البيانات المشتركة ونستخدمها لتوجيه المعالجة. الخلاصة: هناك العديد من المقالات حول التعليقات التوضيحية في Java، وماذا تفعل وما هي قواعد استخدامها. أردت في هذه المقالة أن أوضح من خلال الأمثلة لماذا يجب عليك استخدامها وكيف يمكنك الاستفادة منها. يرجى ملاحظة أن هذه مجرد البداية. بمجرد أن تقرر إنشاء التعليقات التوضيحية، سيتعين عليك معرفة كيفية استخدامها بالطريقة الأكثر فعالية. في الجزء الثاني، سأوضح لك كيفية معالجة التعليقات التوضيحية باستخدام انعكاس Java. — جوني هاكيت، Asktheteam@keyholesoftware.com المقالة الأصلية http://www.javacodegeeks.com/2014/07/creating-your-own-java-annotations.html