Pembuatan kode menggunakan Javadoc

Pembuatan kode otomatis menjadi semakin umum dalam pengembangan perangkat lunak, sebagai akibat dari kebutuhan untuk menyembunyikan kompleksitas dari pengembang perangkat lunak dan penerimaan berbagai antarmuka pemrograman aplikasi standar dan de facto. Menyembunyikan kompleksitas dari pengembang dapat ditunjukkan dengan membuat kelas rintisan dan kerangka di CORBA dari deskripsi bahasa definisi antarmuka mereka dan oleh beberapa database berorientasi objek yang membuat kode adaptor yang diperlukan untuk mempertahankan dan mengambil objek dari database.

Java berisi banyak API yang dianggap oleh pengembang Java sebagai standar de facto. Kompleksitas API ini berkisar dari yang merupakan "inti" dari bahasa Java hingga yang ditemukan di Platform Java 2, Edisi Perusahaan. Misalnya, Java Database Connectivity API menyajikan antarmuka pemersatu untuk berinteraksi dengan database dari berbagai perusahaan. Misalkan Anda ingin objek Java dapat bertahan sendiri ke database dengan menerapkan save()metode sederhana yang memetakan atribut objek ke tabel database. Metode itu akan mengekstrak atribut dari objek dan menggunakan JDBC API untuk membuat pernyataan JDBC yang dijalankan terhadap database. Setelah menerapkansave()metode untuk beberapa kelas, Anda mulai melihat kesamaan dalam struktur kode dan sifat berulang dari penerapan metode itu. Seringkali atribut dasar suatu objek perlu ditransliterasi dan "dicolokkan" ke Java API yang sesuai. Saat itulah pembuat kode dapat menjadi alat yang berguna untuk dimiliki di kotak alat pemrograman Anda.

Dengan menggunakan pembuat kode, Anda dapat mengotomatiskan proses beberapa tugas pengkodean yang membosankan, berulang, dan rawan kesalahan. Fakta bahwa Anda terhubung ke API terkenal meningkatkan kegunaan alat semacam itu, karena ini berlaku untuk khalayak pengembang yang luas. Selain itu, beberapa framework khusus domain "in-house" juga dapat dianggap sebagai target API tetap untuk pembuat kode.

Generator kode dapat menjadi alat penghemat waktu yang meningkatkan kualitas kode dan memperkenalkan pendekatan yang lebih formal dan otomatis ke bagian dari siklus pengembangan. Keuntungan lain dari pembuatan kode otomatis adalah sinkronisasi definisi objek di berbagai bahasa pemrograman. Dalam banyak aplikasi yang terikat ketat, objek bisnis yang sama (misalnya, pesanan untuk membeli saham) harus direpresentasikan secara konsisten dalam C ++, Java, dan SQL. Kemampuan untuk menghasilkan representasi yang berbeda dari model umum tersedia di berbagai alat pemodelan; Namun, saya merasa canggung menggunakan alat tersebut untuk mencapai tingkat penyesuaian yang diperlukan. Generator kode khusus khusus cukup sederhana untuk dibuat dan tidak mengikat Anda ke alat pemodelan tertentu.

Jalan menuju Javadoc

Jalur yang diambil tim saya untuk memilih Javadoc untuk tujuan pembuatan kode agak panjang, dan mungkin umum. Dalam implementasi awal, kami menggunakan skrip Perl untuk mengurai tata bahasa metadata kustom dalam file teks. Ini adalah solusi ad hoc, dan menambahkan format keluaran tambahan sulit. Upaya kedua kami yang berumur pendek adalah memodifikasi kompiler IDL berbasis Java yang sudah ada. Kami segera menyadari bahwa kata kunci IDL tambahan harus diperkenalkan untuk mengirimkan petunjuk ke pembuat kode. Membuat ekstensi ke IDL, atau bahkan memulai dari awal dengan alat seperti lex dan yacc (yang membagi file sumber menjadi token dan menentukan kode yang dipanggil untuk setiap token yang dikenali) tidak cocok secara pribadi. (Lihat Sumberdaya untuk informasi lebih lanjut.)

Solusi ketiga yang lebih menjanjikan adalah mendeskripsikan metadata kelas menggunakan XML. Mendefinisikan skema XML DTD dan membuat dokumen XML untuk mendeskripsikan kelas sepertinya cocok secara alami. File tersebut kemudian dapat diverifikasi dan diurai dengan mudah. Untuk menghindari memulai dari awal, saya pikir seseorang pasti telah mencoba membuat XML DTD yang serupa, dan saya segera menemukan XMI. XMI adalah deskripsi lengkap UML menggunakan XML, dan sekarang digunakan sebagai format pertukaran antara alat UML. (Lihat Sumberdaya untuk informasi lebih lanjut.)

Namun, dokumen XML yang mendeskripsikan kelas sangat bertele-tele dan sulit untuk diedit secara manual. Ada terlalu banyak tag dan deskripsi yang tampaknya tidak berguna untuk disingkirkan agar Anda dapat mengubah satu atribut kelas. Selain itu, memanipulasi file XML di tingkat domain aplikasi bisa sangat membosankan. IBM alphaWorks menghasilkan toolkit XMI yang membuat pemrosesan dokumen XML berbasis XMI jauh lebih mudah, tetapi API toolkit XMI untuk memanipulasi deskripsi kelas sangat mirip dengan Java Reflection atau Doclet API. Dengan pemikiran tersebut, organisasi saya memutuskan untuk menggunakan pendekatan doclet, yang telah berhasil.

Memperkenalkan Javadoc

Javadoc adalah program yang digunakan untuk membuat dokumentasi API Java format HTML. Ini didistribusikan sebagai bagian dari Java SDK dan tahap keluarannya dirancang agar dapat diperluas melalui pembuatan doclet. Doclet API menyediakan infrastruktur untuk mengakses semua aspek file kode sumber Java yang telah diurai oleh Javadoc. Dengan menggunakan Doclet API, yang mirip dengan Reflection API, Anda dapat melihat deskripsi kelas Java, mengakses tag Javadoc kustom, dan menulis output ke file. Doclet standar yang digunakan untuk membuat dokumentasi HTML hanya melakukan itu; itu menulis file HTML saat melintasi semua kode sumber Java. Informasi lebih rinci tentang Javadoc dapat ditemukan di Sumber.

Dengan membuat kelas Java sederhana yang berisi atribut dan beberapa tag Javadoc kustom, Anda mengizinkan kelas tersebut berfungsi sebagai deskripsi metadata sederhana untuk pembuatan kode. Javadoc mengurai kelas-kelas metadata tersebut, dan dokumen khusus mengakses informasi kelas metadata untuk membuat implementasi konkret dari kelas metadata dalam bahasa pemrograman tertentu seperti Java, C ++, atau SQL. Anda juga dapat membuat variasi dari dokumen standar yang menghasilkan tabel HTML sederhana yang mendeskripsikan kelas metadata, yang akan sesuai untuk dimasukkan dalam dokumen pengolah kata. Metadata kelas Java tersebut memiliki tujuan yang sama dengan deskripsi IDL yang sintaksnya mirip dengan C ++.

Menggunakan Javadoc sebagai alat pembuat kode memiliki beberapa keuntungan:

  • Anda tidak perlu menulis kode parsing apa pun; penguraian kelas metadata dilakukan oleh Javadoc, dan disajikan dalam API yang mudah digunakan.
  • Dengan menggunakan tag Javadoc kustom, Anda menambahkan fleksibilitas yang cukup untuk menentukan hook khusus selama pembuatan kode.
  • Karena tipe Java didefinisikan dengan baik, int adalah 32 bit; oleh karena itu, Anda tidak perlu memasukkan kata kunci jenis primitif tambahan untuk mencapai tingkat kejelasan tersebut.
  • Anda dapat memeriksa kelas metadata Java untuk sintaks dan kesalahan lainnya dengan kompilasi.

Memperkenalkan doclets

Sebelum beralih ke doclet yang digunakan untuk pembuatan kode, saya akan menyajikan contoh sederhana "Hello World" yang memperlihatkan bagian-bagian yang relevan tentang cara membuat, menjalankan, dan bermain dengan Doclet API. Kode contoh untuk SimpleDocletdiberikan di bawah ini. (Anda dapat memperoleh kode sumber untuk artikel ini di Resources.) Jika Anda menganggap kode ini agak panjang untuk program "Hello World" yang sebenarnya, Sun Website menyajikan dokumen yang lebih sederhana untuk membantu Anda memulai. (Lihat Sumber.)

paket codegen.samples; import com.sun.javadoc. *; import java.text. *; public static boolean start (RootDoc ​​root) {// iterasi di semua kelas. ClassDoc [] kelas = root.classes (); for (int i = 0; i <class.length; i ++) {// iterasi semua metode dan cetak namanya. MethodDoc [] metode = kelas [i] .methods (); out ("Metode"); di luar("-------"); untuk (int j = 0; j
   
    

Doclet di atas mencetak informasi deskriptif kelas, metode, bidang, dan beberapa informasi tag Javadoc dari kelas yang SimpleOrder.javatercantum di bawah ini:

kelas publik SimpleOrder {public SimpleOrder () {} string publik getSymbol () {return Symbol; } public int getQuantity () {{escriptive return Quantity; } / ** * Simbol saham yang valid. * * @ lihat Buku besar simbol yang valid untuk informasi lebih lanjut. * / Simbol String pribadi; / ** * Total volume pesanan. * * @mytag Tag kustom saya. * / Kuantitas int pribadi; private String OrderType; Harga float pribadi; Private String Duration; private int AccountType; private int TransactionType; }

Setelah menyusun file-file ini, Anda menjalankan alat Javadoc menggunakan perintah ini:

javadoc -private -doclet codegen.samples.SimpleDoclet SimpleOrder.java 

The -privatepilihan memberitahu Javadoc untuk mengekspos informasi lapangan dan metode pribadi, dan -docletpilihan memberitahu Javadoc apa Doclet untuk memohon. Parameter terakhir adalah file yang akan diurai. Output dari program ini adalah sebagai berikut:

Memuat file sumber SimpleOrder.java ... Membuat informasi Javadoc ... Metode ------- Metode: name = getSymbol Metode: name = getQuantity Fields ------ Field: name = Symbol, comment = Valid simbol saham., ketik = java.lang.String; Field Tag Name = @see Field Tag Value = Buku besar simbol yang valid untuk informasi lebih lanjut. Field: name = Quantity, comment = Total order volume., Type = int; Nama Tag Bidang = @mytag Nilai Tag Bidang = Tag kustom saya. Field: name = OrderType, comment =, type = java.lang.String; Field: name = Price, comment =, type = float; Field: name = Durasi, komentar =, type = java.lang.String; Field: name = AccountType, comment =, type = int; Field: name = TransactionType, comment =, type = int;

Kode contoh menunjukkan bahwa Doclet API ada di dalam paket com.sun.javadoc. Karena Anda terhubung ke alat Javadoc dan tidak membuat aplikasi mandiri, Javadoc memanggil doclet Anda dari metode tersebut public static boolean start(RootDoc root).

Setelah startmetode dijalankan, RootDocsimpan semua informasi yang diurai oleh Javadoc. Anda kemudian bisa mulai berjalan melalui semua kelas yang diurai dengan menjalankan metode classes()pada RootDoc. Metode itu mengembalikan ClassDoclarik yang mendeskripsikan semua kelas yang diurai. ClassDocpada gilirannya berisi metode seperti fields()dan methods(). Metode ini mengembalikan FieldDocdan MethodDoclarik yang mendeskripsikan semua bidang dan metode kelas yang diurai. Semua kelas "Doc" berisi metode tags, yang mengembalikan Taglarik yang mendeskripsikan tag Javadoc kustom dan standar. Tag standar yang digunakan dalam contoh ini adalah @see.

The out()metode hanya membungkus output standar, dan MessageFormatkelas membantu memformat output sesuai dengan template tetap.

Kelas yang dapat digunakan kembali untuk pembuatan kode

Berdasarkan contoh di atas, saya harap Anda setuju bahwa membuat doclet Anda sendiri dan mengekstrak informasi kelas menggunakan API Doclet itu mudah. Langkah selanjutnya untuk mem-parsing kelas Java dan menghasilkan kode ke file relatif mudah. Untuk membuat pembuatan dokumen pembuatan kode lebih mudah, saya mengembangkan satu set kecil antarmuka dan kelas dasar abstrak. Diagram kelas dari kelas utilitas ini ditampilkan di bawah.

The interface Maker defines the method signature public void make(ClassDoc classdoc) that you will use to interact with your code generators. The abstract class CodeMaker provides default implementations for manipulating files and indention, which are common to all code generators. Specific code generators inherit from the abstract base class and provide an implementation of the make method. The make method has the class ClassDoc as an argument, not RootDoc. That causes the Maker to enter the code generation logic at the class level.

All classes parsed by Javadoc are looped over in the doclets plug-in method start. An example of how that is done (described in the file SimpleMakerDoclet.java) is shown below:

publik boolean mulai statis (rootDoc ​​root) {ClassDoc [] kelas = root.classes (); // Siapkan Pembuat Kode untuk menjalankan Maker simplemaker = new SimpleCodeMaker ("Description Maker"); // Iterasi melalui semua kelas dan jalankan metode "make" untuk Maker (int i = 0; i <class.length; i ++) {ClassDoc classdoc = class [i]; simplemaker.make (classdoc); } kembali benar; }

Berikut ini adalah bagian dari kode dari generator kode sederhana yang disebut SimpleCodeMaker, yang melakukan tugas yang sama seperti yang SimpleDocletterdaftar sebelumnya. Alih-alih mengirimkan keluaran ke layar, SimpleCodeMakersimpanlah ke file di subdirektori genclasses. Penerapan makemetode juga menjadi lebih terstruktur dengan metode terpisah untuk mengolah bidang dan metode. Hanya metode makedan processMethodsyang tercantum di sini agar singkatnya.