Java annotation

בשפת התכנות Java, אנוטציה (באנגלית: annotation; בתרגום מילולי: "הערת הסבר" או "ביאור") היא סוג של מנגנון תחבירי להוספת metadata לקוד המקור. ניתן להוסיף אנוטציות למחלקות, מתודות, משתנים, פרמטרים ו-packages. שלא כמו תגיות Javadoc, אנוטציות ג'אווה יכולות להיות רפלקטיביות בכך שניתן לשלב אותן בקובצי class הנוצרים על ידי המהדר, והן ניתנות לאחסון על ידי המכונה הווירטואלית של ג'אווה (JVM), כך שניתן יהיה לאחזר אותן בזמן ריצה. תמיכה באנוטציות התווספה החל מגרסה 1.5 של ה-JDK.

השימוש באנוטציות נפוץ בתשתיות תוכנה (כדוגמת Spring ,Hibernate ו-EJB) כאמצעי נוח להוספת פונקציונליות למחלקות ומתודות המוגדרות על ידי המשתמש. ללא שימוש באנוטציות, על מנת ליישם פונקציונליות נוספת של תשתית התוכנה, יש להצהיר עליה במקור חיצוני (כדוגמת קובץ XML לקונפיגורציה), או לתכנת זאת באמצעות קריאות API ייעודיות. האנוטציות כשלעצמן הן לא מתודות והן לא יעשו שום עבודה. במקום זאת, האובייקט של המחלקה מועבר בזמן ריצה למימוש של תשתית התוכנה, שם האנוטציות נקראות ומביאות לביצוע הפונקציונליות הנוספת.

בג'אווה קיימת קבוצת אנוטציות שהמהדר שומר כחלק מהסינטקס של השפה. כמו כן ישנה קבוצת אנוטציות שמורות המשמשות לסימון של אנוטציות אחרות, על מנת לציין היכן ומתי ניתן להשתמש בהן (ראו פירוט בהמשך). מעבר לאנוטציות אלה, המשתמש חופשי להגדיר אנוטציות כרצונו.

אנוטציות מובנות

ג'אווה מגדירה קבוצת אנוטציות שמורות המובנות בתוך השפה:

אנוטציות אשר מיושמות על קוד ג'אווה:

• Override@ - בודקת שהמתודה המסומנת על ידי האנוטציה דורסת מתודה אחרת. גורמת לשגיאת קומפילציה אם המתודה לא נמצאת באחת מהמחלקות שיורשים ממנה או באחד מהממשקים שהמחלקה מממשת.
• Deprecated@ - מציינת שהמתודה מיושנת. גורמת לאזהרת קומפילציה אם משתמשים במתודה.
• SuppressWarnings@ - מורה למהדר להשתיק את אזהרות זמן ההידור אשר מצוינות בפרמטרים של האנוטציה.

אנוטציות אשר מיושמות על אנוטציות אחרות:

• Retention@ - מציינת כיצד האנוטציה המסומנת תישמר: רק בקוד המקור, תעבור הידור לתוך המחלקה, או תהיה זמינה בזמן ריצה באמצעות reflection.
• Documented@ - מסמנת אנוטציה אחרת לצורך הכלה בתיעוד.
• Target@ - מציינת על אילו אלמנטים של ג'אווה ניתן ליישם את האנוטציה המסומנת.
• Inherited@ - מציינת שהאנוטציה האחרת תעבור בירושה למחלקות שיורשות מהמחלקה המסומנת על ידי האנוטציה (כברירת מחדל, אנוטציות אינן עוברות בירושה למחלקות היורשות).

דוגמאות

אנוטציות מובנות

הדוגמה הבאה מציגה את השימוש באנוטציה המובנית Override@ (דריסה). אנוטציה זו מורה למהדר לחפש במחלקות האב (אחת מהמחלקות שהמחלקה הנוכחית יורשת ממנה) אחר מתודות תואמות. בדוגמה זו, תיווצר שגיאת קומפילציה מכיוון שהמתודה ()gettype במחלקה Cat אינה באמת דורסת את המתודה ()getType שבמחלקת Animal ממנה היא יורשת, אלא במקום זאת מצהירה על מתודה חדשה, וזאת מכיוון ששמות המתודות אינם מאויתים באופן זהה.

public abstract class Animal 
{
 public String getType() 
 {
    return "Generic animal";
 }
 public abstract void speak();
}

public class Cat extends Animal
{
 @Override
 public void speak() //This is a good override.
 { 
    System.out.println("Meow.");
 }
 @Override
 public String gettype() //throws compile warning due to mistyped name.
 { 
    return "Cat";
 }
}

הגדרה של אנוטציה חדשה

 // doSomething() היא אנוטציה על המתודה @Workaround
 @Workaround
 public void doSomething() {
 }

 // @Workaround הצהרה על אנוטציה חדשה בשם 
 public @interface Workaround {
 }

אנוטציות יכולות להכיל רשימה אופציונלית של זוגות מסוג מפתח-ערך (key-value):

 // Same as: @Edible(value = true)
 @Edible(true)
 Item item = new Carrot();

 public @interface Edible {
 boolean value() default false;
 }

 @Author(first = "Jules", last = "Verne")
 Book book = new Book();

 public @interface Author {
 String first();
 String last();
 }

דוגמה לשימוש באנוטציות לצורך סימון של אנוטציות אחרות, על מנת לפרט היכן ומתי ניתן להשתמש בהן:

 @Retention(RetentionPolicy.RUNTIME) // Make this annotation accessible at runtime via reflection.
 @Target({ElementType.METHOD}) // This annotation can only be applied to class methods.
 public @interface Scalable {
 }

בדוגמה זו האנוטציות Retention@ ו-Target@ מיושמות על האנוטציה Scalable@ בעת ההצהרה עליה.

קישורים חיצוניים

• Annotations - הסבר על אנוטציות במדריך הרשמי לשפת ג'אווה באתר של Oracle (באנגלית)