تحليل التعليقات في Java (Annotation)

مقدمة

　　　　　　 أدخل Java تعليقات Annotation في إصدار 1.5،والمعروفة أيضًا بـ Java Annotations،تعليق هو بيانو متعدد الوظائف يمكن استخدامه مباشرة في الكود المصدر،ويمكن تعليق الفئات/الطرق/المتغيرات/المتغيرات/اسم الحزمة،وما إلى ذلك.على عكس علامات Javadoc،يمكن للمعالج أن يحافظ على كود التعليقات عند إنشاء ملف class،وإذا كان من الممكن استخدام التعليقات أثناء تشغيل البرنامج (runtime)،فسيحافظ محول Java على التعليقات،وهذا يمكن أن يتم من خلال الاستدلال للحصول على معلومات تعليقات Annotation.

التعليقات المدمجة

في الواقع، نحن نلتقي دائمًا بالتعليقات، مثل @Override،@Deprecated،وهذه هي التعليقات المدمجة في JDK،دعونا نرى ما هي تعليقات Java المدمجة الرئيسية.
　• تُستخدم الملاحظات للاستخدام في الكود المصدر لـ Java
◦@Override يتحقق من أن الطريقة هي طريقة تعديل، وإذا لم يتم العثور على هذه الطريقة في الفئة الأم أو الواجهة المُستخدمة، سيتم إرسال خطأ أثناء عملية التجميع.
　◦@Deprecated يُشير إلى أن الطريقة أو الفئة قد تم إزالتها، وإذا تم استخدام هذه الفئة أو الطريقة، سيتم إرسال تحذير أثناء عملية التجميع
　◦@SuppressWarnings يخبر محول الكود عن تجاهل التحذيرات المتعلقة بالمعلومات الم标注ة
　◦@SafeVarargs يتجاهل التحذيرات المتعلقة بتحويلات الجنسيات في الدعوات إلى طرق أو بناء كائنات يحتوي على معلمات جينية، ملاحظة جديدة إضافية في 1.7
　◦@FunctionalInterface يشير إلى أن واجهة تم إعلانها ستستخدم كواجهة وظيفية، ملاحظة جديدة إضافية في 1.8

• تُسمى الملاحظات التي تُستخدم للاستخدام في ملاحظات أخرى ملاحظات meta (Meta Annotation)
◦@Retention يشير إلى وقت استخدام الملاحظة الم标注ت (أي وقت حفظ الملاحظة)
■ يتم الاحتفاظ بها فقط في الكود المصدر، ويتم التخلص منها أثناء عملية التجميع (RetentionPolicy.RUNTIME)
　■ يتم حفظ الملاحظات أثناء عملية التجميع في ملفات class، ويتم تجاهلها عند تحميل ملفات class (RetentionPolicy.CLASS)
　■ تُقرأ الملاحظات عند تحميل ملفات class، أي أنها متاحة أثناء التشغيل، يمكن الحصول على معلومات الملاحظة باستخدام الت反射 (RetentionPolicy.RUNTIME)

　◦@Documented يشير إلى أن الملاحظة الم标注ت سيتم كتابتها في وثائق Javadoc عند إنشاءها
　◦@Target يشير إلى نطاق تأثير الملاحظة الم标注ت
■ElementType.TYPE: يستخدم لوصف الفئات والواجهات (بما في ذلك أنواع الملاحظات) أو إعلانات enum
　■ElementType.FIELD: يستخدم لوصف الحقول
　■ElementType.METHOD: يستخدم لوصف الطرق
　■ElementType.PARAMETER: يستخدم لوصف المعلمات
　■ElementType.CONSTRUCTOR: يستخدم لوصف المكونات
　■ElementType.LOCAL_VARIABLE: يستخدم لوصف المتغيرات المحلية
　■ElementType.ANNOTATION_TYPE: يستخدم لوصف الملاحظات
　■ElementType.PACKAGE: يستخدم لوصف الحزم

　◦@Inherited يشير إلى أن الملاحظة الم标注ت يتم انتقالها، مما يعني إذا تم استخدام نوع الملاحظة الم修饰ة بـ@Inherited في فئة، فإن الملاحظة ستتأثير أيضًا على الفرع.
　◦@Repeatable يشير إلى أن التعليق المُسجل يمكن تكراره عدة مرات على نفس الكائن، تم إضافة التعليق في الإصدار 1.9

　تعريف التعليق المخصص

تم مناقشة العديد من التعليقات، يجب أن نركز على التعليقات الأساسية، عند تعريف تعليق مخصص، نستخدم التعليقات الأساسية لمساعدتنا. شكل التعليق المخصص هو public @interface اسم_التعليق {جسم التعليق}، عند استخدام @interface لتحديد التعليق، يتم تنسيق java.lang.annotation.Annotation تلقائيًا. عند تعريف التعليق المخصص، لا يمكن توريث التعليقات أو الواجهات الأخرى.

تعريف التعليق المخصص بسيط، باستخدام @interface لتحديد تعليق، مثلما يلي.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface ClassInfo {
 String author() default "Wang";
 String date();
 String comments();
}

تم تعريف تعليق مخصص يُدعى ClassInfo، يمكن معرفة من خلال @Retention أن هذا التعليق سيكون دائمًا موجودًا، أي أثناء تشغيل البرنامج، سيظل هذا التعليق صالحًا؛ @Target(ElementType.TYPE) يوضح أن تعليق ClassInfo يعمل على الكائنات أو الأنواع أو enum المُعلن عنها؛ @Documented
يُمكن كتابة معلومات ClassInfo في وثائق Javadoc.

دعنا نرى بعض معلمات التعليق المخصصة، تحتوي على ثلاثة معلمات تعليق، يمكن تعيين قيم افتراضية للمعلمات التعليق، مثل معلمت التعليق author، القيمة الافتراضية هي Wang، بينما لا تحتوي المعلمتين الأخرى على قيم افتراضية.

دعنا نرى التعليق المخصص الآخر.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface MethodInfo {
 String description() default "No Description";
 String date();
}

التعليق المخصص MethodInfo يعمل على الطريقة، أثناء تشغيل البرنامج، سيكون هذا التعليق موجودًا أيضًا؛ يحتوي على معلمتين تعليق.

تعريف معلمات التعليق (تعريف الطريقة)، يمكن استخدام ميزات الوصول public أو default فقط، وتدعم أنواع المعلمات التالية.
　•أحد عشر نوعًا أساسيًا من البيانات (byte،int،short،long،float،double،char،boolean)
　•نوع String
　•نوع Class
　•نوع enum
　•نوع Annotation
　•جميع أنواع الأنواع المتعددة

استخدام التسمية

إضافةً إلى المقدارين المعدلين أعلاه، تم إضافة تسمية لمنطقة الحقل.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface FieldInfo {
 String type();
 String name();
}

إذا لم يتم تعريف قيمة افتراضية للمعلمات في التسمية المخصصة، يجب تخصيص هذه المعلمات عند استخدام التسمية المخصصة، وإلا سيقوم محرر الكود بإصدار خطأ.

لننظر في رمز استخدام التسمية:

@ClassInfo(author = "wang",
  date = "2016/9/13",
  comments = "demo annotation")
public class AnnotationDemo {
 @FieldInfo(type = "public", name = "firstField")
 public int firstField;
 @FieldInfo(type = "private", name = "secondField")
 private String secondField;
 @MethodInfo(description = "method in AnnotationDemo", name = "firstMethod")
 public void firstMethod(String value) {
  System.out.printf("method involved first");
 }
 @MethodInfo(description = "method in AnnotationDemo", name="secondMethod")
 private void secondMethod() {
  System.out.printf("method involved first");
 }
}

الحصول على معلومات التسمية

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

public class AnnotationTest {
 public static void main(String[] args) {
  resolveClassAnnotationInfo(AnnotationDemo.class);
  resolveFieldAnnotationInfo(AnnotationDemo.class);
  resolveMethodAnnotationInfo(AnnotationDemo.class);
 }
 private static void resolveClassAnnotationInfo(Class<?> clz) {
  // تحقق من أن هذا الكائن له تعليق ClassInfo
  if(clz.isAnnotationPresent(ClassInfo.class)) {
   ClassInfo classInfo = (ClassInfo) clz.getAnnotation(ClassInfo.class);
   System.out.println(classInfo.author() + " " + classInfo.comments() + " " + classInfo.date());
  }
 }
 private static void resolveFieldAnnotationInfo(Class<?> clz) {
  Field[] fields = clz.getDeclaredFields();
  لـ (Field field : fields) {
   if(field.isAnnotationPresent(FieldInfo.class)) {
    FieldInfo fieldInfo = (FieldInfo) field.getAnnotation(FieldInfo.class);
    System.out.println(fieldInfo.type() + " " + fieldInfo.name());
   }
  }
 }
 private static void resolveMethodAnnotationInfo(Class<?> clz) {
  Method[] methods = clz.getDeclaredMethods();
  لـ (Method method : methods) {
   if(method.isAnnotationPresent(MethodInfo.class)) {}}
    MethodInfo methodInfo = (MethodInfo) method.getAnnotation(MethodInfo.class);
    System.out.println(methodInfo.name() + " " + methodInfo.description());
   }
  }
 }
}

من خلال الت反射 في الكائنات للحصول على الحقول / الطرق وما إلى ذلك، للحصول على التعليقات باستخدام getAnnotation() أو getAnnotations() للحصول على التعليقات ذات الصلة، للحصول على التعليقات المحددة للحصول على المعلومات المحددة.

نتائج النشرة كما يلي:

الشكل-1 رسم نتائج العمل

النهاية

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

هذا هو نهاية محتوى هذا المقال، نأمل أن يكون قد ساعدكم في التعلم، ونأمل أن تحصلوا على دعمكم لموقع تعليمي "الصراخ".

بيان: محتوى هذا المقال تم جمعه من الإنترنت، ملكية المقال مملوكة للمالك الأصلي، تم جمع المحتوى من قبل المستخدمين عبر الإنترنت الذين قاموا بتحميله بشكل متعاوني، لا يمتلك هذا الموقع حقوق الملكية، لم يتم تعديل المحتوى بشكل يدوي، ولا يتحمل هذا الموقع أي مسؤولية قانونية مرتبطة بذلك. إذا رأيت محتوى يشتبه في حقوق النسخ، فالرجاء إرسال بريد إلكتروني إلى: notice#oldtoolbag.com (الرجاء استبدال #بـ @ عند إرسال البريد الإلكتروني) لتقديم الشكوى، وتقديم الدليل الداعم، وإذا تم التحقق من صحة الشكوى، سيقوم الموقع ب�除 المحتوى المتهمة بالسرقة بشكل فوري.