แพลตฟอร์ม Eclipse
กฎ API ของสภาวะการทำงาน

เวอร์ชัน 0.15 - แก้ไขล่าสุด 12:00 น. 30 พฤษภาคม 2001

นี่คือกฎของสภาวะการทำงานสำหรับไคลเอ็นต์ของแพลตฟอร์ม Eclipse API (และคอมโพเนนต์อื่นๆ)

อะไรคือความหมายของ API

แพลตฟอร์ม Eclipse นิยามอิลิเมนต์ API สำหรับใช้โดยไคลเอ็นต์ ซึ่งชื่อ ISVs ที่เขียนปลั๊กอิน ปลั๊กอินเหล่านี้อาจนิยามอิลิเมนต์ API สำหรับไคลเอ็นต์ และอื่นๆ อิลิเมนต์ API คือ public face: อิลิเมนต์เหล่านี้ใส่ ข้อกำหนดคุณสมบัติเกี่ยวกับสิ่งที่อิลิเมนต์จะทำ และเกี่ยวกับวิธีที่ ต้องการใช้ อิลิเมนต์ API ได้รับการสนับสนุน:ทีมแพลตฟอร์ม Eclipse จะแก้บักของการนำไปใช้งานซึ่งมีความคลาดเคลื่อน จากลักษณะการทำงานที่ระบุไว้ เนื่องจากมีต้นทุนสูงที่จะเชื่อมโยงกับการหยุดการเปลี่ยนแปลง API ทีมแพลตฟอร์มจะยังพยายามพัฒนาอิลิเมนต์ API ตลอดทั้งรีลีสหลักที่ดำเนินการเป็นผลสำเร็จ

วิธีการแจ้ง API จากสิ่งที่ไม่ใช่ API

ตามลักษณะการทำงานแล้ว อิลิเมนต์ API ถูกจัดทำเป็นเอกสารและมีข้อกำหนดคุณสมบัติ ซึ่งแตกต่างกับอิลิเมนต์ที่ไม่ใช่ API ที่มีรายละเอียดของการนำไปใช้งานภายใน โดยไม่เผยแพร่เอกสารคู่มือหรือข้อกำหนดคุณสมบัติ ดังนั้น หากคุณไม่สามารถค้นหา เอกสารคู่มือสำหรับบางสิ่ง ซึ่งเป็นตัวบ่งชี้ที่ดี ที่ไม่ใช่ API

หากต้องการลองลากเส้นทั้งหมดเพิ่มเติม โค้ดที่อ้างอิงสำหรับแพลตฟอร์ม จะถูกแบ่งออกเป็น API และแพ็กเกจที่ไม่ใช่ API ที่มีอิลิเมนต์ API ทั้งหมดที่ถูกประกาศ ในแพ็กเกจ API ที่ถูกกำหนดไว้

ทุกๆ สิ่งที่นอกเหนือจากนี้ถูกพิจารณาในรายละเอียดของการนำไปใช้งานภายในและจำกัด ไคลเอ็นต์ทั้งหมด โค้ดไคลเอ็นต์ที่ถูกต้องตามกฎหมายต้องไม่ถูกอ้างถึงชื่อของอิลิเมนต์ที่ไม่ใช่ API (ไม่ได้ใช้การสะท้อนถึง Java) ในบางกรณี กฎของความสามารถในการเข้าถึงชื่อของภาษา Java ถูกใช้เพื่อไม่อนุญาตให้อ้างถึงสิ่งที่ผิดกฎเกณฑ์ อย่างไรก็ตาม มีกรณีต่างๆ ที่เป็นกรณีที่อาจเป็นไปไม่ได้ โปรดสังเกตว่าหนึ่งกฎจะ หลีกเลี่ยงปัญหาได้อย่างสมบูรณ์:

กฎทั่วไป

ข้อกำหนดคุณสมบัติของอิลิเมนต์ API ถูกสร้างขึ้นจากข้อคิดเห็น Javadoc ในซอร์สโค้ด Java ของอิลิเมนต์ สำหรับบางชนิดของอิลิเมนต์ ข้อกำหนดคุณสมบัติ อยู่ในรูปแบบข้อตกลง ตัวอย่างเช่น ในกรณีของเมธอด ข้อตกลงอยู่ระหว่างสองกลุ่ม ผู้เรียกของเมธอดและ implementor ของเมธอด กฎพื้นฐานคือ: คำว่า "must" เมื่อใช้ในข้อตกลง API หมายความว่าต้องทำหน้าที่ตามกลุ่ม เพื่อทำให้มั่นใจว่า เงื่อนไขจะตรงกับข้อกำหนด ความล้มเหลวใด ที่ทำไว้จะถูกพิจารณาเป็นข้อผิดพลาดทางด้านโปรแกรมมิงซึ่งเป็นผลที่ไม่ได้ระบุไว้ (และในบางครั้ง ไม่ได้คาดการณ์ไว้) กฎการรับรู้อื่นๆ:

การเรียก API แบบพับลิก

สำหรับโคลเอ็นต์ส่วนใหย๋ กลุ่มของ Eclipse API จะใช้รูปแบบของเมธอดแบบพับลิก บนอินเตอร์เฟสหรือคลาส API ซึ่งผู้ให้บริการไคลเอ็นต์จะเรียก ในเวลาที่เหมาะสม

แพลตฟอร์มตัวอย่างสำหรับคลาส API

ไม่ใช่คลาส API ทั้งหมดที่มีเจตนาให้เป็นเพียงแค่ตัวอย่างโดยบุคคลใดๆ คลาส API มีตัวอย่างข้อตกลงที่บ่งชี้เงื่อนไขภายใต้ อินสแตนซ์ที่อาจสร้างขึ้นได้ ข้อตกลงอาจยังครอบคลุมสิ่งที่คล้ายกับ ความรับผิดชอบในการกำหนดค่าเริ่มต้นที่เหลืออยู่ (ตัวอย่างเช่น การปรับแต่งคุณสมบัติบางอย่าง ก่อนที่อินสแตนซ์จะแอ็คทีฟทั้งหมด) และความรับผิดชอบต่อวงจรอายุที่เชื่อมโยง (ตัวอย่างเช่น การเรียก dispose() เพื่อทำให้รีซอร์ส OS ว่างและหยุดทำงาน ตามอินสแตนซ์) คลาสที่ถูกออกแบบเพื่อให้เป็นตัวอย่างโดยไคลเอ็นต์ จะถูกแฟล็กไว้ในข้อคิดเห็นของคลาส Javadoc (ด้วยคำว่า "ไคลเอ็นต์ อาจเป็นตัวอย่างประกอบ").

การแบ่งคลาสย่อยของคลาสแพลตฟอร์ม API

เฉพาะเซ็ตย่อยของคลาส API เท่านั้นที่ถูกออกแบบให้เป็นคลาสย่อย คลาส API มีข้อตกลงสำหรับคลาสย่อยที่บ่งชี้เงื่อนไขภายใต้คลาสย่อย ที่อาจถูกประกาศไว้ ข้อตกลงนี้ยังครอบคลุมความรับผิดชอบต่อการกำหนดค่าเริ่มต้น และความรับผิดชอบต่อวงจรอายุ คลาสที่ถูกออกแบบเพื่อแบ่งคลาสย่อยตามไคลเอ็นต์ จะถูกแฟล็กไว้ในข้อคิดเห็นของคลาส Javadoc ไว้อย่างชัดเจน (ด้วยคำว่า "ไคลเอ็นต์อาจเป็นคลาสย่อย").

การเรียกเมธอด protected API

การเรียกเมธอดแบบ protected และ public ที่สืบทอดภายในคลาสย่อย ได้รับอนุญาตให้ใช้ทั่วไป อย่างไรก็ตาม บ่อยครั้งที่จำเป็นต้องให้ความระมัดระวัง ในการเรียกให้ถูกต้องเพื่อเรียกเมธอด public จากภายนอกลำดับชั้น

การ overrideเมธอด API

เฉพาะเซ็ตย่อยของเมธอด API แบบ public และ protected เท่านั้น ที่ถูกออกแบบมาเพื่อให้ override ได้ แต่ละเมธอดของ API มีข้อตกลงเกี่ยวกับคลาสย่อย ที่บ่งชี้อยู่ภายใต้คลาสย่อยที่อาจ override ได้ ตามค่าดีฟอลต์แล้ว ไม่อนุญาตให้ใช้ override ซึ่งเป็นสิ่งสำคัญในการตรวจสอบข้อตกลงของคลาสย่อยตามการนำไปใช้งานของเมธอดจริง ที่ override ซึ่งเงื่อนไขของข้อตกลงของคลาสย่อยไม่ได้ถูกส่งผ่าน เมื่อ override เมธอด

การนำแพลตฟอร์มอินเตอร์เฟส API ไปใช้งาน

เฉพาะเซ็ตย่อยของอินเตอร์เฟส API เท่านั้นที่ถูกออกแบบมาเพื่อให้นำไปใช้งานโดย ไคลเอ็นต์ อินเตอร์เฟส API มีข้อตกลงที่บ่งชี้เงื่อนไขภายใต้ อินเตอร์เฟสที่อาจนำไปใช้งาน อินเตอร์เฟสที่ถูกออกแบบมาเพื่อนำไปใช้งานโดยไคลเอ็นต์ ซึ่งถูกแฟลกไว้อย่างชัดเจนในข้อคิดเห็นของคลาส Javadoc (ด้วยคำว่า "ไคลเอ็นต์อาจนำไปใช้งาน"). ไคลเอ็นต์อาจประกาศอินเตอร์เฟสย่อยของ อินเตอร์เฟส API หากได้รับอนุญาตให้นำไปใช้งาน

การนำเมธอด public API ไปใช้งาน

โปรดดู "การ override เมธอด API"

การเข้าถึงฟิลด์ในคลาสและอินเตอร์เฟส API

ไคลเอ็นต์อาจอ่านฟิลด์ API ซึ่งส่วนใหญ่จะเป็น final อ็อบเจ็กต์ struct-like บางตัวอาจมีฟิลด์พับลิกที่ไม่ใช่ final ซึ่งไคลเอ็นต์อาจอ่าน และเขียนยกเว้นว่าจะบ่งชี้ไว้เป็นอย่างอื่น

อ็อบเจ็กต์ Casting ของชนิด API ที่รู้จัก

อ็อบเจ็กต์ของชนิด API ที่รู้จักอาจเป็นเพียง cast กับชนิด API ที่แตกต่างกันเท่านั้น (หรือ cast แบบมีเงื่อนไขโดยใช้ instanceof) หากได้รับอนุญาตให้ใช้ได้อย่างชัดเจน ใน API

และแน่นอน การ casting อ็อบเจ็กต์ใดๆ กับคลาสหรืออินเตอร์เฟสที่ไม่ใช่ API จะเป็นสิ่งที่ไม่เหมาะสม

ไม่ได้ทำตามกฎ

ไม่ว่าจะทำด้วยเจตนาหรือไม่เจตนาจะมีผลต่อการละเมิด กฎ ซึ่งง่ายสำหรับทุกคนที่เกี่ยวข้องหากมี API ที่จะทำให้คุณละเมิดกฎ อย่างไรก็ตาม สิ่งนี้ไม่ใช่กรณีที่จะนำมาพิจารณา สำหรับส่วนใดๆ ความสอดคล้องกันของ API จะทำงานเป็นระบบ ซึ่งมีไคลเอ็นต์ที่รับผิดชอบต่อการรับทราบกฎและปฏิบัติตาม

ข้อตกลงบนอิลิเมนต์จำกัดจำนวนของลักษณะการทำงานที่ได้รับการสนับสนุน และรักษาไว้ เนื่องจากแพลตฟอร์ม Eclipse สมบูรณ์และมีการพัฒนา แพลตฟอร์มจะเป็นข้อกำหนดของ API ที่แนะนำว่าการพัฒนาเกิดขึ้นได้อย่างไร ภายนอกข้อตกลงเหล่านี้ ทุกๆ สิ่งที่ไม่ได้รับการสนับสนุนและเกี่ยวข้องกับการเปลี่ยนแปลงโดยไม่ได้แจ้งให้ทราบ และ ณ เวลาใดๆ (ไม่ว่าจะเป็นช่วงกลางการการรีลีสหรือระหว่างแพลตฟอร์ม OS อื่นใดๆ) โค้ดไคลเอ็นต์ ที่ข้ามขั้นตอนของกฎข้างต้นอาจล้มเหลวบนเวอร์ชันและระดับของแพลตฟอร์ม ที่แตกต่างกัน หรือเมื่อรันบน OSes ที่แตกต่างกัน หรือเมื่อรันด้วยปลั๊กอินที่เหลืออยู่แบบผสมที่แตกต่างกัน หรือเมื่อรัน ด้วยเปอร์สเปคทีฟของ workbench และอื่นๆ โดยส่วนลึกแล้ว ไม่มีใครที่สนใจในการ พิจารณาวิธีการละเมิดอาจกลับมาทำร้าย คุณโดยเฉพาะ เพื่อให้บุคคลเหล่านั้นเลือกที่จะละเว้นกฎ ห้ามพูว่าคุณจะไม่เตือน และห้ามคาดหวังมากเกินกว่าความเห็นพ้องต้องกัน "Told you so"

หรืออีกนัยหนึ่ง โค้ดปลั๊กอินของไคลเอ็นต์ที่ใช้งานจริงตามกฎข้างต้น ควรทำงานข้ามเวอร์ชันอื่นๆ และระดับของแพ็ตช์ของแพลตฟอร์ม ข้าม OSes ที่แตกต่างกัน และควรอยู่ร่วมกันกับ ปลั๊กอินเอื่นๆ หากทุกคนเล่นตามกฎ แพลตฟอร์ม Eclipse จะจัดเตรียมความมั่นคงและการสนับสนุนที่อ้างอิงเพื่อนำเสนอ ผลิตภัณฑ์ใหม่