जावा एसडीके लाइब्रेरी को लागू करना

एंड्रॉइड प्लेटफॉर्म में बड़ी संख्या में साझा जावा लाइब्रेरी हैं जिन्हें वैकल्पिक रूप से ऐप मेनिफेस्ट में <uses-library> टैग के साथ ऐप के क्लासपाथ में शामिल किया जा सकता है। ऐप्स इन पुस्तकालयों के खिलाफ लिंक करते हैं, इसलिए संगतता, एपीआई समीक्षा और टूलींग समर्थन के मामले में उन्हें बाकी एंड्रॉइड एपीआई की तरह व्यवहार करें। हालाँकि, ध्यान दें कि अधिकांश पुस्तकालयों में ये सुविधाएँ नहीं होती हैं।

java_sdk_library मॉड्यूल प्रकार इस प्रकार के पुस्तकालयों को प्रबंधित करने में मदद करता है। डिवाइस निर्माता अपने एपीआई के लिए पश्चगामी संगतता बनाए रखने के लिए, अपने स्वयं के साझा जावा पुस्तकालयों के लिए इस तंत्र का उपयोग कर सकते हैं। यदि डिवाइस निर्माता बूटक्लास पथ के बजाय <uses-library> टैग के माध्यम से अपनी साझा जावा लाइब्रेरी का उपयोग करते हैं, java_sdk_library यह सत्यापित कर सकता है कि वे जावा लाइब्रेरी API-स्थिर हैं।

java_sdk_library ऐप्स द्वारा उपयोग के लिए वैकल्पिक SDK API लागू करता है। आपकी बिल्ड फ़ाइल ( Android.bp ) में java_sdk_library के माध्यम से कार्यान्वित पुस्तकालय निम्नलिखित कार्य करते हैं:

• स्टब्स लाइब्रेरी को stubs , stubs.system और stubs.test को शामिल करने के लिए जेनरेट किया जाता है। ये स्टब्स लाइब्रेरी @hide , @SystemApi , और @TestApi एनोटेशन को पहचानकर बनाए गए हैं।
• java_sdk_library API विनिर्देश फ़ाइलों (जैसे current.txt ) को API उपनिर्देशिका में प्रबंधित करता है। इन फ़ाइलों को नवीनतम कोड के विरुद्ध जाँचा जाता है ताकि यह सुनिश्चित किया जा सके कि वे सबसे वर्तमान संस्करण हैं। यदि वे नहीं हैं, तो आपको एक त्रुटि संदेश प्राप्त होता है जो बताता है कि उन्हें कैसे अपडेट किया जाए। यह सुनिश्चित करने के लिए कि वे आपकी अपेक्षाओं से मेल खाते हैं, सभी अपडेट परिवर्तनों की मैन्युअल रूप से समीक्षा करें।
  
  सभी API को अपडेट करने के लिए, m update-api का उपयोग करें। यह सत्यापित करने के लिए कि कोई API अप-टू-डेट है, m checkapi का उपयोग करें।
• एपीआई विनिर्देश फाइलों को हाल ही में प्रकाशित एंड्रॉइड संस्करणों के खिलाफ जांचा जाता है ताकि यह सुनिश्चित हो सके कि एपीआई पिछली रिलीज के साथ पिछड़ा-संगत है। AOSP के हिस्से के रूप में प्रदान किए गए java_sdk_library मॉड्यूल उनके पहले जारी किए गए संस्करणों को prebuilts/sdk/<latest number> में रखते हैं।
• एपीआई विनिर्देश फाइलों की जांच के संबंध में, आप निम्नलिखित तीन चीजों में से एक कर सकते हैं:
• चेकों को आगे बढ़ने दें। (कुछ मत करो।)
• java_sdk_library में निम्नलिखित जोड़कर चेक अक्षम करें:
  unsafe_ignore_missing_latest_api: true,
• नए java_sdk_library मॉड्यूल के लिए खाली एपीआई प्रदान करें, version/scope/api निर्देशिका में module_name.txt .txt नाम की खाली टेक्स्ट फाइलें बनाएं।
• यदि रनटाइम के लिए कार्यान्वयन पुस्तकालय स्थापित है, तो एक एक्सएमएल फ़ाइल उत्पन्न और स्थापित हो जाती है।

Java_sdk_library कैसे काम करता है

X नामक एक java_sdk_library निम्नलिखित बनाता है:

1. कार्यान्वयन पुस्तकालय की दो प्रतियां: एक पुस्तकालय जिसे X कहा जाता है और दूसरे को X.impl कहा जाता है। लाइब्रेरी X डिवाइस पर स्थापित है। लाइब्रेरी X.impl केवल तभी है जब अन्य मॉड्यूल द्वारा कार्यान्वयन लाइब्रेरी तक स्पष्ट पहुंच की आवश्यकता होती है, जैसे परीक्षण में उपयोग के लिए। ध्यान दें कि स्पष्ट पहुंच की शायद ही कभी आवश्यकता होती है।
2. पहुंच को अनुकूलित करने के लिए कार्यक्षेत्रों को सक्षम और अक्षम किया जा सकता है। (जावा कीवर्ड-एक्सेस संशोधक के समान, एक सार्वजनिक दायरा पहुंच की एक विस्तृत श्रृंखला प्रदान करता है; एक परीक्षण क्षेत्र में केवल परीक्षण में उपयोग किए जाने वाले एपीआई होते हैं।) प्रत्येक सक्षम क्षेत्र के लिए पुस्तकालय निम्नलिखित बनाता है:
• एक स्टब्स स्रोत मॉड्यूल ( droidstubs मॉड्यूल प्रकार का) - कार्यान्वयन स्रोत का उपभोग करता है और API विनिर्देश फ़ाइल के साथ स्टब स्रोतों का एक सेट आउटपुट करता है।
• एक स्टब्स लाइब्रेरी ( java_library मॉड्यूल प्रकार की) - स्टब्स का संकलित संस्करण है। इसे संकलित करने के लिए उपयोग किए गए libs java_sdk_library को दिए गए समान नहीं हैं, जो सुनिश्चित करता है कि कार्यान्वयन विवरण API स्टब्स में लीक न हो।
• यदि आपको स्टब्स को संकलित करने के लिए अतिरिक्त पुस्तकालयों की आवश्यकता है, तो उन्हें आपूर्ति करने के लिए stub_only_libs और stub_only_static_libs गुणों का उपयोग करें।

यदि एक java_sdk_library को " X " कहा जाता है, और इसे " X " के रूप में संकलित किया जा रहा है, तो इसे हमेशा इस तरह देखें और इसे संशोधित न करें। बिल्ड एक उपयुक्त पुस्तकालय का चयन करेगा। यह सुनिश्चित करने के लिए कि आपके पास सबसे उपयुक्त पुस्तकालय है, यह देखने के लिए अपने स्टब्स का निरीक्षण करें कि क्या बिल्ड में त्रुटियां हैं। इस मार्गदर्शन का उपयोग करके कोई भी आवश्यक सुधार करें:

• सत्यापित करें कि आपके पास कमांड लाइन को देखकर एक उपयुक्त पुस्तकालय है और निरीक्षण करें कि आपके दायरे को निर्धारित करने के लिए कौन से स्टब्स सूचीबद्ध हैं:
• दायरा बहुत व्यापक है: निर्भर पुस्तकालय को एपीआई के एक निश्चित दायरे की आवश्यकता होती है। लेकिन आप पुस्तकालय में शामिल एपीआई देखते हैं जो उस दायरे से बाहर आते हैं, जैसे कि सिस्टम एपीआई सार्वजनिक एपीआई के साथ शामिल हैं।
• दायरा बहुत संकीर्ण है: निर्भर पुस्तकालय के पास सभी आवश्यक पुस्तकालयों तक पहुंच नहीं है। उदाहरण के लिए, निर्भर पुस्तकालय को सिस्टम एपीआई का उपयोग करने की आवश्यकता होती है, लेकिन इसके बजाय सार्वजनिक एपीआई प्राप्त होती है। यह आमतौर पर एक संकलन त्रुटि में परिणत होता है क्योंकि आवश्यक एपीआई गायब हैं।
• लाइब्रेरी को ठीक करने के लिए, निम्न में से केवल एक कार्य करें:
• आपको जिस संस्करण की आवश्यकता है उसे चुनने के लिए sdk_version बदलें। या
• स्पष्ट रूप से उपयुक्त पुस्तकालय निर्दिष्ट करें, जैसे <X>.stubs या <X>.stubs.system ।

java_sdk_library एक्स उपयोग

कार्यान्वयन पुस्तकालय X का उपयोग तब किया जाता है जब इसे apex.java_libs से संदर्भित किया जाता है। हालाँकि, एक सूंग सीमा के कारण, जब लाइब्रेरी X को उसी एपेक्स लाइब्रेरी के भीतर किसी अन्य java_sdk_library मॉड्यूल से संदर्भित किया जाता है, तो X.impl स्पष्ट रूप से उपयोग किया जाना चाहिए, लाइब्रेरी X का नहीं।

जब java_sdk_library को कहीं और से संदर्भित किया जाता है, तो एक स्टब्स लाइब्रेरी का उपयोग किया जाता है। स्टब्स लाइब्रेरी का चयन मॉड्यूल की sdk_version प्रॉपर्टी सेटिंग के अनुसार किया जाता है। उदाहरण के लिए, एक मॉड्यूल जो sdk_version: "current" सार्वजनिक स्टब्स का उपयोग करता है, जबकि एक मॉड्यूल जो sdk_version: "system_current" निर्दिष्ट करता है, सिस्टम स्टब्स का उपयोग करता है। यदि कोई सटीक मिलान नहीं मिल पाता है, तो निकटतम स्टब लाइब्रेरी का उपयोग किया जाता है। एक java_sdk_library जो केवल एक सार्वजनिक API प्रदान करती है, सभी के लिए सार्वजनिक स्टब्स की आपूर्ति करेगी।

उदाहरण और स्रोत

java_sdk_library में srcs और api_packages गुण मौजूद होने चाहिए ।

java_sdk_library {
        name: "com.android.future.usb.accessory",
        srcs: ["src/**/*.java"],
        api_packages: ["com.android.future.usb"],
    }

एओएसपी अनुशंसा करता है (लेकिन इसकी आवश्यकता नहीं है) कि नए java_sdk_library उदाहरण स्पष्ट रूप से एपीआई स्कोप को सक्षम करते हैं जिनका वे उपयोग करना चाहते हैं। आप (वैकल्पिक रूप से) मौजूदा java_sdk_library उदाहरणों को माइग्रेट कर सकते हैं ताकि स्पष्ट रूप से उनके द्वारा उपयोग किए जाने वाले API स्कोप को सक्षम किया जा सके:

java_sdk_library {
         name: "lib",
         public: {
           enabled: true,
         },
         system: {
           enabled: true,
         },
         …
    }

रनटाइम के लिए उपयोग की जाने वाली java_library impl का उपयोग करें, जैसे कि hostdex , compile_dex और errorprone ।

java_sdk_library {
        name: "android.test.base",

        srcs: ["src/**/*.java"],

        errorprone: {
          javacflags: ["-Xep:DepAnn:ERROR"],
        },

        hostdex: true,

        api_packages: [
            "android.test",
            "android.test.suitebuilder.annotation",
            "com.android.internal.util",
            "junit.framework",
        ],

        compile_dex: true,
    }

स्टब्स लाइब्रेरी को कॉन्फ़िगर करने के लिए, निम्नलिखित गुणों का उपयोग करें:

• merge_annotations_dirs और merge_inclusion_annotations_dirs ।
• api_srcs : वैकल्पिक स्रोत फ़ाइलों की सूची जो एपीआई का हिस्सा हैं लेकिन रनटाइम लाइब्रेरी का हिस्सा नहीं हैं।
• stubs_only_libs : जावा लाइब्रेरी की सूची जो स्टब्स बनाते समय क्लासपाथ में होती है।
• hidden_api_packages : पैकेज नामों की सूची जिन्हें एपीआई से छिपाया जाना चाहिए।
• droiddoc_options : मेटलवा के लिए अतिरिक्त तर्क।
• droiddoc_option_files : उन फ़ाइलों को सूचीबद्ध करता है जिन्हें $(location <label>) का उपयोग करके droiddoc_options के भीतर से संदर्भित किया जा सकता है, जहां <file> सूची में एक प्रविष्टि है।
• annotations_enabled ।

java_sdk_library एक java_library है, लेकिन यह एक droidstubs मॉड्यूल नहीं है और इसलिए सभी droidstubs गुणों का समर्थन नहीं करता है। निम्न उदाहरण android.test.mock लाइब्रेरी बिल्ड फ़ाइल से लिया गया था।

java_sdk_library {
        name: "android.test.mock",

        srcs: [":android-test-mock-sources"],
        api_srcs: [
            // Note: The following aren’t APIs of this library. Only APIs under the
            // android.test.mock package are taken. These do provide private APIs
            // to which android.test.mock APIs reference. These classes are present
            // in source code form to access necessary comments that disappear when
            // the classes are compiled into a Jar library.
            ":framework-core-sources-for-test-mock",
            ":framework_native_aidl",
        ],

        libs: [
            "framework",
            "framework-annotations-lib",
            "app-compat-annotations",
            "Unsupportedappusage",
        ],

        api_packages: [
            "android.test.mock",
        ],
        permitted_packages: [
            "android.test.mock",
        ],
        compile_dex: true,
        default_to_stubs: true,
    }

पिछड़ी संगतता बनाए रखना

बिल्ड सिस्टम यह जांचता है कि बिल्ड समय पर जेनरेट की गई एपीआई फाइलों के साथ नवीनतम एपीआई फाइलों की तुलना करके एपीआई ने पिछड़ा संगतता बनाए रखा है या नहीं। java_sdk_library prebuilt_apis द्वारा प्रदान की गई जानकारी का उपयोग करके संगतता जांच करता है। java_sdk_library के साथ निर्मित सभी पुस्तकालयों में API फ़ाइलें prebuilt_apis में api_dirs के नवीनतम संस्करण में होनी चाहिए। जब आप संस्करण जारी करते हैं, तो एपीआई फाइलों को सूचीबद्ध करता है और स्टब्स लाइब्रेरी को PRODUCT=sdk_phone_armv7-sdk के साथ डिस्ट बिल्ड के साथ प्राप्त किया जा सकता है।

api_dirs गुण prebuilt_apis में API संस्करण निर्देशिकाओं की सूची है। एपीआई-संस्करण निर्देशिकाएं Android.bp निर्देशिका स्तर पर स्थित होनी चाहिए।

prebuilt_apis {
       name: "foo",
       api_dirs: [
           "1",
           "2",
             ....
           "30",
           "current",
       ],
    }

प्रीबिल्ट डायरेक्टरी के तहत version / scope /api/ स्ट्रक्चर के साथ डायरेक्टरी को कॉन्फ़िगर करें। version एपीआई स्तर से मेल खाता है और scope परिभाषित करता है कि निर्देशिका सार्वजनिक, सिस्टम या परीक्षण है या नहीं।

• version / scope में जावा पुस्तकालय शामिल हैं।
• version / scope /api में एपीआई .txt फाइलें हैं। यहां मॉड्यूल_नाम module_name .txt और module_name -removed.txt नाम की खाली टेक्स्ट फाइलें बनाएं।

   ├── 30
        │   ├── public
        │   │   ├── api
        │   │   │   ├── android.test.mock-removed.txt
        │   │   │   └── android.test.mock.txt
        │   │   └── android.test.mock.jar
        │   ├── system
        │   │   ├── api
        │   │   │   ├── android.test.mock-removed.txt
        │   │   │   └── android.test.mock.txt
        │   │   └── android.test.mock.jar
        │   └── test
        │       ├── api
        │       │   ├── android.test.mock-removed.txt
        │       │   └── android.test.mock.txt
        │       └── android.test.mock.jar
        └── Android.bp