Java Annotations

الدروس التعليمية
Java

توفر التعليقات في جافا معلومات حول الكود. لا تؤثر التعليقات في جافا مباشرة على الكود الذي تعلق. في درس تعليقات جافا، سننظر في النقاط التالية؛

  1. التعليقات المدمجة في جافا
  2. كيفية كتابة تعليق مخصص
  3. استخدام التعليقات وكيفية تحليل التعليقات باستخدام واجهة برمجة التنعيم.

تعليقات جافا

ظهرت Java 1.5 بتقديم التعليقات والتعليمات، والآن يتم استخدامها بشكل كبير في إطارات Java EE مثل Hibernate، Jersey، و Spring. التعليقات في Java هي بيانات عن البرنامج مدمجة في البرنامج نفسه. يمكن تحليلها باستخدام أداة تحليل التعليقات أو المترجم. يمكننا أيضًا تحديد توفر التعليق إما أثناء وقت الترجمة فقط أو حتى وقت التنفيذ. قبل ظهور التعليقات في Java ، كانت بيانات البرنامج متاحة من خلال تعليقات Java أو من خلال Javadoc ، ولكن التعليقات تقدم أكثر من ذلك. يمكن أن تكون بيانات التعليقات متاحة أيضًا أثناء التشغيل، ويمكن لمحللي التعليقات استخدامها لتحديد تدفق العملية. على سبيل المثال، في خدمة Jersey نقوم بإضافة تعليق PATH مع سلسلة URI إلى طريقة، وخلال التشغيل ، يقوم Jersey بتحليلها لتحديد الطريقة التي يجب استدعاؤها لنمط URI المعطى.

تعليق Java المخصص

إن إنشاء تعليق مخصص مشابه لكتابة واجهة، باستثناء أن كلمة الواجهة تسبقها الرمز _@_. يمكننا تعريف الأساليب في التعليق. دعنا نرى مثالاً على تعليق مخصص في جافا ثم سنناقش ميزاته ونقاطه المهمة.

package com.journaldev.annotations;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Documented
@Target(ElementType.METHOD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface MethodInfo{
	String author() default "Pankaj";
	String date();
	int revision() default 1;
	String comments();
}

بعض النقاط المهمة حول تعليقات جافا هي:

  1. لا يمكن أن تحتوي أساليب التعليق على معلمات.
  2. أنواع إرجاع أساليب التعليق محدودة إلى المبادئ الأساسية، والسلاسل، والتعدادات، والتعليقات، أو مصفوفة من هذه الأنواع.
  3. يمكن أن تحتوي أساليب التعليق في جافا على قيم افتراضية.
  4. التعليقات يمكن أن تحتوي على تعليقات فوقية مرفقة بها. يُستخدم التعليق الفوقي لتوفير معلومات حول التعليق.

التعليقات الفوقية في جافا

هناك خمسة أنواع من التعليقات الفوقية:

  1. @Documented – تشير إلى أن العناصر التي تستخدم هذا التعليق يجب أن توثق من قبل javadoc وأدوات مماثلة. يجب استخدام هذا النوع لتوثيق تصريحات الأنواع التي تؤثر تعليقاتها على استخدام العناصر المعلَّمة من قِبل عملائها. إذا كان تعريف النوع موسومًا بـ Documented، فإن تعليقاته تصبح جزءًا من واجهة برمجة التطبيقات العمومية للعناصر المعلَّمة.
  2. الهدف – يشير إلى أنواع العناصر البرمجية التي يمكن تطبيق نوع التعليق عليها. بعض القيم الممكنة هي النوع، الطريقة، البناء، الحقل، إلخ. إذا لم تكن معلمة Target meta-annotation موجودة، فإن التعليق يمكن استخدامه على أي عنصر برمجي.
  3. موروث – يشير إلى أن نوع التعليق يورث تلقائيا. إذا استفسر المستخدم عن نوع التعليق على تصريح فئة، وكان تصريح الفئة لا يحتوي على تعليق لهذا النوع، فسيتم الاستعلام تلقائيا عن تعليق نوع الفئة الأساسية. سيتم تكرار هذه العملية حتى يتم العثور على تعليق لهذا النوع، أو يتم الوصول إلى أعلى تسلسل للفئة (Object).
  4. الاحتفاظ – يشير إلى مدى استمرارية التعليقات ذات النوع المحدد. يأخذ معه وسيط RetentionPolicy القيم الممكنة هي SOURCE، CLASS، و RUNTIME
  5. قابل للتكرار – يستخدم للدلالة على أن نوع التعليق الذي يحدد إعلانه قابل للتكرار.

التعليقات المضمنة في جافا

توفر جافا خمس تعليقات مدمجة.

  1. @Override – عندما نريد استبدال طريقة من الفئة الأساسية، يجب علينا استخدام هذا التعليق لإبلاغ المترجم أننا نقوم بالاستبدال. لذلك عندما تتم إزالة أو تغيير طريقة الفئة الأساسية، سيظهر المترجم رسالة خطأ. تعرف على السبب في أننا يجب دائمًا استخدام تعليق استبدال جافا أثناء الاستبدال لطريقة.
  2. @Deprecated – عندما نريد أن يعرف المترجم أن طريقة معينة قديمة، يجب علينا استخدام هذا التعليق. توصي جافا بتقديم معلومات في جافادوك بشأن سبب قديم هذه الطريقة وما هو البديل لاستخدامها.
  3. @SuppressWarnings – هذا فقط لإبلاغ المترجم بتجاهل تحذيرات معينة ينتجونها، على سبيل المثال استخدام أنواع غير معالجة في تخصيصات جافا. سيتم التخلص منه بواسطة المترجم لأنه سيتم حفظه بسياسته SOURCE.
  4. @FunctionalInterface – تم تقديم هذا التعليق في جافا 8 للإشارة إلى أن الواجهة مقصود أن تكون واجهة وظيفية.
  5. @SafeVarargs – تأكيد للمبرمج أن جسم الطريقة المحددة أو البناء لا يقوم بأي عمليات غير آمنة على معلمته varargs.

مثال على تعليقات جافا

لنرى مثالًا جافاً يظهر استخدام التعليقات المضمنة في جافا بالإضافة إلى استخدام التعليق المخصص الذي أنشأناه في المثال أعلاه.

package com.journaldev.annotations;

import java.io.FileNotFoundException;
import java.util.ArrayList;
import java.util.List;

public class AnnotationExample {

	public static void main(String[] args) {
	}

	@Override
	@MethodInfo(author = "Pankaj", comments = "Main method", date = "Nov 17 2012", revision = 1)
	public String toString() {
		return "Overriden toString method";
	}

	@Deprecated
	@MethodInfo(comments = "deprecated method", date = "Nov 17 2012")
	public static void oldMethod() {
		System.out.println("old method, don't use it.");
	}

	@SuppressWarnings({ "unchecked", "deprecation" })
	@MethodInfo(author = "Pankaj", comments = "Main method", date = "Nov 17 2012", revision = 10)
	public static void genericsTest() throws FileNotFoundException {
		List l = new ArrayList();
		l.add("abc");
		oldMethod();
	}

}

I believe above java annotation example is self-explanatory and showing the use of annotations in different cases.

تحليل تعليقات جافا

سنستخدم الانعكاس لتحليل تعليقات جافا من الفئة. يرجى ملاحظة أن سياسة الاحتفاظ بالتعليق يجب أن تكون RUNTIME وإلا فلن يكون معلوماته متاحة في وقت التشغيل ولن نتمكن من استرداد أي بيانات منه.

package com.journaldev.annotations;

import java.lang.annotation.Annotation;
import java.lang.reflect.Method;

public class AnnotationParsing {

	public static void main(String[] args) {
		try {
			for (Method method : AnnotationParsing.class.getClassLoader()
					.loadClass(("com.journaldev.annotations.AnnotationExample")).getMethods()) {
				// يتحقق مما إذا كان التعليق الموجود لطريقة MethodInfo موجودًا
				if (method.isAnnotationPresent(com.journaldev.annotations.MethodInfo.class)) {
					try {
						// يكرر جميع التعليقات المتاحة في الطريقة
						for (Annotation anno : method.getDeclaredAnnotations()) {
							System.out.println("Annotation in Method '" + method + "' : " + anno);
						}
						MethodInfo methodAnno = method.getAnnotation(MethodInfo.class);
						if (methodAnno.revision() == 1) {
							System.out.println("Method with revision no 1 = " + method);
						}

					} catch (Throwable ex) {
						ex.printStackTrace();
					}
				}
			}
		} catch (SecurityException | ClassNotFoundException e) {
			e.printStackTrace();
		}
	}

}

إخراج البرنامج أعلاه هو:

Annotation in Method 'public java.lang.String com.journaldev.annotations.AnnotationExample.toString()' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=1, comments=Main method, date=Nov 17 2012)
Method with revision no 1 = public java.lang.String com.journaldev.annotations.AnnotationExample.toString()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.oldMethod()' : @java.lang.Deprecated()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.oldMethod()' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=1, comments=deprecated method, date=Nov 17 2012)
Method with revision no 1 = public static void com.journaldev.annotations.AnnotationExample.oldMethod()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.genericsTest() throws java.io.FileNotFoundException' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=10, comments=Main method, date=Nov 17 2012)

واجهة برمجة التطبيقات للانعكاس قوية جدًا وتستخدم على نطاق واسع في جافا، إطارات J2EE مثل Spring، Hibernate، JUnit، تحقق من الانعكاس في جافا. هذا كل شيء بالنسبة لمثال تعليقات جافا، آمل أن تكون قد استفدت شيئًا منه. تحديثات التعليقات في جافا:

  1. لقد قدمت مواصفات الخدمة 3.0 استخدام التعليقات لتكوين خواص الخدمة ومعلمات التهيئة، اقرأ المزيد في دليل خدمة Java.
  2. يمكننا استخدام التعليقات في Struts 2 لتكوين فصول العمل وصفحات النتائج، تحقق من المثال العملي في مثال توضيحي لمرحبًا بك في Struts 2.

المرجع: موقع Oracle

Source:
https://www.digitalocean.com/community/tutorials/java-annotations