W3C

Java language binding for Web IDL

W3C Working Group Note 14 May 2013

This Version:
http://www.w3.org/TR/2013/NOTE-WebIDL-Java-20130514/
Current Editor’s Draft:
http://dev.w3.org/2006/webapi/WebIDL/java.html
Latest Version:
http://www.w3.org/TR/WebIDL-Java/
Previous Version:
http://www.w3.org/TR/2012/WD-WebIDL-Java-20120207/
Editor:
Cameron McCormack, Mozilla Corporation <cam@mcc.id.au>

Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document defines the Java language binding for Web IDL, the interface definition language for the Web platform.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Please send comments about this document to public-script-coord@w3.org (archived).

This document originally existed as a section in the Web IDL specification. [WEBIDL] It was split out into this Working Group Note due to the prospect of it impeding the progress of Web IDL due to having insufficient implementations and because of a general lack of interest in the Java binding.

This document is produced by the Web Applications Working Group, part of the Rich Web Clients Activity in the W3C Interaction Domain. Changes made to this document can be found in the W3C public CVS server.

Note: The Working Group reached consensus to stop work on this specification. It is being published for archival reasons and is no longer being progressed along the W3C's Recommendation Track.

Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is informative.

This document defines a Web IDL language binding for Java 5. [WEBIDL] [JLS3]

1.1. Typographic conventions

The following typographic conventions are used in this document:

  • Defining instances of terms: example term
  • Links to terms defined in this document: example term
  • Links to terms defined in other documents: example term
  • IDL and Java types: ExampleType
  • Code snippets: a = b + obj.f()
  • Unicode characters: U+0030 DIGIT ZERO ("0")
  • Extended attributes: [ExampleExtendedAttribute]
  • Variable names in prose and algorithms: exampleVariableName.
  • Non-normative notes:
    Note

    This is a note.

  • Non-normative examples:
    Example

    This is an example.

  • Code blocks:
    IDL
    // This is an IDL code block.
interface Example {
  attribute long something;
};
    Java
    // This is a Java code block.
Document doc = element.getOwnerDocument();

2. Conformance

Everything in this specification is normative except for diagrams, examples, notes and sections marked as being informative.

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119].

The following conformance class is defined by this specification:

conforming Java implementation

A user agent is considered to be a conforming Java implementation relative to a conforming IDL fragment if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementations for the Java language binding.

3. Java binding

This section describes how definitions written with Web IDL [WEBIDL] correspond to particular constructs in Java 5 [JLS3].

3.1. Names

Since Java has a number of reserved words in the language, some identifiers of Java constructs corresponding to IDL definitions need to be escaped to avoid conflicts. A name is Java escaped as follows:

  • If the name is a Java reserved word, then the Java escaped name is the name prefixed with a U+005F LOW LINE ("_") character.
  • Otherwise, the name is not a Java reserved word. The Java escaped name is simply the name.
Note

At the time of publication, the list of Java reserved words is the following: abstract, assert, boolean, break, byte, case, catch, char, class, const, continue, default, do, double, else, enum, extends, final, finally, float, for, goto, if, implements, import, instanceof, int, interface, long, native, new, package, private, protected, public, return, short, static, strictfp, super, switch, synchronized, this, throw, throws, transient, try, void, volatile, while.

3.2. Java type mapping

This section describes how types in the IDL map to types in Java.

Each sub-section below describes how values of a given IDL type are represented in Java. For each IDL type, it is described how Java values are converted to an IDL value when passed as an argument to a Java method (corresponding to an operation or attribute). Conversely, it is described how IDL values of that type are converted to Java values when being used as the value of a Java final variable (corresponding to a constant) or when returned from a Java method (corresponding to an operation, attribute or exception field).

3.2.1. any

The any IDL type corresponds to a Java java.lang.Object value.

How to convert a Java value to an IDL any value depends on the type of the Java value:

A java.lang.Boolean object
The IDL value is obtained by converting the result of calling the booleanValue() method on the java.lang.Boolean object to an IDL boolean value.
A java.lang.Byte object
The IDL value is obtained by converting the result of calling the byteValue() method on the java.lang.Byte object to an IDL byte value.
A java.lang.Short object
The IDL value is obtained by converting the result of calling the shortValue() method on the java.lang.Short object to an IDL short value.
A java.lang.Integer object
The IDL value is obtained by converting the result of calling the intValue() method on the java.lang.Integer object to an IDL long value.
A java.lang.Long object
The IDL value is obtained by converting the result of calling the longValue() method on the java.lang.Long object to an IDL long long value.
A java.lang.Float object
The IDL value is obtained by converting the result of calling the floatValue() method on the java.lang.Float object to an IDL float value.
A java.lang.Double object
The IDL value is obtained by converting the result of calling the doubleValue() method on the java.lang.Double object to an IDL double value.
A java.lang.String object
The IDL value is obtained by converting the java.lang.String object to an IDL DOMString value.
An array object
The IDL value is the IDL sequence obtained by converting the Java array object to a sequence, as described in section 3.2.23 below.
An object that implements a Java array interface
The IDL value is the IDL array obtained by converting the Java object to an array, as described in section 3.2.24 below.
An object of any other class
The IDL value is an object value that references the same object.
null
The IDL value is the null object? value.

How to convert an IDL any value to a Java java.lang.Object value depends on the specific type of the IDL value:

A value of a primitive type

The Java value is the result of converting the IDL value of the given type to a Java value, and then passing that value to the static method according to the following table:

IDL type Method
boolean java.lang.Boolean.valueOf(boolean)
byte java.lang.Byte.valueOf(byte)
octet java.lang.Byte.valueOf(byte)
short java.lang.Short.valueOf(short)
unsigned short java.lang.Short.valueOf(short)
long java.lang.Integer.valueOf(int)
unsigned long java.lang.Integer.valueOf(int)
long long java.lang.Long.valueOf(long)
unsigned long long java.lang.Long.valueOf(long)
float java.lang.Float.valueOf(float)
unrestricted float java.lang.Float.valueOf(float)
double java.lang.Double.valueOf(double)
unrestricted double java.lang.Double.valueOf(double)
An IDL value of any other type
To obtain a Java value, the rules for converting the specific type of the IDL any value as described in the remainder of this section are performed.

3.2.2. void

The only place that the void type may appear in IDL is as the return type of an operation. Methods on Java objects that implement an operation whose IDL specifies a void return type MUST be declared to have a return type of void.

3.2.3. boolean

IDL boolean values are represented by Java boolean values.

The result of converting a Java boolean value to an IDL value is the IDL boolean that represents the same truth value as the Java boolean.

The result of converting an IDL boolean value to a Java value is the Java boolean that represents the same truth value as the IDL boolean.

3.2.4. byte

IDL byte values are represented by Java byte values.

The result of converting a Java byte value to an IDL value is the IDL byte that represents the same numeric value as the Java byte.

The result of converting an IDL byte value to a Java value is the Java byte that represents the same numeric value as the IDL byte.

3.2.5. octet

IDL octet values are represented by Java byte values. Note that while the IDL octet type is unsigned, with a range of [0, 255], the Java byte type is signed, with a range of [−128, 127].

Conversion of an octet value to a byte is performed as follows:

  1. Let x be the octet value to convert.
  2. If x < 128, return the byte whose value is x.
  3. Otherwise x ≥ 128. Return the byte whose value is x − 256.
Note

In Java this is the same as having the octet value stored in an int and casting it to a byte.

Conversion of a byte to an octet is performed as follows:

  1. Let x be the byte value to decode.
  2. If x ≥ 0, return the octet whose value is x.
  3. Otherwise x < 0. Return the octet whose value is x + 256.
Note

In Java this is the same as performing a bit-wise AND of the byte value with the int constant 0xff.

3.2.6. short

IDL short values are represented by Java short values.

The result of converting a Java short value to an IDL value is the IDL short that represents the same numeric value as the Java short.

The result of converting an IDL short value to a Java value is the Java short that represents the same numeric value as the IDL short.

3.2.7. unsigned short

IDL unsigned short values are represented by Java short values. Note that while the IDL unsigned short type is unsigned, with a range of [0, 65535], the Java short type is signed, with a range of [−32768, 32767].

Conversion of an IDL unsigned short value to a Java short is performed as follows:

  1. Let x be the IDL unsigned short value to convert.
  2. If x < 32768, return the Java short whose value is x.
  3. Otherwise x ≥ 32768. Return the Java short whose value is x − 65536.
Note

In Java this is the same as having the unsigned short value stored in an int and casting it to a short.

Conversion of a Java short to an IDL unsigned short value is performed as follows:

  1. Let x be the Java short value to decode.
  2. If x ≥ 0, return the IDL unsigned short whose value is x.
  3. Otherwise x < 0. Return the IDL unsigned short whose value is x + 65536.
Note

In Java this is the same as performing a bit-wise AND of the short value with the int constant 0xffff.

3.2.8. long

IDL long values are represented by Java int values.

The result of converting a Java int value to an IDL value is the IDL long that represents the same numeric value as the Java int.

The result of converting an IDL long value to a Java value is the Java int that represents the same numeric value as the IDL short.

3.2.9. unsigned long

IDL unsigned long values are represented by Java int values. Note that while the IDL unsigned long type is unsigned, with a range of [0, 4294967295], the Java int type is signed, with a range of [−2147483648, 2147483647].

Conversion of an IDL unsigned long value to a Java int is performed as follows:

  1. Let x be the IDL unsigned long value to convert.
  2. If x < 2147483648, return the Java int whose value is x.
  3. Otherwise x ≥ 2147483648. Return the Java int whose value is x − 4294967296.
Note

In Java this is the same as having the unsigned long value stored in a Java long and casting it to an int.

Conversion of a Java int to an IDL unsigned long value is performed as follows:

  1. Let x be the Java int value to decode.
  2. If x ≥ 0, return the IDL unsigned long whose value is x.
  3. Otherwise x < 0. Return the IDL unsigned long whose value is x + 4294967296.
Note

In Java this is the same as performing a bit-wise AND of the int value with the long constant 0xffffffffL.

3.2.10. long long

IDL long long values are represented by Java long values.

The result of converting a Java long value to an IDL value is the IDL long long that represents the same numeric value as the Java long.

The result of converting an IDL long long value to a Java value is the Java long that represents the same numeric value as the IDL long long.

3.2.11. unsigned long long

IDL unsigned long long values are represented by Java long values. Note that while the IDL unsigned long long type is unsigned, with a range of [0, 18446744073709551615], the Java long type is signed, with a range of [−9223372036854775808, 9223372036854775807].

Conversion of an IDL unsigned long long value to a Java long is performed as follows:

  1. Let x be the IDL unsigned long long value to convert.
  2. If x < 18446744073709551616, return the Java long whose value is x.
  3. Otherwise x ≥ 18446744073709551616. Return the Java long whose value is x − 18446744073709551615.

Conversion of a Java long to an IDL unsigned long long value is performed as follows:

  1. Let x be the Java long value to decode.
  2. If x ≥ 0, return the IDL unsigned long long whose value is x.
  3. Otherwise x < 0. Return the IDL unsigned long long whose value is x + 18446744073709551615.

3.2.12. float

IDL float values are represented by Java float values.

A Java float value V is converted to an IDL float value as follows:

  1. If V is non-finite, then throw a java.lang.IllegalArgumentException.
  2. Otherwise, the IDL float value is the one that represents the same IEEE 754 single precision floating point value as V.

The result of converting an IDL float value to a Java value is the Java float that represents the same IEEE 754 single precision floating point value as the IDL float.

3.2.13. unrestricted float

IDL unrestricted float values are represented by Java float values.

The result of converting a Java float value to an IDL unrestricted float value is the one that represents the same IEEE 754 single precision floating point value as the Java float.

The result of converting an IDL unrestricted float value to a Java value is the Java float that represents the same IEEE 754 single precision floating point value as the IDL unrestricted float.

3.2.14. double

IDL double values are represented by Java double values.

A Java double value V is converted to an IDL double value as follows:

  1. If V is non-finite, then throw a java.lang.IllegalArgumentException.
  2. Otherwise, the IDL double value is the one that represents the same IEEE 754 double precision floating point value as V.

The result of converting an IDL double value to a Java value is the Java double that represents the same IEEE 754 double precision floating point value as the IDL double.

3.2.15. unrestricted double

IDL unrestricted double values are represented by Java double values.

The result of converting a Java double value to an IDL unrestricted double value is the one that represents the same IEEE 754 double precision floating point value as the Java double.

The result of converting an IDL unrestricted double value to a Java value is the Java double that represents the same IEEE 754 double precision floating point value as the IDL unrestricted double.

3.2.16. DOMString

IDL DOMString values are represented by Java java.lang.String reference values.

A Java java.lang.String reference value is converted to an IDL DOMString value as follows:

  • If the value is null, then throw a java.lang.NullPointerException.
  • Otherwise, return the IDL DOMString value that represents the same sequence of code units as the one the Java java.lang.String value represents.

The result of converting an IDL DOMString value to a Java java.lang.String value is a java.lang.String object that represents the same sequence of characters that the IDL DOMString represents.

3.2.17. object

IDL object values are represented by Java java.lang.Object reference values.

A Java java.lang.Object reference value is converted to an IDL object value as follows:

  • If the value is null, then throw a java.lang.NullPointerException.
  • Otherwise, return the IDL object value that is a reference to the same object.

The result of converting an IDL object value to a Java value is a Java java.lang.Object value that is a reference to the same object.

3.2.18. Interface types

IDL interface type values are represented by Java references of the corresponding Java interface type. (See section 3.4 below for how IDL interfaces have corresponding Java interfaces.)

A Java value V is converted to an IDL interface type value by running the following algorithm (where I is the interface):

  1. If V is a platform object that implements I, then return the IDL interface type value that represents a reference to that platform object.
  2. Otherwise, throw a java.lang.IllegalArgumentException.

Conversions from IDL interface type values to Java values are performed in the same way as that for the IDL object type.

3.2.19. Dictionary types

IDL dictionary type values are represented by Java references to objects of the java.util.HashMap<java.lang.String,java.lang.Object> class. Each dictionary member that is present corresponds to an entry in the HashMap.

A Java java.util.HashMap<java.lang.String,java.lang.Object> reference value O is converted to an IDL dictionary type value by running the following algorithm (where D is the dictionary):

  1. If O is null, then throw a java.lang.NullPointerException.
  2. Let dict be an empty dictionary value of type D; every dictionary member is initially considered to be not present.
  3. Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, in order from least to most derived.
  4. For each dictionary dictionary in dictionaries, in order:
    1. For each dictionary member member declared on dictionary, in order:
      1. Let key be the identifier of member.
      2. Let javaKey be the result of converting key to a java.lang.String.
      3. Let present be the result of calling the containsKey method on O with javaKey as the only argument.
      4. If present is true, then:
        1. Let value be the result of calling the get method on O javaKey as the only argument.
        2. Let idlValue be the result of converting value to an IDL value whose type is the type member is declared to be of.
        3. Set the dictionary member on dict with key name key to the value idlValue. This dictionary member is considered to be present.
  5. Return dict.

An IDL dictionary type value V is converted to a Java java.util.HashMap<java.lang.String,java.lang.Object> reference value by running the following algorithm (where D is the dictionary):

  1. Let O be a new java.util.HashMap<java.lang.String,java.lang.Object> object.
  2. Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, in order from least to most derived.
  3. For each dictionary dictionary in dictionaries, in order:
    1. For each dictionary member member declared on dictionaries, in order:
      1. Let key be the identifier of member.
      2. Let javaKey be the result of converting key to a java.lang.String.
      3. If the dictionary member named key is present on V, then:
        1. Let idlValue be the value of member on V.
        2. Let value be the result of converting idlValue to a Java value as if value were an IDL any value.
        3. Call the put method on O with arguments javaKey and value.
  4. Return O.

3.2.20. Enumeration types

IDL enumeration type values are represented by Java java.lang.String reference values.

A Java java.lang.String reference value is converted to an IDL enumeration type value as follows (where E is the enumeration):

  • If the value is null, then throw a java.lang.NullPointerException.
  • If the java.lang.String object does not represent the same string as any of the enumeration’s values, then throw a java.lang.IllegalArgumentException.
  • Return the enumeration value of type E that is equal to the string the java.lang.String object represents.

The result of converting an IDL enumeration type value to a Java java.lang.String value is a java.lang.String object that represents the same sequence of code units as the enumeration value.

3.2.21. Callback function types

IDL callback function type values are represented by Java references of the corresponding Java interface type. (See section 3.5 below for how IDL callback functions have corresponding Java interfaces.)

A Java value V is converted to an IDL callback function type value by running the following algorithm (where C is the callback function):

  1. If V is an object that implements the Java interface for C, then return the IDL callback function type value that represents a reference to that object.
  2. Otherwise, throw a java.lang.IllegalArgumentException.

Conversions from IDL callback function type values to Java values are performed in the same way as that for the IDL object type.

3.2.22. Nullable types — T?

IDL nullable type values are represented with Java object references of a particular class, as determined by the table below:

Nullable type Java class Method to get value
boolean? java.lang.Boolean booleanValue()
byte? java.lang.Byte byteValue()
octet? java.lang.Byte byteValue()
short? java.lang.Short shortValue()
unsigned short? java.lang.Short shortValue()
long? java.lang.Integer intValue()
unsigned long? java.lang.Integer intValue()
long long? java.lang.Long longValue()
unsigned long long? java.lang.Long longValue()
float? java.lang.Float floatValue()
unrestricted float? java.lang.Float floatValue()
double? java.lang.Double doubleValue()
unrestricted double? java.lang.Double doubleValue()
DOMString? java.lang.String –
Enumeration type T? java.lang.String –
Interface type T? The Java interface corresponding to IDL type T –
Dictionary type T? java.util.HashMap<java.lang.String,java.lang.Object> –
sequence<T>? U[], where U is the Java type used to represent the IDL type T –
T[]? The Java array interface for IDL type T –
Union type T? java.lang.Object –

How to convert a Java value of one of the above classes to an IDL nullable type T? depends on the object reference value and the type T:

If the object reference value is null
The IDL value is the null T? value.
If the value is not an object of the right type for T according to the table above
Throw a java.lang.IllegalArgumentException.
If T is a primitive type
Let method be the method indicated in the table above for type T. The IDL value is a T? whose value is obtained by converting the result of calling method on the object to type T.
Anything else
The IDL value is a T? whose value is obtained by converting the object reference value to type T.

How to convert an IDL nullable type value to a Java value depends on its value and the inner type:

If the IDL value is null
The Java value is null.
If the IDL value is a non-null nullable primitive value

The Java value is the result of converting the IDL inner type to a Java value, and then passing that value to the static method according to the following table, where T is the IDL inner type:

T Method
boolean java.lang.Boolean.valueOf(boolean)
byte java.lang.Byte.valueOf(byte)
octet java.lang.Byte.valueOf(byte)
short java.lang.Short.valueOf(short)
unsigned short java.lang.Short.valueOf(short)
long java.lang.Integer.valueOf(int)
unsigned long java.lang.Integer.valueOf(int)
long long java.lang.Long.valueOf(long)
unsigned long long java.lang.Long.valueOf(long)
float java.lang.Float.valueOf(float)
unrestricted float java.lang.Float.valueOf(float)
double java.lang.Double.valueOf(double)
unrestricted double java.lang.Double.valueOf(double)
If the IDL value is a non-null DOMString? value
The Java value is a java.lang.String object representing the same sequence of code units as the DOMString? value.
If the IDL value is a non-null nullable enumeration value
The Java value is a java.lang.String object representing the same sequence of code units as the enumeration value.
If the IDL value is a non-null sequence<T>? value
The Java value is the result of converting the IDL sequence value to a Java array object, as described in section 3.2.23 below.
If the IDL value is a non-null T[]? value
The Java value is the result of converting the IDL array value to a Java object implementing the Java array interface for T, as described in section 3.2.24 below.
If the IDL value is a non-null nullable dictionary type value
The Java value is the result of converting the IDL dictionary value to a Java java.util.HashMap<java.lang.String,java.lang.Object> object, as described in section 3.2.19 above.
If the IDL value is a non-null nullable interface type or object? value
The Java value is a reference to the same object.
If the IDL value is a non-null nullable union type value
The Java value is the result of converting the IDL union type value to a Java java.lang.Object reference, as described in section 3.2.25 below.

3.2.23. Sequences — sequence<T>

IDL sequence<T> values are represented by Java arrays of type U, where U is the Java type used to represent the IDL type T.

A Java array A of type U is converted to an IDL sequence<T> as follows:

  1. If A is null, then throw a java.lang.NullPointerException.
  2. Let n be the length of the array A.
  3. Initialize S0..n−1 to be an IDL sequence with elements of type T, where each element is uninitialized.
  4. Initialize i to be 0.
  5. While i < n:
    1. Let E be the value value of A at index i.
    2. Set Si to the result of converting E to an IDL value of type T.
    3. Set i to i + 1.
  6. Return S.

An IDL sequence value S0..n−1 of type sequence<T> is converted to a Java array of type U object as follows:

  1. Let A be a new Java array object with element type U and length n.
  2. Initialize i to be 0.
  3. While i < n:
    1. Let E be the result of converting Si to a Java value of type U.
    2. Set element i of the array A to the value E.
    3. Set i to i + 1.
  4. Return A.

A Java object implementing an interface with an operation declared to return a sequence<T> value MUST NOT return null from the corresponding method. Similarly, a getter method for an IDL attribute MUST NOT return null if the attribute is declared to be of type sequence<T>.

3.2.24. Arrays — T[]

IDL T[] values are represented by Java objects implementing a particular interface, known as the Java array interface, depending on the type T.

For each of the primitive types there MUST exist a corresponding Java array interface of the following form:

Java
package org.w3c.dom;

public interface PrimitiveNameArray {
  int getLength();
  void setLength(int length);
  PrimitiveType getElement(int index);
  void setElement(int index, PrimitiveType value);
}

where PrimitiveName is the type name of the primitive type and PrimitiveType is the Java type used to represent it.

Example

For example, the Java array interface for the octet[] type is:

Java
package org.w3c.dom;

public interface OctetArray {
  int getLength();
  void setLength(int length);
  byte getElement(int index);
  void setElement(int index, byte value);
}

There MUST also exist the following interface, org.w3c.dom.ObjectArray<E>:

Java
package org.w3c.dom;

public interface ObjectArray<E> {
  int getLength();
  void setLength(int length);
  E getElement(int index);
  void setElement(int index, E value);
}

This interface, parameterized by the Java type used to represent array element type T, is the corresponding Java array interface for T.

Example

For example, the Java array interface for the DOMString[]?[] type is org.w3c.dom.ObjectArray<java.lang.ObjectArray<java.lang.String>>.

A Java object that implements a Java array interface represents a given IDL array value of type T[]. The methods on the object that implement that interface MUST behave as follows:

getLength()

This method returns the current length of the IDL array value.

setLength(length)

When called on an object representing a variable length array, this method sets the length of the array to length. When the array is lengthened, the new elements are set to the IDL value that results from converting to an IDL value the default value of the Java type that T corresponds to ([JLS3], section 4.12.5).

When called on an object representing a fixed length array, this method throws a java.lang.UnsupportedOperationException.

getElement(index)

This method returns the IDL value of type T at the represented array’s index index converted to a Java value.

setElement(index, value)

When called on an object representing an array that is not read only, this method sets the IDL value at the represented array’s index index to the result of converting value to an IDL value of type T.

When called on an object representing an array that is read only, this method throws a java.lang.UnsupportedOperationException.

A Java reference value O for an object implementing a Java array interface is converted to an IDL array value as follows:

  • If O is null, then throw a java.lang.NullPointerException.
  • Otherwise, if O is an object implementing a Java array interface corresponding to a primitive type, then the IDL array value is the array value that O represents. The type of the IDL array value is T[], where T is the primitive type.
  • Otherwise, if O is an object implementing org.w3c.dom.ObjectArray<E>, then the IDL array value is the array value that O represents. The type of the IDL array value is the IDL type that E corresponds to.

An IDL array value A of type T[] is converted to a Java value whose type is an object implementing the Java array interface corresponding to T, as follows:

  • If A is already represented by an object implementing a Java array interface, then the Java value is that object.
  • Otherwise, the Java value is newly created object implementing the Java array interface that corresponds to T.

3.2.25. Union types

IDL union type values are represented by Java java.lang.Object reference values.

To convert a Java value V to an IDL union type value is done as follows:

  1. If the union type includes a nullable type and V is null object reference, then return the IDL value null.
  2. Let types be the flattened member types of the union type.
  3. If V implements a Java array interface, then:
    1. If types includes an array type, then return the result of converting V to that type.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  4. If V is an array object, then:
    1. If types includes an sequence type, then return the result of converting V to that type.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  5. If V is any other platform object, then:
    1. If types includes an interface type that V implements, then return the IDL value that is a reference to the object V.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  6. If V is a java.util.Date object, then:
    1. If types includes Date, then return the result of converting V to Date.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  7. If V is a java.lang.Boolean object, then:
    1. If types includes boolean, then return the result of converting the result of calling the booleanValue() method on V to boolean.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  8. If V is a java.lang.Byte object, then:
    1. If types includes byte, then return the result of converting the result of calling the byteValue() method on V to byte.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  9. If V is a java.lang.Short object, then:
    1. If types includes short, then return the result of converting the result of calling the shortValue() method on V to short.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  10. If V is a java.lang.Integer object, then:
    1. If types includes long, then return the result of converting the result of calling the intValue() method on V to long.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  11. If V is a java.lang.Long object, then:
    1. If types includes long long, then return the result of converting the result of calling the longValue() method on V to long long.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  12. If V is a java.lang.Float object, then:
    1. If types includes float, then return the result of converting the result of calling the floatValue() method on V to float.
    2. If types includes unrestricted float, then return the result of converting the result of calling the floatValue() method on V to unrestricted float.
    3. If types includes object, then return the IDL value that is a reference to the object V.
  13. If V is a java.lang.Double object, then:
    1. If types includes double, then return the result of converting the result of calling the doubleValue() method on V to double.
    2. If types includes unrestricted double, then return the result of converting the result of calling the doubleValue() method on V to unrestricted double.
    3. If types includes object, then return the IDL value that is a reference to the object V.
  14. If V is a java.lang.String object, then:
    1. If types includes DOMString, then return the result of converting V to DOMString.
    2. If types includes object, then return the IDL value that is a reference to the object V.
  15. If V is any other type of object, then:
    1. If types includes a callback interface type, then return the result of converting V to that interface type.
    2. If types includes a dictionary type, then return the result of converting V to that dictionary type.
    3. If types includes object, then return the IDL value that is a reference to the object V.
  16. Throw an IllegalArgumentException.

An IDL union type is converted to a Java value by following the same rules as if the IDL type were any.

3.2.26. Date

IDL Date values are represented by Java java.util.Date reference values.

A Java java.lang.Date reference value is converted to an IDL Date value as follows:

  • If the value is null, then throw a java.lang.NullPointerException.
  • Let m be the millisecond that the java.util.Date object represents.
  • If m cannot be represented by an IDL Date value, then return the undefined IDL Date value.
  • Return the IDL Date value that represents m.

An IDL Date value is converted to a java.lang.Date reference value as follows:

  • If the value is the undefined IDL Date value, then return a newly created java.util.Date object as if by calling new java.util.Date(Long.MIN_VALUE).
  • Otherwise, return a newly created java.util.Date object that represents the same millisecond that the IDL Date value does.

3.3. Java-specific extended attributes

This section defines a single extended attribute whose presence affects only the Java binding.

3.3.1. [JavaPackage]

If the [JavaPackage] extended attribute appears on an interface or exception, it specifies that the corresponding Java interface or class MUST be placed in the package identified. When [JavaPackage] is not used, the Java interface or class MUST be placed in the org.w3c.dom package.

The [JavaPackage] extended attribute MUST take a dotted name, which is defined as the extended attribute matching ExtendedAttributeDottedName in the following grammar, which is to be interpreted in the same manner as the grammar in Web IDL ([WEBIDL], appendix A):

[1]ExtendedAttributeDottedName→identifier DottedNameParts
[2]DottedNameParts→"." identifier DottedNameParts
 | ε

The dotted name identifies the Java package in which the Java interface or class is to be placed.

Interfaces defined for the Web platform SHOULD NOT use [JavaPackage] unless required for compatibility.

Example

The following IDL fragment defines an IDL interface whose corresponding Java interface will not be in the org.w3c.dom package.

IDL
[JavaPackage=org.example]
interface Something {
};

3.4. Interfaces

For every supported IDL interface, there MUST exist a corresponding public Java interface whose name is the Java escaped identifier of the IDL interface.

The Java interface for an interface A MUST be declared to extend the following Java interfaces:

  • the Java interface that corresponds to the interface from which A inherits, if it does inherit from one, and
  • the Java interfaces that correspond to each interface on the right-hand side of an implements statement where A is on the left-hand side.

If the IDL interface has one or more static operations declared on it, then there MUST also exist a public, abstract Java class, which resides in the same Java package as the interface. This class is known as the utility class for the IDL interface, and provides access to the static operations. The name of the Java class is the concatenation of the identifier of the IDL interface and the string “Utils”. If this name is already the name of a Java class or interface, due to IDL definitions, then the name of the Java class is prefixed with a single U+005F LOW LINE ("_") character so as not to conflict.

3.4.1. Constants

For each constant defined on the IDL interface, there MUST be a corresponding constant declared on the Java interface with the following characteristics:

  • The constant has no modifiers.
  • The type of the constant is the Java type that corresponds to the type of the IDL constant, according to the rules in section 3.2 above.
  • The name of the constant is the Java escaped identifier of the constant.
  • The value of the constant is the result of converting the constant’s IDL value to a Java value, according to the rules in section 3.2 above.

3.4.2. Operations

The operations defined on an IDL interface will result in one or more methods being declared on the Java interface (for regular operations) or on a Java utility class (for static operations).

For each unique identifier id of the regular operations declared on the IDL interface:

  • For each pair <callable, type list> in the effective overload set for regular operations with identifier id on the IDL interface and with argument count 0, there MUST exist a method on the Java interface whose name, its Java method name, is determined as follows:
    1. Let identifier be the identifier of the operation callable.
    2. Initialize name to be identifier Java escaped.
    3. If name is the same as the name of one of the methods defined on java.lang.Object, then prepend a single U+005F LOW LINE ("_") character to name.
    4. The name of the method is name.

For each unique identifier id of the static operations declared on the IDL interface:

For each identifierless special operation declared on the IDL interface of the following types,

there MUST exist a method on the Java interface whose name is determined based on the type of special operation:

TypeName
indexed or named property getter“_get”
indexed or named property setter“_set”
indexed or named property creator“_create”
indexed or named property deleter“_delete”
caller“_call”

For all of the above operations – regular, static, and the abovementioned special operations – their corresponding Java methods have the following characteristics, based on the effective overload set entry <callable, type list>:

  • The return type of the method is the Java type that corresponds to the operation return type, according to the rules in section 3.2 above.
  • The method has an argument for each type, in order, that is in type list. The type of method argument j is the Java type that corresponds to the IDL type at index j in type list, according to the rules in section 3.2 above. If the length of type list is the length of the argument list callable is declared with, and callable is a variadic operation, then the method is a variable arity method ([JLS3], section 8.4.1).
  • An implementation of this method MUST perform the following steps:
    1. Let arg0..n−1 be the list of Java argument values passed to the method.
    2. Let idlarg0..n−1 be a list of IDL values, where idlargi is the result of converting argi to an IDL value of the type that the ith argument is declared to be.
    3. Let R be the result of performing the actions listed in the description of the operation callable with idlarg0..n−1 as the argument values.
    4. If the actions performed in the previous step resulted in an exception being thrown, then allow that exception to propagate out from this algorithm. Otherwise, return the result of converting R to a Java value of the type callable is declared to return.

3.4.3. Attributes

For each attribute defined on the IDL interface that does not inherit its getter, there MUST be a corresponding getter method declared on the Java interface with the following characteristics:

  • The method has no modifiers.
  • The return type of the method is the Java type that corresponds to the attribute type, according to the rules in section 3.2 above.
  • The name of the method is determined as follows:
    1. Let identifier be the identifier of the attribute.
    2. Initialize name to be the string “get”.
    3. Let ucIdentifier be identifier with first character uppercased, as if passed to the java.lang.Character.toUpperCase() method.
    4. If there exists another attribute on the interface with identifier ucIdentifier, then append a single U+005F LOW LINE ("_") character to name.
    5. Append ucIdentifier to name.
    6. If there exists a constant or operation on the interface with identifier name, or if name is the same as the name of one of the methods defined on java.lang.Object, then prepend a single U+005F LOW LINE ("_") character to name.
    7. The name of the method is name.
  • The method has no arguments.
  • An implementation of this method MUST perform the following steps:
    1. Let V be the IDL value that results from performing the actions listed for getting the corresponding attribute in the description of the interface.
    2. If the actions performed in the previous step resulted in an exception being thrown, then allow that exception to propagate out from this algorithm. Otherwise, return the result of converting V to a Java value of the type op is declared to return.

For each attribute defined on the IDL interface that is not read only, there MUST be a corresponding setter method declared on the Java interface with the following characteristics:

  • The method has no modifiers.
  • The return type of the method is void.
  • The name of the method is determined as follows:
    1. Let identifier be the identifier of the attribute.
    2. Initialize name to be the string “set”.
    3. Let ucIdentifier be identifier with first character uppercased, as if passed to the java.lang.Character.toUpperCase() method.
    4. If there exists another attribute on the interface with identifier ucIdentifier, then append a single U+005F LOW LINE ("_") character to name.
    5. Append ucIdentifier to name.
    6. If there exists a constant or operation on the interface with identifier name, or if name is the same as the name of one of the methods defined on java.lang.Object, then prepend a single U+005F LOW LINE ("_") character to name.
    7. The name of the method is name.
  • The method has a single argument whose type is the Java type that corresponds to the attribute type, according to the rules in section 3.2 above.
  • An implementation of this method MUST perform the following steps:
    1. Let arg be the Java value that was passed as the argument to the method.
    2. Let idlarg be the result of converting arg to an IDL value of the type the attribute is declared to be.
    3. Perform the actions for setting the corresponding attribute with the value idlarg listed in the description of the interface.
    4. If the actions performed in the previous step resulted in an exception being thrown, then allow that exception to propagate out from this algorithm.

3.5. Callback functions

For every supported IDL callback function, there MUST exist a corresponding public Java interface whose name is the Java escaped identifier of the callback function.

The Java interface for a callback function A MUST not be declared to inherit from any other Java interface.

For each pair <callback, types> in the effective overload set for callback function A with argument count 0, there MUST exist a method on the Java interface with the following characteristics:

  • The name of the method is call.
  • The return type of the method is the Java type that corresponds to the callback function return type, according to the rules in section 3.2 above.
  • The method has an argument for each type, in order, that is in types. The type of method argument j is the Java type that corresponds to the IDL type typesj, according to the rules in section 3.2 above. If the length of types is the length of the argument list the callback function is declared with, and the callback function is declared to be variadic, then the method is a variable arity method ([JLS3], section 8.4.1).

3.6. Platform objects implementing interfaces

A Java platform object that implements an IDL interface MUST be of a Java class which implements the Java interface that corresponds to the IDL interface.

If the IDL interface has a stringifier, the String toString() method MUST be overridden to allow stringification of the object as required by the IDL interface. If the stringifier keyword was used on an attribute A, then, assuming O is the object on which the method was invoked, the behavior of the overridden toString method MUST be as follows:

  1. Let R be the result of invoking the getter method on O that corresponds to the IDL attribute A.
  2. Return R.

Otherwise, if the stringifier keyword was used on an operation O with an identifier, then, assuming O is the object on which the method was invoked, the behavior of the overridden toString method MUST be as follows:

  1. Let R be the result of invoking the method on O that corresponds to the IDL operation O, passing no arguments.
  2. Return R.

Otherwise, if the stringifier keyword was used on an operation without an identifier, then the behavior of the overridden toString() method is the stringification behavior of the IDL interface, as described in the prose for the IDL interface.

3.7. User objects implementing callback interfaces

A Java user object that implements an IDL callback interface MUST be of a Java class that implements the Java interface that corresponds to the IDL interface, either by implementing the interface directly on that class or by inheriting from another class that implements the interface.

Note

For example, with the following IDL:

IDL
callback interface Base {
  void f();
};

callback interface Derived : Base {
  void g();
};

the Java implementation would provide the following interfaces:

Java
public interface Base {
  void f();
}

public interface Derived extends Base {
  void g();
}

and user objects implementing Derived could be defined like the following:

Java
// Directly implementing the interface
class DerivedImpl1 implements Derived {
  public void f() { ... }
  public void g() { ... }
}

// Inheriting from a class that implements the interface
class DerivedImpl2 extends DerivedImpl1 { }

3.8. Exceptions

For every IDL exception, there MUST exist a corresponding Java class whose name is the Java escaped identifier of the IDL exception.

The Java class MUST have only the public modifier. If the IDL exception inherits from another exception, then the Java class MUST be declared to extend the Java class corresponding to that inherited exception. Otherwise, the Java class MUST be declared to extend org.w3c.dom.Exception.

The class MUST also have constructors and methods with definitions as follows, where ExceptionName is the name of the class:

Java
public ExceptionName() {
}

public ExceptionName(String message) {
    super(message);
}

public ExceptionName(String message, Throwable cause) {
    super(message, cause);
}

public ExceptionName(Throwable cause) {
    super(cause);
}

The class org.w3c.dom.Exception is defined as follows:

Java
public class org.w3c.dom.Exception extends RuntimeException {

    public Exception(String message) {
        super(message);
    }

    public Exception(String message, Throwable cause) {
        super(message, cause);
    }

    public Exception(Throwable cause) {
        super(cause);
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    private String name;
}

3.8.1. Constants

For each constant defined on the exception, there MUST be a corresponding constant declared on the Java class with the following characteristics:

  • The constant has no modifiers.
  • The type of the constant is the Java type that corresponds to the type of the IDL constant, according to the rules in section 3.2 above.
  • The name of the constant is the Java escaped identifier of the constant.
  • The value of the constant is the result of converting the constant’s IDL value to a Java value, according to the rules in section 3.2 above.

3.8.2. Exception fields

For each exception field defined on the exception, there MUST be a corresponding instance variable declared on the Java class with the following characteristics:

  • The instance variable has only the modifier public.
  • The type of the instance variable is the Java type that corresponds to the type of the IDL exception field, according to the rules in section 3.2 above.
  • The name of the instance variable is the Java escaped identifier of the exception field.
  • The instance variable is not declared with an initializer.

3.9. Throwing exceptions

When an IDL exception or predefined exception E is to be thrown, with an optional message M and name N, the following steps MUST be followed:

  1. Let C be the corresponding Java class for E if E is an IDL exception, or org.w3c.dom.Exception otherwise.
  2. Let message be the result of converting M to a java.lang.String object if one was specified, or null otherwise.
  3. Let O be the result of constructing a new object of class C, passing message as the sole argument to the constructor.
  4. If an exception name N was specified, then call the setName method of O with that type as a java.lang.String as the sole argument.
  5. Throw O.

4. Extensibility

This section is informative.

Extensions to the Java language binding requirements can be specified using extended attributes that do not conflict with those defined in this document. Extensions for private, project-specific use should not be included in IDL fragments appearing in other specifications. It is recommended that extensions that are required for use in other specifications be coordinated with the group responsible for work on Web IDL, which at the time of writing is the W3C Web Applications Working Group, for possible inclusion in a future version of this document.

Extensions to any other aspect of the IDL language are strongly discouraged.

5. Referencing this specification

This section is informative.

It is suggested that specifications defining interfaces with Web IDL for which Java language bindings are required to exist include a sentence such as the following, to indicate that the IDL is to be interpreted as described in this specification:

The IDL fragment in Appendix A of this specification must be interpreted as required for conforming IDL fragments, as described in the “Web IDL” specification. [WEBIDL]

In addition, it is suggested that the conformance class for user agents in referencing specifications be linked to the conforming Java implementation class from this specification:

A conforming FooML user agent must also be a conforming Java implementation of the IDL fragment in Appendix A of this specification, as described in the “Java language binding for Web IDL” specification. [WEBIDL-JAVA]

6. Acknowledgements

This section is informative.

The editor would like to thank contributors to the Web IDL specification, from which this Java language binding was split out in December 2011.

A. References

A.1. Normative references

[JLS3]
The Java Language Specification, Third Edition. J. Gosling, et al. Upper Saddle River, New Jersey, Addison-Wesley, 2005.
Available at http://java.sun.com/docs/books/jls/.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
Available at http://tools.ietf.org/html/rfc2119.
[WEBIDL]
Web IDL. C. McCormack, Editor. World Wide Web Consortium, work in progress, 19 April 2012.
Available at http://www.w3.org/TR/2012/CR-WebIDL-20120419/.

B. Changes

The following is a list of substantial changes to the document on each publication.

14 May 2013 – NOTE

  • Changed the org.w3c.dom.Exception class to take into account the renaming of “exception types” to “exception names”.

  • Added support for IDL unrestricted float and double types.

07 February 2012 – FPWD

  • Added support for IDL callbacks and callback interfaces.

  • Added support for IDL union types.

  • Added support for IDL enumerations.

12 December 2011 – ED