3. Metadane i adnotacje

1. Wprowadzenie

• do celów poprawy niezawodności programowania (np. @override),
• do generacji dodatkowych kodów programu (uzupełniających klas),
• do określania sposobu funkcjonowaniu programu w fazie wykonania (można krótko zapisać różne rzeczy).
• do celów konfiguracyjnych,
• do generowania pomocniczych plików (np. różnych deskryptorów itp.)

• zastosowanie adnotacji może znacznie ułatwić pisanie i wdrażanie aplikacji, szczególnie dużych; kody mogą być wielokrotnie mniejsze, pracochłonność znacząco ograniczona itp.

• pojawiają się jakby nowe elementy składniowo-semantyczne; ponieważ każdy może definiować własne adnotacje, to istnieje niebezpieczeństwo, że pojawi się mnóstwo "dialektów" Javy - czyli standard Javy + wymyślne, niestandardowe adnotacje,
• adnotacje pozwalają upraszczać wiele rzeczy, zapisywać niejako symbolicznie jednym słowem, to co bez nich wymagało być może dziesiątek linii kodu; ale tych zapisów (notacji i ich znaczeń) trzeba się też uczyć (dla różnych środowisk za każdym razem od nowa) i mieć świadomość, do czego tego tak naprawdę te skróty prowadzą (co robią),
• na razie nie ma dobrej koncepcji sprawdzania błędowi na poziomie metadanych.

2. Rodzaje adnotacji

• adnotacje wbudowane w Javę
• regularne
• metaadnotacje

• adnotacje użytkownika (tworzone przez użytkownika)
• stosowane na etapie kompilacji (przetwarzane przez narzędzia)
• stosowane w fazie wykonania (za pomocą mechanizmów refleksji)

• pakietów
• klas
• interfejsów
• pól
• konstruktorowi
• metod
• zmiennych lokalnych
• innych adnotacji

1. adnotacja nie oznaczona znacznikiem @Target ma zastosowanie wszędzie.
2. aby określić kilka możliwych zastosowań piszemy @Target({ a, b, c } ), gdzie a, b, c to elementy w postaci ElementType.rodzaj, a rodzaj to jeden z PACKAGE, METHOD, FIELD itp.

• przez narzędzia do generacji (i ew. równoczesnej kompilacji) kodu (wtedy potrzebne są tylko w fazie kompilacji),
• albo przez mechanizmy refleksji  - wtedy powinny być zapisane w klasie wykonywalnej i dostępne dla tych mechanizmów w fazie wykonania programu,
• albo przez narzędzia przetwarzania "binarnej" postaci klas (umożliwiające m.in. różne iniekcje, zmiany, usuwanie kodu binarnego) - wtedy powinny być zapisane w klasie, ale nie muszą być dostępne dla mechanizmów refleksji.

3. Definiowanie adnotacji

• typy proste (int, short, long, byte, char, double, float, boolean),
• String,
• typ referencyjny, reprezentowany przez Class, w tym także w wersji sparametryzowanej,
• enum.
• adnotacja,
• tablica (w/w elementów).

public @interface Opis {
    String text() default "Brak opisu";
    int version() default 1;
}


// i zastosowanie np. do opisu klasy:

@Opis(text="Klasa warzyw", version=2)
public class Warzywa { ... }

4. Przetwarzanie adnotacji w fazie wykonania

• ustalić rodzaj adnotacji przez @Retention(RetentionPolicy.RUNTIME),
• użyć metod refleksji do uzyskania informacji które elementy i za pomocą jakich adnotacji są zaznaczane,
• od uzyskanych adnotacji dowiedzieć się ew. dodatkowych informacji, zapisanych w nich jako dane; po czym na podstawie adnotacji i tych danych dynamicznie wytworzyć i wykonać odpowiedni kod.

• przy zastosowaniu nazwanych pakietów nazwy interfejsów adnotacji muszą być kwalifikowane nazwą pakietu,
• wszystkie adnotacje (jako interfejsy) rozszerzają interfejs Annotation, wobec czego mogą być traktowane jako Annotation i dlatego takie są wyniki w/w metod; zwróćmy uwagę, że dzięki parametryzacji nie musimy stosować konwersji zawężających.

import java.lang.annotation.*;
import java.awt.*;

@Target(ElementType.FIELD)             // do oznaczania pól
@Retention(RetentionPolicy.RUNTIME)    // faza wykonania

public @interface Loc {
   String to();
}

import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
import java.lang.reflect.*;

public class Annot0 extends JFrame {

  JComponent cp = (JComponent) getContentPane();

  @Loc(to="cp") JPanel p1 = new JPanel();
  @Loc(to="cp") JPanel p2 = new JPanel();

  @Loc(to="p1") JButton b1 = new JButton("Przycisk 1");
  @Loc(to="p1") JButton b2 = new JButton("Przycisk 2");
  @Loc(to="p2") JButton b3 = new JButton("Przycisk 3");
  @Loc(to="p2") JButton b4 = new JButton("Przycisk 4");
  @Loc(to="p2") JButton b5 = new JButton("Przycisk 5");

  public Annot0() {
    setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
    cp.setLayout(new BoxLayout(cp, BoxLayout.Y_AXIS));
    try {
      locateComponents();   // metoda ta zajmie się wkładaniem do kontenerow
    } catch(Exception exc) {
        exc.printStackTrace();
    }
    pack();
    show();
  }
//....
}

  private void locateComponents() throws Exception {
    Class klasa =  getClass();
    for (Field f : klasa.getDeclaredFields()) {   // po polach klasy
      Loc annot = f.getAnnotation(Loc.class);     // dla f uzyskać anotację Loc
      if (annot == null) continue;                // nie ma - następne pole
      System.out.println(annot);                  // zobaczmy jak wygląda
      String contName = annot.to();               // od adnotacji: nazwa kontenera
      Field contField = klasa.getDeclaredField(contName);  // pole, ktore go deklaruje
      Object container = contField.get(this);  // sam obiekt-kontener
      Method m = container.getClass().getMethod("add", Component.class); // metoda add
      m.invoke(container, f.get(this)); // i jej wywołanie - dodajemy komponent
    }
}

5. Przetwarzanie adnotacji w fazie kompilacji

import java.lang.annotation.*;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface BeanTemplate {
}

import com.sun.mirror.apt.*;
import com.sun.mirror.declaration.*;
import com.sun.mirror.type.*;
import com.sun.mirror.util.*;

import java.beans.*;
import java.io.*;
import java.util.*;


public class BeanTemplateAnnotationFactory
       implements AnnotationProcessorFactory
{

   // Typ adnotacji
   private final String annoType = "BeanTemplate";

   public Collection<String> supportedAnnotationTypes() {
      return Arrays.asList(annoType);
   }

   public Collection<String> supportedOptions() {
      return Arrays.asList(new String[0]);
   }

   public AnnotationProcessor   // ważna metoda getProcessorFor
          getProcessorFor(Set<AnnotationTypeDeclaration> atds,
                          final AnnotationProcessorEnvironment env)
   {
      return new AnnotationProcessor() { // procesor - w klasie wewnętrznej

        public void process() {
          // deklaracje markowane adnotacją annoType (teraz "BeanTemplate")
          Collection<Declaration> dcls =
             env.getDeclarationsAnnotatedWith(
                (AnnotationTypeDeclaration) env.getTypeDeclaration(annoType));

          for (Declaration d : dcls) { 
             if (d instanceof ClassDeclaration) {  // jeżeli klasa
               ClassDeclaration cdcl = (ClassDeclaration) d;
               String name = cdcl.getSimpleName();
               if (!name.endsWith("Template")) {
                  // od env uzyskujemy środki raportowania błędów, ostrzeżeń, info.
                  env.getMessager().printWarning("Wadliwa nazwa klasy bean template");
                  continue;
               }
               String qname = cdcl.getQualifiedName();
               env.getMessager().printNotice(qname);
               qname = qname.substring(0, qname.lastIndexOf("Template"));
               name = name.substring(0, name.lastIndexOf("Template"));
               try {
                 // od env uzyskamy plik i skojarzony z nim PrintWriter
                 PrintWriter out = env.getFiler().createSourceFile(qname);
                 // generujemy świeży kod na podstawie info o zaznaczonej klasie
                 out.println("public class " + name + " {" );
                 Collection<FieldDeclaration> fdcl = cdcl.getFields();
                 for (FieldDeclaration f : fdcl) {
                   String fname = f.getSimpleName();
                   String mname = Character.toUpperCase(fname.charAt(0)) +
                                  fname.substring(1);
                   String ftype = f.getType().toString();
                   out.println("  private " + ftype + " " + fname + ";");
                   out.println("  public " + ftype + " get" +  mname +
                               "() { return " + fname + "; }");
                   out.println("  public void set" +  mname +
                               "(" + ftype + " v) { " + fname + " = v; }");
                 }
                 out.println("}");
                 out.close();
               } catch(IOException exc) { exc.printStackTrace(); }
             }
             else  // jeśli nie byla klasa, to ktoś się pomylił i zazn. interfejs
               env.getMessager().printWarning("Adnotacja dotyczy interfejsu");
          }
        }
      };
   }



}

import java.awt.*;
@BeanTemplate public class Bean1Template {
  String txt;
  Color color;
}

import java.awt.*;
public class Annot1 {


  public Annot1() {
    Bean1 b = new Bean1();
    b.setTxt("Pies");
    b.setColor(Color.BLUE);

    System.out.println(b.getTxt() + "\n" + b.getColor());

  }

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

}

apt -factory BeanTemplateAnnotationFactory *.java

public class Bean1 {
  private java.awt.Color color;
  public java.awt.Color getColor() { return color; }
  public void setColor(java.awt.Color v) { color = v; }
  private java.lang.String txt;
  public java.lang.String getTxt() { return txt; }
  public void setTxt(java.lang.String v) { txt = v; }
}

Zobacz multimedialną prezentację użycia APT

6. Adnotacje a transformowanie kodu binarnego

• Javassist,
• BCEL.

• zastępowaniu metod i konstruktorów.
• dodawanie kodu na początku lub w końcu ciała metod lub konstruktorów.

7. Podsumowanie

• rodzajami adnotacji, ich składnią, semantyką,
• sposobami definiowania adnotacji,
• wykorzystaniem adnotacji w fazie wykonania programu za pomocą mechanizmów refleksji,
• wykorzystaniem adnotacji w fazie kompilacji i użyciem narzędzia apt,
• informacjami o transformacji kodu binarnego (możliwośc użycia adnotacji do modyfikowania binarnego kodu klas).

8. Zadania