شرح جافا

📅 آخر تحديث: ١٧ يوليو ٢٠٢٦
✍️ نُشر في: ١٧ يوليو ٢٠٢٦
الموسوعة الحرة

في لغة برمجة جافا ، تُعدّ التعليقات التوضيحية شكلاً من أشكال البيانات الوصفية النحوية التي يمكن إضافتها إلى شفرة جافا المصدرية ، تمامًا مثل السمة . [ 1 ] يمكن إضافة التعليقات التوضيحية إلى الفئات ، والأساليب ، والمتغيرات ، والمعاملات ، وحزم جافا . وكما هو الحال مع وسوم Javadoc ، يمكن قراءة التعليقات التوضيحية في جافا من ملفات المصدر. ولكن على عكس وسوم Javadoc ، يمكن أيضًا تضمين التعليقات التوضيحية في جافا وقراءتها من ملفات فئات جافا التي يُنشئها مُصرّف جافا . وهذا يسمح لآلة جافا الافتراضية بالاحتفاظ بالتعليقات التوضيحية أثناء التشغيل وقراءتها عبر الانعكاس . [ 2 ] من الممكن إنشاء تعليقات توضيحية وصفية من التعليقات التوضيحية الموجودة في جافا. [ 3 ]

تاريخ

تتضمن منصة جافا آليات تعليق مخصصة متنوعة ، مثل transientالمُعدِّل @Deprecatedوعلامة جافا دوك. وقد أدخل طلب مواصفات جافا JSR-175 خاصية التعليق للأغراض العامة (المعروفة أيضًا باسم البيانات الوصفية ) إلى عملية مجتمع جافا في عام 2002، وحصل على الموافقة في سبتمبر 2004. [ 4 ]

أصبحت التعليقات التوضيحية متاحة في اللغة نفسها بدءًا من الإصدار 1.5 من مجموعة أدوات تطوير جافا (JDK). وفرت aptالأداة واجهة مؤقتة لمعالجة التعليقات التوضيحية في وقت الترجمة في الإصدار 1.5 من JDK؛ وقد تم إضفاء الطابع الرسمي على ذلك في JSR-269، وتم دمجها في مترجم javac في الإصدار 1.6.

في C++26 ، أضافت لغة C++ تعليقات توضيحية للانعكاس تشبه التعليقات التوضيحية في Java.

التعليقات التوضيحية المدمجة

تُعرّف لغة جافا مجموعة من التعليقات التوضيحية المدمجة فيها. من بين التعليقات التوضيحية القياسية السبعة، ثلاثة منها جزء من مكتبة java.lang ، أما الأربعة المتبقية فتُستورد من مكتبة أخرى java.lang.annotation. [ 5 ] [ 6 ]

شرحطَردوصف
@Deprecatedjava.langيُشير هذا إلى أن الطريقة قديمة. ويتسبب في ظهور تحذير أثناء الترجمة إذا تم استخدام الطريقة.
@FunctionalInterfacejava.langيُشير إلى واجهة المستخدم على أنها مصممة لتكون واجهة وظيفية.
@Overridejava.langيشير هذا إلى أن الدالة تُعيد تعريف دالة مُعرّفة في فئة أصلية. ويتسبب في حدوث خطأ في الترجمة إذا لم يتم العثور على الدالة في إحدى الفئات الأصلية أو الواجهات المُنفذة .
@SafeVarargsjava.langقم بإخفاء التحذيرات لجميع مستدعي طريقة أو مُنشئ مع مُعامل varargs عام ، منذ Java 7.
@SuppressWarningsjava.langيوجه هذا الأمر المترجم إلى كبت تحذيرات وقت الترجمة المحددة في معلمات التعليق التوضيحي.
@Documentedjava.lang.annotationيشير هذا إلى إضافة تعليق آخر لإدراجه في الوثائق.
@Inheritedjava.lang.annotationيشير إلى تعليق توضيحي آخر ليتم توريثه إلى الفئات الفرعية للفئة المعلقة (بشكل افتراضي، لا يتم توريث التعليقات التوضيحية بواسطة الفئات الفرعية).
@Nativejava.lang.annotationيشير إلى حقل يحدد قيمة ثابتة على أنه من المحتمل الرجوع إليه من التعليمات البرمجية الأصلية.
@Repeatablejava.lang.annotationيشير إلى تعليق آخر على أنه قابل للتكرار.
@Retentionjava.lang.annotationيحدد كيفية تخزين التعليق المميز، سواء كان ذلك في الكود فقط، أو يتم تجميعه في الفئة، أو يكون متاحًا في وقت التشغيل من خلال الانعكاس.
@Targetjava.lang.annotationيشير هذا إلى تعليق توضيحي آخر لتقييد نوع عناصر جافا التي يمكن تطبيق التعليق التوضيحي عليها.

في Jakarta EE (المعروفة سابقًا باسم Java Platform, Enterprise Edition)، توجد التعليقات التوضيحية التالية أيضًا في jakarta.annotation(سابقًا javax.annotation): [ 7 ] [ 8 ]

شرحطَردوصف
@Generatedjakarta.annotationيشير إلى شفرة المصدر التي تم إنشاؤها (أي لم يكتبها مستخدم، أو تم إنشاؤها تلقائيًا بواسطة جهاز كمبيوتر).
@Resourcejakarta.annotationيشير إلى فئة أو طريقة أو حقل كمرجع لمورد.
@Resourcesjakarta.annotationيُعلن عن مرجع للموارد، كحاوية لإعلانات موارد متعددة.
@PostConstructjakarta.annotationيشير إلى طريقة للإشارة إلى أنه يجب تنفيذها بعد حقن التبعية لإجراء التهيئة، أي يجب استدعاء الطريقة قبل استخدام الفئة.
@PreDestroyjakarta.annotationيُشير هذا إلى طريقة ما على أنها إشعار رد نداء للإشارة إلى أن المثيل قيد الإزالة بواسطة الحاوية، أي أن الطريقة تُستخدم لتحرير الموارد التي يحتفظ بها المثيل.
@Priorityjakarta.annotationتُستخدم هذه العلامات لتحديد ترتيب استخدام عناصر البرنامج.
@Nonnulljakarta.annotationيُشير إلى أي عنصر لا يمكن أن يكون null.
@Nullablejakarta.annotationيشير إلى أي عنصر لديه إمكانية صريحة ليكون null.
@RunAsjakarta.annotationيحدد هذا الدور الأمني ​​للتطبيق أثناء تنفيذه في حاوية Jakarta EE.
@RolesAllowedjakarta.annotation.securityيحدد هذا الأسلوب طريقة لتحديد أدوار الأمان المسموح لها بالوصول إلى الأسلوب.
@PermitAlljakarta.annotation.securityيحدد هذا الأسلوب إمكانية وصول جميع الأدوار الأمنية إليه.
@DenyAlljakarta.annotation.securityيحدد هذا الأسلوب أنه لا يجوز لأي أدوار أمنية الوصول إلى الأسلوب.
@DeclareRolesjakarta.annotation.securityيحدد أدوار الأمان التي يستخدمها التطبيق.
@DataSourceDefinitionjakarta.annotation.sqlيُعرّف حاوية DataSourceمسجلة في واجهة تسمية ودليل جافا (JNDI).
@DataSourceDefinitionsjakarta.annotation.sqlيُعلن عن حاوية DataSource، تعمل كحاوية لإعلانات مصادر البيانات المتعددة.

كانت هناك سابقًا إضافةٌ تُسمى `<managedBean>` @ManagedBean، موجودة في ` jakarta.annotation<managedBean>`، والتي كانت تُستخدم تاريخيًا للإعلان عن كائن مُدار بواسطة حاوية، وهو كائن مُدار بواسطة حاوية يدعم مجموعة صغيرة من الخدمات الأساسية مثل حقن الموارد، وردود استدعاء دورة الحياة، والمُعترضات. ومع ذلك، فقد تمت إزالتها. [ 9 ] [ 10 ]

مثال

التعليقات التوضيحية المدمجة

يوضح هذا المثال استخدام @Overrideالتعليق التوضيحي. فهو يُوجه المُصرّف للتحقق من وجود توابع مُطابقة في الفئات الأصلية. في هذه الحالة، يظهر خطأ لأن التابع gettype()في الفئة Cat لا يُعيد تعريف التابع getType()في الفئة Animal كما هو مطلوب، وذلك بسبب عدم تطابق حالة الأحرف . في حال عدم وجود التعليق التوضيحي، سيتم إنشاء @Overrideتابع جديد باسم في الفئة Cat.gettype()

public class Animal { public void speak () {}public String getType () { return "Generic animal" ; } }public class Cat extends Animal { @Override public void speak () { // هذا تعديل جيد. System . out . println ( "مواء." ); }@Override public String gettype () { // خطأ في وقت الترجمة بسبب خطأ إملائي: يجب أن يكون getType() وليس gettype(). return "Cat" ; } }

التعليقات التوضيحية المخصصة

تتشابه تعريفات أنواع التعليقات التوضيحية مع تعريفات الواجهات العادية. يسبق رمز @ الكلمة المفتاحية "interface".

// @Twizzle هو تعليق توضيحي للدالة toggle(). @Twizzle public void toggle () {}// يُعلن عن التعليق التوضيحي Twizzle. public @interface Twizzle {}

قد تتضمن التعليقات التوضيحية مجموعة من أزواج المفاتيح والقيم، والتي تُنمذج كطرق من نوع التعليق التوضيحي. يُعرّف كل تعريف طريقة عنصرًا من نوع التعليق التوضيحي. يجب ألا تحتوي تعريفات الطرق على أي معلمات أو عبارة throws. تقتصر أنواع الإرجاع على الأنواع الأولية ، والسلاسل النصية ، والفئات، والتعدادات ، والتعليقات التوضيحية، ومصفوفات الأنواع السابقة. يمكن أن تحتوي الطرق على قيم افتراضية .

// نفس الشيء كما يلي: @Edible(value = true) @Edible ( true ) Item item = new Carrot ();public @interface Edible { boolean value () default false ; }@Author ( first = "Oompah" , last = "Loompah" ) Book book = new Book ();public @interface Author { String first (); String last (); }

يمكن إضافة تعليقات توضيحية إلى التعليقات نفسها للإشارة إلى مكان وزمان استخدامها:

استيراد java.lang.annotation.* ;@Retention ( RetentionPolicy.RUNTIME ) // اجعل هذا التعليق التوضيحي متاحًا في وقت التشغيل عبر الانعكاس. @Target ( { ElementType.METHOD } ) // لا يمكن تطبيق هذا التعليق التوضيحي إلا على أساليب الفئة. public @interface Tweezable {}

يحتفظ المترجم بمجموعة من التعليقات التوضيحية الخاصة (بما في ذلك و @Deprecated) لأغراض نحوية.@Override@SuppressWarnings

تُستخدم التعليقات التوضيحية على نطاق واسع في أطر العمل كوسيلة لتطبيق سلوكيات مُيسّرة على الفئات والأساليب المُعرّفة من قِبل المستخدم، والتي يجب تعريفها في مصدر خارجي (مثل ملف تكوين XML) أو برمجيًا (عبر استدعاءات واجهة برمجة التطبيقات). [ 11 ] على سبيل المثال، تستخدم مكتبة Project Lombok التعليقات التوضيحية بشكل مكثف لتقليل الشيفرة النمطية. [ 12 ] فيما يلي، على سبيل المثال، فئة بيانات Jakarta Persistence مع التعليقات التوضيحية :

package org.wikipedia.examples ;استيراد java.io.Serializable ؛استيراد jakarta.persistence.Column ؛ استيراد jakarta.persistence.Entity ؛ استيراد jakarta.persistence.GenerationType ؛ استيراد jakarta.persistence.GeneratedValue ؛ استيراد jakarta.persistence.Id ؛ استيراد jakarta.persistence.Table ؛@Entity // يُعلن عن هذا كائن كيان @Table ( name = "people" ) // يربط الكائن بجدول SQL "people" public class Person implements Serializable { @Id // يربط هذا بعمود المفتاح الأساسي. @GeneratedValue ( strategy = GenerationType.AUTO ) // ستُنشئ قاعدة البيانات مفاتيح أساسية جديدة ، وليس نحن. private Integer id ;@Column ( length = 32 ) // اقتطاع قيم العمود إلى 32 حرفًا. private String name ;public Integer getId () { return id ; }public void setId ( Integer id ) { this . id = id ; }public String getName () { return name ; }public void setName ( String name ) { this . name = name ; } }

لا تُعدّ التعليقات التوضيحية استدعاءات للدوال، ولن تُحدث أي تغيير بمفردها. بل يتم تمرير كائن الفئة إلى تطبيق Jakarta Persistence أثناء التشغيل ، والذي يقوم بدوره باستخراج التعليقات التوضيحية لإنشاء ربط بين الكائن والقاعدة العلائقية .

فيما يلي مثال كامل:

package org.wikipedia.examples.annotation ;استيراد java.lang.annotation.Documented ؛ استيراد java.lang.annotation.ElementType ؛ استيراد java.lang.annotation.Inherited ؛ استيراد java.lang.annotation.Retention ؛ استيراد java.lang.annotation.RetentionPolicy ؛ استيراد java.lang.annotation.Target ؛@Documented @Retention ( RetentionPolicy.RUNTIME ) @Target ( { ElementType.TYPE , ElementType.METHOD , ElementType.CONSTRUCTOR , ElementType.ANNOTATION_TYPE , ElementType.PACKAGE , ElementType.FIELD , ElementType.LOCAL_VARIABLE } ) @Inherited public @interface Unfinished { public enum Priority { LOW , MEDIUM , HIGH } String value ( ) ; String [ ] changedBy ( ) default " " ; String [ ] lastChangedBy ( ) default " " ; Priority priority ( ) default Priority.MEDIUM ; String createdBy ( ) default " James Gosling " ; String lastChanged ( ) default " 2011-07-08 " ; }
package org.wikipedia.examples.annotation ;public @interface UnderConstruction { String owner () default "Patrick Naughton" ; String value () default "Object is Under Construction." ; String createdBy () default "Mike Sheridan" ; String lastChanged () default "2011-07-08" ; }

ثم باستخدام تطبيق Jakarta Faces :

package org.wikipedia.examples.validators ;استيراد jakarta.faces.application.FacesMessage ؛ استيراد jakarta.faces.component.UIComponent ؛ استيراد jakarta.faces.context.FacesContext ؛ استيراد jakarta.faces.validator.Validator ؛ استيراد jakarta.faces.validator.ValidatorException ؛استيراد org.wikipedia.examples.annotation.UnderConstruction ؛ استيراد org.wikipedia.examples.annotation.Unfinished ؛ استيراد org.wikipedia.examples.annotation.Unfinished.Priority ؛ استيراد org.wikipedia.examples.util.Util ؛@UnderConstruction ( owner = "Jon Doe" ) public class DateValidator implements Validator { public void validate ( FacesContext context , UIComponent component , Object value ) throws ValidatorException { String date = ( String ) value ; String errorLabel = "الرجاء إدخال تاريخ صحيح." ; if ( ! component.getAttributes ( ). isEmpty ()) { errorLabel = ( String ) component.getAttributes ( ). get ( " errordisplayval " ); }إذا لم يتم التحقق من صحة التاريخ المُعطى (` date` )، فسيتم تنفيذ ما يلي: `@Unfinished ( changedBy = " Steve " , value = " تأكيد ما إذا كان سيتم إضافة الرسالة إلى السياق أم لا، تأكيد " , priority = Priority.HIGH ) FacesMessage message = new FacesMessage ( ) ; message.setSeverity ( FacesMessage.SEVERITY_ERROR ) ; message.setSummary ( errorLabel ) ; message.setDetail ( errorLabel ) ; throw new ValidatorException ( message ) ; } } } `

يعالج

عند تجميع كود جافا المصدري، يمكن معالجة التعليقات التوضيحية بواسطة مكونات إضافية للمُجمِّع تُسمى معالجات التعليقات التوضيحية. تستطيع هذه المعالجات إنتاج رسائل إعلامية أو إنشاء ملفات أو موارد مصدرية إضافية لجافا، والتي بدورها قد تُجمَّع وتُعالَج. مع ذلك، لا تستطيع معالجات التعليقات التوضيحية تعديل الكود المُعلَّق عليه نفسه. (يمكن تنفيذ تعديلات الكود باستخدام طرق تتجاوز مواصفات لغة جافا). يقوم مُجمِّع جافا بتخزين بيانات تعريف التعليقات التوضيحية بشكل مشروط في ملفات الفئات، إذا كان للتعليق التوضيحي قيمة `true` RetentionPolicyأو CLASS`false` RUNTIME. لاحقًا، يمكن لآلة جافا الافتراضية أو برامج أخرى البحث عن بيانات التعريف لتحديد كيفية التفاعل مع عناصر البرنامج أو تغيير سلوكها.

بالإضافة إلى معالجة التعليقات التوضيحية باستخدام معالج التعليقات التوضيحية، يمكن لمبرمج جافا كتابة كود خاص به يستخدم تقنية الانعكاس لمعالجة التعليقات التوضيحية. يدعم Java SE 5 واجهة جديدة مُعرَّفة في java.lang.reflectالحزمة. تحتوي هذه الحزمة على واجهة تُسمى `repplication` AnnotatedElement، والتي تُنفَّذ بواسطة فئات انعكاس جافا Class، بما في ذلك ` Constructorrepplication` و` Fieldrepplication` و` Methodrepplication` و`repplication` Package. تُستخدم تطبيقات هذه الواجهة لتمثيل عنصر مُعلَّق عليه في البرنامج قيد التشغيل حاليًا في آلة جافا الافتراضية. تسمح هذه الواجهة بقراءة التعليقات التوضيحية باستخدام تقنية الانعكاس.

تتيح هذه AnnotatedElementالواجهة الوصول إلى التعليقات التوضيحية التي تحتفظ بالبيانات RUNTIME. ويتم توفير هذا الوصول من خلال الطرق التالية: getAnnotation` getAnnotationsand` و`and` isAnnotationPresent. ولأن أنواع التعليقات التوضيحية تُجمَّع وتُخزَّن في ملفات بايت كود تمامًا مثل الفئات، يمكن الاستعلام عن التعليقات التوضيحية التي تُرجعها هذه الطرق تمامًا مثل أي كائن جافا عادي. فيما يلي مثال كامل لمعالجة تعليق توضيحي:

package org.wikipedia.examples.annotation ;استيراد java.lang.annotation.Retention ؛ استيراد java.lang.annotation.RetentionPolicy ؛// هذا هو التعليق المراد معالجته // القيمة الافتراضية للهدف هي جميع عناصر جافا // تغيير سياسة الاحتفاظ إلى وقت التشغيل (الافتراضي هو فئة) @Retention ( RetentionPolicy . RUNTIME ) public @interface TypeHeader { // القيمة الافتراضية المحددة لخاصية المطور String developer () default "Unknown" ; String lastModified (); String [] teamMembers (); int meaningOfLife (); }
// هذا هو التعليق التوضيحي الذي يتم تطبيقه على فئة @TypeHeader ( developer = "Bob Bee" , lastModified = "2013-02-12" , teamMembers = { "Ann" , "Dan" , "Fran" }, meaningOfLife = 42 ) public class SetCustomAnnotation { // محتويات الفئة هنا }
package org.wikipedia.examples ;// هذا مثال على الكود الذي يعالج التعليق التوضيحي import java.lang.annotation.Annotation ; import java.lang.reflect.AnnotatedElement ;public class UseCustomAnnotation { public static void main ( String [] args ) { Class < SetCustomAnnotation > classObject = SetCustomAnnotation . class ; readAnnotation ( classObject ); }static void readAnnotation ( AnnotatedElement element ) { try { System . out . println ( "قيم عنصر التعليق التوضيحي: %n" ); if ( element . isAnnotationPresent ( TypeHeader . class )) { // getAnnotation تُرجع نوع التعليق التوضيحي Annotation singleAnnotation = element . getAnnotation ( TypeHeader . class ); TypeHeader header = ( TypeHeader ) singleAnnotation ;System.out.printf ( " المطور : %s%n" , header.developer ( ) ) ; System.out.printf ( " آخر تعديل : %s% n " , header.lastModified ( ) ) ;// يتم إرجاع أعضاء الفريق كـ String[] System.out.print ( " أعضاء الفريق: " ); for ( String member : header.teamMembers ( ) ) { System.out.printf ( " % s , " , member ) ; } System.out.println ( ) ;System.out.println ( " معنى الحياة: %s% n " , header.meaningOfLife ( ) ) ; } } catch ( Exception e ) { e.printStackTrace ( ) ; } } }

تستخدم مكتبات مثل JUnit معالجة التعليقات التوضيحية لإنشاء اختبارات الوحدة.

انظر أيضاً

مراجع

  1. ↑ "التعليقات" . شركة صن مايكروسيستمز . مؤرشف من الأصل بتاريخ 25-09-2011 . تم الاطلاع عليه بتاريخ 30-09-2011 ..
  2. ↑ صن مايكروسيستمز (2005). مواصفات لغة جافا ( الطبعة الثالثة). برنتيس هول . ISBN  0-321-24678-0..
  3. ↑ دار أوباسانجو (2007). "مقارنة بين لغة برمجة سي شارب من مايكروسوفت ولغة برمجة جافا من صن مايكروسيستمز: تعليقات البيانات الوصفية" . دار أوباسانجو. مؤرشف من الأصل بتاريخ 19-09-2012 . تم الاطلاع عليه بتاريخ 20-09-2012 .
  4. ↑ كوارد، داني (2006-11-02). "JSR 175: أداة بيانات وصفية للغة برمجة Java™" . عملية مجتمع جافا . تم الاسترجاع في 2008-03-05 .
  5. ↑ "أنواع التعليقات التوضيحية المُعرّفة مسبقًا" . شركة أوراكل . تم الاسترجاع في 17 ديسمبر 2016 .
  6. ↑ "التعليقات المضمنة : التعليقات القياسية" . تم الاطلاع عليه بتاريخ 17-12-2016 . 
  7. ^ "واجهة برمجة تطبيقات التعليقات التوضيحية في جاكرتا 1.3.5 API" . جاكرتا إي . تم الاسترجاع 2025-08-13 .
  8. ^ “شروح جاكرتا” . جاكرتا إي . تم الاسترجاع 2025-08-13 .
  9. ^ "واجهة برمجة تطبيقات التعليقات التوضيحية في جاكرتا 1.3.5 API" . جاكرتا إي . تم الاسترجاع 2025-08-13 .
  10. ^ “شروح جاكرتا” . جاكرتا إي . تم الاسترجاع 2025-08-13 .
  11. ↑ يو، تشونغشينغ؛ باي، تشنغقانغ؛ سينتورييه، ليونيل؛ مونبيروس، مارتن (2021). "توصيف استخدام وتطور وتأثير تعليقات جافا في الممارسة العملية". معاملات IEEE في هندسة البرمجيات . 47 (5): 969-986 . arXiv : 1805.01965 . doi : 10.1109/TSE.2019.2910516 . ISSN 1939-3520 . 
  12. ↑ مشروع لومبوك (22 أبريل 2026). "نظرة عامة (لومبوك)" . projectlombok.org . مشروع لومبوك.