سياسات الاحتفاظ وأنواع الأهداف
اختر احتفاظ SOURCE أو CLASS أو RUNTIME، وقيّد العناصر المستهدفة باستخدام @Target
سياسات الاحتفاظ وأنواع الأهداف درس مجاني في Java Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Java Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Java Academy 4 دروس في المجموع.
سياسات الاحتفاظ الثلاث
SOURCE: يتخلص منه المترجم (ولا يفيد إلا في APT). CLASS: يُكتب في ملفات .class ولا يكون متاحًا وقت التشغيل. RUNTIME: يكون متاحًا عبر الانعكاس. تستخدم معظم التعليقات التوضيحية الخاصة بالأطر سياسة RUNTIME.
الاحتفاظ بـ SOURCE: وقت الترجمة فقط
تُعالَج التعليقات التوضيحية من نوع SOURCE بواسطة معالجات التعليقات التوضيحية ثم يُتخلَّص منها. إن @Override و@SuppressWarnings من نوع SOURCE؛ فهما يقدّمان معلومات للمترجم، لكنهما لا يظهران في ملف .class.
@Retention(RetentionPolicy.SOURCE)
public @interface GenerateBuilder {}
// APT generates a Builder class when it sees @GenerateBuilder
// The annotation itself disappears from the compiled outputالاحتفاظ بـ CLASS: تحليل الرمز الثنائي
تُضمَّن التعليقات التوضيحية من نوع CLASS في ملفات .class لكي تستخدمها أدوات تحليل الرمز الثنائي (PMD وFindBugs وASM)، لكنها ليست قابلة للقراءة وقت التشغيل عبر الانعكاس.
@Retention(RetentionPolicy.CLASS)
public @interface ThreadSafe {}
// Visible in bytecode, invisible to Class.getAnnotation() at runtimeالاحتفاظ بـ RUNTIME: المعالجة بالانعكاس
تبقى التعليقات التوضيحية من نوع RUNTIME حتى وقت التشغيل، ويمكن قراءتها باستخدام getAnnotation(). تستخدم Spring وJUnit وJackson وHibernate سياسة الاحتفاظ RUNTIME.
@Retention(RetentionPolicy.RUNTIME)
public @interface Route {
String path();
String method() default "GET";
}
// At runtime:
Route r = handler.getClass().getMethod("handle").getAnnotation(Route.class);
System.out.println(r.path()); // e.g. "/users"@Target: تقييد مواضع التطبيق
يستخدم @Target ثوابت ElementType لتقييد المواضع التي يمكن أن يظهر فيها التعليق التوضيحي. ويؤدي تطبيقه على عنصر غير مسموح به إلى ظهور خطأ وقت الترجمة.
import static java.lang.annotation.ElementType.*;
@Target({METHOD, CONSTRUCTOR})
@Retention(RetentionPolicy.RUNTIME)
public @interface Measured {}جميع قيم ElementType
القائمة الكاملة: TYPE (إعلان فئة أو واجهة أو تعداد)، وFIELD، وMETHOD، وPARAMETER، وCONSTRUCTOR، وLOCAL_VARIABLE، وANNOTATION_TYPE، وPACKAGE، وTYPE_PARAMETER (معلمة نوع عامة)، وTYPE_USE (أي استخدام لنوع).
// TYPE_USE: annotate any type reference
@NotNull String name;
List<@NonNull String> items;
public @Valid User createUser(@NotNull String name) { ... }TYPE مقابل TYPE_USE
يستهدف TYPE إعلانات الفئات والواجهات والتعدادات. أما TYPE_USE (في Java 8 وما بعده) فيستهدف أي استخدام لنوع، بما في ذلك الأنواع العامة والتحويلات وبنود extends، مما يتيح تعليقات توضيحية لسلامة الأنواع من القيم الفارغة.
@Target(ElementType.TYPE_USE)
@interface NonNull {}
// Can be applied to:
List<@NonNull String> list;
@NonNull String result = (@NonNull String) obj;الجمع بين Target وRetention
تجمع معظم التعليقات التوضيحية المفيدة الخاصة بالأطر بين الاحتفاظ من نوع RUNTIME وأهداف محددة. ومن أمثلتها تعليق توضيحي للتحقق يُطبَّق على الحقول فقط.
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Range {
int min() default 0;
int max() default Integer.MAX_VALUE;
}توريث التعليقات التوضيحية باستخدام @Inherited
إن @Inherited تعليق توضيحي فوقي يجعل التعليقات التوضيحية على مستوى الفئة موروثةً في الفئات الفرعية. ولا يؤثر في التعليقات التوضيحية على مستوى الدوال أو الحقول.
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Framework {}
@Framework class Base {}
class Child extends Base {} // @Framework visible on Child too@Documented: تضمين التعليقات في Javadoc
طبّق @Documented لكي يظهر التعليق التوضيحي في Javadoc المُنشأ للعناصر التي تحمل هذا التعليق. وبدونه، تكون التعليقات التوضيحية غير ظاهرة في توثيق الواجهة البرمجية.
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Auditable {
String description() default "";
}قراءة معلومات الاحتفاظ وقت التشغيل
يمكنك فحص مدة الاحتفاظ بنوع التعليق التوضيحي نفسه باستخدام getAnnotation(Retention.class) على كائن الفئة الخاص بالتعليق التوضيحي.
Retention r = Retry.class.getAnnotation(Retention.class);
System.out.println(r.value()); // RUNTIME, CLASS, or SOURCEتحقق سريع
أي قيمة من ElementType تغطي إعلانات الفئات والواجهات والتعدادات؟
مراجعة
استخدم SOURCE لأدوات وقت الترجمة، وCLASS لتحليل الرمز الثنائي، وRUNTIME للأطر التي تعتمد على الانعكاس. قيّد الاستخدام باستخدام @Target لمنع إساءة الاستخدام. أضف @Documented لتعليقات الواجهة البرمجية التوضيحية، و@Inherited للتعليقات التوضيحية الخاصة بالتسلسل الهرمي للفئات.
الأسئلة الشائعة
هل درس «سياسات الاحتفاظ وأنواع الأهداف» مجاني؟
نعم — نص درس «سياسات الاحتفاظ وأنواع الأهداف» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Java Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Java Academy 4 دروس في المجموع.
ماذا ستتعلم في «سياسات الاحتفاظ وأنواع الأهداف»؟
اختر احتفاظ SOURCE أو CLASS أو RUNTIME، وقيّد العناصر المستهدفة باستخدام @Target تتمرن على Java Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Java Academy؟
لا تُشترط خبرة سابقة. Java Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.
كم من الوقت يستغرق درس «سياسات الاحتفاظ وأنواع الأهداف»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Java Academy هذا؟
نعم. كل درس في Java Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية
- سياسات الاحتفاظ وأنواع الأهداف
- معالجة التعليقات التوضيحية أثناء التشغيل
- معالجات التعليقات التوضيحية أثناء الترجمة