Udostępnij za pośrednictwem

Tworzenie powiązań biblioteki języka Java

  • Artykuł

Społeczność systemu Android ma wiele bibliotek Java, których możesz użyć w aplikacji; W tym przewodniku wyjaśniono, jak dołączyć biblioteki Java do aplikacji platformy Xamarin.Android, tworząc bibliotekę powiązań.

Omówienie

Ekosystem bibliotek innych firm dla systemu Android jest ogromny. W związku z tym często warto użyć istniejącej biblioteki systemu Android niż utworzyć nową. Platforma Xamarin.Android oferuje dwa sposoby korzystania z tych bibliotek:

  • Utwórz bibliotekę powiązań, która automatycznie opakowuje bibliotekę za pomocą otoek języka C#, aby można było wywołać kod Java za pośrednictwem wywołań języka C#.

  • Użyj interfejsu natywnego Java (JNI), aby bezpośrednio wywołać wywołania w kodzie biblioteki Języka Java. JNI to struktura programowania, która umożliwia wywoływanie kodu Java i wywoływanie ich przez aplikacje lub biblioteki natywne.

W tym przewodniku wyjaśniono pierwszą opcję: jak utworzyć bibliotekę powiązań, która opakowuje co najmniej jedną istniejącą bibliotekę Java do zestawu, z którym można połączyć się w aplikacji. Aby uzyskać więcej informacji na temat korzystania z interfejsu JNI, zobacz Praca z interfejsem JNI.

Platforma Xamarin.Android implementuje powiązania przy użyciu zarządzanych otoek z możliwością wywołania (MCW). MCW to mostek JNI, który jest używany, gdy zarządzany kod musi wywoływać kod Java. Zarządzane otoki z możliwością wywoływania zapewniają również obsługę podklasowania typów języka Java i zastępowania metod wirtualnych w typach języka Java. Podobnie, gdy kod środowiska uruchomieniowego systemu Android (ART) chce wywołać kod zarządzany, robi to za pośrednictwem innego mostka JNI znanego jako Android Callable Wrappers (ACW). Ta architektura jest pokazana na poniższym diagramie:

Android JNI bridge architecture

Biblioteka powiązań to zestaw zawierający zarządzane otoki z możliwością wywołania dla typów języka Java. Na przykład poniżej znajduje się typ języka Java , MyClassktóry chcemy opakowować w bibliotece powiązań:

package com.xamarin.mycode;

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

Po wygenerowaniu biblioteki powiązań dla .jar , która zawiera MyClass, możemy utworzyć jej wystąpienie i wywołać metody z poziomu języka C#:

var instance = new MyClass ();

string result = instance.MyMethod (42);

Aby utworzyć tę bibliotekę powiązań, użyj szablonu Biblioteka powiązań Języka Java platformy Xamarin.Android. Wynikowy projekt powiązania tworzy zestaw .NET z klasami MCW, plikami .jar i zasobami dla projektów biblioteki systemu Android osadzonych w nim. Można również utworzyć biblioteki powiązań dla archiwum systemu Android (. Pliki AAR) i projekty biblioteki android środowiska Eclipse. Odwołując się do wynikowego zestawu DLL bindings Library, możesz ponownie użyć istniejącej biblioteki Java w projekcie platformy Xamarin.Android.

Podczas odwołowania się do typów w bibliotece powiązań należy użyć przestrzeni nazw biblioteki powiązań. Zazwyczaj dodaje się dyrektywę using w górnej części plików źródłowych języka C#, które są wersją przestrzeni nazw .NET nazwy pakietu Java. Jeśli na przykład nazwa pakietu Java dla powiązanego .jar jest następująca:

com.company.package

Następnie umieścisz następującą using instrukcję w górnej części plików źródłowych języka C#, aby uzyskać dostęp do typów w powiązanym pliku .jar :

using Com.Company.Package;

Podczas tworzenia powiązania istniejącej biblioteki systemu Android należy pamiętać o następujących kwestiach:

  • Czy istnieją jakieś zależności zewnętrzne dla biblioteki? — Wszystkie zależności języka Java wymagane przez bibliotekę systemu Android muszą być uwzględnione w projekcie Xamarin.Android jako ReferenceJar lub EmbeddedReferenceJar. Wszystkie zestawy natywne należy dodać do projektu powiązania jako element EmbeddedNativeLibrary.

  • Jaka wersja interfejsu API systemu Android jest docelowa biblioteki systemu Android? — Nie można "obniżyć" poziomu interfejsu API systemu Android; upewnij się, że projekt powiązania platformy Xamarin.Android jest przeznaczony dla tego samego poziomu interfejsu API (lub wyższego) co biblioteka systemu Android.

  • Jaka wersja zestawu JDK została użyta do skompilowania biblioteki? — Błędy powiązań mogą wystąpić, jeśli biblioteka systemu Android została skompilowana z inną wersją zestawu JDK niż używana przez platformę Xamarin.Android. Jeśli to możliwe, ponownie skompiluj bibliotekę systemu Android przy użyciu tej samej wersji zestawu JDK używanego przez instalację zestawu Xamarin.Android.

Akcje kompilacji

Podczas tworzenia biblioteki powiązań ustawiasz akcje kompilacji na .jar lub . Pliki AAR dołączone do projektu Biblioteka powiązań — każda akcja kompilacji określa, w jaki sposób .jar lub . Plik AAR zostanie osadzony w bibliotece powiązań (lub przywołyni przez program ). Poniższa lista zawiera podsumowanie tych akcji kompilacji:

  • EmbeddedJar — osadza .jar w wynikowej bibliotece DLL powiązań jako zasób osadzony. Jest to najprostsza i najczęściej używana akcja kompilacji. Użyj tej opcji, jeśli chcesz , aby .jar automatycznie skompilowany do kodu bajtowego i spakowany do biblioteki powiązań.

  • InputJar — nie osadza .jar w wynikowej bibliotece powiązań .DLL. Biblioteka powiązań .DLL będzie mieć zależność od tej .jar w czasie wykonywania. Użyj tej opcji, jeśli nie chcesz dołączać .jar do biblioteki powiązań (na przykład ze względów licencjonowania). Jeśli używasz tej opcji, upewnij się, że dane wejściowe .jar są dostępne na urządzeniu z uruchomioną aplikacją.

  • LibraryProjectZip — osadza element . Plik AAR w wynikowej bibliotece powiązań .DLL. Jest to podobne do EmbeddedJar, z tą różnicą, że można uzyskać dostęp do zasobów (a także kodu) w powiązanym obiekcie . Plik AAR. Użyj tej opcji, jeśli chcesz osadzić element . AAR w bibliotece powiązań.

  • ReferenceJar— Określa .jar odwołania: odwołanie .jar jest .jar, że jeden z powiązanych .jar lub . Pliki AAR zależą od. Ta dokumentacja .jar służy tylko do spełnienia zależności czasu kompilacji. Jeśli używasz tej akcji kompilacji, powiązania języka C# nie są tworzone dla .jar odwołania i nie są osadzone w wynikowej bibliotece powiązań .DLL. Użyj tej opcji, jeśli utworzysz bibliotekę powiązań dla odwołania .jar , ale jeszcze tego nie zrobiono. Ta akcja kompilacji jest przydatna w przypadku tworzenia pakietów wielu .jars (i/lub . AARs) do wielu zależnych bibliotek powiązań.

  • EmbeddedReferenceJar — osadza odwołanie .jar w wynikowej bibliotece powiązań .DLL. Użyj tej akcji kompilacji, jeśli chcesz utworzyć powiązania języka C# dla danych wejściowych .jar (lub . AAR) i wszystkie jej odwołania .jar w bibliotece powiązań.

  • EmbeddedNativeLibrary — osadza natywny plik .so w powiązaniu. Ta akcja kompilacji jest używana dla plików ., więc pliki wymagane przez powiązany plik .jar . Może być konieczne ręczne załadowanie biblioteki .so przed wykonaniem kodu z biblioteki Języka Java. Opisano to poniżej.

Te akcje kompilacji zostały szczegółowo wyjaśnione w poniższych przewodnikach.

Ponadto następujące akcje kompilacji służą do importowania dokumentacji interfejsu API języka Java i konwertowania ich na dokumentację języka C# XML:

  • JavaDocJar Służy do wskazywania archiwum Javadoc Jar dla biblioteki Java zgodnej ze stylem pakietu Maven (zwykle FOOBAR-javadoc**.jar**).
  • JavaDocIndex służy do wskazywania index.html pliku w dokumentacji referencyjnej interfejsu API HTML.
  • JavaSourceJar Służy do uzupełnienia JavaDocJarelementu , aby najpierw wygenerować dokument JavaDoc ze źródeł, a następnie traktować wyniki jako JavaDocIndexbibliotekę Języka Java zgodną ze stylem pakietu Maven (zwykle FOOBAR-sources**.jar**).

Dokumentacja interfejsu API powinna być domyślnym dokumentem z zestawu JAVA8, Java7 lub Java6 SDK (są one różne formaty) lub stylem DroidDoc.

Dołączanie biblioteki natywnej do powiązania

Może być konieczne dołączenie biblioteki .so do projektu powiązania platformy Xamarin.Android w ramach powiązania biblioteki Języka Java. Po wykonaniu opakowanego kodu Java narzędzie Xamarin.Android zakończy się niepowodzeniem wywołania JNI i komunikatem o błędzie java.lang.UnsatisfiedLinkError: nie znaleziono metody natywnej: pojawi się w logcat dla aplikacji.

Rozwiązaniem tego problemu jest ręczne załadowanie biblioteki .so z wywołaniem metody Java.Lang.JavaSystem.LoadLibrary. Na przykład przy założeniu, że projekt platformy Xamarin.Android ma udostępnioną bibliotekę libpocketsphinx_jni.so uwzględnioną w projekcie powiązania z akcją kompilacji EmbeddedNativeLibrary, następujący fragment kodu (wykonany przed użyciem biblioteki udostępnionej) załaduje bibliotekę .so :

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

Dostosowywanie interfejsów API języka Java do języka C⧣

Generator powiązań platformy Xamarin.Android zmieni niektóre idiomy i wzorce języka Java, aby odpowiadały wzorcom platformy .NET. Na poniższej liście opisano sposób mapowania języka Java na C#/.NET:

  • Metody setter/Getter w języku Java to właściwości na platformie .NET.

  • Pola w języku Java to właściwości na platformie .NET.

  • Odbiorniki/interfejsy odbiornika w języku Java to zdarzenia na platformie .NET. Parametry metod w interfejsach wywołania zwrotnego będą reprezentowane przez podklasę EventArgs .

  • Statyczna klasa zagnieżdżona w języku Java to klasa zagnieżdżona na platformie .NET.

  • Klasa wewnętrzna w języku Java to klasa zagnieżdżona z konstruktorem wystąpienia w języku C#.

Scenariusze powiązań

Następujące przewodniki scenariusza powiązania mogą pomóc w powiązaniu biblioteki Java (lub bibliotek) w celu włączenia ich do aplikacji: