Die Android-Plattform enthält viele XML-Dateien zum Speichern von Konfigurationsdaten (z. B. Audiokonfiguration). Viele der XML-Dateien befinden sich in der vendor
, werden jedoch in der system
gelesen. In diesem Fall dient das Schema der XML-Datei als Schnittstelle zwischen den beiden Partitionen. Daher muss das Schema explizit angegeben werden und abwärtskompatibel weiterentwickelt werden.
Vor Android 10 bot die Plattform keine Mechanismen, um die Angabe und Verwendung des XML-Schemas zu erfordern oder inkompatible Änderungen im Schema zu verhindern. Android 10 bietet diesen Mechanismus namens Config File Schema API. Dieser Mechanismus besteht aus einem Tool namens xsdc
und einer Build-Regel namens xsd_config
.
Das xsdc
Tool ist ein XML Schema Document (XSD)-Compiler. Es analysiert eine XSD-Datei, die das Schema einer XML-Datei beschreibt, und generiert Java- und C++-Code. Der generierte Code analysiert XML-Dateien, die dem XSD-Schema entsprechen, in einen Baum von Objekten, von denen jedes ein XML-Tag modelliert. XML-Attribute werden als Felder der Objekte modelliert.
Die Build-Regel xsd_config
integriert das xsdc
Tool in das Build-System. Für eine bestimmte XSD-Eingabedatei generiert die Build-Regel Java- und C++-Bibliotheken. Sie können die Bibliotheken mit den Modulen verknüpfen, in denen die XSD-konformen XML-Dateien gelesen und verwendet werden. Sie können die Build-Regel für Ihre eigenen XML-Dateien verwenden, die in den system
und vendor
verwendet werden.
Erstellen einer Konfigurationsdatei-Schema-API
In diesem Abschnitt wird beschrieben, wie Sie die Konfigurationsdateischema-API erstellen.
Konfigurieren der Build-Regel xsd_config in Android.bp
Die Build-Regel xsd_config
generiert den Parser-Code mit dem xsdc
Tool. Die Eigenschaft package_name
der Build-Regel xsd_config
bestimmt den Paketnamen des generierten Java-Codes.
Beispiel für xsd_config
Build-Regel in Android.bp
:
xsd_config {
name: "hal_manifest",
srcs: ["hal_manifest.xsd"],
package_name: "hal.manifest",
}
Beispielverzeichnisstruktur:
├── Android.bp
├── api
│ ├── current.txt
│ ├── last_current.txt
│ ├── last_removed.txt
│ └── removed.txt
└── hal_manifest.xsd
Das Build-System generiert mithilfe des generierten Java-Codes eine API-Liste und prüft die API anhand dieser. Diese API-Prüfung wird zu DroidCore hinzugefügt und bei m -j
ausgeführt.
Erstellen von API-Listendateien
Für die API-Prüfungen sind API-Listendateien im Quellcode erforderlich.
Zu den API-Listendateien gehören:
-
current.txt
undremoved.txt
prüfen, ob sich die APIs geändert haben, indem sie sie mit den generierten API-Dateien zur Erstellungszeit vergleichen. -
last_current.txt
undlast_removed.txt
prüfen durch Vergleich mit API-Dateien, ob die APIs abwärtskompatibel sind.
So erstellen Sie die API-Listendateien:
- Erstellen Sie leere Listendateien.
- Führen Sie den Befehl
make update-api
aus.
Verwendung des generierten Parser-Codes
Um den generierten Java-Code zu verwenden, fügen Sie :
als Präfix zum xsd_config
Modulnamen in der Java- srcs
Eigenschaft hinzu. Das Paket des generierten Java-Codes ist dasselbe wie die Eigenschaft package_name
.
java_library {
name: "vintf_test_java",
srcs: [
"srcs/**/*.java"
":hal_manifest"
],
}
Um den generierten C++-Code zu verwenden, fügen Sie den Modulnamen xsd_config
“ zu den Eigenschaften generated_sources
“ und generated_headers
“ hinzu. Und fügen Sie libxml2
zu static_libs
oder shared_libs
hinzu, da libxml2
im generierten Parsercode erforderlich ist. Der Namespace des generierten C++-Codes ist derselbe wie die Eigenschaft package_name
. Wenn der Name des xsd_config
Moduls beispielsweise hal.manifest
lautet, lautet der Namespace hal::manifest
.
cc_library{
name: "vintf_test_cpp",
srcs: ["main.cpp"],
generated_sources: ["hal_manifest"],
generated_headers: ["hal_manifest"],
shared_libs: ["libxml2"],
}
Verwendung des Parsers
Um den Java-Parser-Code zu verwenden, verwenden Sie die Methode XmlParser#read
oder read{ class-name }
, um die Klasse des Stammelements zurückzugeben. Das Parsen erfolgt zu diesem Zeitpunkt.
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();
…
}
}
…
}
Um den C++-Parsercode zu verwenden, schließen Sie zunächst die Header-Datei ein. Der Name der Header-Datei ist der Paketname mit Punkten (.), die in Unterstriche (_) umgewandelt werden. Verwenden Sie dann die Methode read
oder read{ class-name }
um die Klasse des Stammelements zurückzugeben. Das Parsen erfolgt zu diesem Zeitpunkt. Der Rückgabewert ist ein 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();
…
}
…
}
Alle zur Verwendung des Parsers bereitgestellten APIs befinden sich in api/current.txt
. Aus Gründen der Einheitlichkeit werden alle Element- und Attributnamen in Kamel-Schreibweise umgewandelt (z. B. ElementName
) und als entsprechende Variable, Methode und Klassenname verwendet. Die Klasse des analysierten Stammelements kann mit der Funktion read{ class-name }
abgerufen werden. Wenn nur ein Wurzelelement vorhanden ist, lautet der Funktionsname read
. Der Wert eines analysierten Unterelements oder Attributs kann mit der Funktion get{ variable-name }
abgerufen werden.
Parser-Code generieren
In den meisten Fällen müssen Sie xsdc
nicht direkt ausführen. Verwenden Sie stattdessen die Build-Regel xsd_config
, wie unter Konfigurieren der Build-Regel xsd_config in Android.bp beschrieben. In diesem Abschnitt wird der Vollständigkeit halber die xsdc
Befehlszeilenschnittstelle erläutert. Dies kann zum Debuggen nützlich sein.
Sie müssen dem xsdc
Tool den Pfad zur XSD-Datei und ein Paket geben. Das Paket ist ein Paketname im Java-Code und ein Namespace im C++-Code. Die Optionen zur Bestimmung, ob der generierte Code Java oder C ist, sind -j
bzw. -c
. Die Option -o
ist der Pfad des Ausgabeverzeichnisses.
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
Beispielbefehl:
$ xsdc audio_policy_configuration.xsd -p audio.policy -j