com.sun.java.browser.plugin2.liveconnect.v1
Interface ConversionDelegate

public interface ConversionDelegate

Converts values between types, and provides a measure of the cost of performing such conversion.

Incoming values from the JavaScript engine in the web browser usually require conversion to be able to pass them to Java objects, or to objects of non-Java languages hosted on the JVM. The reason is that the JavaScript language is untyped, and different JavaScript engines represent entities like numeric values differently.

When handling an incoming method call, field access, etc. from JavaScript via the InvocationDelegate interface, the Bridge represents incoming values according to the following rules:

• Numeric values from the JavaScript engine are boxed in the analogous Java boxing types: Integer, Double, etc. (Different JavaScript engines represent numeric values differently, so implementations should be robust with regard to the precise boxing class used in various situations.)
• JavaScript strings are converted to Java Strings.
• JavaScript objects and arrays are mirrored as instances of netscape.javascript.JSObject.
• Java and non-Java objects of other types which were previously returned to the JavaScript engine are passed through unchanged.

The InvocationDelegate will typically call Bridge.convert to coerce values to certain types in preparation for invoking a method or setting a field; for example, to perform narrowing conversions on primitive types. The Bridge delegates this work to the registered ConversionDelegates.

A ConversionDelegate may choose to compute a cost for a particular conversion and/or perform the conversion, or pass this work on to the next delegate in the chain. A default ConversionDelegate is registered and is called last if no other delegate handles the operation. The default delegate represents types with java.lang.Class instances, and implements the following conversions:

• Conversions among all primitive types, including narrowing conversions and conversions to boolean
• Conversion of any value to java.lang.String
• Conversion of java.lang.String to a numeric value or boolean; an empty String corresponds to the value false
• Conversion of JavaScript arrays to Java arrays, including multi-dimensional arrays

To assist in overloaded method resolution, this package assigns costs to conversions. (It is unclear whether this scheme will stand the test of time, which is why "v1" (version 1) is included in the package name.) ConversionDelegate implementations should try to assign costs to conversions in a way that minimizes the probability that two methods with the same number of arguments, but materially different signatures, will report an ambiguity for a certain argument list when it is obvious which method should be invoked.

To avoid creating overdependencies, the exact algorithm and values currently used by the default ConversionDelegate are left unspecified. However, as a hint to other implementors, it uses the following set of rules when computing costs:

• The following conversions have the lowest cost:
  • Null to any non-primitive type
  • JSObject to JSObject
  • Class type to Class type where the types are equal
• The following conversions report higher cost:
  • Numeric type to a different primitive type
  • String to numeric type
  • Class type to superclass type; this assists in overload resolution where one method takes a subclass as argument and another method takes a superclass as argument, and an instance of the subclass is passed in. The default delegate computes a measure of the "distance" in the class hierarchy between a value and the desired type.
• The following conversion reports still higher cost:
  • Any Java value to String
• The following conversions report even higher cost:
  • JSObject to String
  • JSObject to Java array
• The following are reported as not convertible (negative conversion cost):
  • Any value to a non-Class type
  • Null to primitive type
  • JSObject to any type not described above
  • Any other conversion not described above

Method Summary

int	conversionCost(Object object, Object toType) Computes the cost of converting the given object to the given type.
boolean	convert(Object object, Object toType, Object[] result) Converts the given object to the given type.

Method Detail

conversionCost

int conversionCost(Object object,
                   Object toType)

Computes the cost of converting the given object to the given type. Both are represented as opaque entities (java.lang.Object) since different delegates may represent classes and objects in different ways. A zero or positive value indicates this delegate can convert the value to the type. Lower numbers represent better matches. A negative return value indicates this delegate can not perform the conversion.

Parameters:

object - the object to convert

toType - the type to which to convert the object

Returns:

the cost of converting the given object to the type, or a negative value if this delegate can not convert the object to the given type

convert

boolean convert(Object object,
                Object toType,
                Object[] result)
                throws Exception

Converts the given object to the given type. This should produce a valid result if conversionCost returns a nonnegative value, although this may not be possible in all cases; for example, during conversion of a JavaScript array to a Java primitive array when the JS array contains an inconvertible value. Should return true if this delegate handles the conversion; false if it wants to pass through to the next delegate; and should throw an exception if it both handles the conversion and the conversion is illegal.

Parameters:

object - the object to convert

toType - the type to which to convert the object

result - 1-length array into which to store the result of the conversion, or the original object if it does not require conversion

Returns:

true if this ConversionDelegate handled the conversion, false if it should be passed to the next delegate

Throws:

Exception - if an exception occurred during conversion