Привязка библиотеки 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 Native Interface (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 (ГРАФИКА) хочет вызывать управляемый код, она делает это с помощью другой мост JNI, известные как Android вызываемой оболочки (ACW).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:

Мост архитектуры Android JNIAndroid 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);

Чтобы создать эту библиотеку привязок, используйте Xamarin.Android библиотека Java Bindings шаблона.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, как ReferenceJar или как EmbeddedReferenceJar.– Any Java dependencies required by the Android library must be included in the Xamarin.Android project as a ReferenceJar or as an EmbeddedReferenceJar. Все собственные сборки необходимо добавить в проект привязки, как EmbeddedNativeLibrary.Any native assemblies must be added to the binding project as an EmbeddedNativeLibrary.

  • Какая версия Android API-интерфейса не Android целевой библиотеки?What version of the Android API does the Android library target? – Невозможно «понизить» уровня Android API; Убедитесь, что проект привязки 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 в итоговый библиотеку привязок. БИБЛИОТЕКА DLL.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 в итоговый библиотеку привязок. БИБЛИОТЕКА DLL.LibraryProjectZip – Embeds an .AAR file into the resulting Bindings Library .DLL. Это похоже на EmbeddedJar, за исключением того, что можно доступ к ресурсам (а также код) в качестве границы. 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: ссылка .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. Эта ссылка .jar используется только для удовлетворения зависимостей во время компиляции.This reference .jar is used only to satisfy compile-time dependencies. При использовании действие построения C# привязки не создаются для ссылки на .jar и он не встроен в итоговый библиотека привязок. БИБЛИОТЕКА DLL.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. Используйте этот параметр, при внесении библиотека привязок для ссылки на .jar , но этого не сделали еще.Use this option when you will make a Bindings Library for the reference .jar but have not done so yet. Действие построения полезен для упаковки несколько .jars (и (или). AARs) в нескольких независимых библиотек привязки.This build action is useful for packaging multiple .jars (and/or .AARs) into multiple interdependent Bindings Libraries.

  • EmbeddedReferenceJar – Внедряет ссылку .jar в итоговый библиотеку привязок. БИБЛИОТЕКА DLL.EmbeddedReferenceJar – Embeds a reference .jar into the resulting Bindings Library .DLL. Это действие построения используется, если вы хотите создать C# привязки для входной, так .jar (или). AAR) и все его ссылку .jar(s) в библиотеке привязки.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 – Внедряет собственный .so в привязку.EmbeddedNativeLibrary – Embeds a native .so into the binding. Это действие построения используется для .so файлы, которые требуются .jar файл привязки.This build action is used for .so files that are required by the .jar file being bound. Может потребоваться вручную загрузить .so библиотеки перед выполнением кода из библиотеки 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.

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

  • JavaDocJar используется для указания на архивный Javadoc 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 файла в справочную документацию по API HTML.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 должен быть doclet по умолчанию из Java8, Java7 или Java6 SDK (они все другой формат), или DroidDoc стиль.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 для вызова JNI и сообщение об ошибке не удастся Xamarin.Android java.lang.UnsatisfiedLinkError: Собственный метод, не найден: будет отображаться в 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.

Способ устранения этой проблемы является вручную загрузить .so библиотеки с помощью вызова 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.so включен в проект привязки с действием сборки EmbeddedNativeLibrary, следующий фрагмент кода (выполняется перед использованием общей библиотеки) будет загружать .so библиотеки: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.

  • Интерфейсы прослушиватели/Listener в 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. Чтение в этом пошаговом руководстве, чтобы узнать, как выполнить привязку библиотеки проектов Eclipse для Android.Read this walkthrough to learn how to bind Eclipse Android Library Projects.

  • Настройка привязок объясняет, как вручную изменить привязки для устранения ошибок сборки и пожелания получающийся API, так как это дополнительные "C#-как».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.