Metadata vazeb Java

Knihovna vazeb .NET pro Android Java se snaží automatizovat většinu práce potřebné pro vytvoření vazby existující knihovny Androidu pomocí nástroje, který se někdy označuje jako Generátor vazeb. Při vytváření vazby knihovny Java bude .NET pro Android kontrolovat třídy Java a generovat seznam všech balíčků, typů a členů, které mají být vázány. Tento seznam rozhraní API je uložen v souboru XML, který lze najít v adresáři {project}\obj{Configuration}\api.xml.

Umístění souboru api.xml ve složce obj/Debug

Generátor vazeb použije soubor api.xml jako vodítko pro generování nezbytných wrapper tříd jazyka C#. Následující fragment kódu je příkladem obsahu api.xml:

<api>
    <package name="android">
        <class abstract="false" deprecated="not deprecated" extends="java.lang.Object"
            extends-generic-aware="java.lang.Object" 
            final="true" 
            name="Manifest" 
            static="false" 
            visibility="public">
            <constructor deprecated="not deprecated" final="false"
                name="Manifest" static="false" type="android.Manifest"
                visibility="public">
            </constructor>
        </class>
...
</api>

V tomto příkladu api.xml deklaruje třídu v android balíčku pojmenovaném Manifest, která rozšiřuje java.lang.Object.

V mnoha případech je potřeba lidská pomoc, aby se rozhraní Java API více podobalo rozhraní .NET nebo k odstranění problémů, které brání kompilaci vázacího sestavení. Může být například nutné změnit názvy balíčků Java na obory názvů .NET, přejmenovat třídu nebo změnit návratový typ metody.

Tyto změny by neměly být dosaženy úpravou api.xml přímo. Místo toho se změny zaznamenávají ve speciálních souborech XML, které poskytuje šablona knihovny vazeb Java. Při kompilaci sestavení vazby .NET pro Android bude generátor vazeb ovlivněn těmito soubory mapování při vytváření sestavení vazby.

SouborMetadata.xml je nejdůležitější z těchto souborů, protože umožňuje změny vazby pro obecné účely, například:

Přejmenování oborů názvů, tříd, metod nebo datových polí tak, aby odpovídala konvencím .NET.
Odebrání oborů názvů, tříd, metod nebo polí, která nejsou potřeba.
Přesouvání tříd do různých oborů názvů
Přidání dalších tříd podpory, aby návrh vazby odpovídal vzorům rámce .NET.

Metadata.xml transformační soubor

Jak jsme se už naučili, soubor Metadata.xml používá Generátor vazeb k ovlivnění vytvoření sestavení vazby. Formát metadat používá syntaxi XPath .

Tato implementace je téměř kompletní implementace XPath 1.0, a proto podporuje položky ve standardu 1.0. Tento soubor je výkonný mechanismus založený na XPathu pro změnu, přidání, skrytí nebo přesunutí libovolného prvku nebo atributu v souboru rozhraní API. Všechny prvky pravidla ve specifikaci metadat obsahují path atribut pro identifikaci uzlů, na které se má pravidlo použít. K dispozici jsou následující typy elementů:

add-node – připojí podřízený uzel k uzlu určenému atributem cesty.
attr – Nastaví hodnotu atributu prvku určeného atributem path.
remove-node – Odebere uzly odpovídající specifikovanému výrazu XPath.

Následuje příklad souboru Metadata.xml :

<metadata>
    <!-- Normalize the namespace for .NET -->
    <attr path="/api/package[@name='com.evernote.android.job']" 
        name="managedName">Evernote.AndroidJob</attr>

    <!-- Don't need these packages for the .NET for Android binding/public API --> 
    <remove-node path="/api/package[@name='com.evernote.android.job.v14']" />
    <remove-node path="/api/package[@name='com.evernote.android.job.v21']" />

    <!-- Change a parameter name from the generic p0 to a more meaningful one. -->
    <attr path="/api/package[@name='com.evernote.android.job']/class[@name='JobManager']/method[@name='forceApi']/parameter[@name='p0']" 
        name="name">api</attr>
</metadata>

Následující seznam uvádí některé běžně používané elementy XPath pro rozhraní JAVA API:

interface – Slouží k vyhledání rozhraní Java. např. /interface[@name='AuthListener'].
class – Slouží k vyhledání třídy . např. /class[@name='MapView'].
method – Slouží k vyhledání metody ve třídě nebo rozhraní Java. např. /class[@name='MapView']/method[@name='setTitleSource'].
parameter – Identifikujte parametr pro metodu. Například /parameter[@name='p0']

Přidání typů

Element add-node řekne projektu vazby .NET pro Android, aby přidal novou třídu do api.xml. Následující fragment kódu například nasměruje Generátor vazeb na vytvoření třídy s konstruktorem a jedním polem:

<add-node path="/api/package[@name='org.alljoyn.bus']">
    <class abstract="false" deprecated="not deprecated" final="false" name="AuthListener.AuthRequest" static="true" visibility="public" extends="java.lang.Object">
        <constructor deprecated="not deprecated" final="false" name="AuthListener.AuthRequest" static="false" type="org.alljoyn.bus.AuthListener.AuthRequest" visibility="public" />
        <field name="p0" type="org.alljoyn.bus.AuthListener.Credentials" />
    </class>
</add-node>

Odstraňování datových typů

Je možné dát generátoru vazeb .NET pro Android pokyn, aby ignoroval typ Javy a neváže ho. To se provádí přidáním elementu remove-node XML do souboruMetadata.xml :

<remove-node path="/api/package[@name='{package_name}']/class[@name='{name}']" />

Přejmenování členů

Přejmenování členů nelze provést přímo úpravou souboru api.xml , protože .NET pro Android vyžaduje původní názvy JNI (Java Native Interface) pro komunikaci s Javou. //class/@name Proto atribut nelze změnit. Pokud ano, vazba nebude fungovat.

Vezměte v úvahu případ, kdy chceme přejmenovat typ, android.Manifest. Abychom toho dosáhli, můžeme se pokusit přímo upravit api.xml a přejmenovat třídu takto:

<attr path="/api/package[@name='android']/class[@name='Manifest']" 
    name="name">NewName</attr>

Výsledkem bude generátor vazeb, který vytvoří následující kód jazyka C# pro třídu obálky:

[Register ("android/NewName")]
public class NewName : Java.Lang.Object { ... }

Všimněte si, že třída obálky byla přejmenována na NewName, zatímco původní typ Java je stále Manifest. Pro třídu vazby .NET pro Android už není možné přistupovat k žádné metodě na android.Manifest; třída obálky je vázána na neexistující Java typ.

Chcete-li správně změnit "spravovaný" název zabaleného typu (nebo metody), je nutné nastavit managedName atribut, jak je znázorněno v tomto příkladu:

<attr path="/api/package[@name='android']/class[@name='Manifest']" 
    name="managedName">NewName</attr>

Použití managedName se vyžaduje při pokusu o přejmenování libovolného člena, jako jsou třídy, rozhraní, metody a parametry.

Přejmenování `EventArg` tříd obálky

Když generátor vazeb .NET pro Android identifikuje metodu onXXX setter pro typ posluchače, bude vygenerována událost C# a EventArgs podtřída pro podporu rozhraní API stylizovaného podle .NET pro vzor posluchače založený na Javě. Jako příklad zvažte následující třídu a metodu Java:

com.someapp.android.mpa.guidance.NavigationManager.on2DSignNextManuever(NextManueverListener listener);

.NET pro Android zahodí předponu on z metody setter a místo toho se použije 2DSignNextManuever jako základ pro název EventArgs podtřídy. Podtřída bude mít název něco podobného:

NavigationManager.2DSignNextManueverEventArgs

Nejedná se o právní název třídy jazyka C#. Chcete-li tento problém vyřešit, musí autor vazby argsType použít atribut a zadat platný název jazyka C#pro podtřídu EventArgs :

<attr path="/api/package[@name='com.someapp.android.mpa.guidance']/
    interface[@name='NavigationManager.Listener']/
    method[@name='on2DSignNextManeuver']" 
    name="argsType">NavigationManager.TwoDSignNextManueverEventArgs</attr>

Podporované atributy

Následující části popisují některé atributy transformace rozhraní Java API.

typ argumentů

Tento atribut se umístí do metod setter pro pojmenování EventArg podtřídy, která se vygeneruje pro podporu posluchačů Java. Toto je podrobněji popsáno v části Přejmenování tříd obálky EventArg v této příručce.

název události

Určuje název události. Pokud je název prázdný, zabrání generování událostí. Toto je podrobněji popsáno v části Přejmenování tříd obálky EventArg.

spravovanýNázev

Slouží ke změně názvu balíčku, třídy, metody nebo parametru. Chcete-li například změnit název třídy MyClass Java na NewClassName:

<attr path="/api/package[@name='com.my.application']/class[@name='MyClass']" 
    name="managedName">NewClassName</attr>

Následující příklad znázorňuje výraz XPath pro přejmenování metody java.lang.object.toString na Java.Lang.Object.NewManagedName:

<attr path="/api/package[@name='java.lang']/class[@name='Object']/method[@name='toString']" 
    name="managedName">NewMethodName</attr>

managedType

managedType slouží ke změně návratového typu metody. V některých situacích generátor vazeb nesprávně odvodí návratový typ metody Java, což způsobí chybu v době kompilace. Jedním z možných řešení v této situaci je změnit návratový typ metody.

Například věří Bindings Generator, že Java metoda de.neom.neoreadersdk.resolution.compareTo() by měla vrátit int a vzít Object jako parametry, což má za následek chybovou zprávu Chyba CS0535: 'DE.Neom.Neoreadersdk.Resolution' nenaplňuje člena rozhraní 'Java.Lang.IComparable.CompareTo(Java.Lang.Object)'. Následující fragment kódu ukazuje, jak změnit typ prvního parametru vygenerované metody jazyka C# z metody na DE.Neom.Neoreadersdk.ResolutionJava.Lang.Object:

<attr path="/api/package[@name='de.neom.neoreadersdk']/
    class[@name='Resolution']/
    method[@name='compareTo' and count(parameter)=1 and
    parameter[1][@type='de.neom.neoreadersdk.Resolution']]/
    parameter[1]" name="managedType">Java.Lang.Object</attr>

managedReturn

Změní návratový typ metody. Tím se nezmění návratový atribut (protože změny návratových atributů můžou vést k nekompatibilním změnám podpisu JNI). V následujícím příkladu se návratový append typ metody změní z SpannableStringBuilder na IAppendable:

<attr path="/api/package[@name='android.text']/
    class[@name='SpannableStringBuilder']/
    method[@name='append']" 
    name="managedReturn">Java.Lang.IAppendable</attr>

Zakódovány

Nástroje, které zatemňují knihovny Java, mohou kolidovat s .NET for Android Binding Generatorem a jeho schopností generovat obálkové třídy v jazyce C#. Charakteristiky obfuskovaných tříd zahrnují:

Název třídy obsahuje , $tj. a$.class.
Název třídy je zcela složen z malých písmen, tj. a.class.

Tento fragment kódu je příkladem toho, jak vygenerovat typ C# bez obfuskování:

<attr path="/api/package[@name='{package_name}']/class[@name='{name}']" 
    name="obfuscated">false</attr>

propertyName

Tento atribut lze použít ke změně názvu spravované vlastnosti.

Specializovaný případ použití propertyName zahrnuje situaci, kdy třída Java má pouze metodu setter pro pole. V takovém případě by generátor vazeb chtěl vytvořit vlastnost jen pro zápis, což je něco, co se nedoporučuje v .NET. Následující fragment kódu ukazuje, jak "odebrat" vlastnosti .NET nastavením propertyName na prázdný řetězec:

<attr path="/api/package[@name='org.java_websocket.handshake']/class[@name='HandshakeImpl1Client']/method[@name='setResourceDescriptor' 
    and count(parameter)=1 
    and parameter[1][@type='java.lang.String']]" 
    name="propertyName"></attr>
<attr path="/api/package[@name='org.java_websocket.handshake']/class[@name='HandshakeImpl1Client']/method[@name='getResourceDescriptor' 
    and count(parameter)=0]" 
    name="propertyName"></attr>

Všimněte si, že metody setter a getter budou stále vytvořeny pomocí Bindings Generator, pouze nebudou převedeny na vlastnost .NET.

odesílatel

Určuje, který parametr metody má být sender parametrem při mapování metody na událost. Hodnota může být true nebo false. Například:

<attr path="/api/package[@name='android.app']/
    interface[@name='TimePickerDialog.OnTimeSetListener']/
    method[@name='onTimeSet']/
    parameter[@name='view']" 
    name="sender">true</ attr>

viditelnost

Tento atribut se používá ke změně viditelnosti třídy, metody nebo vlastnosti. Například může být nutné zvýšit úroveň protected metody Java tak, aby odpovídající obálka jazyka C# byla public:

<!-- Change the visibility of a class -->
<attr path="/api/package[@name='namespace']/class[@name='ClassName']" name="visibility">public</attr>

<!-- Change the visibility of a method --> 
<attr path="/api/package[@name='namespace']/class[@name='ClassName']/method[@name='MethodName']" name="visibility">public</attr>

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-02