Android API के लिए लाइब्रेरी रैपर   Android Game Development Kit का हिस्सा.

लाइब्रेरी रैपर, कमांड-लाइन टूल (सीएलआई) होता है. यह Java में लिखे गए Android API के लिए, C-लैंग्वेज रैपर कोड जनरेट करता है. इस कोड का इस्तेमाल, नेटिव Android ऐप्लिकेशन में किया जा सकता है. इससे Java API को कॉल किया जा सकता है. इसके लिए, आपको मैन्युअल तरीके से Java नेटिव इंटरफ़ेस या JNI बनाने की ज़रूरत नहीं होगी. इस टूल की मदद से, C या C++ में लिखे गए Android ऐप्लिकेशन को आसानी से डेवलप किया जा सकता है.

यह टूल, आपके दिए गए Java Archive (JAR) फ़ाइलों में मौजूद सार्वजनिक सिंबल या टूल की कॉन्फ़िगरेशन फ़ाइल में तय की गई क्लास या दोनों के लिए C कोड जनरेट करके काम करता है. इस टूल से जनरेट किया गया कोड, Java API की जगह नहीं लेता है. इसके बजाय, यह आपके C कोड और Java के बीच एक पुल की तरह काम करता है. आपके ऐप्लिकेशन को अब भी उन Java लाइब्रेरी की ज़रूरत होगी जिन्हें आपने रैप किया है. इसलिए, उन्हें अपने प्रोजेक्ट में शामिल करें.

डाउनलोड करें

लाइब्रेरी रैपर संग्रह को डाउनलोड करें और उसके कॉन्टेंट को अपनी पसंद की डायरेक्ट्री में अनपैक करें.

वाक्य-विन्यास

लाइब्रेरी रैपर टूल का कमांड लाइन सिंटैक्स यहां दिया गया है:

java -jar lw.jar \
  [-i jar-file-to-be-wrapped] \
  [-o output-path] \
  [-c config-file] \
  [-fa allow-list-file] \
  [-fb block-list-file] \
  [--skip_deprecated_symbols]

रैपर कॉन्फ़िगरेशन फ़ाइल

लाइब्रेरी रैपर कॉन्फ़िगरेशन एक JSON फ़ाइल होती है. इसकी मदद से, कोड जनरेट करने की प्रोसेस को कंट्रोल किया जा सकता है. फ़ाइल में इस स्ट्रक्चर का इस्तेमाल किया जाता है.

{
  // An array of type-specific configs. A type config is useful when a user wants to map
  // a Java type to a manually defined C type without generating the code. For example, when a developer
  // has their own implementation of the "java.lang.String" class, they can tell the generator to use it
  // instead of generating it.
  "type_configs": [
    {
      // [Required] Name of a fully qualified Java type.
      "java_type": "java.lang.String",
      // The C type that the java_type will be mapped to.
      "map_to": "MyOwnStringImplementation",
      // A header file that contains the declaration of the "map_to" type.
      "source_of_definition": "my_wrappers/my_own_string_implementation.h",
      // Controls if a value should be passed by pointer or value.
      "pass_by_value": false
    }
  ],
  // An array of package-specific configs.
  "package_configs": [
    {
      // [Required] A name of a Java package that this section regards. A wildchar * can be used at the
      // end of the package name to apply this config to all packages whose name starts with this value.
      "package_name": "androidx.core.app*",
      // A subdirectory relative to the root directory where the generated code will be located.
      "sub_directory": "androidx_generated/",
      // If true, the generated file structure reflects the package name. For example, files generated
      // for the package com.google.tools will be placed in the directory com/google/tools/.
      "file_location_by_package_name": true,
      // A prefix added to all class names from this package.
      "code_prefix": "Gen",
      // A prefix added to all generated file names from this package.
      "file_prefix": = "gen_"
    }
  ],
  // An array of manually defined classes for wrapping. Defining classes manually is useful when a
  // jar file with desired classes are not available or a user needs to wrap just a small part of an SDK.
  "custom_classes": [
    {
      // [Required] A fully-qualified Java class name. To define inner class, use symbol "$", for example
      // "class com.example.OuterClass$InnerClass".
      "class_name": "class java.util.ArrayList<T>",
      // List of methods.
      "methods": [
        "ArrayList()", // Example of a constructor.
        "boolean add(T e)", // Example of a method that takes a generic parameter.
        "T get(int index)", // Example of a method that returns a generic parameter.
        "int size()" // Example of parameterless method.
      ]
    },
  ]
}

फ़ाइलें फ़िल्टर करना

ऐसा हो सकता है कि आपको रैप की जाने वाली JAR फ़ाइलों से कुछ सिंबल हटाने हों. सिंबल हटाने के लिए, कॉन्फ़िगरेशन में फ़िल्टर फ़ाइल तय की जा सकती है. फ़िल्टर फ़ाइल एक सामान्य टेक्स्ट फ़ाइल होती है. इसमें हर लाइन, रैप करने के लिए एक सिंबल तय करती है. फ़ाइलें फ़िल्टर करने के लिए, इस सिंटैक्स का इस्तेमाल करें:

java-symbol-name java-jni-type-signature

फ़िल्टर फ़ाइल का एक उदाहरण यहां दिया गया है:

# Class filter
java.util.ArrayList Ljava.util.ArrayList;

# Method filter
java.util.ArrayList.lastIndexOf (Ljava.lang.Object;)I

# Field filter
android.view.KeyEvent.KEYCODE_ENTER I

आपको कॉन्फ़िगरेशन के लिए फ़िल्टर फ़ाइल देनी होती है. इसमें ऐसे सिंबल शामिल होते हैं जिन्हें -fa पैरामीटर का इस्तेमाल करके अनुमति दी जाती है. साथ ही, इसमें ऐसे सिंबल भी शामिल होते हैं जिन्हें -fb पैरामीटर का इस्तेमाल करके ब्लॉक किया जाता है. दोनों पैरामीटर का इस्तेमाल एक साथ किया जा सकता है. अगर दोनों फ़िल्टर दिए गए हैं, तो किसी सिंबल को तब रैप किया जाएगा, जब उसे अनुमति वाले फ़िल्टर की फ़ाइल में तय किया गया हो और वह ब्लॉक फ़िल्टर की फ़ाइल में मौजूद न हो.

उदाहरण के तौर पर

मान लें कि आपको JAR फ़ाइल ChatLibrary.jar को रैप करना है. इसमें यह क्लास शामिल है:

public class ChatManager {
  public static void sendMessage(int userId, String message) {...}
}

आपके C प्रोजेक्ट के लिए, इस JAR के लिए एक नेटिव रैपर जनरेट करना ज़रूरी है. इससे आपका नेटिव Android ऐप्लिकेशन, रनटाइम के दौरान इसे कॉल कर पाएगा. इस कोड को जनरेट करने के लिए, लाइब्रेरी रैपर का इस्तेमाल करें. इसके लिए, यह निर्देश दें:

java -jar lw.jar -i ChatLibrary.jar -o ./generated_code/

ऊपर दिया गया निर्देश, ./generated_code डायरेक्ट्री में C सोर्स कोड जनरेट करता है. जनरेट की गई फ़ाइल chat_manager.h में, इस तरह का कोड होता है. इससे आपको अपने प्रोजेक्ट में लाइब्रेरी को कॉल करने की सुविधा मिलती है:

#include "java/lang/string.h"

typedef struct ChatManager_ ChatManager;
void ChatManager_sendMessage(int32_t user_id, String* message);

उदाहरण के तौर पर, ज़्यादा जानकारी वाले किसी परिदृश्य के लिए, लाइब्रेरी रैपर गाइड देखें.

टूल की जानकारी

यहां दिए गए सेक्शन में, लाइब्रेरी रैपर की सुविधाओं के बारे में पूरी जानकारी दी गई है.

आउटपुट डायरेक्ट्री स्ट्रक्चर

सभी C सोर्स और हेडर फ़ाइलें, उन सबडायरेक्ट्री में मौजूद होती हैं जो रैप की गई Java क्लास के पैकेज के नाम को दिखाती हैं. उदाहरण के लिए, तय किए गए JAR java.lang.Integer के लिए रैपर कोड, ./java/lang/integer.[h/cc] डायरेक्ट्री में जनरेट किया जाता है.

टूल की कॉन्फ़िगरेशन फ़ाइल का इस्तेमाल करके, इस आउटपुट के व्यवहार को कंट्रोल किया जा सकता है.

ऑब्जेक्ट लाइफ़साइकल

C कोड में Java ऑब्जेक्ट को ओपेक पॉइंटर के तौर पर दिखाया जाता है. इन्हें रैपर कहा जाता है. रैपर, उससे जुड़े Java ऑब्जेक्ट के लिए JNI रेफ़रंस मैनेज करता है. इन स्थितियों में रैपर बनाया जा सकता है:

• MyClass_wrapJniReference(jobject jobj) फ़ंक्शन को कॉल करके, मौजूदा JNI रेफ़रंस को रैप करके. यह फ़ंक्शन, दिए गए रेफ़रंस का मालिकाना हक नहीं लेता है. हालांकि, यह अपना ग्लोबल JNI रेफ़रंस बनाता है.
• एक नया ऑब्जेक्ट बनाकर, जो Java में कंस्ट्रक्टर को कॉल करने के बराबर है: MyClass_construct()
• किसी फ़ंक्शन से नया रैपर वापस लाकर, उदाहरण के लिए: Score* Leaderboard_getScore(Leaderboard* instance, String* leaderboard_name)

जब रैपर का इस्तेमाल नहीं किया जा रहा हो, तो आपको उन्हें डिस्ट्रॉय करना होगा. ऐसा करने के लिए, destroy() फ़ंक्शन MyClass_destroy(MyClass* instance) को कॉल करें.

रैपर दिखाने वाले फ़ंक्शन, हर कॉल के लिए नई मेमोरी असाइन करते हैं. भले ही, रैपर एक ही Java इंस्टेंस को दिखाते हों.

उदाहरण के लिए, जब Java का Singleton.getInstance() तरीका हमेशा एक ही इंस्टेंस दिखाता है, तो C की तरफ़ मौजूद फ़ंक्शन, उसी Java इंस्टेंस के लिए रैपर का नया इंस्टेंस बनाएगा:

Singleton* singleton_a = Singleton_getInsance();
Singleton* singleton_b = Singleton_getInsance();

// singleton_a and singleton_b are different pointers, even though they represent the same Java instance.

बिना किसी रेफ़रंस वाली क्लास मैनेज करना

जब किसी JAR में क्लास नहीं मिलती है, तो लाइब्रेरी रैपर एक बेसिक इंप्लीमेंटेशन बनाता है. इसमें एक ओपेक पॉइंटर और ये तरीके शामिल होते हैं:

• wrapJniReference()
• getJniReference()
• destroy()

कोड जनरेट करने की जानकारी

लाइब्रेरी रैपर को चलाने पर, यह टूल को दी गई JAR फ़ाइल में मौजूद सार्वजनिक सिंबल के आधार पर C कोड जनरेट करता है. जनरेट किए गए C कोड और रैप किए गए Java कोड में अंतर हो सकता है. उदाहरण के लिए, C में OOP, जेनेरिक टाइप, मेथड ओवरलोडिंग या Java की अन्य सुविधाओं का इस्तेमाल नहीं किया जा सकता.

इन स्थितियों को दिखाने वाला जनरेट किया गया C कोड, C डेवलपर की उम्मीद के मुताबिक कोड से अलग हो सकता है. यहां दिए गए उदाहरणों से, यह समझने में मदद मिलती है कि टूल, Java कोड से C कोड कैसे जनरेट कर सकता है. ध्यान दें: कोड स्निपेट में, यहां दिए गए उदाहरणों में C/C++ और Java कोड के स्निपेट शामिल हैं. इन स्निपेट का मकसद सिर्फ़ यह दिखाना है कि टूल, दी गई हर स्थिति के लिए कोड कैसे जनरेट करता है.

कक्षाएं

C में क्लास को opaque pointers के तौर पर दिखाया जाता है:

typedef struct MyClass_ MyClass;

public class MyClass { ... }

ओपेक पॉइंटर के इंस्टेंस को रैपर के तौर पर रेफ़र किया जाता है. रैपर टूल, हर क्लास के लिए सहायता से जुड़े अतिरिक्त फ़ंक्शन जनरेट करता है. ऊपर दिए गए उदाहरण में, क्लास MyClass के लिए ये फ़ंक्शन जनरेट किए गए हैं:

// Wraps a JNI reference with MyClass. The 'jobj' must represent MyClass on the Java side.
MyClass* MyClass_wrapJniReference(jobject jobj);

// Return JNI reference associated with the 'MyClass' pointer.
jobject MyClass_getJniReference(const MyClass* object);

// Destroys the object and releases underlying JNI reference.
void MyClass_destroy(const MyClass* object);

कंस्ट्रक्टर

पब्लिक या डिफ़ॉल्ट कंस्ट्रक्टर वाली क्लास को खास फ़ंक्शन का इस्तेमाल करके दिखाया जाता है:

MyClass* MyClass_construct(String* data);

public class MyClass {
  public MyClass(String data) { ... }
}

माटिंग में इस्तेमाल हुए तरीके

तरीकों को सामान्य फ़ंक्शन के तौर पर दिखाया जाता है. फ़ंक्शन के नाम में, क्लास का ओरिजनल नाम शामिल होता है. नॉन-स्टैटिक इंस्टेंस मेथड को दिखाने वाले फ़ंक्शन के पहले पैरामीटर के तौर पर, Java ऑब्जेक्ट को दिखाने वाले स्ट्रक्चर का पॉइंटर होता है. इस ऑब्जेक्ट के लिए फ़ंक्शन को कॉल किया जाता है. यह तरीका, this पॉइंटर के जैसा ही है.

Result* MyClass_doAction(const MyClass* my_class_instance, int32_t action_id, String* data);
int32_t MyClass_doAction(int32_t a, int32_t b);

public class MyClass {
  public Result doAction(int actionId, String data) { ... }
  public static int doCalculations(int a, int b) { ... }
}

इनर क्लास

इनर क्लास को सामान्य क्लास की तरह ही दिखाया जाता है. हालांकि, इससे जुड़े C स्ट्रक्चर के नाम में आउटर क्लास के चेन किए गए नाम शामिल होते हैं:

typedef struct MyClass_InnerClass_ MyClass_InnerClass;

public class MyClass {
  public class InnerClass {...}
}

इनर क्लास के तरीके

इनर क्लास के तरीकों को इस तरह दिखाया जाता है:

bool MyClass_InnerClass_setValue(MyClass_InnerClass* my_class_inner_class_instance, int32_t value);

public class MyClass {
  public class InnerClass {
    public boolean setValue(int value) { ... }
  }
}

जेनरिक टाइप

लाइब्रेरी रैपर, सामान्य टाइप को सीधे तौर पर रैप नहीं करता है. इसके बजाय, यह टूल सिर्फ़ सामान्य टाइप के इंस्टैंटिएशन के लिए रैपर जनरेट करता है.

उदाहरण के लिए, जब किसी एपीआई में कोई क्लास MyGeneric<T> मौजूद होती है और इस क्लास के दो इंस्टैंटिएशन होते हैं, जैसे कि MyGeneric<Integer> और MyGeneric<String>, तो उन दो इंस्टैंटिएशन के लिए रैपर जनरेट किए जाते हैं. इसका मतलब है कि अलग-अलग टाइप कॉन्फ़िगरेशन का इस्तेमाल करके, MyGeneric<T> टाइप के नए इंस्टैंटिएशन नहीं बनाए जा सकते. यह उदाहरण देखें:

// result.h

typedef struct Result_Integer_ Result_Integer;
typedef struct Result_Float_ Result_Float;

Integer* Result_Integer_getResult(const Result_Integer* instance);
Float* Result_Float_getResult(const Result_Float* instance);

// data_processor.h

typedef struct DataProcessor_ DataProcessor;

Result_Integer* DataProcessor_processIntegerData(const DataProcessor* instance);
Result_Float* DataProcessor_processFloatData(constDataProcessor* instance);

public class Result<T> {
  public T getResult();
}

public class DataProcessor {
  public Result<Integer> processIntegerData();
  public Result<Float> processFloatData();
}

इंटरफ़ेस लागू करना

implementInterface() को कॉल करके, C इंटरफ़ेस लागू करें. साथ ही, हर इंटरफ़ेस के तरीके के लिए कॉलबैक फ़ंक्शन उपलब्ध कराएं. इस तरीके से सिर्फ़ इंटरफ़ेस लागू किए जा सकते हैं. क्लास और ऐब्स्ट्रैक्ट क्लास लागू नहीं की जा सकतीं. यह उदाहरण देखें:

// observer.h

typedef struct Observer_ Observer;
typedef void (*Observer_onAction1Callback)();
typedef void (*Observer_onAction2Callback)(int32_t data);

Observer* Observer_implementInterface(
Observer_onAction1Callback observer_on_action1_callback,
Observer_onAction2Callback observer_on_action2_callback);

public interface Observer {
  void onAction1();
  void onAction2(int data);
}

public class Subject {
  public void registerObserver(Observer observer);
}

इस्तेमाल का उदाहरण:

void onAction1() {
  // Handle action 1
}

void onAction2(int32_t data) {
  // Handle action 2
}

Observer* observer = Observer_implementInterface(onAction1, onAction2);
Subject_registerObserver(subject, observer);

सीमाएं

लाइब्रेरी रैपर टूल, बीटा वर्शन में उपलब्ध है. आपको इन सीमाओं का सामना करना पड़ सकता है:

Java के ऐसे कंस्ट्रक्ट जिनका इस्तेमाल नहीं किया जा सकता

लाइब्रेरी रैपर के बीटा वर्शन में, इन कंस्ट्रक्ट का इस्तेमाल नहीं किया जा सकता:

• मेथड ओवरलोडिंग

  C लैंग्वेज में, एक ही नाम वाले दो फ़ंक्शन बनाने की अनुमति नहीं है. अगर क्लास में मेथड ओवरलोडिंग का इस्तेमाल किया जाता है, तो जनरेट किया गया C कोड कंपाइल नहीं होगा. इसका समाधान यह है कि पैरामीटर के ज़रूरी सेट के साथ सिर्फ़ एक तरीके का इस्तेमाल किया जाए. फ़िल्टर का इस्तेमाल करके, बाकी फ़ंक्शन को फ़िल्टर किया जा सकता है. यह कंस्ट्रक्टर पर भी लागू होता है.

• टेम्प्लेट वाले तरीके

• static final int और static final String के अलावा अन्य फ़ील्ड

• श्रेणियां

नाम मेल खाने की संभावित समस्याएं

C कोड में Java क्लास को जिस तरह से दिखाया जाता है उसकी वजह से, बहुत कम मामलों में नाम से जुड़ी समस्याएं हो सकती हैं. उदाहरण के लिए, C में Foo क्लास के अंदर मौजूद क्लास Foo<Bar> और इनर क्लास Bar को एक ही सिंबल से दिखाया जाता है: typedef struct Foo_Bar_ Foo_Bar;

सहायता

अगर आपको लाइब्रेरी रैपर में कोई समस्या मिलती है, तो कृपया हमें बताएं.