Bagikan melalui

Mengikat Pustaka Java

  • Artikel

Komunitas Android memiliki banyak pustaka Java yang mungkin ingin Anda gunakan di aplikasi Anda; panduan ini menjelaskan cara menggabungkan pustaka Java ke dalam aplikasi Xamarin.Android Anda dengan membuat Pustaka Pengikatan.

Gambaran Umum

Ekosistem pustaka pihak ketiga untuk Android sangat besar. Karena itu, sering masuk akal untuk menggunakan pustaka Android yang ada daripada membuat yang baru. Xamarin.Android menawarkan dua cara untuk menggunakan pustaka ini:

  • Buat Pustaka Pengikatan yang secara otomatis membungkus pustaka dengan pembungkus C# sehingga Anda dapat memanggil kode Java melalui panggilan C#.

  • Gunakan Java Native Interface (JNI) untuk memanggil panggilan dalam kode pustaka Java secara langsung. JNI adalah kerangka kerja pemrograman yang memungkinkan kode Java untuk memanggil dan dipanggil oleh aplikasi atau pustaka asli.

Panduan ini menjelaskan opsi pertama: cara membuat Pustaka Pengikatan yang membungkus satu atau beberapa pustaka Java yang ada ke dalam rakitan yang dapat Anda tautkan di aplikasi Anda. Untuk informasi selengkapnya tentang menggunakan JNI, lihat Bekerja dengan JNI.

Xamarin.Android mengimplementasikan pengikatan dengan menggunakan Managed Callable Wrappers (MCW). MCW adalah jembatan JNI yang digunakan ketika kode terkelola perlu memanggil kode Java. Pembungkus yang dapat dipanggil terkelola juga menyediakan dukungan untuk subkelas jenis Java dan untuk mengambil alih metode virtual pada jenis Java. Demikian juga, setiap kali kode runtime Android (ART) ingin memanggil kode terkelola, kode tersebut melakukannya melalui jembatan JNI lain yang dikenal sebagai Android Callable Wrappers (ACW). Arsitektur ini diilustrasikan dalam diagram berikut:

Android JNI bridge architecture

Pustaka Pengikatan adalah rakitan yang berisi Pembungkus Yang Dapat Dipanggil Terkelola untuk jenis Java. Misalnya, berikut adalah jenis Java, MyClass, yang ingin kita bungkus dalam Pustaka Pengikatan:

package com.xamarin.mycode;

public class MyClass
{
    public String myMethod (int i) { ... }
}

Setelah kita membuat Pustaka Pengikatan untuk .jar yang berisi MyClass, kita dapat membuat instans dan memanggil metode di atasnya dari C#:

var instance = new MyClass ();

string result = instance.MyMethod (42);

Untuk membuat Pustaka Pengikatan ini, Anda menggunakan templat Pustaka Pengikatan Java Xamarin.Android. Proyek pengikatan yang dihasilkan membuat rakitan .NET dengan kelas MCW, file .jar , dan sumber daya untuk proyek Android Library yang disematkan di dalamnya. Anda juga dapat membuat Pustaka Pengikatan untuk Arsip Android (. AAR) dan proyek Eclipse Android Library. Dengan mereferensikan rakitan DLL Pustaka Pengikatan yang dihasilkan, Anda dapat menggunakan kembali pustaka Java yang ada di proyek Xamarin.Android Anda.

Saat mereferensikan jenis di Pustaka Pengikatan, Anda harus menggunakan namespace pustaka pengikatan Anda. Biasanya, Anda menambahkan using direktif di bagian atas file sumber C# Anda yang merupakan versi namespace layanan .NET dari nama paket Java. Misalnya, jika nama paket Java untuk .jar terikat Anda adalah sebagai berikut:

com.company.package

Kemudian Anda akan menempatkan pernyataan berikut using di bagian atas file sumber C# Anda untuk mengakses jenis dalam file .jar terikat:

using Com.Company.Package;

Saat mengikat pustaka Android yang ada, perlu diingat poin-poin berikut:

  • Apakah ada dependensi eksternal untuk pustaka? – Dependensi Java apa pun yang diperlukan oleh pustaka Android harus disertakan dalam proyek Xamarin.Android sebagai ReferenceJar atau sebagai EmbeddedReferenceJar. Setiap rakitan asli harus ditambahkan ke proyek pengikatan sebagai EmbeddedNativeLibrary.

  • Versi Android API apa yang ditargetkan oleh pustaka Android? – Tidak dimungkinkan untuk "menurunkan" tingkat ANDROID API; pastikan bahwa proyek pengikatan Xamarin.Android menargetkan tingkat API yang sama (atau lebih tinggi) dengan pustaka Android.

  • Versi JDK apa yang digunakan untuk mengkompilasi pustaka? – Kesalahan pengikatan dapat terjadi jika pustaka Android dibuat dengan versi JDK yang berbeda dari yang digunakan oleh Xamarin.Android. Jika memungkinkan, kompilasi ulang pustaka Android menggunakan versi JDK yang sama yang digunakan oleh penginstalan Xamarin.Android Anda.

Tindakan Build

Saat membuat Pustaka Pengikatan, Anda mengatur tindakan build pada .jar atau . File AAR yang Anda masukkan ke dalam proyek Pustaka Pengikatan Anda - setiap tindakan build menentukan bagaimana .jar atau . File AAR akan disematkan ke dalam (atau direferensikan oleh) Pustaka Pengikatan Anda. Daftar berikut ini meringkas tindakan build ini:

  • EmbeddedJar – Menyematkan .jar ke dalam DLL Pustaka Pengikatan yang dihasilkan sebagai sumber daya yang disematkan. Ini adalah tindakan build yang paling sederhana dan paling umum digunakan. Gunakan opsi ini saat Anda ingin .jar dikompilasi secara otomatis ke dalam kode byte dan dikemas ke dalam Pustaka Pengikatan.

  • InputJar – Tidak menyematkan .jar ke dalam .DLL Pustaka Pengikatan yang dihasilkan. Pustaka Pengikatan Anda .DLL akan memiliki dependensi pada .jar ini saat runtime. Gunakan opsi ini saat Anda tidak ingin menyertakan .jar di Pustaka Pengikatan Anda (misalnya, karena alasan lisensi). Jika Anda menggunakan opsi ini, Anda harus memastikan bahwa input .jar tersedia di perangkat yang menjalankan aplikasi Anda.

  • LibraryProjectZip – Menyematkan . File AAR ke dalam .DLL Pustaka Pengikatan yang dihasilkan. Ini mirip dengan EmbeddedJar, kecuali Anda dapat mengakses sumber daya (serta kode) di terikat . File AAR. Gunakan opsi ini saat Anda ingin menyematkan . AAR ke Pustaka Pengikatan Anda.

  • ReferenceJar– Menentukan .jar referensi: .jar referensi adalah .jar bahwa salah satu .jar terikat Anda atau . File AAR bergantung pada. Referensi ini .jar digunakan hanya untuk memenuhi dependensi waktu kompilasi. Saat Anda menggunakan tindakan build ini, pengikatan C# tidak dibuat untuk referensi .jar dan tidak disematkan dalam .DLL Pustaka Pengikatan yang dihasilkan. Gunakan opsi ini saat Anda akan membuat Pustaka Pengikatan untuk referensi .jar tetapi belum melakukannya. Tindakan build ini berguna untuk mengemas beberapa .jar(dan/atau . ARS) ke dalam beberapa Pustaka Pengikatan yang saling bergantung.

  • EmbeddedReferenceJar – Menyematkan referensi .jar ke dalam .DLL Pustaka Pengikatan yang dihasilkan. Gunakan tindakan build ini saat Anda ingin membuat pengikatan C# untuk input .jar (atau . AAR) dan semua .jar referensinya di Pustaka Pengikatan Anda.

  • EmbeddedNativeLibrary – Menyematkan .so asli ke dalam pengikatan. Tindakan build ini digunakan untuk file .so yang diperlukan oleh file .jar yang terikat. Mungkin perlu memuat pustaka .so secara manual sebelum menjalankan kode dari pustaka Java. Ini dijelaskan di bawah ini.

Tindakan build ini dijelaskan secara lebih rinci dalam panduan berikut.

Selain itu, tindakan build berikut digunakan untuk membantu mengimpor dokumentasi Java API dan mengonversinya menjadi dokumentasi C# XML:

  • JavaDocJar digunakan untuk menunjuk ke Jar arsip Javadoc untuk pustaka Java yang sesuai dengan gaya paket Maven (biasanya FOOBAR-javadoc**.jar**).
  • JavaDocIndex digunakan untuk menunjuk ke index.html file dalam HTML dokumentasi referensi API.
  • JavaSourceJar digunakan untuk melengkapi JavaDocJar, untuk terlebih dahulu menghasilkan JavaDoc dari sumber dan kemudian memperlakukan hasilnya sebagai JavaDocIndex, untuk pustaka Java yang sesuai dengan gaya paket Maven (biasanya FOOBAR-sources**.jar**).

Dokumentasi API harus menjadi doclet default dari Java8, Java7, atau Java6 SDK (semuanya adalah format yang berbeda), atau gaya DroidDoc.

Menyertakan Pustaka Asli dalam Pengikatan

Mungkin perlu menyertakan pustaka .so dalam proyek pengikatan Xamarin.Android sebagai bagian dari pengikatan pustaka Java. Ketika kode Java yang dibungkus dijalankan, Xamarin.Android akan gagal melakukan panggilan JNI dan pesan kesalahan java.lang.UnsatisfiedLinkError: Metode asli tidak ditemukan: akan muncul di logcat keluar untuk aplikasi.

Perbaikan untuk ini adalah memuat pustaka .so secara manual dengan panggilan ke Java.Lang.JavaSystem.LoadLibrary. Misalnya dengan asumsi bahwa proyek Xamarin.Android memiliki pustaka bersama libpocketsphinx_jni.so termasuk dalam proyek pengikatan dengan tindakan build EmbeddedNativeLibrary, cuplikan berikut (dijalankan sebelum menggunakan pustaka bersama) akan memuat pustaka .so:

Java.Lang.JavaSystem.LoadLibrary("pocketsphinx_jni");

Mengadaptasi API Java ke C⧣

Generator Pengikatan Xamarin.Android akan mengubah beberapa idiom dan pola Java agar sesuai dengan pola .NET. Daftar berikut ini menjelaskan bagaimana Java dipetakan ke C#/.NET:

  • Metode Setter/Getter di Java adalah Properti di .NET.

  • Bidang di Java adalah Properti di .NET.

  • Antarmuka Pendengar/Pendengar di Java adalah Peristiwa di .NET. Parameter metode dalam antarmuka panggilan balik akan diwakili oleh EventArgs subkelas.

  • Kelas Berlapis Statis di Java adalah kelas Berlapis di .NET.

  • Kelas Dalam di Java adalah kelas Berlapis dengan konstruktor instans di C#.

Skenario Pengikatan

Panduan skenario pengikatan berikut dapat membantu Anda mengikat pustaka Java (atau pustaka) untuk penggabungan ke dalam aplikasi Anda:

  • Mengikat . JAR adalah panduan untuk membuat Pustaka Pengikatan untuk file .jar .

  • Mengikat . AAR adalah panduan untuk membuat Pustaka Pengikatan untuk . File AAR. Baca panduan ini untuk mempelajari cara mengikat pustaka Android Studio.

  • Mengikat Eclipse Library Project adalah panduan untuk membuat pustaka pengikatan dari Proyek Pustaka Android. Baca panduan ini untuk mempelajari cara mengikat Proyek Pustaka Android Eclipse.

  • Menyesuaikan Pengikatan menjelaskan cara membuat modifikasi manual pada pengikatan untuk mengatasi kesalahan build dan membentuk API yang dihasilkan sehingga lebih "seperti C#".

  • Pemecahan masalah Pengikatan mencantumkan skenario kesalahan pengikatan umum, menjelaskan kemungkinan penyebabnya, dan menawarkan saran untuk mengatasi kesalahan ini.