Language Bindings for DOM Specifications

3.3.1. Constants

A constant is a definition that matches the Const non-terminal, and is used to bind a constant value to a name. Constants can appear on interfaces and also at the module or outermost scope.

The ConstExpr part of a constant definition gives the value of the constant, which can be one of the two boolean literal terminals ("TRUE" and "FALSE"), an integer terminal or a float terminal.

The value of the boolean literal terminals are as follows:

• The value of the "TRUE" terminal is a value of type boolean: true.
• The value of the "FALSE" terminal is a value of type boolean: false.

The value of an integer terminal is determined as follows:

1. Let S be the string value of the integer terminal.
2. Let n be the length of S.
3. Initialize mag to 0.
4. Initialize sign to 1.
5. Initialize base to 10.
6. Initialize i to 0.
7. If the first character of S is not U+002D HYPHEN-MINUS ("-"), then go to step 10.
8. Set sign to −1.
9. Set i to 1.
10. If the ith zero-based character of S is not U+0030 DIGIT ZERO ("0"), then go to step 16.
11. Set base to 8.
12. Set i to i + 1.
13. If the ith zero-based character of S is not U+0058 LATIN CAPITAL LETTER X ("X") or U+0078 LATIN SMALL LETTER X ("x"), then go to step 16.
14. Set base to 16.
15. Set i to i + 1.
16. Let digit be the value obtained by looking up the ith zero-based character of S in the table below:

    Character	Value of digit
    U+0030 DIGIT ZERO ("0")	0
    U+0031 DIGIT ONE ("1")	1
    U+0032 DIGIT TWO ("2")	2
    U+0033 DIGIT THREE ("3")	3
    U+0034 DIGIT FOUR ("4")	4
    U+0035 DIGIT FIVE ("5")	5
    U+0036 DIGIT SIX ("6")	6
    U+0037 DIGIT SEVEN ("7")	7
    U+0038 DIGIT EIGHT ("8")	8
    U+0039 DIGIT NINE ("9")	9
    U+0041 LATIN CAPITAL LETTER A ("A")	10
    U+0041 LATIN CAPITAL LETTER B ("B")	11
    U+0041 LATIN CAPITAL LETTER C ("C")	12
    U+0041 LATIN CAPITAL LETTER D ("D")	13
    U+0041 LATIN CAPITAL LETTER E ("E")	14
    U+0041 LATIN CAPITAL LETTER F ("F")	15
    U+0061 LATIN SMALL LETTER A ("a")	10
    U+0061 LATIN SMALL LETTER B ("b")	11
    U+0061 LATIN SMALL LETTER C ("c")	12
    U+0061 LATIN SMALL LETTER D ("d")	13
    U+0061 LATIN SMALL LETTER E ("e")	14
    U+0061 LATIN SMALL LETTER F ("f")	15

17. Set mag to mag * base + digit.
18. Set i to i + 1.
19. If i < n, go to step 16.
20. The value of the integer terminal is sign * mag.

The type of an integer terminal is the same as the type of the constant it is being used as the value of. The value of the integer terminal must not lie outside the valid range of values for its type, as given in section 3.7 below.

The type of a float terminal is float, and its value is determined as follows:

1. Let S be the string value of the float terminal.
2. Let n be the length of S.
3. Initialize mant to 0.
4. Initialize sign to 1.
5. Initialize exp1 to 0.
6. Initialize exp2 to 0.
7. Initialize expSign to 1.
8. Iniitalize afterDot to false.
9. Initialize i to 0.
10. If the first character of S is not U+002D HYPHEN-MINUS ("-"), then go to step 13.
11. Set sign to −1.
12. Set i to 1.
13. If the ith zero-based character of S is U+0045 LATIN CAPITAL LETTER E ("E") or U+0045 LATIN SMALL LETTER E ("e"), then go to step 23.
14. If the ith zero-based character of S is not U+002E FULL STOP ("."), then go to step 17.
15. Set afterDot to true.
16. Go to step 20.
17. Let digit be the Unicode codepoint of the ith zero-based character of S minus 48.
18. Set mant to mant * 10 + digit.
19. If afterDot is true, set exp1 to exp1 − 1.
20. Set i to i + 1.
21. If i < n, go to step 13.
22. Go to step 33.
23. Set i to i + 1.
24. If the ith zero-based character of S is not U+002D HYPHEN-MINUS ("-"), then go to step 27.
25. Set expSign to −1.
26. Set i to i + 1.
27. If the ith zero-based character of S is not U+002B PLUS SIGN ("+"), then set i to i + 1.
28. Let digit be the Unicode codepoint of the ith zero-based character of S minus 48.
29. Set exp2 to exp2 * 10 + digit.
30. Set i to i + 1.
31. If i < n, go to step 33.
32. Go to step 28.
33. The value of the float terminal is the IEEE 754 floating point number closest to sign * mant * 10^{expSign * exp2 + exp1}. [IEEE-754]

A constant must be assigned a value of the same type that the constant is declared to be.

No extended attributes are applicable to constants.

3.3.2. Attributes

An attribute is an interface member that matches the Attribute non-terminal, and is used to declare that objects implementing the interface will have an attribute with the given identifier that can be assigned and retrieved.

The type of the attribute is given by the DeclarationType non-terminal. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the attribute is defined, to an interface, typedef or boxed valuetype that has been declared previously.

The attribute is read only if the "readonly" terminal is used in the definition. An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute. It is language binding specific whether assignment is simply disallowed by the language, ignored or an exception is thrown.

The GetRaises and SetRaises clauses are used to declare the possible exceptions that can be thrown when retrieving the value of and assigning a value to the attribute, respectively. Each scoped name in the GetRaises and SetRaises clauses must resolve, with respect to the enclosing module of the interface on which the attribute is defined, to an exception that has been declared previously.

The following extended attributes are applicable to attributes: [NoNull], [PutForwards].

3.3.3. Operations

An operation is an interface member that matches the Operation non-terminal, and is used to declare that objects implementing the interface will have a method with the given identifier.

The return type of the operation is given by the ReturnType non-terminal. A return type of "void" indicates that the operation returns no value. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the operation is defined, to an interface, typedef or boxed valuetype that has been declared previously.

The ArgumentList non-terminal gives the list of arguments for the operation. The identifier of an argument is given by the identifier terminal in the Argument, and the type of the argument is given by the DeclarationType. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the operation is defined, to an interface, typedef or boxed valuetype that has been declared previously.

Each argument can be preceded by a list of extended attributes (matching ExtendedAttributeList), which can control how a value passed as the argument value will be handled in language bindings.

The Raises clause is used to declare the possible exceptions that can be thrown when invoking the operation. Each scoped name in the Raises clause must resolve, with respect to the enclosing module of the interface on which the operation is defined, to an exception that has been declared previously.

The following extended attributes are applicable to operations: [IndexGetter], [IndexSetter], [NameGetter], [NameSetter], [NoNull], [Overloads].

The following extended attributes are applicable to operation arguments: [NoNull], [Variadic].

3.7.1. any

The any type is the union of all other possible types.

3.7.2. boolean

The boolean type has two values: true and false.

boolean constant values in IDL are represented with the "TRUE" and "FALSE" terminals.

3.7.3. octet

The octet type is an unsigned integer type that has values in the range [0, 255].

octet constant values in IDL are represented with integer terminals.

3.7.4. short

The short type is a signed integer type that has values in the range [−32768, 32767].

short constant values in IDL are represented with integer terminals.

3.7.5. unsigned short

The unsigned short type is an unsigned integer type that has values in the range [0, 65535].

unsigned short constant values in IDL are represented with integer terminals.

3.7.6. long

The long type is a signed integer type that has values in the range [−2147483648, 2147483647].

long constant values in IDL are represented with integer terminals.

3.7.7. unsigned long

The unsigned long type is an unsigned integer type that has values in the range [0, 4294967295].

unsigned long constant values in IDL are represented with integer terminals.

3.7.8. long long

The long long type is a signed integer type that has values in the range [−9223372036854775808, 9223372036854775807].

long long constant values in IDL are represented with integer terminals.

3.7.9. unsigned long long

The unsigned long long type is an unsigned integer type that has values in the range [0, 18446744073709551615].

unsigned long long constant values in IDL are represented with integer terminals.

3.7.10. float

The float type is a floating point numeric type that corresponds to the set of possible single-precision 32 bit IEEE 754 floating point numbers. [IEEE-754]

float constant values in IDL are represented with float terminals.

3.7.11. sequence<T>

The sequence<T> type is a parameterized type whose values are (possibly zero-length) sequences of values of type T. Sequences can have an arbitrary length that is immutable. However, sequence element values are mutable.

There is no way to represent a sequence constant value in IDL.

3.7.12. Object

The Object type corresponds to the set of all possible object references, plus the special value null, which indicates no object reference.

There is no way to represent an Object constant value in IDL.

3.7.13. Object implementing an interface

A scoped name that resolves to an interface is used to refer to a type that corresponds to the set of all possible references to objects that implement that interface, plus the special value null, which indicates no object reference.

There is no way to represent an Object constant value in IDL.

3.7.14. Boxed valuetype

A scoped name that resolves to a boxed valuetype is used to refer to a type that corresponds to the set of values for the type being boxed, plus the special value null, which indicates no value.

There is no way to represent a boxed valuetype constant value in IDL.

3.8.1. [Constructor]

If the [Constructor] extended attribute appears on an interface, it indicates that there must be a way to construct objects that implement this interface. How such objects can be constructed is specific to the language binding.

The [Constructor] extended attribute must take no argument.

interface NodeList {
  Node item(in unsigned long index);
  readonly attribute unsigned long length;
};

[Constructor]
interface Circle {
  attribute float r;
  attribute float cx;
  attribute float cy;
  readonly attribute float circumference;
};

var x = new Circle();    // x is now a reference to a host object that implements the Circle interface.
var y = new NodeList();  // This would throw a TypeError.

interface Circle {
  attribute float r;
  attribute float cx;
  attribute float cy;
  readonly attribute float circumference;

  [Constructor] Circle createCircle(in float r, in float cx, in float cy);
};

3.8.2. [ExceptionConsts]

If the [ExceptionConsts] extended attribute appears on a module, it indicates that any constants declared on that module are intended to exist on the language construct that corresponds to the exception given by the extended attribute’s argument (for languages that support constants on exceptions). Exactly how these constants are exposed is language binding specific.

The [ExceptionConsts] must take a single argument, an identifier, which must be the identifier of an exception, defined in that module, on which the constants declared at the module scope should live.

[ExceptionConsts=FileIOException]
module fileio {

  exception FileIOException {
    unsigned short code;
  };

  const unsigned short FILE_NOT_FOUND = 1;
  const unsigned short READ_ERROR = 2;
  const unsigned short WRITE_ERROR = 3;
};

typeof FileIOException;          // evaluates to "object"
FileIOException.FILE_NOT_FOUND;  // evaluates to 1

3.8.3. [IndexGetter]

If the [IndexGetter] extended attribute appears on an operation with a single unsigned long argument, it indicates that an object that implements the interface can be indexed with an unsigned long, resulting in the same effect as calling the operation with the given index (for languages that support such object indexing). If an object implements interfaces such that it has more than one operation annotated with [IndexGetter], then which operation is invoked when an object is indexed with an unsigned long value is undefined.

The [IndexGetter] extended attribute must take no argument.

valuetype DOMString sequence<unsigned short>;

interface OrderedMap {
  readonly attribute unsigned long size;

  [IndexGetter] any getByIndex(in unsigned long index);
  [IndexSetter] void setByIndex(in unsigned long index, in any value);

  [NameGetter] any get(in DOMString name);
  [NameSetter] void set(in DOMString name, in any value);
};

var map = getOrderedMap();  // Assume map is a host object implementing the OrderedMap interface.
var x, y;

x = map[0];                 // Same as: x = map.getByIndex(0)
map[1] = false;             // Same as: map.setByIndex(1, false)

y = map.apple;              // Same as: y = map.get('apple')
map.banana = 123;           // Same as: map.set('banana', 123)

3.8.4. [IndexSetter]

If the [IndexSetter] extended attribute appears on an operation with two arguments, the first of which is unsigned long, it indicates that an object that implements the interface can be indexed with an unsigned long for assignment, resulting in the same effect as calling the operation with the given index and value to assign (for languages that support such object indexing). If an object implements interfaces such that it has more than one operation annotated with [IndexSetter], then which operation is invoked when an object is indexed with an unsigned long value for assignment is undefined.

The [IndexSetter] extended attribute must take no argument.

3.8.5. [NameGetter]

If the [NameGetter] extended attribute appears on an operation with a single sequence<unsigned short> valuetype argument, it indicates that an object that implements the interface can be indexed with a string, resulting in the same effect as calling the operation with the given index name (for languages that support such object indexing). If an object has both a [NameGetter]- and [IndexGetter]-annotated operation, then which operation is invoked when an object is indexed is language binding specific.

The [NameGetter] extended attribute must take no argument.

3.8.6. [NameSetter]

If the [NameSetter] extended attribute appears on an operation with a two arguments, the first of which is a sequence<unsigned short> boxed valuetype, it indicates that an object that implements the interface can be indexed with a string for assignment, resulting in the same effect as calling the operation with the given index and value to assign (for languages that support such object indexing). If an object implements interfaces such that it has more than one operation annotated with [NameSetter], then which operation is invoked when an object is indexed with a boxed sequence<unsigned short> value for assignment is undefined.

The [NameSetter] extended attribute must take no argument.

3.8.7. [NoNull]

If the [NoNull] extended attribute appears on an attribute, an operation or an operation argument, whose type is a boxed valuetype, it indicates that a null value is not expected and will never be returned. How implementations treat the assignment of a null value to an attribute with the [NoNull] extended attribute, or passing a null value as a [NoNull] operation argument, is specific to the language binding.

The [NoNull] extended attribute must take no argument.

valuetype DOMString sequence<unsigned short>;

interface Dog {
  [NoNull] attribute DOMString name;
  attribute DOMString shortName;

  boolean isMemberOfBreed([NoNull] in DOMString breedName);
};

var d = getDog();         // Assume d is a host object implementing the Dog interface.

d.name = null;            // This assigns the string "null" to the .name property.
d.isMemberOfBreed(null);  // This passes the string "null" to the isMemberOfBreed function.

typedef sequence<unsigned short> DOMString;
valuetype DOMStringOrNull DOMString;

3.8.8. [Overloads]

If the [Overloads] extended attribute appears on an operation, it indicates that the operation is to be considered to overload the operation with the identifier given as the extended attribute argument. The extent to which a language supports method overloading determines whether an object implementing an interface with overloaded operations must implement the operation using the overloaded name or the original name, and is specific to the language binding.

The [Overloads] extended attribute must take a single argument, an identifier, which must be the identifier of another operation defined on the interface, which this operation overloads. The identifier must not identify an operation that itself is declared with an [Overloads] extended attribute.

interface Person;

interface PersonFactory {
  Person createPerson();
  [Overloads=createPerson] Person createPersonWithAge(in short age);
};

var f = getFactory();          // Assume f is a host object implementing the PersonFactory interface.

typeof f.createPerson;         // Evaluates to "function".
typeof f.createPersonWithAge;  // Evaluates to "undefined".

var p1 = f.createPerson();     // Corresponds to the createPerson operation.
var p2 = f.createPerson(26);   // Corresponds to the createPersonWithAge operation.

PersonFactory* f = getFactory();

Person* p1 = PersonFactory_createPerson(f);             // Corresponds to the createPerson operation.
Person* p2 = PersonFactory_createPersonWithAge(f, 26);  // Corresponds to the createPersonWithAge operation.

3.8.9. [PutForwards]

If the [PutForwards] extended attribute appears on a read only attribute declaration whose type is an object implementing an interface, it indicates that assigning to the attribute will have specific behavior. Namely, the assignment is “forwarded” to the attribute (specified by the extended attribute argument) on the object that is currently the value of the attribute being assigned to.

It is binding language specific what behavior occurs when assigning to such an attribute when its value is null.

The [PutForwards] extended attribute must take a single argument, an identifier, which must be the identifier of an attribute that exists on the interface that is the type of this attribute, which is the attribute that assignments will be forward to.

valuetype DOMString sequence<unsigned short>;

interface Name {
  attribute DOMString full;
  attribute DOMString family;
  attribute DOMString given;
};

interface Person {
  [PutForwards=full] readonly attribute Name name;
  attribute unsigned short age;
};

var p = getPerson();           // Assume p is a host object implementing the Person interface.

p.name = 'John Citizen';       // This statement...
p.name.full = 'John Citizen';  // ...has the same behavior as this one.

3.8.10. [Variadic]

If the [Variadic] extended attribute appears on the final argument of an operation, it indicates that the operation is variadic, and can be passed zero or more arguments after the regular arguments. Each of these extra arguments will have to be of the type specified by that final argument. How such arguments are passed is specific to the language binding.

The [Variadic] extended attribute must take no argument.

interface IntegerSet {
  readonly unsigned long cardinality;

  void union([Variadic] in long integers);
  void intersection([Variadic] in long integers);
};

var s = getIntegerSet();  // Assume s is a host object implementing the IntegerSet interface.

s.union();                // Passing no arguments corresponding to 'integers'.
s.union(1, 4, 7);         // Passing three arguments corresponding to 'integers'.

any executeSql(DOMString q, [Variadic] DOMString p, Callback c);
any executeSql(Array a, Callback f);

4.1.1. any

The any IDL type can correspond to any ECMAScript type.

4.1.2. void

The only place that the void type may appear in IDL is as the return type of an operation. Functions on host objects that implement an operation whose IDL specifies a void return type must return the undefined value.

ECMAScript functions that implement an operation whose IDL specifies a void return type may return any value, which will be discarded.

4.1.3. boolean

Values passed to a host object that expects a boolean must first be converted to an ECMAScript Boolean value by the ToBoolean operator defined in section 9.2 of [ECMA-262].

boolean values returned from a host object must be ECMAScript Boolean values.

4.1.4. octet

Values passed to a host object that expects an octet must first be converted to an ECMAScript Number value by the ToUint8 operator, which functions, analagously to the ToUint32 operator defined in section 9.6 of [ECMA-262], as follows:

1. Call ToNumber on the input argument.
2. If Result(1) is NaN, +0, −0, +∞, or −∞, return +0.
3. Compute sign(Result(1)) * floor(abs(Result(1))).
4. Compute Result(3) modulo 2⁸.
5. Return Result(4).

octet values returned from a host object must be ECMAScript Number values.

4.1.5. short

Values passed to a host object that expects a short must first be converted to an ECMAScript Number value by the ToInt16 operator, which functions, analagously to the ToInt32 operator defined in section 9.5 of [ECMA-262], as follows:

1. Call ToNumber on the input argument.
2. If Result(1) is NaN, +0, −0, +∞, or −∞, return +0.
3. Compute sign(Result(1)) * floor(abs(Result(1))).
4. Compute Result(3) modulo 2¹⁶.
5. If Result(4) is greater than or equal to 2¹⁵, return Result(4) − 2¹⁶. Otherwise, return Result(4).

short values returned from a host object must be ECMAScript Number values.

4.1.6. unsigned short

Values passed to a host object that expects an unsigned short must first be converted to an ECMAScript Number value by the ToUint16 operator defined in section 9.7 of [ECMA-262].

unsigned short values returned from a host object must be ECMAScript Number values.

4.1.7. long

Values passed to a host object that expects an long must first be converted to an ECMAScript Number value by the ToInt32 operator defined in section 9.5 of [ECMA-262].

long values returned from a host object must be ECMAScript Number values.

4.1.8. unsigned long

Values passed to a host object that expects an unsigned long must first be converted to an ECMAScript Number value by the ToUint32 operator defined in section 9.5 of [ECMA-262].

unsigned long values returned from a host object must be ECMAScript Number values.

4.1.9. long long

Values passed to a host object that expects a long long must first be converted to an ECMAScript Number value by the ToInt64 operator, which functions, analagously to the ToInt32 operator defined in section 9.5 of [ECMA-262], as follows:

1. Call ToNumber on the input argument.
2. If Result(1) is NaN, +0, −0, +∞, or −∞, return +0.
3. Compute sign(Result(1)) * floor(abs(Result(1))).
4. Compute Result(3) modulo 2⁶⁴.
5. If Result(4) is greater than or equal to 2⁶³, return Result(4) − 2⁶⁴. Otherwise, return Result(4).

long long values returned from a host object must be ECMAScript Number values. If the long long value cannot be represented exactly by a Number value (i.e., it is less than or equal to −2⁵³ or greater than or equal to 2⁵³), the Number value returned must be the number representable by a Number closest to the given long long.

4.1.10. unsigned long long

Values passed to a host object that expects an unsigned long long must first be converted to an ECMAScript Number value by the ToUint64 operator, which functions, analagously to the ToUint32 operator defined in section 9.6 of [ECMA-262], as follows:

1. Call ToNumber on the input argument.
2. If Result(1) is NaN, +0, −0, +∞, or −∞, return +0.
3. Compute sign(Result(1)) * floor(abs(Result(1))).
4. Compute Result(3) modulo 2⁶⁴.
5. Return Result(4).

unsigned long long values returned from a host object must be ECMAScript Number values. If the unsigned long long value cannot be represented exactly by a Number value (i.e., it is greater than or equal to 2⁵³), the Number value returned must be the number representable by a Number closest to the given unsigned long long.

4.1.11. float

Values passed to a host object that expects a float must first be converted to an ECMAScript Number value by the ToNumber operator defined in section 9.3 of [ECMA-262].

float values returned from a host object must be ECMAScript Number values.

4.1.12. sequence<T>

Values passed to a host object that expects a sequence<T> must be objects with a length property whose value is a non-negative integer Number that specifies the number of elements in the sequence. Such objects must return the element in the sequence at position n when their [[Get]] internal method is invoked with n as its argument. (An ECMAScript Array is an object that matches this description.) When the host object gets an element of the sequence using the [[Get]] method, the returned value must first be handled according to the rules in this section for the type T.

If a host object expecting a sequence<T> is passed a value which is not an object with a non-negative integer Number length property, a TypeError exception must be thrown.

Sequences are passed by reference. If a reference to a sequence passed to a host object is kept (whether internally or as the value of an attribute), and the passed sequence is not an ECMAScript Array object, the kept reference must be a newly created ECMAScript Array object whose contents is the elements of the sequence.

typedef sequence<unsigned short> Integers;

[Constructor]
interface LotteryResults {
  attribute Integers numbers;
};

var results = new LotteryResults();  // results is a new host object implementing the LotteryResults interface.
var a = [4, 8, 15, 16, 23, 42];      // An object that can serve as a sequence<unsigned short>.

results.numbers = a;                 // Assign the sequence.
a[0] = 5;                            // Change the array.
results.numbers[0];                  // Evaluates to 5, since results.numbers is a reference to 'a'.

4.1.13. sequence<unsigned short>

As a special case, a sequence<unsigned short> is represented by an ECMAScript String value.

Values passed to a host object that expects a sequence<unsigned short> value must first be converted to an ECMAScript String value by the ToString operator defined in section 9.8 of [ECMA-262].

sequence<unsigned short> values returned from a host object must be ECMAScript String values.

4.1.14. Object

If a host object that expects an Object is passed the null value, then that value must passed without modification. Otherwise, the value being passed must first be converted to an ECMAScript Object value by the ToObject operator defined in section 9.9 of [ECMA-262].

If a host object returns an Object that is null, then the ECMAScript null value must be returned. Otherwise, an ECMAScript Object value must be returned.

4.1.15. Object implementing an interface

If a host object that expects an object that implements an interface I is passed the null value, then that value must passed without modification. Otherwise, the value being passed must first be converted to an ECMAScript Object value by the ToObject operator defined in section 9.9 of [ECMA-262]. If after that conversion the object is not one that implements I (either intrinsically for a host object, or as described in section 4.4 below for a native object), then a TypeError must be thrown.

If a host object returns an object that implements an interface I that is null, then the ECMAScript null value must be returned. Otherwise, an ECMAScript Object value that implements I must be returned.

4.1.16. Boxed valuetype

A boxed valuetype is represented by either the ECMAScript type corresponding to the IDL type being boxed, or the ECMAScript null value.

If a host object that expects a boxed valuetype that is not annotated with the [NoNull] extended attribute is passed the null value, then that value must be passed without modification. However, if the [NoNull] extended attribute does apply and the null value is passed to the host object, the behavior depends on the type being boxed. If the type being boxed is sequence<unsigned short>, then the ECMAScript String "null" must be passed to the host object. If the type being boxed is anything else, the behavior is implementation specific.

If a host object that expects a boxed valuetype is passed an ECMAScript Object value, the value must first be handled according to the rules in this section corresponding to the IDL type being boxed.

If a host object returns a boxed valuetype that is null, then the ECMAScript null value must be returned. If the operation or attribute is annotated with the [NoNull] extended attribute, the host object must not return null. If the value returned is not null, it must be handled according to the rules in this section corresponding to the IDL type being boxed.

4.2.1. Interface object

The interface object for a particular interface has an internal [[Prototype]] object whose value is the Object prototype object.

In addition, there is a property on the interface object for each constant defined on the interface with the same name as that constant. These properties have the attributes { DontDelete }.

If the interface is declared with the [Constructor] extended attribute, then the interface object also has a [[Construct]] internal property, which allows construction of objects that implement the given interface. The behavior of this [[Construct]] method is not necessarily the same as that described for Function objects in section 13.2.2 of [ECMA-262].

The interface object also has a property named prototype with attributes { DontDelete, ReadOnly } whose value is an object called the interface prototype object. This object provides access to the functions that correspond to the operations defined on the interface.

4.2.2. Interface prototype object

The interface prototype object for a particular interface has properties that correspond to the operations defined on that interface. Each such property has attribute { DontEnum }. These properties are described in more detail in section 4.2.3 below.

If the interface is declared with the [Constructor] extended attribute, the interface prototype object also has a property named constructor with attribute { DontEnum } whose value is a reference to the interface object for the interface.

No particular value must be used for the internal [[Prototype]] property of the interface prototype object. However, it must be an object that provides access to the properties defined on all superinterfaces of the interfaces. Changes made to the interface prototype objects of superinterfaces must be reflected through this object. If more than one superinterface has a given property, it is implementation specific which one is accessed.

interface A {
  void f();
};

interface B {
  void g();
};

interface C : A, B {
  void f();
};

interface D : C {
  void h();
};

4.2.3. Operations

In order to describe how properties on the interface prototype object corresponding to operations are chosen in the presence of overloading, the notion of potential ambiguity is first defined. Two operations on an interface, O₁ and O₂, are potentially ambiguous if the following algorithm returns true:

1. …

interface CanvasRenderingContext2D {
  …
  CanvasPattern createPattern(in HTMLImageElement image, DOMString repetition);
  CanvasPattern createPattern(in HTMLCanvasElement image, DOMString repetition);
  …
};

The overload set for an operation O is defined as follows:

• If O is not declared with an [Overloads] extended attribute, then the set is equal to the union of { O } and all other operations declared on the interface with the [Overloads] extended attribute whose argument is the name of O.
• Otherwise, if O is declared with an [Overloads] extended attribute with argument N, then the set is equal to the overload set for the operation with identifier N declared on the interface.

An operation O is a non-overloadable operation if it matches one of the following two criteria:

1. The overload set of O is equal to { O }.
2. There exists two operations O₁ and O₂ in the overload set for O such that O₁ and O₂ are potentially ambiguous.

An operation is an overloaded operation if it is not declared with an [Overloads] extended attribute and the cardinality of its overload set is greater than 1.

For each non-overloadable operation O defined on the interface, a property exists on the interface prototype object whose name is the name of the operation and whose value is a Function object that behaves as follows:

1. Let n be the number of arguments passed to the function.
2. Let arity be the number of arguments that O is declared with if the final argument does not have the [Variadic] extended attribute, or the number of arguments that O is declared with minus 1 otherwise.
3. If n < arity, an implementation specific exception is thrown and these steps are ended.
4. Let arg_0‥n−1 be the arguments passed to the function.
5. Initialize i to 0.
6. While i < arity:
   1. Convert arg_i, according to the type of the formal argument in position i, by following the relevant steps from section 4.1 above.
   2. If the type of the formal argument in position i is a boxed sequence<unsigned short> valuetype and is declared with the [NoNull] extended attribute, and arg_i is null, set arg_i to the String value "null".
   3. Set i to i + 1.
7. Let j be n if the final argument of O is declared with the [Variadic] extended attribute, or arity otherwise.
8. While i < j:
   1. Convert arg_i, according to the type of the formal argument in position arity + 1, by following the relevant steps from section 4.1 above.
   2. If the type of the formal argument in position arity + 1 is a boxed sequence<unsigned short> valuetype and is declared with the [NoNull] extended attribute, and arg_i is null, set arg_i to the String value "null".
   3. Set i to i + 1.
9. Perform the actions listed in the description of O with arg_0‥j−1 as the argument values.

For each overloaded operation defined on the interface, a property exists on the interface prototype object whose name is the name of the operation and whose value is a Function object that behaves as follows:

1. …

4.3.1. Host object [[Get]] method

The internal [[Get]] method of every host object O that implements at least one IDL interface behaves, assuming P is the property name passed to [[Get]], as follows:

1. Determine the name of an [IndexGetter]-annotated operation on the interfaces that O implements. If there is no such operation, go to step 8.
2. Compute ToUint32(P).
3. Compute ToString(Result(2)).
4. If Result(3) is equal to P and Result(2) is not equal to 2³² − 1, go to step 8.
5. Invoke the [[Get]] method of object O with Result(1) as the argument.
6. Invoke the [[Call]] method of Result(5), providing O as the this value and Result(2) as the single argument value.
7. Return Result(5).
8. Determine the name of a [NameGetter]-annotated operation on the interfaces that O implements. If there is no such operation, go to step 14.
9. Invoke the [[HasProperty]] method of object O with P as the argument.
10. If Result(8) is true, go to step 14.
11. Invoke the [[Get]] method of object O with Result(7) as the argument.
12. Invoke the [[Call]] method of Result(10), providing O as the this value and P as the single argument value.
13. Return Result(11).
14. If O doesn’t have a property with name P, go to step 17.
15. Get the value of the property.
16. Return Result(15).
17. If the [[Prototype]] of O is null, return undefined.
18. Call the [[Get]] method of [[Prototype]] with property name P.
19. Return Result(18).

4.3.2. Host object [[Put]] method

The internal [[Put]] method of every host object O that implements at least one IDL interface behaves, assuming P is the property name and V is the property value passed to [[Put]], as follows:

1. Determine the name of a [IndexSetter]-annotated operation on the interfaces that O implements. If there is no such operation, go to step 8.
2. Compute ToUint32(P).
3. Compute ToString(Result(2)).
4. If Result(3) is equal to P and Result(2) is not equal to 2³² − 1, go to step 8.
5. Invoke the [[Get]] method of object O with Result(1) as the argument.
6. Invoke the [[Call]] method of Result(5), providing O as the this value and Result(2) and V as the two argument values.
7. Return Result(5).
8. Determine the name of a [NameSetter]-annotated operation on the interfaces that O implements. If there is no such operation, go to step 14.
9. Invoke the [[HasProperty]] method of object O with P as the argument.
10. If Result(8) is true, go to step 14.
11. Invoke the [[Get]] method of object O with Result(7) as the argument.
12. Invoke the [[Call]] method of Result(10), providing O as the this value and P and V as the two argument values.
13. Return Result(11).
14. If O has a property with name P and that property does not correspond to an IDL operation declared readonly, then go to step 19.
15. If the property on O with name P does not correspond to an IDL operation declared with a [PutForwards] extended attribute, then an implementation specific exception is thrown and these steps are ended.
16. Call the [[Get]] method of O with name P.
17. Call the [[Put]] method of Result(16) with the property name being the argument to the [PutForwards] extended attribute, and value V.
18. Return.
19. Call the [[CanPut]] method of O with name P.
20. If Result(19) is false, return.
21. If O doesn’t have a property with name P, go to step 23.
22. Set the value of the property to V. The attributes of the property are not changed.
23. Return.
24. Create a property with name P, set its value to V and give it empty attributes.
25. Return.

4.5.1. Exception interface object

The exception interface object for a particular exception has an internal [[Prototype]] object whose value is the Object prototype object.

If the enclosing module of the exception has been declared with the [ExceptionConsts] extended attribute, and the argument to that extended attribute is the identifier of the exception, then the exception interface object has a property for each constant declared at the enclosing module’s scope. These properties have the attributes { DontDelete }.

try {
  document.removeChild(document);
} catch (e) {
  alert(e.NOT_FOUND_ERR);
}

5.2.1. any

The any IDL type corresponds to a Java java.lang.Object value. Values of IDL types that correspond to Java primitive types must be represented with an object according to the following table:

5.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.

5.2.3. boolean

The IDL boolean type maps exactly to the Java boolean type.

5.2.4. octet

The IDL octet type corresponds to the Java byte type. 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].

To encode an octet value in a byte, the following steps must be followed:

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

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

To decode an octet value from a byte, the following steps must be followed:

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

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

5.2.5. short

The IDL short type maps exactly to the Java short type.

5.2.6. unsigned short

The IDL unsigned short type corresponds to the Java short type. 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].

To encode an IDL unsigned short value in a Java short, the following steps must be followed:

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

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

To decode an IDL unsigned short value from a Java short, the following steps must be followed:

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

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

5.2.7. long

The IDL long type maps exactly to the Java int type.

5.2.8. unsigned long

The IDL unsigned long type corresponds to the Java int type. 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].

To encode an IDL unsigned long value in a Java int, the following steps must be followed:

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

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

To decode an IDL unsigned long value from a Java int, the following steps must be followed:

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

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

5.2.9. long long

The IDL long long type maps exactly to the Java long type.

5.2.10. unsigned long long

The IDL unsigned long long type corresponds to the Java long type. 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].

To encode an IDL unsigned long long value in a Java long, the following steps must be followed:

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

To decode an IDL unsigned long long value from a Java long, the following steps must be followed:

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

5.2.11. float

The IDL float type maps exactly to the Java float type.

5.2.12. sequence<T>

The IDL sequence<T> type corresponds to a Java array of type T.

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>.

A Java object implementing an interface with an operation declared to take an argument of type sequence<T> must throw a NullPointerException exception if null is passed as the corresponding argument to the corresponding method. Similarly, a setter method for an IDL attribute must throw a NullPointerException exception if the attribute is declared to be of type sequence<T>.

5.2.13. sequence<unsigned short>

As a special case, a sequence<unsigned short> is represented by a Java String object.

A Java object implementing an interface with an operation declared to return a sequence<unsigned short> 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<unsigned short>.

A Java object implementing an interface with an operation declared to take an argument of type sequence<unsigned short> must throw a NullPointerException exception if null is passed as the corresponding argument to the corresponding method. Similarly, a setter method for an IDL attribute must throw a NullPointerException exception if the attribute is declared to be of type sequence<unsigned short>.

5.2.14. Object

The IDL Object type maps exactly to the Java java.lang.Object type.

5.2.15. Object implementing an interface

An IDL interface type maps exactly to the corresponding Java interface type.

5.2.16. Boxed valuetype

A boxed valuetype is represented differently depending on the type being boxed. Let T be the type being boxed.

If T maps to a Java object value, which is the case for any, sequence<T>, sequence<unsigned short>, Object and interface types, then a boxed valuetype is represented by the Java null value (if the value of the boxed valuetype is null) or by a value as described in this section for the mapping for T (if the value of the boxed valuetype is not null). Thus, a Java object whose method implements an operation declared to take an argument of a sequence type must not throw an exception simply for being passed a null value.

If T does not map to a Java object value, then the boxed valuetype maps to a Java class as specified in the table below:

If the value of the boxed valuetype is not null, then the value stored inside the object of the given class must be as specified by the rules in this section for type T.

5.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 properties:

• 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 5.2 above.
• The name of the constant is the Java escaped identifier of the constant.
• The value of the constant is the Java value that is equivalent to the constant’s IDL value, according to the rules in section 5.2 above.

5.4.2. Operations

For each operation defined on the IDL interface, there must be a corresponding method declared on the Java interface with the following properties:

• The method has no modifiers.
• The return type of the method is the Java type that corresponds to the operation return type, according to the rules in section 5.2 above.
• If the operation is a non-overloadable operation, then the tentative name of the method is the Java escaped identifier of the operation. Otherwise, the tentative name of the method is the Java escaped identifier that is the argument to the [Overloads] extended attribute on the operation. The name of the method is the tenative name of the method prefixed with the smallest number of U+005F LOW LINE ("_") characters required to make the name not equal to the name of a constant declared on the Java interface or one of the methods on the java.lang.Object class.
• The method has an argument for each argument on the operation. The type of the method argument is as follows. Let T be the Java type that corresponds to the operation argument type according to the rules in section 5.2 above. If the argument is the final argument on the operation, and it is declared with the [Variadic] extended attribute, then the type of the method argument will be an array of T (i.e., T[]). Otherwise, the type of the method argument will be T.

In addition, the method should have a throws clause specifying all of the Java exception classes that correspond to the IDL exceptions that are listed in the Raises clause of the operation, and no others.

5.4.3. Attributes

For each attribute defined on the IDL interface, there must be a corresponding getter method declared on the Java interface with the following properties:

• 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 5.2 above.
• The tentative name of the method is a U+0067 LATIN SMALL G ("g") character, followed by a U+0065 LATIN SMALL E ("e") character, followed by a U+0074 LATIN SMALL T ("t") character, followed by the first character of the identifier of the attribute uppercased (as if passed to the java.lang.Character.toUpperCase() method), followed by the remaining characters from the identifier of the attribute. The name of the method is the Java escaped tenative name of the method prefixed with the smallest number of U+005F LOW LINE ("_") characters required to make the name not equal to the name of a constant or method declared on the Java interface or one of the methods on the java.lang.Object class.
• The method has no arguments.

In addition, the method should have a throws clause specifying all of the Java exception classes that correspond to the IDL exceptions that are listed in the GetRaises clause of the attribute, and no others.

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 properties:

• The method has no modifiers.
• The return type of the method is void.
• The tentative name of the method is a U+0073 LATIN SMALL S ("s") character, followed by a U+0065 LATIN SMALL E ("e") character, followed by a U+0074 LATIN SMALL T ("t") character, followed by the first character of the identifier of the attribute uppercased (as if passed to the java.lang.Character.toUpperCase() method), followed by the remaining characters from the identifier of the attribute. The name of the method is the Java escaped tenative name of the method prefixed with the smallest number of U+005F LOW LINE ("_") characters required to make the name not equal to the name of a constant or method declared on the Java interface or one of the methods on the java.lang.Object class.
• The method has a single argument whose type is the Java type that corresponds to the attribute type, according to the rules in section 5.2 above.

In addition, the method should have a throws clause specifying all of the Java exception classes that correspond to the IDL exceptions that are listed in the SetRaises clause of the attribute, and no others.

For each attribute defined on the IDL interface that is read only and is declared with the [PutForwards] extended attribute, there must be a corresponding setter method declared on the Java interface with the following properties:

• The method has no modifiers.
• The return type of the method is void.
• The tentative name of the method is a U+0073 LATIN SMALL S ("s") character, followed by a U+0065 LATIN SMALL E ("e") character, followed by a U+0074 LATIN SMALL T ("t") character, followed by the first character of the identifier of the attribute uppercased (as if passed to the java.lang.Character.toUpperCase() method), followed by the remaining characters from the identifier of the attribute. The name of the method is the Java escaped tenative name of the method prefixed with the smallest number of U+005F LOW LINE ("_") characters required to make the name not equal to the name of a constant or method declared on the Java interface or one of the methods on the java.lang.Object class.
• The method has a single argument whose type is the Java type that corresponds to the type of the attribute identified by the [PutForwards] extended attribute on the interface type that this attribute is declared to be of, according to the rules in section 5.2 above.

In addition, the method should have a throws clause specifying all of the Java exception classes that correspond to the IDL exceptions that are listed in the SetRaises clause of the attribute identified by the [PutForwards] extended attribute on the interface type that this attribute is declared to be of, and no others.

5.6.1. Constants

For each constant defined on the enclosing module of the IDL exception, where that module has been declared with the [ExceptionConsts] extended attribute, there must be a corresponding constant declared on the Java class with the following properties:

• 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 5.2 above.
• The name of the constant is the Java escaped identifier of the constant.
• The value of the constant is the Java value that is equivalent to the constant’s IDL value, according to the rules in section 5.2 above.

5.6.2. Exception members

For each exception member defined on the exception, there must be a corresponding instance variable declared on the Java class with the following properties:

• 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 member, according to the rules in section 5.2 above.
• The name of the instance variable is the Java escaped identifier of the exception member.
• The instance variable is not declared with an initializer.