Привязка библиотеки JavaBinding a Java Library

Сообщество Android имеет множество библиотек Java, которые можно использовать в приложении; в этом руководство объясняется, как внедрить библиотеки Java в приложение Xamarin. Android, создав библиотеку привязок.The Android community has many Java libraries that you may want to use in your app; this guide explains how to incorporate Java libraries into your Xamarin.Android application by creating a Bindings Library.

ОбзорOverview

Экосистема библиотеки сторонних производителей для Android является большой.The third-party library ecosystem for Android is massive. Поэтому часто имеет смысл использовать существующую библиотеку Android, чем создать новую.Because of this, it frequently makes sense to use an existing Android library than to create a new one. Xamarin. Android предлагает два способа использования этих библиотек:Xamarin.Android offers two ways to use these libraries:

  • Создайте библиотеку привязок , которая автоматически заключает библиотеку в C# оболочку, чтобы можно было вызывать код Java через C# вызовы.Create a Bindings Library that automatically wraps the library with C# wrappers so you can invoke Java code via C# calls.

  • Используйте собственный интерфейс Java (JNI) для непосредственного вызова вызовов в библиотеке Java.Use the Java Native Interface (JNI) to invoke calls in Java library code directly. JNI — это платформа программирования, которая позволяет коду Java вызываться и вызываться собственными приложениями или библиотеками.JNI is a programming framework that enables Java code to call and be called by native applications or libraries.

В этом руководство объясняется первый вариант: создание библиотеки привязок , которая заключает одну или несколько существующих библиотек Java в сборку, к которой можно установить связь в приложении.This guide explains the first option: how to create a Bindings Library that wraps one or more existing Java libraries into an assembly that you can link to in your application. Дополнительные сведения об использовании JNI см. в разделе Работа с JNI.For more information about using JNI, see Working with JNI.

Xamarin. Android реализует привязки с помощью управляемых вызываемых оболочек (MCW).Xamarin.Android implements bindings by using Managed Callable Wrappers (MCW). MCW — это мост JNI, который используется, когда управляемому коду необходимо вызывать код Java.MCW is a JNI bridge that is used when managed code needs to invoke Java code. Управляемые вызываемые оболочки также предоставляют поддержку для подклассов типов Java и переопределения виртуальных методов для типов Java.Managed callable wrappers also provide support for subclassing Java types and for overriding virtual methods on Java types. Аналогичным образом, каждый раз, когда коду среды выполнения Android (ART) нужно вызвать управляемый код, он делает это с помощью другого моста JNI, известного как вызываемые оболочки Android (АКВ).Likewise, whenever Android runtime (ART) code wishes to invoke managed code, it does so via another JNI bridge known as Android Callable Wrappers (ACW). Эта архитектура показана на схеме ниже.This architecture is illustrated in the following diagram:

Архитектура моста JNI для AndroidAndroid JNI bridge architecture

Библиотека привязок — это сборка, содержащая управляемые вызываемые оболочки для типов Java.A Bindings Library is an assembly containing Managed Callable Wrappers for Java types. Например, вот тип Java, MyClassкоторый мы хотим перенести в библиотеку привязок:For example, here is a Java type, MyClass, that we want to wrap in a Bindings Library:

package com.xamarin.mycode;

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

После создания библиотеки привязок для JAR -файла, который содержит MyClass, мы можем создать его экземпляр и вызвать методы из: C#After we generate a Bindings Library for the .jar that contains MyClass, we can instantiate it and call methods on it from C#:

var instance = new MyClass ();

string result = instance.MyMethod (42);

Чтобы создать эту библиотеку привязок, используйте шаблон библиотеки привязок Java для Xamarin. Android.To create this Bindings Library, you use the Xamarin.Android Java Bindings Library template. Полученный проект привязки создает сборку .NET с классами MCW, JAR -файлами и ресурсами для проектов библиотек Android, внедренных в него.The resulting binding project creates a .NET assembly with the MCW classes, .jar file(s), and resources for Android Library projects embedded in it. Также можно создать библиотеки привязок для архива Android (. AAR) файлы и проекты библиотеки Android для Eclipse.You can also create Bindings Libraries for Android Archive (.AAR) files and Eclipse Android Library projects. Ссылаясь на сборку библиотеки DLL результирующей привязки, можно повторно использовать существующую библиотеку Java в проекте Xamarin. Android.By referencing the resulting Bindings Library DLL assembly, you can reuse an existing Java library in your Xamarin.Android project.

При ссылке на типы в библиотеке привязки необходимо использовать пространство имен библиотеки привязки.When you reference types in your Binding Library, you must use the namespace of your binding library. Как правило, в верхней using части C# исходных файлов добавляется директива, которая представляет собой версию имени пакета Java для пространства имен .NET.Typically, you add a using directive at the top of your C# source files that is the .NET namespace version of the Java package name. Например, если имя пакета Java для связанного . jar имеет следующий код:For example, if the Java package name for your bound .jar is the following:

com.company.package

Затем следует добавить следующую using инструкцию в начало C# исходных файлов, чтобы получить доступ к типам в связанном JAR -файле:Then you would put the following using statement at the top of your C# source files to access types in the bound .jar file:

using Com.Company.Package;

При привязке существующей библиотеки Android необходимо помнить о следующих моментах.When binding an existing Android library, it is necessary to keep the following points in mind:

  • Существуют ли какие либо внешние зависимости для библиотеки?Are there any external dependencies for the library? –Все зависимости Java, необходимые для библиотеки Android, должны быть добавлены в проект Xamarin. Android как референцежар или как ембеддедреференцежар.– Any Java dependencies required by the Android library must be included in the Xamarin.Android project as a ReferenceJar or as an EmbeddedReferenceJar. Все сборки машинного кода должны быть добавлены в проект привязки в качестве ембеддеднативелибрари.Any native assemblies must be added to the binding project as an EmbeddedNativeLibrary.

  • Какая версия API Android поддерживает платформу Android Library?What version of the Android API does the Android library target? –Невозможно понизить уровень API Android. Убедитесь, что в проекте привязки Xamarin. Android используется тот же уровень API (или выше), что и в библиотеке Android.– It is not possible to "downgrade" the Android API level; ensure that the Xamarin.Android binding project is targeting the same API level (or higher) as the Android library.

  • Какая версия JDK использовалась для компиляции библиотеки?What version of the JDK was used to compile the library? –Ошибки привязки могут возникать, если библиотека Android была построена с использованием другой версии JDK, чем используется Xamarin. Android.– Binding errors may occur if the Android library was built with a different version of JDK than in use by Xamarin.Android. Если возможно, перескомпилируйте библиотеку Android с использованием той же версии JDK, которая используется в вашей установке Xamarin. Android.If possible, recompile the Android library using the same version of the JDK that is used by your installation of Xamarin.Android.

Действия при сборкеBuild Actions

При создании библиотеки привязок необходимо задать действия сборки для JAR -файла или. AAR файлы, которые вы включили в проект – библиотеки привязок, каждое действие сборки определяет, как . jar или. Файл AAR будет внедрен в библиотеку привязок (или ссылается на нее).When you create a Bindings Library, you set build actions on the .jar or .AAR files that you incorporate into your Bindings Library project – each build action determines how the .jar or .AAR file will be embedded into (or referenced by) your Bindings Library. В следующем списке перечислены следующие действия сборки:The following list summarizes these build actions:

  • EmbeddedJarВнедряет JAR-файл в результирующую библиотеку DLL-библиотеки привязок в качестве внедренного ресурса. –EmbeddedJar – Embeds the .jar into the resulting Bindings Library DLL as an embedded resource. Это простейшее и наиболее часто используемое действие сборки.This is the simplest and most commonly-used build action. Используйте этот параметр, если нужно, чтобы JAR -файл автоматически компилировался в байтовый код и упакован в библиотеку привязок.Use this option when you want the .jar automatically compiled into byte code and packaged into the Bindings Library.

  • InputJarНе внедряет JAR-файл в результирующую библиотеку привязок. – Компоновки.InputJar – Does not embed the .jar into the resulting Bindings Library .DLL. Библиотека привязок. DLL будет иметь зависимость от этого JAR -файла во время выполнения.Your Bindings Library .DLL will have a dependency on this .jar at runtime. Используйте этот параметр, если не нужно включать JAR -файл в библиотеку привязок (например, по соображениям лицензирования).Use this option when you do not want to include the .jar in your Bindings Library (for example, for licensing reasons). При использовании этого параметра необходимо убедиться, что входной . jar доступен на устройстве, где выполняется приложение.If you use this option, you must ensure that the input .jar is available on the device that runs your app.

  • LibraryProjectZip– Внедряет. AAR файл в результирующую библиотеку привязок. Компоновки.LibraryProjectZip – Embeds an .AAR file into the resulting Bindings Library .DLL. Это похоже на Ембеддеджар, за исключением того, что вы можете получить доступ к ресурсам (а также к коду) в привязке. Файл AAR.This is similar to EmbeddedJar, except that you can access resources (as well as code) in the bound .AAR file. Используйте этот параметр, если нужно внедрить. AAR в библиотеку привязок.Use this option when you want to embed an .AAR into your Bindings Library.

  • ReferenceJar Указывает ссылку. jar — файл Reference. jar — это файл JAR, который является одним из ваших привязанных JAR-файлов или. – Файлы AAR зависят от.ReferenceJar – Specifies a reference .jar: a reference .jar is a .jar that one of your bound .jar or .AAR files depends on. Этот файл Reference . jar используется только для соблюдения зависимостей времени компиляции.This reference .jar is used only to satisfy compile-time dependencies. При использовании этого действия сборки C# привязки не создаются для Reference . jar и не внедряются в итоговую библиотеку привязок. Компоновки.When you use this build action, C# bindings are not created for the reference .jar and it is not embedded in the resulting Bindings Library .DLL. Используйте этот параметр, если вы сделаете библиотеку привязок для Reference . jar , но еще не сделали этого.Use this option when you will make a Bindings Library for the reference .jar but have not done so yet. Это действие сборки полезно для упаковки нескольких JAR-файлов (и/или). Аарс) в несколько библиотек привязок, взаимозависимых с.This build action is useful for packaging multiple .jars (and/or .AARs) into multiple interdependent Bindings Libraries.

  • EmbeddedReferenceJarВнедряет файл Reference . jar в полученную библиотеку привязок. – Компоновки.EmbeddedReferenceJar – Embeds a reference .jar into the resulting Bindings Library .DLL. Используйте это действие сборки, если требуется создать C# привязки для входного JAR -файла (или. AAR) и все его ссылки ( JAR-файл) в библиотеке привязок.Use this build action when you want to create C# bindings for both the input .jar (or .AAR) and all of its reference .jar(s) in your Bindings Library.

  • EmbeddedNativeLibraryВнедряет собственный объект . Поэтому в привязку. –EmbeddedNativeLibrary – Embeds a native .so into the binding. Это действие сборки используется для . файлы, необходимые для привязки JAR -файла.This build action is used for .so files that are required by the .jar file being bound. Может потребоваться вручную загрузить библиотеку . Итак , прежде чем выполнять код из библиотеки Java.It may be necessary to manually load the .so library before executing code from the Java library. Это описано ниже.This is described below.

Эти действия по сборке более подробно описаны в следующих руководствах.These build actions are explained in more detail in the following guides.

Кроме того, следующие действия сборки используются для импорта документации по API Java и преобразования их в C# XML-документацию:Additionally, the following build actions are used to help importing Java API documentation and convert them into C# XML documentation:

  • JavaDocJarиспользуется для указания Javadoc Archive JAR для библиотеки Java, которая соответствует стилю пакета Maven (обычно FOOBAR-javadoc**.jar**).JavaDocJar is used to point to Javadoc archive Jar for a Java library that conforms to a Maven package style (usually FOOBAR-javadoc**.jar**).
  • JavaDocIndexиспользуется для указания index.html файла в HTML справочной документации по API.JavaDocIndex is used to point to index.html file within the API reference documentation HTML.
  • JavaSourceJarиспользуется для дополнения JavaDocJar, чтобы сначала создать Javadoc из источников, а затем обрабатывать результаты как JavaDocIndex, для библиотеки Java, которая соответствует стилю пакета Maven (обычно FOOBAR-sources**.jar**).JavaSourceJar is used to complement JavaDocJar, to first generate JavaDoc from sources and then treat the results as JavaDocIndex, for a Java library that conforms to a Maven package style (usually FOOBAR-sources**.jar**).

Документация по API должна быть Доклет по умолчанию из пакета SDK Java8, Java7 или java6 (все они имеют разный формат) или в стиле Дроиддок.The API documentation should be the default doclet from Java8, Java7 or Java6 SDK (they are all different format), or the DroidDoc style.

Включение собственной библиотеки в привязкуIncluding a Native Library in a Binding

Может потребоваться включить библиотеку . so в проект привязки Xamarin. Android как часть привязки библиотеки Java.It may be necessary to include a .so library in a Xamarin.Android binding project as a part of binding a Java library. При выполнении упакованного кода Java Xamarin. Android не сможет выполнить вызов JNI и сообщение об ошибке Java. lang. унсатисфиедлинкеррор: Собственный метод не найден: будет отображаться в logcat out для приложения.When the wrapped Java code executes, Xamarin.Android will fail to make the JNI call and the error message java.lang.UnsatisfiedLinkError: Native method not found: will appear in the logcat out for the application.

Исправление для этого — вручную загрузить библиотеку . так , чтобы библиотека вызывала вызов Java.Lang.JavaSystem.LoadLibrary.The fix for this is to manually load the .so library with a call to Java.Lang.JavaSystem.LoadLibrary. Например, предположим, что проект Xamarin. Android имеет общую библиотеку libpocketsphinx_jni. Поэтому он включается в проект привязки с действием сборки ембеддеднативелибрари, приведенным ниже фрагментом кода (выполняется перед использованием общей библиотеки). загрузит библиотеку . так :For example assuming that a Xamarin.Android project has shared library libpocketsphinx_jni.so included in the binding project with a build action of EmbeddedNativeLibrary, the following snippet (executed before using the shared library) will load the .so library:

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

Адаптация API-интерфейсов Java к C⧣Adapting Java APIs to C⧣

Генератор привязки Xamarin. Android изменит некоторые стили и закономерности Java в соответствии с шаблонами .NET.The Xamarin.Android Binding Generator will change some Java idioms and patterns to correspond to .NET patterns. В следующем списке описано, как Java сопоставляется C#с/.NET:The following list describes how Java is mapped to C#/.NET:

  • Методы задания и считывания в Java являются свойствами в .NET.Setter/Getter methods in Java are Properties in .NET.

  • Поля в Java являются свойствами в .NET.Fields in Java are Properties in .NET.

  • Прослушиватели и интерфейсы прослушивателя в Java — это события в .NET.Listeners/Listener Interfaces in Java are Events in .NET. Параметры методов в интерфейсах обратного вызова будут представлены EventArgs подклассом.The parameters of methods in the callback interfaces will be represented by an EventArgs subclass.

  • Статический вложенный класс в Java — это вложенный класс в .NET.A Static Nested class in Java is a Nested class in .NET.

  • Внутренний класс в Java является вложенным классом с конструктором экземпляра в C#.An Inner class in Java is a Nested class with an instance constructor in C#.

Сценарии привязкиBinding Scenarios

Следующие руководства по сценариям привязки помогут привязать библиотеку (или библиотеки) Java для взаимодействия с приложением.The following binding scenario guides can help you bind a Java library (or libraries) for incorporation into your app:

  • Привязка. JAR — это пошаговое руководство по созданию библиотек привязок для JAR -файлов.Binding a .JAR is a walkthrough for creating Bindings Libraries for .jar files.

  • Привязка объекта. AAR — это пошаговое руководство по созданию библиотек привязок для. AAR файлы.Binding an .AAR is a walkthrough for creating Bindings Libraries for .AAR files. Ознакомьтесь с этим пошаговым руководством, чтобы узнать, как привязать Android Studio библиотеки.Read this walkthrough to learn how to bind Android Studio libraries.

  • Привязка проекта библиотеки Eclipse — это пошаговое руководство по созданию библиотек привязки из проектов библиотек Android.Binding an Eclipse Library Project is a walkthrough for creating binding libraries from Android Library Projects. Ознакомьтесь с этим пошаговым руководством, чтобы узнать, как привязать проекты библиотеки Android Eclipse.Read this walkthrough to learn how to bind Eclipse Android Library Projects.

  • Настройка привязок объясняет, как вносить изменения в привязку вручную для разрешения ошибок сборки и формирования РЕЗУЛЬТИРУЮЩего API, чтобы он был больше "C#-Like".Customizing Bindings explains how to make manual modifications to the binding to resolve build errors and shape the resulting API so that it is more "C#-like".

  • В разделе Устранение неполадок приводятся распространенные сценарии ошибок привязки, объясняются возможные причины и предлагаются предложения по устранению этих ошибок.Troubleshooting Bindings lists common binding error scenarios, explains possible causes, and offers suggestions for resolving these errors.