Java 라이브러리 바인딩Binding a Java Library

Android 커뮤니티는 앱에서 사용 하려는 많은 Java 라이브러리 이 가이드에서는 Xamarin.Android 응용 프로그램에 바인딩 라이브러리를 만들어 Java 라이브러리를 통합 하는 방법을 설명 합니다.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 관리 코드에서 Java 코드를 호출 해야 할 때 사용 되는 JNI 브리지입니다.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 런타임 (최신) 코드는 관리 코드를 호출 하려는, 때마다으로 Android 호출 가능 래퍼 (ACW) 알려진 다른 JNI 브리지를 통해 수행 하도록 합니다.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 JNI 브리지 아키텍처Android 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 바인딩 라이브러리 템플릿.To create this Bindings Library, you use the Xamarin.Android Java Bindings Library template. 결과 바인딩 프로젝트 MCW 클래스를 사용 하 여.NET 어셈블리를 만듭니다 .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) 파일 및 Eclipse Android 라이브러리 프로젝트.You can also create Bindings Libraries for Android Archive (.AAR) files and Eclipse Android Library projects. 결과 바인딩 라이브러리 DLL 어셈블리를 참조 하 여 Xamarin.Android 프로젝트에서 기존 Java 라이브러리를 재사용할 수 있습니다.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# 원본 파일에.NET 네임 스페이스 버전의 Java 패키지 이름입니다.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? – Android 라이브러리에 필요한 Java 종속성을 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 라이브러리는 Xamarin.Android에서 사용에서 보다 JDK의 다른 버전으로 작성 된 경우 발생할 수 있습니다.– Binding errors may occur if the Android library was built with a different version of JDK than in use by Xamarin.Android. 가능한 경우 동일한 버전의 Xamarin.Android 설치에서 사용 되는 JDK 사용 하 여 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 Maven 패키지 스타일을 따르는 Java 라이브러리에 대 한 Javadoc 아카이브 Jar 가리키는 데 사용 됩니다 (일반적으로 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 설명서 Java8, Java7 또는 Java6 SDK (다른 모든 형식으로) 기본 doclet 해야 합니다. 또는 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 Java 라이브러리 바인딩의 일부로 Xamarin.Android 바인딩 프로젝트의 라이브러리입니다.It may be necessary to include a .so library in a Xamarin.Android binding project as a part of binding a Java library. Xamarin.Android JNI 호출 및 오류 메시지에 실패 하기 래핑된 Java 코드를 실행 하는 경우 java.lang.UnsatisfiedLinkError: 네이티브 메서드를 찾을 수 없음: 응용 프로그램에 대 한 아웃 logcat에 나타납니다.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");

C Java Api를 조정합니다.⧣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:

  • Setter/Getter 메서드 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.

  • A 정적 중첩 클래스 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#-같은"입니다.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.