Metaprogramovanie / Metadáta a anotácie

Príklady

@Deprecated
public Integer someOldApi() {
    ...

@SuppressWarnings(value = "unchecked")
void myMethod()
    ...

Spring

@Autowired
Biker(@Qualifier("bike") Vehicle vehicle) {
    this.vehicle = vehicle;
}

@Configuration
@PropertySource("classpath:/annotations.properties")
@PropertySource("classpath:/vehicle-factory.properties")
class VehicleFactoryConfig {}

Spring MVC

@Controller
@RequestMapping(value = "/vehicles", method = RequestMethod.GET)
class VehicleController {

    @RequestMapping("/home")
    String home() {
        return "home";
    }
}

JetBrains Annotations

public void myMethod(@NotNull Object param) {
    ...

@Contract("null -> false")
public static boolean isNotEmptyString(String str) {
    return str != null && !str.isEmpty();
}

Na čo slúžia anotácie?

Metadáta

• Metadáta — dáta poskytujúce informácie o iných dátach.
• Anotácie — štrukturované metadáta o zdrojovom kóde programu.

Význam metadát

• Príklad: definície typov
• Doplňujúce informácie
• Lepšie vyjadrenie významu kódu
• Umožňujú vytvárať pomocné nástroje

Klasifikácia metadát

• Definícia:
  • štandardné
  • používateľské
• Štruktúra:
  • štruktúrované
  • neštruktúrované
• Umiestnenie:
  • zabudované (embedded)
  • externé

Anotácie v Jave

• Názov: @Entity
• Parametre: @Column(name="description", nullable=false)

Čo je možné anotovať?

• Deklarácie
• Použitie typu

Použitie metadát

• Generovanie kódu
• Konfigurácia počas behu (run-time)
• Deklaratívna špecifikácia vlastností kódu
• Zaznamenanie návrhových rozhodnutí

Príklady

• Zobrazenie objektov na
  • relačnú databázu (JPA, Hibernate)
  • JSON (Jackson)
  • XML (JAXB)
  • formálne jazyky (YAJCo)
  • iné objekty (Dozer)

Príklady

• Jednotkové testy (JUnit)
• Konfigurácia webového rámca (Spring MVC)
• Generovanie SOAP webových služieb (JAX-WS)
• Konfigurácia RESTful webových služieb (Jersey, Spring @RestController)
• Konfigurácia prepojenia medzi UI a serverovou časťou (GWT)
• Validácia a „programming by contract“ (OVal)
• Konfigurácia závislosti (Spring, Guice)

Vlastné anotácie

Anotačný typ

• Názov
• Parametre
• Predvolené hodnoty

Definícia anotačného typu

• Rozhranie
  • @interface
• Metódy → parametre anotácie
  • default
• Typy parametrov:
  • primitívne, enumeračné, anotačné, String, Class
  • polia

Príklad

public @interface Length {
	int min() default 0;
	int max();
}

public class Person {
	@Length(max=30)
	private String name;
	...
}

Meta-anotácie

• Anotácie pre anotačné typy

@Target

• ElementType.ANNOTATION_TYPE
• ElementType.CONSTRUCTOR
• ElementType.FIELD
• ElementType.LOCAL_VARIABLE
• ElementType.METHOD
• ElementType.PACKAGE
• ElementType.PARAMETER
• ElementType.TYPE
• ElementType.TYPE_PARAMETER
• ElementType.TYPE_USE

@Retention

• RetentionPolicy.SOURCE
• RetentionPolicy.CLASS
• RetentionPolicy.RUNTIME

Ďalšie

• @Documented
• @Inherited
• @Repeatable

Článok

E. Guerra, M. Cardoso, J. Silva, and C. Fernandes, “Idioms for code annotations in the Java language,” in Proceedings of the 8th Latin American Conference on Pattern Languages of Programs - SugarLoafPLoP’10, 2010 doi: 10.1145/2581507.2581514.

Reflexia

AnnotatedElement

• Rozhranie implementované metaobjektmi
• <T extends Annotation> T getAnnotation(Class<T> type)
• boolean isAnnotationPresent( Class<? extends Annotation> annotationType)
• Annotation[] getAnnotations()
• Annotation[] getDeclaredAnnotations()
• Annotation — rodičovské rozhranie pre všetky anotačné typy

Príklad

Doplnenie JSON encodera

• @JsonIgnore
• @JsonProperty(String value)

Riešenie

JsonEncoder (vetva annotations)

Ako to robia iní?

GSON

• https://github.com/google/gson
• Minimum anotácií — vzor Strategy
• Modifikátor transient
• @SerializedName("custom_naming")
• @Expose

Verzie

public class VersionedClass {
  @Since(1.1) private final String newerField;
  @Since(1.0) private final String newField;
  private final String field;
  ...

Gson gson = new GsonBuilder().setVersion(1.0).create();

Jackson

• https://github.com/FasterXML/jackson-annotations
• @JsonProperty("firstName")
• @JsonIgnore

@JsonIgnoreProperties({ "extra", "uselessValue" })
public class Value {
  public int value;
}

public class CtorPOJO {
   private final int _x, _y;

   @JsonCreator
   public CtorPOJO(
          @JsonProperty("x") int x,
          @JsonProperty("y") int y) {
      _x = x;
      _y = y;
   }
}

@JsonTypeInfo(use=Id.MINIMAL_CLASS, include=As.PROPERTY,
              property="type")
@JsonSubTypes({@Type(Car.class), @Type(Aeroplane.class)})
public abstract class Vehicle { }
public class Car extends Vehicle {
  public String licensePlate;
}
public class Aeroplane extends Vehicle {
  public int wingSpan;
}

public class PojoWithTypedObjects {
  public List<Vehicle> items;
}

{ "items": [
  { "type": "Car", "licensePlate": "X12345" },
  { "type": "Aeroplane", "wingSpan": 13 }
]}

Alternatívy

Komentáre

/**
 * @ORM\Entity
 * @ORM\Table(name="products") */
class Product{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue */
    protected $id;

Externá konfigurácia

<hibernate-mapping>
   <class name="Employee" table="EMPLOYEE">
      <id name="id" type="int" column="id">
         <generator class="native"/>
      </id>
      <property name="firstName" column="first_name" type="string"/>
      <property name="lastName" column="last_name" type="string"/>
      <property name="salary" column="salary" type="int"/>
   </class>
</hibernate-mapping>

Iné jazyky

C#

• Attributes

[Obsolete("ThisClass is obsolete. Use ThisClass2 instead.")]
public class ThisClass
{
}

Python

• Typové anotácie

def greeting(name: str) -> str:
    return 'Hello ' + name

@dataclass
class Model:
    number: int

Nielen typy

from typing import Annotated
from pydantic import AfterValidator, BaseModel

class Model(BaseModel):
    number: Annotated[int, AfterValidator(is_even)]

Literatúra

• The Java Tutorials: Annotations
• JavaDoc: AnnotatedElement