ประโยชน์หลักของคำอธิบายประกอบไม่ได้มาจากการใช้มาตรฐานที่มีอยู่แล้วใน JDK ในเวลาเดียวกัน แทบไม่ต้องสร้างคำอธิบายประกอบของคุณเอง แต่ถ้าเรากำลังพัฒนาระบบขนาดใหญ่หรือสร้างไลบรารีแยกต่างหาก ในระดับสถาปัตยกรรม การใช้คำอธิบายประกอบของเราเองจะให้ผลตอบแทนแน่นอน
มาลองสร้างคำอธิบายประกอบกัน
ในการทำเช่นนี้ ให้สร้างไฟล์ แต่แทนที่จะเขียนclassหรือinterfaceให้เขียน@interface นี่จะเป็นไฟล์สำหรับคำอธิบายประกอบของเรา โครงสร้างภายในของคำอธิบายประกอบคล้ายกับอินเทอร์เฟซ
public @interface Sum {
int sum() default 0;
}
@interfaceระบุว่านี่คือคำอธิบายประกอบ ค่า
เริ่มต้นบอกว่าพารามิเตอร์จะมีค่าเริ่มต้นเฉพาะ
ทะ-ดา! เราสร้างคำอธิบายประกอบแล้ว! ในทางทฤษฎีเราสามารถใช้งานได้แล้ว แต่ก่อนอื่นควรกำหนดค่าก่อน
หากไม่มีการกำหนดค่า คำอธิบายประกอบของเราสามารถนำไปใช้กับอะไรก็ได้ (กับคลาส เมธอด แอตทริบิวต์ ฯลฯ) ดังนั้นจึงไม่สมเหตุสมผลเลยที่จะใช้ ณ จุดนี้ อาจดูแปลก แต่คำอธิบายประกอบของเราจำเป็นต้องรวมคำอธิบายประกอบอื่นๆ ด้วย!
เริ่มต้นด้วย@Target
คำ อธิบายประกอบ @Target (เกี่ยวข้องตั้งแต่ Java 1.5) จำกัดความสามารถในการใช้คำอธิบายประกอบ หากต้องการจำกัดการใช้งานในระดับหนึ่ง เราจำเป็นต้องส่งอาร์กิวเมนต์ไปยัง คำอธิบายประกอบ @Targetเพื่อระบุว่าสามารถใช้กับประเภทใดได้บ้าง นี่คือบางประเภทที่ใช้กันทั่วไป:
@Target(ElementType.PACKAGE) | สำหรับแพ็คเกจ |
@Target(ElementType.TYPE) | สำหรับชั้นเรียน |
@Target(ElementType.CONSTRUCTOR) | สำหรับตัวสร้าง |
@Target(ElementType.METHOD) | สำหรับวิธีการ |
@Target(ElementType.FIELD) | สำหรับแอตทริบิวต์ (ตัวแปร) ในคลาส |
@Target(ElementType.PARAMATER) | สำหรับพารามิเตอร์เมธอด |
@Target(ElementType.LOCAL_VARIABLE) | สำหรับตัวแปรโลคัล |
หากคุณต้องการคำอธิบายประกอบสำหรับหลายประเภท คุณสามารถส่งอาร์กิวเมนต์หลายรายการเป็นอาร์เรย์ได้:
@Target({ ElementType.PARAMETER, ElementType.LOCAL_VARIABLE })
ส่วนต่อไปที่สำคัญของการกำหนดค่าคือคำอธิบายประกอบ@Retention
คำอธิบายประกอบนี้ระบุส่วนต่างๆ ของวงจรชีวิตของรหัสซึ่งจะมีคำอธิบายประกอบของเรา:
RetentionPolicy.SOURCE | คำอธิบายประกอบที่ทำเครื่องหมายด้วย นโยบายการเก็บรักษา SOURCEจะถูกยกเลิกเมื่อรันไทม์ |
RetentionPolicy.CLASS | คำอธิบายประกอบที่ทำเครื่องหมายด้วย นโยบายการเก็บรักษา CLASSจะถูกเขียนลงใน ไฟล์ .classแต่จะถูกลบออกเมื่อรันไทม์ |
RetentionPolicy.RUNTIME | คำอธิบายประกอบที่ทำเครื่องหมายด้วย นโยบายการเก็บรักษา RUNTIMEจะคงอยู่ ณ รันไทม์ และสามารถเข้าถึงได้ในโปรแกรมของเราเมื่อรันไทม์ |
มีคำอธิบายประกอบเพิ่มเติมสองสามรายการที่คุณใช้สำหรับการกำหนดค่าได้:
คำอธิบายประกอบ | ค่า |
---|---|
@รับการถ่ายทอด | บ่งชี้ว่าคลาสที่ได้รับสืบทอดการนำคำอธิบายประกอบของคลาสพาเรนต์ไปใช้ |
@จัดทำเป็นเอกสาร | สิ่งนี้บ่งชี้ว่าหมายเหตุประกอบจะรวมอยู่ในเอกสารคู่มือ Javadoc ที่สร้างขึ้น |
ตอนนี้ลองสร้างคำอธิบายประกอบของเราเอง
เราจะสร้างคำอธิบายประกอบสำหรับคลาสและเมธอด และมีข้อมูลเกี่ยวกับผู้เขียนโค้ดและเวอร์ชัน:
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Info {
String author() default "Author";
String version() default "0.0";
}
เราสามารถใช้คำอธิบายประกอบของเรากับเมธอดและคลาส ข้อมูลเมตาของคำอธิบายประกอบของเราจะพร้อมใช้งานในขณะดำเนินการ ให้ความสนใจกับพารามิเตอร์ของคำอธิบายประกอบของเรา: เราสามารถระบุสองอาร์กิวเมนต์ (ผู้เขียนและเวอร์ชัน) หรือคุณสามารถละเว้นได้ หากเราละเว้น ค่าเริ่มต้นที่ระบุ ( ค่าเริ่มต้น "ผู้เขียน"และค่าเริ่มต้น "0.0" ) จะถูกใช้
เป็นที่น่าสังเกตว่าเราไม่ต้องระบุค่าเริ่มต้นสำหรับพารามิเตอร์ ในกรณีนี้ พารามิเตอร์จะกลายเป็นข้อบังคับ
เมื่อผ่านการโต้แย้ง เราต้อง ระบุพารามิเตอร์ที่เกี่ยวข้องโดยใช้สัญกรณ์value = "value" ต้องตั้งชื่อพารามิเตอร์ให้ชัดเจนเสมอ แม้ว่าคำอธิบายประกอบจะมีพารามิเตอร์เดียวก็ตาม
ลองใช้คำอธิบายประกอบของเรากับบางคลาส:
@Info
public class MyClass1 {
@Info
public void myClassMethod() {}
}
@Info(version = "2.0")
public class MyClass2 {
@Info(author = "Anonymous")
public void myClassMethod() {}
}
@Info(author = "Anonymous", version = "2.0")
public class MyClass3 {
@Info(author = "Anonymous", version = "4.0")
public void myClassMethod() {}
}