Vytvoření vazby knihovny Java

Komunita Androidu obsahuje mnoho knihoven Java, které můžete chtít použít ve své aplikaci. Tato příručka vysvětluje, jak začlenit knihovny Jazyka Java do aplikace Xamarin.Android vytvořením knihovny vazeb.

Přehled

Ekosystém knihoven třetích stran pro Android je obrovský. Proto má často smysl použít existující knihovnu androidu než vytvořit novou. Xamarin.Android nabízí dva způsoby použití těchto knihoven:

  • Vytvořte knihovnu vazeb, která automaticky zabalí knihovnu s obálkami jazyka C#, abyste mohli volat kód Java prostřednictvím volání jazyka C#.

  • K přímému vyvolání volání v kódu knihovny Java použijteJNI(Java Native Interface). JNI je programovací rozhraní, které umožňuje kódu Java volat a volat nativní aplikace nebo knihovny.

Tato příručka vysvětluje první možnost: jak vytvořit knihovnu vazeb, která zabalí jednu nebo více existujících knihoven Java do sestavení, na které můžete vytvořit odkaz v aplikaci. Další informace o používání JNI najdete v tématu Práce s JNI.

Xamarin.Android implementuje vazby pomocí spravovaných obálky volatelných volání(MCW). MCW je most JNI, který se používá, když spravovaný kód potřebuje vyvolat kód Java. Spravované volatelné obálky také poskytují podporu pro podtřídy typů Java a přepisování virtuálních metod u typů Java. Pokaždé, když kód modulu runtime Android (ART) chce vyvolat spravovaný kód, udělá to také prostřednictvím jiného mostu JNI, který se označuje jako obálky Android Callable Wrapper (ACW). Tato architektura je znázorněna v následujícím diagramu:

Architektura mostu Android JNI

Knihovna vazeb je sestavení obsahující obálky spravovaných volání pro typy Java. Tady je například typ Jazyka Java, MyClass který chceme zabalit do knihovny vazeb:

package com.xamarin.mycode;

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

Po vygenerování knihovny vazeb pro soubor .jar, který obsahuje , můžeme vytvořit jeho instanci a volat metody z jazyka C#:

var instance = new MyClass ();

string result = instance.MyMethod (42);

K vytvoření této knihovny vazeb použijete šablonu Xamarin.Android Java Bindings Library. Výsledný projekt vazby vytvoří sestavení .NET s vloženými třídami MCW, soubory .jar a prostředky pro projekty knihovny pro Android. Můžete také vytvořit knihovny vazeb pro Archiv Androidu (. AAR) a projekty knihovny Eclipse pro Android. Odkazováním na výsledné sestavení dll knihovny vazeb můžete znovu použít existující knihovnu Java v projektu Xamarin.Android.

Při odkazech na typy v knihovně vazeb musíte použít obor názvů vaší knihovny vazeb. Na začátek zdrojových souborů jazyka C# obvykle přidáte direktivu , která je verzí oboru názvů .NET názvu balíčku using Java. Pokud je například název balíčku Java pro váš vázaný soubor .jar následující:

com.company.package

Pak byste na začátek zdrojových souborů jazyka C# vložili následující příkaz pro přístup k typům using v vázaném using

using Com.Company.Package;

Při vytváření vazby existující knihovny pro Android je potřeba mít na paměti následující body:

  • Existují nějaké externí závislosti pro knihovnu? – Všechny závislosti Java vyžadované knihovnou androidu musí být zahrnuté v projektu Xamarin.Android jako reference Nebojako EmbeddedReferenceN. Jakákoli nativní sestavení musí být přidána do projektu vazby jako EmbeddedNativeLibrary.

  • Na jakou verzi rozhraní Android API knihovna Androidu cílí? – Není možné downgradovat úroveň rozhraní Android API. Ujistěte se, že projekt vazby Xamarin.Android cílí na stejnou úroveň rozhraní API (nebo vyšší) jako knihovna pro Android.

  • Jakou verzi sady JDK jste použili ke kompilaci knihovny? – K chybám vazby může dojít v případě, že byla knihovna androidu sestavena s jinou verzí sady JDK, než kterou používá Xamarin.Android. Pokud je to možné, znovu zkompilujte knihovnu pro Android pomocí stejné verze sady JDK, kterou používá vaše instalace Xamarin.Android.

Akce sestavení

Při vytváření knihovny vazeb nastavíte akce sestavení pro soubor .jar nebo . Soubory AAR, které začleníte do projektu knihovny vazeb – každá akce sestavení určuje, jak soubor .jar nebo . Soubor AAR se do vaší knihovny vazeb za vložený (nebo na který bude odkazovat). Následující seznam shrnuje tyto akce sestavení:

  • EmbeddedJar – Vloží EmbeddedJar výsledné knihovny DLL vazeb jako vložený prostředek. Toto je nejjednodušší a nejčastěji používaná akce sestavení. Tuto možnost použijte, pokud chcete soubor .jar automaticky zkompilovat do kódu byte a zabalit ho do knihovny vazeb.

  • InputJar – Nevkládá InputJar do výsledného souboru Bindings Library .DLL. Vaše knihovna vazeb .DLL bude mít závislost na tomto souboru .jar za běhu. Tuto možnost použijte, pokud nechcete do knihovny vazeb zahrnout soubor .jar (například kvůli licencování). Pokud použijete tuto možnost, musíte zajistit, aby byl vstupní soubor .jar dostupný na zařízení, na které běží vaše aplikace.

  • LibraryProjectZip – Vloží . Soubor AAR do výsledné knihovny vazeb .DLL. Je to podobné jako Embedded S tím rozdílem, že můžete přistupovat k prostředkům (i ke kódu) v vázaném objektu . Soubor AAR. Tuto možnost použijte, když chcete vložit . AAR do knihovny vazeb.

  • ReferenceJar– Určuje referenční soubor ReferenceJarReferenční soubor .jar je soubor .jar, který je jedním z vašich vázaných souborů .jar nebo . Na souborech AAR závisí. Tento referenční soubor .jar slouží pouze ke splnění závislostí v době kompilace. Pokud použijete tuto akci sestavení, nevytvářely se vazby jazyka C# pro referenční soubor .jar a nejsou vloženy do výsledné knihovny vazeb .DLL. Tuto možnost použijte, pokud chcete vytvořit knihovnu vazeb pro referenční soubor .jar, ale ještě jste to neudělali. Tato akce sestavení je užitečná pro balení více souborů .jar(a/nebo . AARs) do několika vzájemně závislých knihoven vazeb.

  • EmbeddedReferenceJar – Vloží odkaz EmbeddedReferenceJar do výsledného souboru Bindings Library .DLL. Tuto akci sestavení použijte, když chcete vytvořit vazby jazyka C# pro vstupní soubor .jar (nebo . AAR) a všechny jeho referenční soubory .jar(s) v knihovně vazeb.

  • EmbeddedNativeLibrary – Vloží nativní EmbeddedNativeLibrary vazby. Tato akce sestavení se používá pro soubory .so, které jsou vyžadovány vázaným souborem .jar. Před spuštěním kódu z knihovny Java může být nutné ručně načíst knihovnu .so. To je popsáno níže.

Tyto akce sestavení jsou podrobněji vysvětleny v následujících příručkách.

Následující akce sestavení se navíc používají k importu dokumentace k rozhraní Java API a k jejich převodu do dokumentace XML v jazyce C#:

  • JavaDocJar se používá k odkazování na soubor Jar archivu Javadoc pro knihovnu Java, která odpovídá stylu balíčku Maven (obvykle FOOBAR-javadoc**.jar** ).
  • JavaDocIndex se používá k odkazování na index.html soubor v kódu HTML referenční dokumentace rozhraní API.
  • JavaSourceJar se používá jako doplněk pro , aby se nejprve vygenerovala JavaDoc ze zdrojů a výsledky se pak považovaly za , a to pro knihovnu Java, která odpovídá stylu balíčku JavaDocJarJavaDocIndex Maven (obvykle FOOBAR-sources**.jar** ).

Dokumentace k rozhraní API by měla být výchozí doclet z Java8, Java7 nebo Java6 SDK (všechny mají jiný formát) nebo styl DroidDoc.

Zahrnutí nativní knihovny do vazby

Jako součást vazby knihovny Java může být nutné zahrnout knihovnu .so do projektu vazby Xamarin.Android. Při spuštění zabaleného kódu Java se Xamarin.Android nepodaří provést volání JNI a chybovou zprávu java.lang.UnsatisfiedLinkError: Nativní metoda se nenašla: zobrazí se v logcat out pro aplikaci.

Opravou tohoto problému je ruční načtení knihovny .so s voláním . Například za předpokladu, že projekt Xamarin.Android má sdílenou knihovnu libpocketsphinx_jni.so zahrnutou do projektu vazby s akcí sestavení EmbeddedNativeLibrary,načte následující fragment kódu (spuštěný před použitím sdílené knihovny) knihovnu .so:

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

Přizpůsobení rozhraní JAVA API jazyku C⧣

Generátor vazeb Xamarin.Android změní některé idiomy a vzory Jazyka Java tak, aby odpovídaly vzorům .NET. Následující seznam popisuje, jak se Java mapuje na C#/.NET:

  • Metody Setter/Getter v Javě jsou vlastnosti v .NET.

  • Pole v Javě jsou vlastnosti v .NET.

  • Naslouchací proces nebo rozhraní naslouchacího procesu v Javě jsou události v .NET. Parametry metod v rozhraních zpětného volání budou reprezentovány EventArgs podtřídou.

  • Statická vnořená třída v Javě je vnořená třída v .NET.

  • Vnitřní třída v Javě je vnořená třída s konstruktorem instance v jazyce C#.

Scénáře vazeb

Následující průvodci scénářem vazeb vám můžou pomoct s vytvořením vazby knihovny Java (nebo knihoven) k začlenění do vaší aplikace:

  • Vytvoření vazby . JAR je návod pro vytváření knihoven vazeb pro soubory .jar.

  • Vytvoření vazby . AAR je návod pro vytváření knihoven vazeb pro . Soubory AAR. V tomto názorném postupu se dozvíte, jak vytvořit Android Studio knihovny.

  • Vytvoření vazby knihovny Eclipse Project je názorný postup pro vytváření vazeb knihoven z projektů knihovny pro Android. V tomto názorném postupu se dozvíte, jak vytvořit vazbu projektů knihovny Pro Android v Eclipse.

  • Přizpůsobení vazeb vysvětluje, jak ručně upravit vazbu, aby se vyřešily chyby sestavení, a tvarovat výsledné rozhraní API tak, aby se více podobaly jazyku C#.

  • Vazby pro řešení potíží uvádí běžné chybové scénáře vazeb, vysvětluje možné příčiny a nabízí návrhy pro řešení těchto chyb.