[mono-android] java binding library

[Jonathan Pryor]

On Jun 21, 2012, at 2:19 PM, Wally McClure wrote:
> I decided to go back to the drawing board and create some simple .jar files that I could transform and then be less of a hassle.  I have a method called: multiplefloat which takes two floats and multiplies them together and returns a float.  I'd like to rename that method to MultipleFloat in the .NET side because I am a bad java programmer.  I've tried the following transforms in the Metadata.xml file with no luck.  Any suggestions?
>  
> <metadata>
> <attr path="/api/package[@name='com.scalabledevelopment.math.operations.multiplyfloat']"name="managedName">Com.Scalabledevelopment.Math.Operations.MultiplyFloat</attr>
> <attr
> path="/api/package[@name='com.scalabledevelopment.math.operations']/class[@name='multiplyfloat']"name="managedName">Com.Scalabledevelopment.Math.Operations.MultiplyFloat</attr>
> </metadata>

Looks like a job for...clearer docs. Now if I only knew how to clarify the docs...

First up is that the metadata path is intimately tied to the input file, which is obj/Debug/api.xml. You generally need to have api.xml open while writing Metadata.xml.

Secondly is the structure of api.xml:

	<api>
		<package name="PACKAGE-NAME">
			<class name="CLASS-NAME" ...>
				<method name="METHOD-NAME" ...>
				</method>
			</class>
		</package>
	</api>

For example, consider java.lang.Object.toString():

	http://developer.android.com/reference/java/lang/Object.html#toString()

PACKAGE-NAME will be "java.lang", CLASS-NAME will be "Object", and METHOD-NAME will be "toString".

Now suppose we wanted to rename the toString() method. How would we select it? The XPath to reach the <method/> element is /api/package[@name='java.lang']/class[@name='Object']/method[@name='toString'], so that's what we need to use:

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

Note that ANY XPath is valid; we could have instead done:

	<attr
		path="//method[@name='toString']"
		name="managedName"
	>NewMethodName</attr>

This has the benefit that it would rename ALL toString() methods. This has the disadvantage that it's _slow_, at least when processing gigantic APIs like android.jar. ;-) (This is why all of our samples use fully qualified XPath expressions, because trying to use XPath abbreviations results in more twiddling of fingers.)

Next, what value can we use for managedName? It needs to be a valid C# token for a method name. "NewMethodName" works; "Some.Dotted.Name" will not work, because the resulting C# code will be invalid, akin to:

	public string Some.Dotted.Name () {/* ... */}

With that background out of the way, let's look at your description:

> I have a method called: multiplefloat which takes two floats and multiplies them together and returns a float

So "multiplefloat" is a method.

However, when we look at your path expression:

	<attr
		path="/api/package[@name='com.scalabledevelopment.math.operations.multiplyfloat']"
		name="managedName"
	>Com.Scalabledevelopment.Math.Operations.MultiplyFloat</attr>

The problem is that what you wrote doesn't match what you wrote; you said you have a method, yet your XPath expression will be selecting a package element, not a method. In all likelihood, the above XPath expression doesn't match anything, which should generate a warning that the expression matched no elements.

I would guess that what you actually want is:

	<attr
		path="/api/package[@name='com.scalabledevelopment.math']/class[@name='operations']/method[@name='multiplyfloat']"
		name="managedName"
	>MultiplyFloat</attr>

Note that we separately specify the package name, class name, and method name, as is required in order for XPath to actually match the desired api.xml element. Further note that we're using a valid C# method name of "MultiplyFloat".

 - Jon