لتعلم التعليقات التوضيحية بعمق، يجب أن نكون قادرين على تحديد التعليقات التوضيحية الخاصة بنا واستخدامها قبل تحديد التعليقات التوضيحية الخاصة بنا، يجب أن نفهم بناء جملة التعليقات التوضيحية والتعليقات التوضيحية ذات الصلة التي توفرها Java.
-------------------------------------------------- ----------------------------------
شرح ميتا:
يتمثل دور التعليقات التوضيحية في إضافة تعليقات توضيحية إلى التعليقات التوضيحية الأخرى. يحدد Java5.0 أربعة أنواع قياسية من التعليقات التوضيحية، والتي تُستخدم لتوفير وصف لأنواع التعليقات التوضيحية الأخرى. التعليقات التوضيحية التعريفية المحددة بواسطة Java5.0:
1.@الهدف،
2.@الاحتفاظ،
3.@موثقة،
4.@موروثة
هذه الأنواع والفئات التي تدعمها موجودة في الحزمة java.lang.annotation. دعونا نلقي نظرة على دور كل تعليق توضيحي وتعليمات استخدام المعلمات الفرعية المقابلة.
-------------------------------------------------- ----------------------------------
@هدف:
يشرح @Target نطاق الكائنات المعدلة بواسطة التعليق التوضيحي: يمكن استخدام التعليق التوضيحي للحزم والأنواع (الفئات والواجهات والتعدادات وأنواع التعليقات التوضيحية) وأعضاء النوع (الطرق والمنشئات ومتغيرات الأعضاء وقيم التعداد) ومعلمات الطريقة والمتغيرات المحلية ( مثل متغيرات الحلقة ومعلمات الالتقاط). يمكن أن يؤدي استخدام الهدف في الإعلان عن نوع التعليق التوضيحي إلى جعل الهدف المعدل أكثر وضوحًا.
الوظيفة: تستخدم لوصف نطاق استخدام التعليقات التوضيحية (على سبيل المثال: حيث يمكن استخدام التعليقات التوضيحية الموضحة)
القيم (ElementType) هي:
1.CONSTRUCTOR: يستخدم لوصف المنشئ 2.FIELD: يستخدم لوصف المجال 3.LOCAL_VARIABLE: يستخدم لوصف المتغيرات المحلية 4.METHOD: يستخدم لوصف الطريقة 5.PACKAGE: يستخدم لوصف الحزمة 6.PARAMETER: يستخدم لوصف المعلمات 7.TYPE: يستخدم لوصف الفئات والواجهات (بما في ذلك أنواع التعليقات التوضيحية) أو إعلانات التعداد
أمثلة الاستخدام:
@Target(ElementType.FIELD)
@interface NoDBColumn {
}
-------------------------------------------------- ----------------------------------
@حفظ:
@Retention يحدد طول الوقت الذي يتم فيه الاحتفاظ بالتعليقات التوضيحية: تظهر بعض التعليقات التوضيحية فقط في الكود المصدري ويتم تجاهلها بواسطة المترجم؛ بينما سيتم قراءة الآخرين عند تحميل الفصل (يرجى ملاحظة أن ذلك لا يؤثر على تنفيذ الفصل، لأنه يتم استخدام التعليق التوضيحي والفئة بشكل منفصل). استخدم هذا التعليق التوضيحي للحد من "دورة حياة" التعليق التوضيحي.
الوظيفة: تشير إلى المستوى الذي يجب حفظ معلومات التعليق التوضيحي فيه، وتستخدم لوصف دورة حياة التعليق التوضيحي (أي: ضمن أي نطاق يكون التعليق التوضيحي الموصوف صالحًا)
القيم (RetentionPoicy) هي:
1.SOURCE: صالح في الملف المصدر (أي يتم الاحتفاظ بالملف المصدر)
2.CLASS: صالح في ملفات الفصل الدراسي (أي الفصل محجوز)
3.RUNTIME: صالح في وقت التشغيل (أي يتم الاحتفاظ به في وقت التشغيل)
يحتوي نوع التعليق التوضيحي التعريفي للاحتفاظ على قيمة فريدة كعضو، وتأتي قيمته من قيمة نوع التعداد java.lang.annotation.RetentionPolicy. الأمثلة المحددة هي كما يلي:
-------------------------------------------------- ----------------------------------
@موثق:
يتم استخدام @Documented لوصف أنواع أخرى من التعليقات التوضيحية التي يجب استخدامها كواجهة برمجة التطبيقات العامة لأعضاء البرنامج المشروح وبالتالي يمكن توثيقها بواسطة أدوات مثل javadoc. الموثق عبارة عن تعليق توضيحي ولا يحتوي على أعضاء.
التعليق التوضيحي @Inherited هو تعليق توضيحي ترميزي ينص @Inherited على أن نوعًا معينًا من التعليقات التوضيحية موروث. إذا تم استخدام نوع تعليق توضيحي تم تعديله باستخدامInherited لفئة ما، فسيتم استخدام هذا التعليق التوضيحي للفئات الفرعية من تلك الفئة.
ملاحظة: يتم توريث أنواع التعليقات التوضيحية @Inherited بواسطة الفئات الفرعية للفئة المشروحة. لا يرث الفصل التعليق التوضيحي من الواجهة التي ينفذها، ولا ترث الطريقة التعليق التوضيحي من الطريقة التي يتم تحميلها بشكل زائد.
عندما يكون الاحتفاظ بالتعليق التوضيحي الموضح بنوع التعليق التوضيحي @Inherited هو RetentionPolicy.RUNTIME، فإن واجهة برمجة تطبيقات الانعكاس تعمل على تحسين هذا الوراثة. إذا استخدمنا java.lang.reflect للاستعلام عن تعليق توضيحي لنوع التعليق التوضيحي @Inherited، فسيبدأ فحص الكود الانعكاسي في العمل: التحقق من الفصل والفصل الأصلي الخاص به حتى يتم العثور على نوع التعليق التوضيحي المحدد، أو المستوى الأعلى لبنية وراثة الفصل تم التوصل إليه.
رمز المثال:
-------------------------------------------------- ----------------------------------
تعليق توضيحي مخصص:
عند استخدام @interface لتخصيص التعليقات التوضيحية، يتم توريث واجهة java.lang.annotation.Annotation تلقائيًا، ويتم إكمال التفاصيل الأخرى تلقائيًا بواسطة المترجم. عند تحديد التعليقات التوضيحية، لا يمكنك وراثة التعليقات التوضيحية أو الواجهات الأخرى. يتم استخدام @interface للإعلان عن تعليق توضيحي، وكل طريقة تعلن فعليًا عن معلمة تكوين. اسم الطريقة هو اسم المعلمة، ونوع قيمة الإرجاع هو نوع المعلمة (يمكن أن يكون نوع قيمة الإرجاع عبارة عن أنواع أساسية فقط، أو فئة، أو سلسلة، أو تعداد). يمكنك إعلان القيمة الافتراضية للمعلمة بشكل افتراضي.
تحديد تنسيق التعليق التوضيحي:
اسم التعليق التوضيحي @interface العام {نص التعريف}
أنواع البيانات المدعومة لمعلمات التعليقات التوضيحية:
1. جميع أنواع البيانات الأساسية (int، float، boolean، byte، double، char، long، short)
2. نوع السلسلة 3. نوع الفئة 4. نوع التعداد 5. نوع التعليق التوضيحي 6. المصفوفات من جميع الأنواع المذكورة أعلاه
كيفية تعيين المعلمات في نوع التعليق التوضيحي:
أولاً، لا يمكن تعديلها إلا باستخدام حقي الوصول العام أو الافتراضي. على سبيل المثال، يتم تعيين قيمة السلسلة () هنا على النوع الافتراضي؛
ثانيًا، يمكن لأعضاء المعلمات استخدام أنواع البيانات الأساسية الثمانية فقط وهي البايت، والقصير، والشار، والكثافة السكانية، والطويلة، والعائمة، والمزدوجة، والمنطقية، وأنواع البيانات مثل السلسلة، والتعداد، والفئة، والتعليقات التوضيحية، والمصفوفات من هذه الأنواع، على سبيل المثال. قيمة السلسلة ()؛ عضو المعلمة هنا هو سلسلة؛
ثالثًا، إذا كان هناك عضو معلمة واحد فقط، فمن الأفضل تعيين اسم المعلمة إلى "قيمة" متبوعة بأقواس. مثال: يحتوي التعليق التوضيحي FruitName في المثال التالي على عضو معلمة واحد فقط.
التعليقات التوضيحية المخصصة البسيطة وأمثلة لاستخدام التعليقات التوضيحية:
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* ملاحظات على أسماء الفاكهة
* @المؤلف بيدا
*
*/
@Target(ElementType.FIELD)
@الاحتفاظ(RetentionPolicy.RUNTIME)
@موثقة
@interface اسم الفاكهة العام {
قيمة السلسلة () الافتراضية ""؛
}
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* شرح لون الفاكهة
* @المؤلف بيدا
*
*/
@Target(ElementType.FIELD)
@الاحتفاظ(RetentionPolicy.RUNTIME)
@موثقة
@interface العامة FruitColor {
/**
* تعداد الألوان
* @المؤلف بيدا
*
*/
التعداد العام Color{BULE,RED,GREEN};
/**
* سمات اللون
* @يعود
*/
Color FruitColor() default Color.GREEN;
}
import annotation.FruitColor.Color;
الطبقة العامة أبل {
@FruitName("أبل")
سلسلة خاصة اسم التفاح؛
@FruitColor(fruitColor=Color.RED)
سلسلة خاصة appleColor؛
مجموعة الفراغ العامAppleColor(سلسلة appleColor) {
this.appleColor = appleColor;
}
سلسلة عامة getAppleColor() {
إرجاع appleColor;
}
مجموعة الفراغ العامAppleName(سلسلة اسم التفاح) {
this.appleName = appleName;
}
سلسلة عامة getAppleName () {
إرجاع اسم التفاحة؛
}
اسم عرض الفراغ العام () {
System.out.println("اسم الفاكهة: تفاحة");
}
}