學習筆記-kotlin註解

註解本質上是一種代碼的標籤，做用的對象是代碼。使用註解能夠將額外的元數據關聯到聲明上，這些元數據能夠被源代碼工具和反射訪問並作必定的操做。

使用處目標

kotlin中的元素生成java中的元素可能有多個，好比kotlin中的屬性會生成屬性、getter和setter，因此生成的java文件中註釋會有多個可能位置。在某些狀況下，須要精準的指定應該生成該註解（類如@get:JvmStatic），kotlin中支持的使用處目標有：

• file：文件。
• property：此註解對java不可見。
• field：字段。
• get：屬性getter。
• set：屬性setter。
• receiver：擴張函數或者屬性的接受者參數，即賦值目標。
• param：構造函數參數。
• setparm：屬性setter參數。
• delegate：爲委託屬性存儲其委託實例的字段。

若是不指定使用處目標，會根據@Target標註的能夠做爲目標的種類中選擇目標。若是有多個適用目標，則根據param-property-field的順序選擇第一個適用的目標。

元註解

元註解就像它的名字同樣，是註解中的基石。kotlin中定義了四個元註解，這四個註解是最基本的註解，他們都是用於給註解(包括他們自身)打標籤，也就是註解的註解。

• Target ：標註能夠做爲註釋目標的元素種類，也就是標註的註釋能夠做用於類或者變量等等種的哪些種類。傳入值是一個變長參數：枚舉類AnnotationTarget。AnnotationTarget中定義了各類元素種類：

  • CLASS：類、接口、註解類等。

  • ANNOTATION_CLASS：僅註解類。

  • TYPE_PARAMETER：泛型（不支持）。

  • PROPERTY：屬性。

  • FIELD：字段（字段和屬性的區別是字段能夠直接訪問，屬性須要經過getter和setter訪問。但在kotlin中並不能手動聲明字段，使用的效果和PROPPERTY並無差異）。

  • LOCAL_VARIABLE：局部變量。

  • VALUE_PARAMETER：函數或者構造函數的入參。

  • CONSTRUCTOR：構造函數。

  • FUNCTION：不包含構造函數的函數。

  • PROPERTY_GETTER：屬性的getter方法。

  • PROPERTY_SETTER：屬性的setter方法。

  • TYPE：類型（好比是Int，Double這些，在聲明的時候能夠給他們加上註解）。

  • EXPRESSION：表達式。

  • FILE：文件（須要配合@file明確註解目標，類如@file:JvmName("1")）。

  • TYPEALIAS：類型別名。

• Retention ：標記註釋的保留期，傳入一個枚舉類AnnotationRetention。AnnotationRetention中定義了三個時期：

  • SOURCE：源代碼時期，編譯器會丟棄該註解。

  • BINARY：編譯時期，記錄在CLASS文件中，運行時不會被JVM保留。

  • RUNTIME：運行時期，會被JVM保留，能夠進行反射讀取他們，也是默認的保留期。

• MustBeDocumented：標註一個註釋爲公共API的一部分，保證該註解在生成的API文檔中可見。

• Repeatable ：標記一個註釋能夠在一個代碼元素上屢次使用。

預置註解

kotlin的語法和java的語法仍是有很大的不一樣，針對這個問題，kotlin中預置了一些註解，解決與Java兼容問題。

• JvmDefault： kotlin中，給接口中的方法設置實體，反編譯成java代碼後，會在接口中生成一個靜態內部類 DefaultImpls，將方法的實體放入其中，對應的調用時都須要先調用這個靜態內部類。使用JvmDefault能夠去除這個靜態內部類，將方法實體直接放入了接口之中(JAVA8)。

• JvmFiled：kotlin中定義的公開屬性，反編譯成java中的屬性是私有的且將setter和getter暴漏出來的，不能直接訪問；加上JvmFiled，變量在java中就成了公開變量，能夠直接訪問。在伴生對象companion object中定義一個val變量，生成的會是一個私有變量但將getter方法生成到Companion對象中，在java中訪問須要調用伴生對象中的getter方法，給這個變量加上const修飾詞會讓生成的變量是公開靜態變量，加上JvmFiled註解效果相同，讓變量能夠在Java中直接訪問，不用加上Companion。

• JvmName：指定kotlin反編譯的Java的方法名，字段名，類名等。

• JvmMultifileClass：將不一樣的kotlin文件生成到一個java文件中，須要使用JvmName指定生成的文件名，以後就能夠在java中經過這個文件名訪問不一樣kotlin中代碼。

• JvmOverloads：kotlin中的方法能夠給入參設置默認值，這樣在kotlin中調用的時候就能夠不傳入全部的值，可是在java中卻不能這樣調用，由於生成的java代碼只有一個傳入了所有參數的方法。使用Jvmoverloads指定函數生成多個重載，就能夠在Java中調用。通常須要在自定義view的時候使用，將構造函數重載成多個，不然在XML中使用這個view會拋出異常。

• JvmPackageName：指定從該文件生成.class文件的包名稱。

• JvmStatic：想要在kotlin中定義靜態方法是將這些方法放入伴生對象中，雖然在kotlin中能夠經過調用靜態方法那樣經過類名調用，但反編譯Java是經過定義一個靜態內部類Companion，其中存放着伴生對象中的方法，類中持有一個這個內部靜態類的實例對象來調用這些方法。給這些方法加上JvmStatic註解以後，會把這些方法暴露成java的靜態方法。若是標註的是靜態屬性，則會生成靜態的getter和setter。

• JvmSuppressWildcards：在kotlin中，沒有通配符（類如 ？ extends Number），能夠直接進行泛型轉換 val numberList : List<Number> = ArrayList<Int>()，這種寫法在Java中會報錯。默認狀況下，kotlin反編譯Java的時候會在必要的狀況下（1.類型不是最終類。2.不是函數的返回類型。）生成通配符。

  類以下面生成的方法中，入參生成Number的通配符List<? extends Number>，另外一個入參List<String>由於是最終類沒有生成，返回值也沒有生成。

  某些狀況下，若是想要更改默認的生成行爲，可使用JvmSUppressWildcards，此註釋可傳入一個布爾值（默認值是true），true表示生成類型不帶通配符，false表示生成類型帶通配符。

fun transformList(list : List<Number>, list : List<String>) : List<Number> // Kotlin

public List<Number> transformList(List<? extends Number> list, List<String> list) // Java
複製代碼

• JvmWildcard：與上一個一致，至關於JvmSuppressWildcards(false)，不一樣的是能夠作用的目標對象不一樣，JvmWildcard只能做用於類型參數，JvmSuppressWildcards能夠做用於類、函數、屬性、類型參數。

• JvmSynthetic：在生成的Java字節碼中加上'ACC_SYNTHETIC'標誌，標記爲合成，禁止方法在java中訪問。

• Throws：kotlin中沒有受檢的異常（不強制要求必須處理異常），能夠有選擇的決定是否對異常進行處理，因此在kotlin中沒有聲明異常的throws關鍵字。使用註解Thorws會讓生成的Java代碼中進行throws，這樣在java中調用的時候會檢查這個異常。

• Volatile：充當java中vilatile關鍵字（多線程變量可見性）。

• Transient：充當java中transient關鍵字（不被序列化）。

• Strictfp：充當java中strictfp關鍵字（浮點數精度）。

• Synchronized：充當java中synchronized關鍵字（鎖）。