مقدمة إلى الاحتفاظ بالتعليقات التوضيحية لجافا وتوثيقها ووراثتها

ملاحظة الاحتفاظ

يشير التعليق التوضيحي للاحتفاظ إلى المرحلة التي سيتم الاحتفاظ بهذا النوع من التعليقات التوضيحية فيها. هناك ثلاث قيم:
1.RetentionPolicy.SOURCE - يتم الاحتفاظ بهذا النوع من التعليقات التوضيحية فقط على مستوى الكود المصدري وسيتم تجاهله أثناء التجميع.
2.RetentionPolicy.CLASS - يتم الاحتفاظ بهذا النوع من التعليقات التوضيحية أثناء الترجمة وهو موجود في ملف الفئة، لكن JVM سيتجاهله
3.RetentionPolicy.RUNTIME - سيتم الاحتفاظ بالتعليقات التوضيحية من هذا النوع بواسطة JVM، بحيث يمكن قراءتها واستخدامها بواسطة JVM أو أي تعليمات برمجية أخرى باستخدام آلية الانعكاس في وقت التشغيل.
يوضح المثال 5 إعلان RetentionPolicy.RUNTIME:

مثال 1 لتعليقات Java التوضيحية:

انسخ رمز الكود كما يلي:
@الاحتفاظ(سياسة الاحتفاظ.RUNTIME)
@interface العامة Test_Retention {
سلسلة doTestRetention();
}

في هذا المثال، يشير التعليق التوضيحي @Retention(RetentionPolicy.RUNTIME) إلى أنه سيتم الاحتفاظ بالتعليق التوضيحي Test_Retention بواسطة الجهاز الظاهري بحيث يمكن قراءته من خلال الانعكاس في وقت التشغيل.

الشروحات الموثقة

يشير التعليق التوضيحي الموثق إلى أنه يجب تسجيل هذا التعليق التوضيحي بواسطة أداة javadoc بشكل افتراضي، لا يتضمن javadoc تعليقات توضيحية، ولكن إذا تم تحديد @Documented عند الإعلان عن تعليق توضيحي، فستتم معالجته بواسطة أدوات مثل javadoc، وبالتالي فإن معلومات نوع التعليق التوضيحي. سيتم تضمينه أيضًا في الوثائق التي تم إنشاؤها، ويوضح المثال 6 استخدام @Documented:

المثال 2 لتعليقات Java التوضيحية:
انسخ رمز الكود كما يلي:
@موثقة
@interface العامة Test_Documented {
سلسلة doTestDocument();
}

بعد ذلك، قم بتعديل فئة TestAnnotations كما يلي:

انسخ رمز الكود كما يلي:
التعليقات التوضيحية للطبقة العامة {
public static void main(String arg[]) {
new TestAnnotations().doSomeTestRetention();
new TestAnnotations().doSomeTestDocumented();
}
@Test_Retention (doTestRetention="اختبار الاحتفاظ بمعلومات التعليق التوضيحي")
الفراغ العام doSomeTestRetention() {
System.out.printf("اختبار نوع التعليق التوضيحي "الاحتفاظ"");
}
@Test_Documented(doTestDocument="مرحبًا بالمستند")
الفراغ العام doSomeTestDocumented() {
System.out.printf("اختبار نوع التعليق التوضيحي 'موثق'");
}
}

الآن، إذا استخدمت الأمر javadoc لإنشاء ملف TestAnnotations.html، فسترى نتائج مشابهة للشكل 1.

كما ترى من لقطة الشاشة، لا توجد طريقة معلومات من نوع التعليق التوضيحي () لطريقة doSomeTestRetention() في المستند، ومع ذلك، توفر وثيقة طريقة doSomeTestDocumented() معلومات وصفية للتعليق التوضيحي تتم إضافة العلامةDocumented إلى التعليق التوضيحي Test_Documented. لم يحدد التعليق التوضيحي السابق Test_Retention العلامة @Documented.

تعليق توضيحي موروث (قد يكون هناك خطأ ما في هذه الفقرة...)

هذا نوع تعليق توضيحي أكثر تعقيدًا إلى حد ما، ويشير إلى أن الفئة المشروحة سترث تلقائيًا، وبشكل أكثر تحديدًا، إذا تم استخدام العلامةInherited عند تحديد التعليق التوضيحي، ثم تم استخدام التعليق التوضيحي المحدد للتعليق على فئة أصل أخرى، فستكون الفئة الأصلية. إذا كان يحتوي على فئة فرعية، فسيتم توريث جميع خصائص الفئة الأصلية إلى فئتها الفرعية. في المثال 7، ستشاهد فوائد استخدام العلامة @Inherited.

مثال 3 من التعليقات التوضيحية لجافا

أولاً، قم بتحديد التعليق التوضيحي الخاص بك:
انسخ رمز الكود كما يلي:
@موروثة
عامة @interface MyParentObject {
boolean isInherited() default true;
String doSomething() default "افعل ماذا؟";
}

بعد ذلك، يتم شرح الفصل باستخدام التعليقات التوضيحية:

انسخ رمز الكود كما يلي:
@MyParentObject
فئة عامة MyChildObject {
}

كما ترون، لا تحتاج إلى تحديد أساليب الواجهة في فئة التنفيذ، بسبب العلامة @Inherited، كيف سيبدو الأمر إذا استخدمت طريقة قديمة لتحديد فئة التنفيذ؟ نظرة أدناه هذا تطبيق قديم:

انسخ رمز الكود كما يلي:
الطبقة العامة MyChildObject تنفذ MyParentObject {
منطقية عامة موروثة () {
عودة كاذبة.
}
سلسلة عامة تفعل شيئًا () {
يعود ""؛
}
منطقية عامة يساوي (كائن كائن) {
عودة كاذبة.
}
كود التجزئة العام () {
العودة 0؛
}
سلسلة عامة إلى سلسلة () {
يعود ""؛
}
نوع التعليق التوضيحي للفئة العامة () {
عودة فارغة؛
}
}

هل ترى الفرق؟ كما ترون، يجب عليك تنفيذ جميع أساليب الواجهة الأصلية بالإضافة إلى أساليب isInherited() وdoSomething() من myParentObject، تحتاج أيضًا إلى تنفيذ يساوي()، toString(. ) وطريقة hasCode() توجد أيضًا طريقة annotationType() للفئة java.lang.annotation.Annotation سواء كنت تريد تنفيذ هذه الطرق أم لا، يجب عليك تضمينها في الكائن الموروث.

ختاماً

توضح لك هذه المقالة كيفية جعل التطوير أسهل باستخدام ميزة التعليقات التوضيحية في JDK5. لا تؤثر التعليقات التوضيحية بشكل مباشر على دلالات البرنامج. يمكن لأدوات التطوير والنشر قراءة هذه التعليقات التوضيحية ومعالجتها بطريقة ما، وذلك باستخدام البرنامج الذي يحتوي على التعليقات التوضيحية يمكن أن يحل محل ملفات مصدر Java الإضافية أو مستندات XML أو غيرها من العناصر القديمة. يمكن أن يؤدي استخدام التعليقات التوضيحية إلى تحقيق نفس الشيء باستخدام تعليمات برمجية أقل والحصول على اكتشاف أفضل للأخطاء في وقت الترجمة. الغرض من التعليقات التوضيحية هو قضاء وقت أقل في التفاصيل الصعبة وغير المفيدة والتركيز أكثر على قواعد منطق الأعمال. هذه المقالة هي الجزء الأول من سلسلة تعليقات Java التوضيحية. في الجزء الثاني، ستتعلم كيفية استخدام التعليقات التوضيحية لتطوير لغة بسيطة تطبيق الويب وأخيرًا، في الجزء الثالث، سترى مثالًا معقدًا يتضمن جداول قاعدة بيانات متعددة.