توفر التعليقات التوضيحية (المعروفة أيضًا باسم البيانات الوصفية) طريقة رسمية لنا لإضافة معلومات في التعليمات البرمجية الخاصة بنا ، مما يتيح لنا استخدام هذه البيانات بشكل مريح للغاية في لحظة لاحقة.
1. بناء الجملة الأساسي
Java SE5 لديها ثلاثة تعليقات قياسية مدمجة
Override: يشير إلى أن تعريف الطريقة الحالية سوف يكتب الأساليب في الطبقة الفائقة. إذا قمت بتهجئة الإملاء الخطأ عن طريق الخطأ ، أو أن توقيع الطريقة لا يتطابق مع الطريقة المكتوبة ، فسيقوم المترجم بإصدار رسالة خطأ.
DePrecated: إذا كان المبرمج يستخدم عنصرًا مشروحًا ، فسيصدر برنامج التحويل البرمجي رسالة تحذير
supperesswarnings: أغلق رسالة التحذير غير لائقة التحذير.
Java SE5 لديها أربعة شرائح التوقيت المدمجة
@target: يشير إلى مكان استخدام هذا التعليق. تتضمن معلمات elementType الممكنة:
1) مُنشئ: بيان المنشئ
2) الحقل: إعلان المجال (بما في ذلك مثيلات التعداد)
3) local_variable: إعلان متغير محلي
4) الطريقة: بيان الطريقة
5) الحزمة: بيان الحزمة
6) المعلمة: إعلان المعلمة
7) النوع: فئة ، واجهة (بما في ذلك نوع التعليق التوضيحي) أو إعلان التعداد
الاحتفاظ: يشير إلى أي مستوى لحفظ معلومات التعليقات التوضيحية. تشمل المعلمات الاختيارية للاحتفاظ بسيرة:
1) المصدر: سيتم التخلص من التعليقات التوضيحية من قبل المترجم
2) الفصل: التعليقات التوضيحية متوفرة في ملفات الفصل ، ولكن سيتم التخلص منها بواسطة VM
3) وقت التشغيل: سيحتفظ VM أيضًا بالتعليقات التوضيحية أثناء وقت التشغيل ، بحيث يمكن قراءة معلومات التعليق التوضيحي من خلال آلية الانعكاس.
documented: قم بتضمين هذا التعليق التوضيحي في Javadoc
inherited: السماح للفئات الفرعية براث التعليقات التوضيحية في فصول الوالدين معظم الوقت ، ويحدد المبرمجون بشكل أساسي التعليقات التوضيحية الخاصة بهم واكتب معالجاتهم الخاصة للتعامل معها.
usecase.java
حزمة كوم ؛ استيراد java.lang.annotation.elementType ؛ استيراد java.lang.annotation.Reentering ؛ استيراد java.lang.annotation.RetentionPolicy ؛ استيراد java.lang.annotation.target ؛ target (elementType.method) // استخدم لتحديد مكان تطبيق التعليق التوضيحي الخاص بك ، ويتم تطبيق ذلك كطريقة // استخدام لتحديد المستوى الذي يتوفر فيه التعليق ، في الكود المصدري (الفئة) أو وقت التشغيل (وقت التشغيل) وصف السلسلة العامة () الافتراضي "لا وصف" ؛ } passwordUtils .java package com ؛ فئة PasswordUtils العامة { @uSecase (id = 47 ، الوصف = "يجب أن تحتوي كلمات المرور على رقم واحد على الأقل") } @usecase (id = 48) سلسلة عامة encryptPassword (سلسلة كلمة مرور) {return password ؛ } uSeCase (id = 49 ، description = "jong_cai") public void disterame () {system.out.println ("jong_cai") ؛ }}
2. اكتب معالج التعليقات التوضيحية
إذا لم تكن هناك أداة لقراءة التعليقات التوضيحية ، فلن تكون التعليقات التوضيحية أكثر فائدة من التعليقات التوضيحية. في عملية استخدام التعليقات التوضيحية ، جزء مهم هو إنشاء واستخدام معالجات التعليقات التوضيحية. يمتد Java SE5 واجهة برمجة تطبيقات آلية الانعكاس لمساعدة المبرمجين على بناء مثل هذه الأدوات. في الوقت نفسه ، يوفر أيضًا أداة خارجية APT لمساعدة المبرمجين على تحليل رمز المصدر Java مع التعليقات التوضيحية. فيما يلي معالج شرح بسيط للغاية ، سنستخدمه لقراءة فئة PasswordUtils واستخدام آلية الانعكاس للعثور على علامة usecase. نحن نقدمها بمجموعة من قيم المعرف ، ثم يسرد حالات الاستخدام الموجودة في PasswordUtils ، وكذلك حالات الاستخدام المفقودة.
usecasetracker.java package com ؛ استيراد java.lang.reflect.method ؛ استيراد java.util.arraylist ؛ استيراد java.util.collections ؛ استيراد java.util.list ؛ الفئة العامة USECASETRACKER {public static void trackUseCases (list <Steger> list ، class <؟> cl) {for (method m: cl.getDeclaredMethods ()) {usecase us = m.getAnnotation (usecase.class) ؛ if (us! = null) {system.out.println ("تم العثور على حالة استخدام:" + us.id () + "" + us.description ()) ؛ list.remove (عدد صحيح جديد (us.id ())) ؛ }} لـ (int i: list) {system.out.println ("تحذير: مفقود استخدام الحالة" + i) ؛ }} public static void main (string [] args) {list <integer> list = new ArrayList <integer> () ؛ Collections.Addall (قائمة ، 47،48،49،50،51) ؛ TrackUseCases (قائمة ، passwordUtils.Class) ؛ }}
يستخدم هذا البرنامج طريقتين للانعكاس: getDeclaredMethods () و getAnnotation (). كلاهما ينتمي إلى واجهة المشروح (فئة ، الطريقة والحقل والفئات الأخرى تنفذ هذه الواجهة). تقوم طريقة getAnnotation () بإرجاع كائن شرح من النوع المحدد ، وهو usecase. إذا لم يكن للطريقة المشروحة تعليقًا من النوع ، فإنه يعيد قيمة فارغة. ثم نستخرج قيمة العنصر من كائن USECASE الذي تم إرجاعه عن طريق استدعاء طرق المعرف () والوصف (). لا تحدد طريقة EncryptPassword () قيمة الوصف عند التعليق ، لذلك عندما يقوم المعالج بمعالجة التعليق التوضيحي المقابل له ، يتم الحصول على القيمة الافتراضية لطريقة الوصف () بواسطة طريقة الوصف ().
توضيح التعليقات التوضيحية في عالم جافا. إذا كان لديك وقت ، فاكتب هذه المقالة التعليقات التوضيحية البسيطة. إنها مقدمة للتعليق. أتمنى أن تتمكن من رمي الطوب والتعلم معًا ...
إذا توقفت عن الحديث عن هراء ، فإن الممارسة هي النتيجة النهائية.
3. مثال
دعنا نتحدث عن مفهوم التعليق التوضيحي أولاً ، ثم نتحدث عن كيفية تصميم التعليقات التوضيحية الخاصة بك.
أولاً ، في حزمة java.lang.annotation التي تأتي مع JDK ، افتح ملفات المصدر التالية:
ملف المصدر Target.java
documented @receent (attreentionpolicy.runtime) target (elementType.annotation_type) الهدف العام {elementType [] value () ؛ documented @receent (attreentionpolicy.runtime) target (elementType.annotation_type) الهدف العام {elementType [] value () ؛ }
interface هي كلمة رئيسية. عند تصميم التعليقات التوضيحية ، يجب تعريف النوع على أنه interface ، ولا يمكنك استخدام الكلمات الرئيسية للفئة أو الواجهة (هل تعتقد أن الشمس خادعة بعض الشيء ، لكنها تشبه الواجهة).
مصدر الملف الاحتفاظ
documented @receent (attreentionpolicy.runtime) target (elementType.Annotation_type) public interface entry {entrentionPolicy value () ؛ } documented @retention (attreentionpolicy.runtime) target (elementType.Annotation_type) public interface entry {entrentionpolicy value () ؛ }
بعد رؤية هذا ، قد تكون غامضًا ولا تعرف ما الذي تتحدث عنه. لا تقلق ، ألقِ نظرة. تستخدم الملفات المذكورة أعلاه الحقلين attreencepolicy و elementType ، وقد تخمن أن هما ملفان Java. في الواقع ، فإن رموز المصدر لهذين الملفان هي كما يلي:
مصدر ملف entrypolicy.java
التعداد العام attreencepolicy {source ، class ، reclime} reateRencepolicy {source ، class ، time} هذا نوع التعداد ، مع ثلاث قيم ، وهي المصدر والفئة ووقت التشغيل.
المصدر يعني أنه سيتم الاحتفاظ بمعلومات نوع التعليقات التوضيحية فقط في رمز مصدر البرنامج. إذا تم تجميع الرمز المصدر ، فستختفي بيانات التعليقات التوضيحية ولن يتم الاحتفاظ بها في ملف .class المترجم.
تعني الفصل أنه يتم الاحتفاظ بمعلومات نوع التعليقات التوضيحية في رمز مصدر البرنامج ، وسيتم الاحتفاظ بها أيضًا في ملف .class المترجم. عند التنفيذ ، لن يتم تحميل هذه المعلومات في الجهاز الظاهري (JVM). لاحظ أنه عندما لا تقم بتعيين قيمة الاحتفاظ بنوع التعليقات التوضيحية ، فإن القيمة الافتراضية للنظام هي فئة.
والثالث هو وقت التشغيل ، مما يعني أنه يتم الاحتفاظ بالمعلومات في رمز المصدر وملف .class المترجمة ، وسيتم تحميل هذه المعلومات في JVM أثناء التنفيذ.
على سبيل المثال ، إذا تم ضبط الاحتفاظ في Override على المصدر ، إذا كان التجميع ناجحًا ، فلن تحتاج إلى هذه المعلومات المحددة ؛ على العكس من ذلك ، تم تعيين الاحتفاظ في DePrecated على وقت التشغيل ، مما يعني أنه بالإضافة إلى تحذيرنا الأسلوب الذي يتم استخدامه أثناء التجميع ، يمكنك أيضًا التحقق مما إذا كانت الطريقة قد تم إهمالها عند التنفيذ.
مصدر ملف elementType.java
elementtype elementType {type ، الحقل ، الطريقة ، المعلمة ، مُنشئ ، محلي _ ＠ يتم استخدام elementType في الهدف لتحديد نوع التعليقات التوضيحية عناصر يمكن استخدامها. دعنا نوضح: النوع (النوع) ، الحقل (السمة) ، الطريقة (الطريقة) ، المعلمة (المعلمة) ، مُنشئ (مُنشئ) ، محلي_
بالإضافة إلى ذلك ، يمكن ملاحظة من الكود المصدري لـ 1 الذي استخدم نفسه أيضًا نفسه لإعلان نفسه ، ولا يمكن استخدامه إلا في التعليق التوضيحي.
إذا لم يحدد نوع التعليقات التوضيحية عناصر @target التي يتم استخدامها ، فيمكن استخدامه على أي عنصر ، ويشير العنصر هنا إلى الأنواع الثمانية المذكورة أعلاه.
اسمحوا لي أن أعطيك بعض الأمثلة الصحيحة:
target (elementType.Method)
target (value = elementType.method)
target (elementType.method ، elementType.Constructor)
يرجى الرجوع إلى وثائق Javadoc للحصول على التفاصيل
جميع الملفات المصدر تستخدم documented. الغرض من documented هو تمكين معلومات نوع التعليقات التوضيحية التي يتم عرضها على مستند Javaapi Description ؛ إذا لم تتم إضافته ، فلن يتم العثور على المعلومات التي تم إنشاؤها بواسطة هذا النوع عند استخدام Javadoc لإنشاء مستند API.
نقطة أخرى هي أنه إذا كنت بحاجة إلى ورث بيانات التعليقات التوضيحية إلى فئة فرعية ، فستستخدم نوع التعليق التوضيحي inherited.
ما يلي هو أبسط مثال شرح للتصميم ، والذي يتكون من أربعة ملفات ؛
الوصف
حزمة أخف. javaeye.com ؛ استيراد java.lang.annotation.documented ؛ استيراد java.lang.annotation.elementType ؛ استيراد java.lang.annotation.Reentering ؛ استيراد java.lang.annotation.RetentionPolicy ؛ استيراد java.lang.annotation.target ؛ target (elementType.type) retention (attreencepolicy.runtime) documented public interface الوصف {string value () ؛ } package أخف. javaeye.com ؛ استيراد java.lang.annotation.documented ؛ استيراد java.lang.annotation.elementType ؛ استيراد java.lang.annotation.Reentering ؛ استيراد java.lang.annotation.RetentionPolicy ؛ استيراد java.lang.annotation.target ؛ target (elementType.type) retention (attreencepolicy.runtime) documented public interface الوصف {string value () ؛ }
ملاحظة: سترث جميع التعليقات التوضيحية تلقائيًا الواجهة java.lang.annotation ، لذلك لا يمكنك أن ترث فئات أو واجهات أخرى.
النقطة الأكثر أهمية هي كيفية تعيين المعلمات في نوع التعليق التوضيحي:
أولاً ، يمكنك فقط استخدام حقوق الوصول العامة أو الافتراضية لتعديلها. على سبيل المثال ، قيمة السلسلة () ؛ هنا قم بتعيين الطريقة على النوع الافتراضي الافتراضي.
ثانياً ، يمكن لأعضاء المعلمة استخدام ثمانية أنواع بيانات أساسية فقط: بايت ، شورت ، char ، int ، طويلة ، تعويم ، مزدوجة ، منطقية ، وأنواع البيانات مثل السلسلة ، التعداد ، الفئة ، التعليقات التوضيحية ، وكذلك صفائف من هذه الأنواع. على سبيل المثال ، قيمة السلسلة () ؛ عضو المعلمة هنا هو سلسلة.
ثالثًا ، إذا كان هناك عضو واحد فقط معلمة ، فمن الأفضل تعيين اسم المعلمة على "القيمة" وإضافة قوسين بعد ذلك. مثال: المثال أعلاه لديه عضو واحد فقط معلمة.
name.java
حزمة أخف. javaeye.com ؛ استيراد java.lang.annotation.documented ؛ استيراد java.lang.annotation.elementType ؛ استيراد java.lang.annotation.Reentering ؛ استيراد java.lang.annotation.RetentionPolicy ؛ استيراد java.lang.annotation.target ؛ // لاحظ أن target هنا يختلف عن description ، وأعضاء المعلمة يختلفون أيضًا عن target (elementType.method) @repinention (attreentionpolicy.runtime) documented public interface name {string arenginate () ؛ سلسلة المجتمع () ؛ } package أخف. javaeye.com ؛ استيراد java.lang.annotation.documented ؛ استيراد java.lang.annotation.elementType ؛ استيراد java.lang.annotation.Reentering ؛ استيراد java.lang.annotation.RetentionPolicy ؛ استيراد java.lang.annotation.target ؛ // لاحظ أن target هنا يختلف عن description ، وأعضاء المعلمة يختلفون أيضًا عن target (elementType.method) @repinention (attreentionpolicy.runtime) documented public interface name {string arenginate () ؛ سلسلة المجتمع () ؛ }
javaeyer.java
حزمة أخف. javaeye.com ؛ description ("Javaeye ، Be the Best Software Exchange Community") الطبقة العامة javaeyer {name (arensinate = "مؤسسة: Robbin" ، community = "javaeye") السلسلة العامة getName () {return null ؛ } name (arensinate = "مؤسسة: Jianggnan Baiyi" ، Community = "Springside") السلسلة العامة getName2 () {return "Borrow اثنين من المعرفات ، يرجى أن تسامحني لكتابة هذا المثال!" ؛ }} package أخف. javaeye.com ؛ description ("Javaeye ، Be the Best Software Exchange Community") الطبقة العامة javaeyer {name (arensinate = "مؤسسة: Robbin" ، community = "javaeye") السلسلة العامة getName () {return null ؛ } name (arensinate = "مؤسسة: Jianggnan Baiyi" ، Community = "Springside") السلسلة العامة getName2 () {return "Borrow اثنين من المعرفات ، يرجى أن تسامحني لكتابة هذا المثال!" ؛ }}اكتب فئة TestAnnotation التي يمكنها تشغيل معلومات extract javaeyer
حزمة أخف. javaeye.com ؛ استيراد java.lang.reflect.method ؛ استيراد java.util.hashset ؛ استيراد java.util.set ؛ الفئة العامة TestAnnotation { / *** المؤلف أخف وزناً* ملاحظة: للحصول على التفاصيل ، يرجى الرجوع إلى وثائق Javadoc لاستخدام API API* / Public Static Void Main (String [] args) reconsed {string class_name = "lighter.javaeye.com.javaeyer" ؛ اختبار الفئة = class.forname (class_name) ؛ الطريقة [] method = test.getMethods () ؛ العلم المنطقي = test.isannotationpresent (description.class) ؛ if (flag) {description des = (description) test.getAnnotation (description.class) ؛ System.out.println ("الوصف:"+des.value ()) ؛ System.out.println("------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Hashset <) ؛ System.out.println ("تم إنشاؤه". api api*/ public static void main (string [] args) يلقي الاستثناء {string class_name = "lighter.javaeye.com.javaeyer" ؛ اختبار الفئة = class.forname (class_name) ؛ الطريقة [] method = test.getMethods () ؛ العلم المنطقي = test.isannotationpresent (description.class) ؛ if (flag) {description des = (description) test.getAnnotation (description.class) ؛ System.out.println ("الوصف:"+des.value ()) ؛ System.out.println("------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- { boolean otherflag = mething [i] نتائج التشغيل:
الوصف: Javaeye ، أفضل مجتمع تبادل البرمجيات مؤسس: Robbin Created Community: Javaeye مؤسس: Javaeye Created Community: Springside