Config File Schema API लागू करना

Android प्लैटफ़ॉर्म में कॉन्फ़िगरेशन डेटा (जैसे, ऑडियो कॉन्फ़िगरेशन) सेव करने के लिए कई एक्सएमएल फ़ाइलें होती हैं. ज़्यादातर एक्सएमएल फ़ाइलें vendor पार्टिशन में हैं, लेकिन उन्हें system पार्टिशन में पढ़ा जाता है. इस मामले में, एक्सएमएल फ़ाइल का स्कीमा, दोनों पार्टीशन के बीच इंटरफ़ेस के तौर पर काम करता है. इसलिए, स्कीमा को साफ़ तौर पर बताया जाना चाहिए. साथ ही, इसे बैकवर्ड-कंपैटिबल तरीके से विकसित किया जाना चाहिए.

Android 10 से पहले, प्लैटफ़ॉर्म में एक्सएमएल स्कीमा को तय करने और इस्तेमाल करने के लिए, कोई तरीका उपलब्ध नहीं था. साथ ही, स्कीमा में ऐसे बदलावों को रोकने का कोई तरीका भी उपलब्ध नहीं था जो काम नहीं करते. Android 10 में यह सुविधा उपलब्ध है. इसे कॉन्फ़िगरेशन फ़ाइल स्कीमा एपीआई कहा जाता है. इस तरीके में, xsdc नाम का एक टूल और xsd_config नाम का एक बिल्ड नियम शामिल होता है.

xsdc टूल, एक्सएमएल स्कीमा दस्तावेज़ (एक्सएसडी) कंपाइलर है. यह एक्सएमएल फ़ाइल के स्कीमा के बारे में बताने वाली XSD फ़ाइल को पार्स करता है. साथ ही, Java और C++ कोड जनरेट करता है. जनरेट किया गया कोड, XSD स्कीमा के मुताबिक एक्सएमएल फ़ाइलों को ऑब्जेक्ट के ट्री में पार्स करता है. इनमें से हर ऑब्जेक्ट, एक्सएमएल टैग को मॉडल करता है. एक्सएमएल एट्रिब्यूट को ऑब्जेक्ट के फ़ील्ड के तौर पर मॉडल किया जाता है.

xsd_config बिल्ड रूल, xsdc टूल को बिल्ड सिस्टम में इंटिग्रेट करता है. किसी दी गई XSD इनपुट फ़ाइल के लिए, बिल्ड रूल, Java और C++ लाइब्रेरी जनरेट करता है. लाइब्रेरी को उन मॉड्यूल से लिंक किया जा सकता है जहां XSD के मुताबिक एक्सएमएल फ़ाइलें पढ़ी और इस्तेमाल की जाती हैं. system और vendor, दोनों के लिए इस्तेमाल की गई अपनी एक्सएमएल फ़ाइलों के लिए, बिल्ड रूल का इस्तेमाल किया जा सकता है.

Build Config File Schema API

इस सेक्शन में, कॉन्फ़िगरेशन फ़ाइल स्कीमा एपीआई बनाने का तरीका बताया गया है.

Android.bp में xsd_config बिल्ड नियम को कॉन्फ़िगर करना

xsd_config बिल्ड रूल, xsdc टूल की मदद से पार्सर कोड जनरेट करता है. xsd_config बिल्ड रूल की package_name प्रॉपर्टी से, जनरेट किए गए Java कोड के पैकेज का नाम तय होता है.

Android.bp में xsd_config के लिए, बिल्ड नियम का उदाहरण:

xsd_config {
    name: "hal_manifest",
    srcs: ["hal_manifest.xsd"],
    package_name: "hal.manifest",
}

डायरेक्ट्री स्ट्रक्चर का उदाहरण:

├── Android.bp
├── api
│   ├── current.txt
│   ├── last_current.txt
│   ├── last_removed.txt
│   └── removed.txt
└── hal_manifest.xsd

बिल्ड सिस्टम, जनरेट किए गए Java कोड का इस्तेमाल करके एपीआई की सूची जनरेट करता है. साथ ही, एपीआई की जांच करता है. एपीआई की इस जांच को DroidCore में जोड़ा जाता है और इसे m -j पर लागू किया जाता है.

एपीआई की सूचियों वाली फ़ाइलें बनाना

एपीआई की जांच के लिए, सोर्स कोड में एपीआई की सूची वाली फ़ाइलें ज़रूरी होती हैं.

एपीआई से मिली फ़ाइलों की सूची में ये शामिल हैं:

• current.txt और removed.txt, बिल्ड प्रोसेस में लगने वाले समय पर जनरेट की गई एपीआई फ़ाइलों से तुलना करके यह पता लगाते हैं कि एपीआई में बदलाव किया गया है या नहीं.
• last_current.txt और last_removed.txt एपीआई फ़ाइलों की तुलना करके, यह पता लगाते हैं कि एपीआई पिछले वर्शन के साथ काम करते हैं या नहीं.

एपीआई की सूचियों वाली फ़ाइलें बनाने के लिए:

1. खाली सूचियों वाली फ़ाइलें बनाना.
2. make update-api कमांड चलाएं.

जनरेट किए गए पार्सर कोड का इस्तेमाल करना

जनरेट किए गए Java कोड का इस्तेमाल करने के लिए, Java srcs प्रॉपर्टी में xsd_config मॉड्यूल के नाम से पहले : को प्रीफ़िक्स के तौर पर जोड़ें. जनरेट किए गए Java कोड का पैकेज, package_name प्रॉपर्टी के पैकेज जैसा ही होता है.

java_library {
    name: "vintf_test_java",
    srcs: [
        "srcs/**/*.java"
        ":hal_manifest"
    ],
}

जनरेट किए गए C++ कोड का इस्तेमाल करने के लिए, xsd_config मॉड्यूल का नाम generated_sources और generated_headers प्रॉपर्टी में जोड़ें. साथ ही, libxml2 को static_libs या shared_libs में जोड़ें, क्योंकि जनरेट किए गए पार्सर कोड में libxml2 ज़रूरी है. जनरेट किए गए C++ कोड का नेमस्पेस, package_name प्रॉपर्टी के जैसा ही होता है. उदाहरण के लिए, अगर xsd_config मॉड्यूल का नाम hal.manifest है, तो नेमस्पेस hal::manifest होगा.

cc_library{
    name: "vintf_test_cpp",
    srcs: ["main.cpp"],
    generated_sources: ["hal_manifest"],
    generated_headers: ["hal_manifest"],
    shared_libs: ["libxml2"],
}

पार्सर का इस्तेमाल करना

Java पार्सर कोड का इस्तेमाल करने के लिए, XmlParser#read या read{class-name} तरीके का इस्तेमाल करके, रूट एलिमेंट की क्लास वापस लाएं. इस दौरान पार्सिंग होती है.

import hal.manifest.*;

…

class HalInfo {
    public String name;
    public String format;
    public String optional;
    …
}

void readHalManifestFromXml(File file) {
    …
    try (InputStream str = new BufferedInputStream(new FileInputStream(file))) {
        Manifest manifest = XmlParser.read(str);
        for (Hal hal : manifest.getHal()) {
            HalInfo halinfo;
            HalInfo.name = hal.getName();
            HalInfo.format = hal.getFormat();
            HalInfo.optional = hal.getOptional();
            …
        }
    }
    …
}

C++ पार्सर कोड का इस्तेमाल करने के लिए, पहले हेडर फ़ाइल शामिल करें. हेडर फ़ाइल का नाम, पैकेज का नाम होता है. इसमें मौजूद अवधि (.) को अंडरस्कोर (_) में बदल दिया जाता है. इसके बाद, रूट एलिमेंट की क्लास वापस पाने के लिए, read या read{class-name} तरीके का इस्तेमाल करें. इस दौरान पार्सिंग होती है. इस फ़ंक्शन से मिलने वाली वैल्यू, std::optional<> होती है.

include "hal_manifest.h"

…
using namespace hal::manifest

struct HalInfo {
    public std::string name;
    public std::string format;
    public std::string optional;
    …
};

void readHalManifestFromXml(std::string file_name) {
    …
    Manifest manifest = *read(file_name.c_str());
    for (Hal hal : manifest.getHal()) {
        struct HalInfo halinfo;
        HalInfo.name = hal.getName();
        HalInfo.format = hal.getFormat();
        HalInfo.optional = hal.getOptional();
        …
    }
    …
}

पार्सर का इस्तेमाल करने के लिए उपलब्ध कराए गए सभी एपीआई, api/current.txt में मौजूद हैं. एक जैसा फ़ॉर्मैट रखने के लिए, सभी एलिमेंट और एट्रिब्यूट के नामों को कैमल केस (उदाहरण के लिए, ElementName) में बदल दिया जाता है. साथ ही, इनका इस्तेमाल वैरिएबल, तरीके, और क्लास के नाम के तौर पर किया जाता है. पार्स किए गए रूट एलिमेंट की क्लास, read{class-name} फ़ंक्शन का इस्तेमाल करके पाई जा सकती है. अगर सिर्फ़ एक रूट एलिमेंट है, तो फ़ंक्शन का नाम read होता है. पार्स किए गए किसी सब-एलिमेंट या एट्रिब्यूट की वैल्यू पाने के लिए, get{variable-name} फ़ंक्शन का इस्तेमाल किया जा सकता है.

पार्सर कोड जनरेट करना

ज़्यादातर मामलों में, आपको xsdc को सीधे तौर पर चलाने की ज़रूरत नहीं होती. इसके बजाय, xsd_config build rule का इस्तेमाल करें. इसके बारे में Android.bp में xsd_config build rule को कॉन्फ़िगर करना लेख में बताया गया है. इस सेक्शन में, xsdc कमांड लाइन इंटरफ़ेस के बारे में बताया गया है. यह जानकारी, डीबग करने के लिए काम आ सकती है.

आपको xsdc टूल को XSD फ़ाइल का पाथ और एक पैकेज देना होगा. पैकेज, Java कोड में पैकेज का नाम होता है और C++ कोड में नेमस्पेस होता है. जनरेट किया गया कोड Java या C है या नहीं, यह तय करने के लिए -j या -c विकल्पों का इस्तेमाल करें. -o विकल्प, आउटपुट डायरेक्ट्री का पाथ है.

usage: xsdc path/to/xsd_file.xsd [-c] [-j] [-o <arg>] [-p]
 -c,--cpp           Generate C++ code.
 -j,--java          Generate Java code.
 -o,--outDir <arg>  Out Directory
 -p,--package       Package name of the generated java file. file name of
                    generated C++ file and header

निर्देश का उदाहरण:

$ xsdc audio_policy_configuration.xsd -p audio.policy -j