Kuidas kasutada annotatsioone Kotlinis?

Kotlinis anotatsioonid kasutatakse metaandmete lisamiseks klassidele, omadustele, funktsioonidele, väljenditele ja parameetritele. Need ei täida otsest tegevust, kuid võivad olla kasutusel kompilaatorite, raamistike või teiste teekide poolt erinevate töötlemiste jaoks:

Peamised kasutusvaldkonnad:

1. Süntaks: Anotatsioonid märgivad elementi enne, millele need rakenduvad, nurksulgudes @. Kui anotatsioonil on parameetrid, märgitakse need pärast nime sulgudes:

   @Deprecated("Use newFunction instead")
   fun oldFunction() {
       // ...
   }
   
   @JvmStatic
   fun staticMethod() {
       // ...
   }
   

2. Rakendamine erinevatele elementidele: Anotatsioone saab rakendada:

   • Klassidele (class):

     @Serializable
     class User(val name: String)
     

   • Omadustele (val, var):

     @Inject
     lateinit var userRepository: UserRepository
     

   • Funktsioonidele (fun):

     @Test
     fun testSomething() {
         // ...
     }
     

   • Konstruktorite/funktsioonide parameetritele:

     fun processUser(@NotNull user: User) {
         // ...
     }
     

   • Väljenditele:

     fun calculate(@Ignore parameter: Int) {
         // ...
     }
     

   • Tüüpidele (@Target(AnnotationTarget.TYPE)):

     val list: @NotNull List<String> = emptyList()
     

3. Kasutuspaigad (Use-site Targets): Kui on vaja täpsustada, millele täpselt anotatsioon rakendub, kui neid on mitu (näiteks väli ja getter), kasutatakse use-site targets:

   Target	Kirjeldus
   @file:	Rakendub kogu failile
   @property:	Rakendub kogu omadusele
   @field:	Rakendub tagasituleva väljale (backing field)
   @get:	Rakendub omaduse getter'ile
   @set:	Rakendub omaduse setter'ile
   @param:	Rakendub konstruktorile/funktsiooni parameetrile
   @setparam:	Rakendub omaduse setter'i parameetrile
   @delegate:	Rakendub delegeeritud omaduse instantsile
   @receiver:	Rakendub vastuvõtja tüübile

   class Example(@field:Inject val dependency: Dependency) {
       // @field:Inject rakendub 'dependency' väljale
   }
   

4. Kasutaja määratletud anotatsioonid: Oma anotatsioone defineeritakse annotation class abil. Anotatsiooni parameetrid võivad olla primitiivsed tüübid, stringid, klassid (KClass), nimekirjad, teised anotatsioonid või nende massiivid:

   annotation class MyAnnotation(val value: String, val count: Int = 0)
   
   @MyAnnotation("Hello", count = 5)
   class AnnotatedClass {
       // ...
   }
   

5. Meta-anotatsioonid: Anotatsioonid võivad olla märgitud meta-anotatsioonidega, mis määravad nende käitumise ja rakendatavuse:

   • @Target: näitab, millised elemendid võivad olla anotatsiooniga märgitud.
   • @Retention: näitab, millal on anotatsioon olemas (SOURCE, BINARY, RUNTIME).
   • @Repeatable: võimaldab rakendada anotatsiooni mitu korda ühe elemendi kohta.
   • @MustBeDocumented: näitab, et anotatsioon peab olema osa avalikust API-st, mida dokumenteerimisvahend genereerib.

   @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
   @Retention(AnnotationRetention.RUNTIME)
   annotation class ProcessedByFramework
   

Anotatsioonid on laialdaselt kasutusel Kotlinis JVM-i raamistikus (Spring, Android), serialiseerimises (Kotlinx.serialization), testimises (JUnit) ja oma teekide loomisel, mis põhinevad metaandmetel.