OpenAjax Metadata 1.0 Specification API Metadata

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.


<--previous       contents--^       next-->


Contents

Chapter 6: API Metadata

Introduction

This chapter defines the OpenAjax Metadata XML grammar for the runtime JavaScript APIs (e.g., classes and methods) that are available for a given Ajax library.

The following elements are defined in this chapter:

The following elements are defined in subsequent chapters:

Additional information about API Metadata can be found in:


Common attributes

The following attributes are available on multiple elements defined in this chapter:

Attribute summary

AttributeDescriptionTypeRequiredDefault
scope Whether this feature is instance-based or static. instance|static no instance
visibility Intended visibility of this feature to other parts of the JavaScript application. public|private|protected|internal|protected-internal no public

Attribute details

'scope' attribute

The scope attribute specifies whether the feature belongs to the class itself or to instances of the class. A value of instance indicates that the given feature is available only after an instance of this class has been created. A value of static indicates that this feature belongs to the class itself and does not require object instantiation.

'visibility' attribute

The visibility attribute specifies the intended visibility of the feature to other parts of the JavaScript application. Its value can be any of the following access modifiers:

  • public indicates that the given feature is intended to be available to any code within the application. (This is the default.)
  • private indicates that the given feature is intended to be available only within the <class> or <singleton> itself. Private features are not intended to be available to derived classes.
  • protected indicates that the given feature is intended to be available only within the <class> or <singleton> itself and to derived classes.
  • internal indicates that the given feature is intended to be public across the class's top-level namespace (including all descendant namespaces, classes and singletons), but private to JavaScript logic outside of the top-level namespace. (For the purposes of this attribute, if a class has the name "aaa.bbb.ccc", then "aaa" and "aaa.bbb" are considered namespaces, and "aaa" is the top-level namespace.)
  • protected-internal indicates that access to the given feature is the union of the access granted by protected and the access granted by internal.


<api>

The <api> element is the root element of an OpenAjax Metadata file that defines JavaScript APIs.

An Ajax library may define all of its APIs within a single OpenAjax Metadata file or split the API definitions across multiple OpenAjax Metadata files. (For additional information, refer to the File naming conventions section in the Introduction.)

Schema

api_element = element api {
  api_content  &  api_attributes  &  foreign_nodes
}
api_content = (
  descriptive_elements  &  
  class_element*  &  classes_element*  &  config_element*  &  configs_element*  &  
  enum_element*  &  enums_element*  &  globals_element*  &  
  interface_element*  &  interfaces_element*  &  license_element?  &  locale_element*  &  
  mixin_element*  &  mixins_element*  &  namespace_element*  &  namespaces_element*  &  
  singleton_element*  &  singletons_element*
)
api_attributes = (
  lang?  &  language?  &  spec  &  version?  &
  pattern_attributes  
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
language Programming language to which the API metadata applies. String (see below) no javascript
spec Version number of the OpenAjax Metadata spec to which this metadata file conforms. Version string (see below) yes none
version Version number for the JavaScript APIs that are described by this metadata file. Version string (see below) no none
lang Identifies the natural or formal language for the content. Defined in Localization chapter.
pattern_attributes Attributes 'getterPattern', 'setterPattern', 'registerHandlerPattern' and 'unregisterHandlerPattern'. Defined in Pattern attributes section in Properties chapter.

Attribute details

'language' attribute

The language attribute specifies the programming language for which the API metadata applies. The default is "javascript", which indicates the various versions of the language whose standard is named "ECMAScript" (e.g., ECMA-262).

'spec' attribute

The spec attribute specifies the version number of the OpenAjax Metadata spec to which this metadata file conforms. (See the write-up on Version number attributes in the Compatibility chapter for rules on version number attributes.)

'version' attribute

The version attribute specifies the version number for the group of JavaScript APIs (i.e., the library) described by this metadata file. (See the write-up on Version number attributes in the Compatibility chapter for rules on version number attributes.)


<alias>

The <alias> element can be used to specify an alternate name for a class or singleton that a developer tool might use during content assist. Typically, the alternate name is shorter and/or more understandable that the original name.

Schema

alias_element = element alias {
  alias_content  &  alias_attributes  &  foreign_attributes
}
alias_content = (
  empty
)
alias_attributes = ( 
  name
)

Child content

<alias> must be an empty element (i.e., no child content).

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Name of the alias. String yes none

Attribute details

'name' attribute

The name attribute specifies the name of the alias. The name MUST be globally unique within the context of a particular JavaScript library.

Additional information

Example:

<class name="jQuery">
  <alias name="$" />
</class>


<ancestor>

The <ancestor> element specifies (via the datatype attribute) a "superclass" for the current class or interface.

Schema

ancestor_element = element ancestor {
  ancestor_content  &  ancestor_attributes  &  foreign_attributes
}
ancestor_content = (
  empty
)
ancestor_attributes = ( 
  datatype
)

Child content

<ancestor> must be an empty element (i.e., no child content).

Attribute summary

AttributeDescriptionTypeRequiredDefault
datatype Name of an ancestor <class>, <interface>, <mixin> or <singleton>. String (see below) yes none

Attribute details

'datatype' attribute

The datatype attribute specifies the name of a <class>, <interface>, <mixin> or <singleton> whose <property>, <method>, <event>, <alias>, <ancestor>, <config>, <constructor>, <event> and <mix> elements are included within the current class. For additional information, refer to the detailed specification for the 'datatype' attribute in the Datatypes chapter.


<class>

The <class> element describes a JavaScript class.

Schema

class_element = element class {
  class_content  &  class_attributes  &  foreign_nodes
}
class_content = (
  descriptive_elements  &  compatibility_elements  &  
  alias_element*  &  aliases_element*  &  ancestor_element*  &  ancestors_element*  &  
  config_element*  &  configs_element*  &  constructor_element*  &  constructors_element*  &  
  event_element*  &  events_element*  &  mix_element*  &  mixes_element*  &  
  method_element*  &  methods_element*  &  property_element*  &  properties_element*
)
class_attributes = (
  name  &  visibility?  &
  pattern_attributes  &  registerCallbackPattern?  &  unregisterCallbackPattern?    
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Absolute object name for the class. String (see below) yes none
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.
pattern_attributes Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter.
registerCallbackPattern Specifies the name pattern for the event handler registration function. Defined in Properties chapter.
unregisterCallbackPattern Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter.

Attribute details

'name' attribute

The name attribute specifies the absolute object name for the class using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit" and a subobject "io" with subobject "httpreq", which is set up as a JavaScript class with an appropriate constructor function). The name MUST be globally unique within the context of a particular JavaScript library.


<constructor>

The <constructor> element describes a constructor method. A constructor can be described by multiple <constructor> elements, in which case the different <constructor> elements can be used to specify different parameter and return value alternatives.

If no <returnType> is specified, the constructor method is assumed to return an instance of the class.

Schema

constructor_element = element constructor {
  constructor_content  &  constructor_attributes  &  foreign_nodes
}
constructor_content = (
  descriptive_elements  &  compatibility_elements  &  
  exception_element*  &  exceptions_element*  &  parameter_element*  &  parameters_element*  &  
  returnType_element*  &  returnTypes_element*
)
constructor_attributes = (
  visibility?
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.


Example

<class name="jQuery">
  <constructor>

    <shortDescription>This function accepts a string containing a CSS selector which is 
	                  then used to match a set of elements.</shortDescription>
    <description>
      The core functionality of jQuery centers around this function. Everything in jQuery 
      is based upon this, or uses this in some way. The most basic use of this function is 
      to pass in an expression (usually consisting of CSS), which then finds all matching 
      elements.

      By default, if no context is specified, $() looks for DOM elements within the context
      of the current HTML document. If you do specify a context, such as a DOM element or 
      jQuery object, the expression will be matched against the contents of that context.
    </description>

    <!-- parameters here -->

    <returnType datatype="jQuery"/>

    <!-- examples here -->

  </constructor>
  <!-- more constructors here -->
</class>


<event>

The <event> element is used to describe various aspects of library-specific events, such as the naming pattern used by the library for functions to register and unregister event handlers.

Schema

event_element = element event {
  event_content  &  event_attributes  &  foreign_nodes
}
event_content = (
  descriptive_elements  &  compatibility_elements  &  
  handlerFunction_element?
)
event_attributes = (
  name  &  registerCallbackPattern?  &  unregisterCallbackPattern?  &  visibility?
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Name of the event. String (see below) yes none
registerCallbackPattern Specifies the name pattern for the event handler registration function. Defined in Properties chapter.
unregisterCallbackPattern Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter.
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.

Attribute details

'name' attribute

The name attribute specifies the name of the event. The name MUST be globally unique within the context of current container object.


<exception>

The <exception> element describes an exception that a JavaScript function might throw.

Schema

exception_element = element exception {
  exception_content  &  exception_attributes  &  foreign_nodes
}
exception_content = (
  descriptive_elements  &  compatibility_elements  &  
  parameter_element*  &  parameters_element*  &  property_element*  &  properties_element*  &  
  returnType_element*  &  returnTypes_element*
)
exception_attributes = (
  datatype?
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
datatype Class name for the exception object. String (see below) no Error

Attribute details

'datatype' attribute

The datatype attribute specifies the class name for the exception object. See the Datatypes chapter for the detailed definition of this attribute.


<globals>

The <globals> element describes properties and methods that are global to the JavaScript runtime environment (i.e., available directly from the JavaScript window object) and therefore not contained within a particular namespace or class.

Schema

globals_element = element globals {
  globals_content  &  globals_attributes  &  foreign_nodes
}
globals_content = (
  property_element*  &  properties_element*  &  method_element*  &  methods_element*
)
globals_attributes = (
  pattern_attributes  
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

pattern_attributes Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter.


<handlerFunction>

The <handlerFunction> element is an optional child element to the <event> element that can be used to describe the naming pattern for the function that registers an event handler for the event and to describe the parameters to the event handler function.

Schema

handlerFunction_element = element handlerFunction {
  handlerFunction_content  &  handlerFunction_attributes  &  foreign_nodes
}
handlerFunction_content = (
  descriptive_elements  &  compatibility_elements  &  
  exception_element*  &  exceptions_element*  &  parameter_element*  &  parameters_element*  &  
  returnType_element*  &  returnTypes_element*
)
handlerFunction_attributes = (
  registerCallbackPattern?  &  unregisterCallbackPattern?
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
registerCallbackPattern Specifies the name pattern for the event handler registration function. Defined in Properties chapter.
unregisterCallbackPattern Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter.


Example

In the following example, the function to register an event handler is named locationChangeHandler. It takes a single parameter, which is the callback function. This callback function will be passed two parameters, both of which are Number values.

<event name="locationChange">
  <handlerFunction registerCallbackPattern="{{event}}Handler({{callback}})">
    <parameter name="lat" datatype="Number"/>
    <parameter name="long" datatype="Number"/>
  </handlerFunction>
</event>


<interface>

The <interface> element describes a logical group of JavaScript features (e.g., methods and properties) that are used as a superclass by other classes or interfaces. Typically, <interface> elements are referenced by <ancestor> elements.

Schema

interface_element = element interface {
  interface_content  &  interface_attributes  &  foreign_nodes
}
interface_content = (
  descriptive_elements  &  compatibility_elements  &  
  ancestor_element*  &  ancestors_element*  &  config_element*  &  configs_element*  &  
  constructor_element*  &  constructors_element*  &  event_element*  &  events_element*  &  
  mix_element*  &  mixes_element*  &  method_element*  &  methods_element*  &  
  property_element*  &  properties_element*
)
interface_attributes = (
  name  &  visibility?  &
  pattern_attributes  &  registerCallbackPattern?  &  unregisterCallbackPattern?  
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Absolute object name for the interface. String yes none
pattern_attributes Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter.
registerCallbackPattern Specifies the name pattern for the event handler registration function. Defined in Properties chapter.
unregisterCallbackPattern Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter.
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.

Attribute details

'name' attribute

The name attribute specifies the absolute object name for the interface using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq" which is set up as a JavaScript interface). The name MUST be globally unique within the context of a particular JavaScript library.


<method>

The <method> element describes a JavaScript function that is not used as a constructor.

Schema

method_element = element method {
  method_content  &  method_attributes  &  foreign_nodes
}
method_content = (
  descriptive_elements  &  compatibility_elements  &  
  exception_element*  &  exceptions_element*  &  parameter_element*  &  parameters_element*  &  
  returnType_element*  &  returnTypes_element*
)
method_attributes = (
  name  &  scope?  &  visibility?
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name JavaScript name for this function. String yes none
scope Whether this feature is instance-based or static. Defined in Common attributes section.
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.

Attribute details

'name' attribute

The name attribute specifies the JavaScript name for this function. The name MUST be globally unique within the context of current container object.

Example

<method name="addClass" scope="instance">
  <shortDescription>Adds the specified class(es) to each of the set of matched elements.</shortDescription>

  <parameters>
    <parameter name="class" datatype="String" usage="required">
      <description>One or more classes to add to the elements; these are separated by spaces.</description>
    </parameter>
  </parameters>

  <returnType datatype="jQuery"/>

<! -- examples here -->
</method>


<mix>

The <mix> element indicates that methods and properties (and other features) from another object are copied (i.e., mixed in) into this object. The datatype attribute specifies the name of a <class>, <interface>, <mixin> or <singleton> whose <property>, <method>, <event>, <alias>, <ancestor>, <config>, <constructor>, <event> and <mix> elements are included within the current class. This element can be used to mix in either a set of methods and properties or (if the fromProperty attribute has a value) an individual method or property.

Schema

mix_element = element mix {
  mix_content  &  mix_attributes  &  foreign_nodes
}
mix_content = (
  descriptive_elements
)
mix_attributes = (
  datatype  &  fromProperty?  &  toProperty?  &  fromScope?  &  toScope?
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
datatype Reference to an element whose features should be mixed in. String (see below) yes none
fromProperty Name of single method or property to be mixed in. String no (see below)
fromScope Whether to mix in the properties and methods of an object instance or of the class. instance|static no instance
toProperty Name for method or property when mixed in. String no value of fromProperty
toScope Whether to mix into object instance or class. instance|static no value of fromScope

Attribute details

'datatype' attribute

The datatype attribute is a reference to the name of the element whose features should be mixed in.

'fromProperty' attribute

If the fromProperty attribute has a value and is not the empty string, then only a single method or property will be mixed in. The fromProperty attribute provides the name of the property that is to be copied from the referenced <mixin>, <interface>, <class> or <singleton> element.

'fromScope' attribute

The fromScope attribute applies to properties and methods. A value of "instance" indicates that all instance properties and methods should be mixed in. A value of "static" indicates that all static properties and methods should be mixed in. (See the description of the scope attribute.)

'toProperty' attribute

The toProperty attribute provides the name for the mixed-in property when placed on the given <mixin>, <interface>, <class> or <singleton>. If not specified or if it is the empty string, then the mixed-in property's name has the same name as the fromProperty. This attribute is ignored if no fromProperty attribute is present.

'toScope' attribute

The toScope attribute applies to properties and methods. A value of "instance" indicates that all properties and methods should be mixed in on an instance basis. A value of "static" indicates that all properties and methods should mixed in on a static basis. (See the description of the scope attribute.)


<mixin>

The <mixin> element defines a collection of methods, properties, etc. that are available to be mixed into other classes (i.e., referred to by a <mix> element). Mixins are parallel to classes and singletons (whose methods and properties can also be mixed into other classes); unlike the methods and properties inside <class> and <singleton> elements, those inside <mixin> elements are *only* available for mixing and do not have any meaning on their own.

Schema

mixin_element = element mixin {
  mixin_content  &  mixin_attributes  &  foreign_nodes
}
mixin_content = (
  descriptive_elements  &  
  config_element*  &  configs_element*  &  constructor_element*  &  constructors_element*  &  
  event_element*  &  events_element*  &  mix_element*  &  mixes_element*  &  
  method_element*  &  methods_element*  &  property_element*  &  properties_element*
)
mixin_attributes = (
  name  &  scope?  &  visibility?  &  
  pattern_attributes  &  registerCallbackPattern?  &  unregisterCallbackPattern?    
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Absolute object name for the mixin. String (see below) yes none
scope Whether this feature is instance-based or static. Defined in Common attributes section.
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.
pattern_attributes Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter.
registerCallbackPattern Specifies the name pattern for the event handler registration function. Defined in Properties chapter.
unregisterCallbackPattern Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter.

Attribute details

'name' attribute

The name attribute specifies the absolute object name for the mixin using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq" which is set up as a JavaScript class with an appropriate constructor function). The name MUST be globally unique within the context of a particular JavaScript library.


<namespace>

The <namespace> element can be used to describe a JavaScript object that is a base object for other JavaScript classes but which itself is not a class (i.e., there is no constructor which creates instances of this object). For example, suppose there is a class named "MyLibrary.io.xhr" where the "xhr" object has a constructor, but "MyLibrary" and "io" do not. In this case, "MyLibrary" and "MyLibrary.io" are candidates for the <namespace> element.

Schema

namespace_element = element namespace {
  namespace_content  &  namespace_attributes  &  foreign_nodes
}
namespace_content = (
  descriptive_elements
)
namespace_attributes = (
  name  &  visibility?
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Absolute object name for the namespace. String (see below) yes none
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.

Attribute details

'name' attribute

The name attribute specifies the absolute object name for the namespace using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq"). The name MUST be globally unique within the context of a particular JavaScript library.


<parameter>

The <parameter> element describes a parameter to a JavaScript function.

Schema

parameter_element = element parameter {
  parameter_content  &  parameter_attributes  &  foreign_nodes
}
parameter_content = (
  descriptive_elements  &  compatibility_elements  &  
  option_element*  &  options_element*  &  
  parameter_element*  &  parameters_element*  &  property_element*  &  properties_element*  &
  returnType_element*  &  returnTypes_element*
)
parameter_attributes = (
  datatype?  &  name  &  usage?  &
  datatype_supplemental_attributes
)

Child content

This element might contain any of the following sub-elements:

This element MAY contain <property> or <properties> sub-elements only when the datatype attribute is set to or allows the value type "Object". In this case, the <property> elements provide descriptive detail about the various properties on the Object.

This element MAY contain <parameter>, <parameters>, <returnType> or <returnTypes> sub-elements only when the datatype attribute is set to or allows the value type "Function". In this case, the <parameter> and <returnType> elements provide descriptive detail about the parameters and return types for the Function.

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Name of the parameter. String (see below) yes none
datatype Allowed datatype(s) for the parameter. String (see below) no String
usage Whether the parameter is required or optional and whether a variable number of values may be provided. required|optional|zero-or-more|one-or-more no required
datatype_supplemental_attributes Various attributes that provide additional information about the datatype, such as min and max values. Defined in Datatypes chapter.

Attribute details

'name' attribute

The name attribute specifies the name of the parameter. The name MUST be globally unique within the context of current container object.

'datatype' attribute

The datatype attribute specifies the allowed datatype(s) for the parameter. See the Datatypes chapter for the detailed definition of this attribute.

'usage' attribute

The usage attribute specifies whether the parameter is required or optional and whether a variable number of values may be provided (i.e., zero-or-more or one-or-more). Permissible values are:

  • required (the default value for this attribute)
  • optional
  • zero-or-more
  • one-or-more

Example

<method name="animate" scope="instance">

  <shortDescription>A function for making custom animations.</shortDescription>

  <parameters>
    <parameter name="params" datatype="Object" usage="required">
      <description>A set of style attributes that you wish to animate, and to what end.</description>
      <properties>
        <property name="duration" datatype="String|Number" defaultValue="normal">
          <description>A string representing one of the three predefined speeds 
                       ("slow", "normal", or "fast") or the number of milliseconds 
                       to run the animation (e.g. 1000).</description>
        </property>
        <property name="easing" datatype="String" defaultValue=""swing"">
          <description>The name of the easing effect that you want to use (plugin required). 
                       There are two built-in values,  "linear" and "swing".</description>
        </property>
        <property name="complete" datatype="Function" defaultValue="">
          <description>A function to be executed whenever the animation completes, executes 
                       once for each element animated against.</description>
        </property>
        <property name="step" datatype="Function" defaultValue="" />
        <property name="queue" datatype="Boolean" defaultValue="true">
          <description>Setting this to false will make the animation skip the queue 
                       and begin running immediately. (Added in jQuery 1.2)</description>
        </property>
      </properties>
    </parameter>

    <parameter name="options" datatype="Object" usage="required">
      <description>A set of options with which to configure the animation.</description>
      <properties>
        <property name="duration" datatype="String|Number" defaultValue="normal">
          <description>A string representing one of the three predefined speeds 
                       ("slow", "normal", or "fast") or the number of milliseconds 
                       to run the animation (e.g. 1000).</description>
        </property>
        <property name="easing" datatype="String" defaultValue="swing">
          <description>The name of the easing effect that you want to use (plugin required). 
                       There are two built-in values,  "linear" and "swing".</description>
        </property>
        <property name="complete" datatype="Function" defaultValue="">
          <description>A function to be executed whenever the animation completes, executes 
                       once for each element animated against.</description>
        </property>
        <property name="step" datatype="Function" defaultValue="" />
        <property name="queue" datatype="Boolean" defaultValue="true">
          <description>Setting this to false will make the animation skip the queue 
                       and begin running immediately. (Added in jQuery 1.2)</description>
        </property>
      </properties>
    </parameter>
  </parameters>

  <returnType datatype="jQuery"/>
</method>


<returnType>

The <returnType> element specifies the datatype of and descriptive information about the value that a method returns.

Schema

returnType_element = element returnType {
  returnType_content  &  returnType_attributes  &  foreign_nodes
}
returnType_content = (
  descriptive_elements  &  
  parameter_element*  &  parameters_element*  &  property_element*  &  properties_element*  &  
  returnType_element*  &  returnTypes_element*
)
returnType_attributes = (
  datatype  &  paramName?  &  paramValue?  &
  datatype_supplemental_attributes
)

Child content

This element might contain any of the following sub-elements:

This element MAY contain <property> or <properties> sub-elements only when the datatype attribute is set to or allows the value type "Object". In this case, the <property> elements provide descriptive detail about the various properties on the Object.

This element MAY contain <parameter>, <parameters>, <returnTypes> or <returnTypes> sub-elements only when the datatype attribute is set to or allows the value type "Function". In this case, the <parameter> and <returnType> elements provide descriptive detail about the parameters and return types for the Function.

Attribute summary

AttributeDescriptionTypeRequiredDefault
datatype Datatype for the value that the method returns. String (see below) yes none
paramName Name of the parameter on which the datatype depends (for factory methods; see below). String yes none
paramValue Value of the parameter on which the datatype depends (for factory methods; see below). String yes none
datatype_supplemental_attributes Various attributes that provide additional information about the datatype, such as min and max values. Defined in Datatypes chapter.

Attribute details

'datatype' attribute

The 'datatype' attribute specifies the datatype of the value that the method returns. The detailed specification for the 'datatype' attribute can be found in the Datatypes chapter.

Note, however, for the <returnType> element, the datatype attribute includes one additional feature that targets factory methods, where the datatype attribute can reference one of the method's parameters. See Factory methods below.

'paramName' and 'paramValue' attributes

The paramName and paramValue attributes target factory methods where the datatype of the return value is dependent on a parameter whose possible values consists of an enumeration. See Factory methods below.


Factory methods

The <returnType> element includes special rules to describe factory methods where the return value from the factory method depends on one of the parameters passed into the function. The potential cases are outlined below.

Case 1: Simple factory method

For this case:

  • The string value of the datatype attribute MUST exactly match the string value of the name attribute on one of the <parameter> elements for this method.
  • The <returnType> element does not include attributes paramName and paramValue.

If the string value of the <returnType> element's datatype exactly matches the name attribute on one of the <parameter> elements (and the <returnType> element does not include paramName and paramValue attributes), then the return value from the method is an instance object for the class identified by the value of the referenced <parameter>.

To illustrate the simple factory method case where the referenced parameter identifies the class using a String, suppose you have the following method definition:

<method name="classFactory1">
  <parameter name="classToInstantiate" datatype="String"/>
  <returnType datatype="classToInstantiate"/>
</method>

and suppose that this method might be invoked at runtime by any of the following:

[1] myShape = classFactory1('acme.graphtools.circleClass');
[2] myShape = classFactory1('acme.graphtools.rectClass');

In [1] above, the classFactory1 method returns an instance object for the acme.graphtools.circleClass class, whereas [2] returns an instance object for the acme.graphtools.rectClass class.

The next example illustrates the situation where the referenced parameter identifies the class constructor function instead of a String (i.e., datatype="Function"):

<method name="Sys.Component.create">
  <parameter name="componentType" datatype="Function"/>
  <parameter name="properties" datatype="Object" />
  <parameter name="events" datatype="Object" />
  <parameter name="references" datatype="Object" />
  <parameter name="element" datatype="HTMLElement" />

  <returnType datatype="componentType"/>
</method>

Suppose that this method might be invoked at runtime by the following:

Sys.Component.create(Sys.UI.DataView, null, null, null, document.getElementById("someDiv"));

The above code would return an instance of the Sys.UI.DataView class.

Case 2: Factory methods using paramName and paramValue

The paramName and paramValue attributes target the factory method scenario where the datatype of the return value is dependent on a parameter whose possible values consist of an enumeration. If paramName and paramValue are provided, then the method returns an instance object for the class identified by the datatype attribute specified on the <returnType> element whose paramName exactly matches the name attribute of one of the <parameters> elements and whose paramValue attribute exactly matches the value of that parameter. For this scenario, typically the <method> element will have multiple <returnType> sub-elements.

To illustrate, suppose you have the following method definition:

<method name="create">
     <parameter name="classToInstantiate" datatype="String">
       <options>
         <option value="beta.database"/>
         <option value="beta.desktop"/>
         <option value="beta.geolocation"/>
         <option value="beta.httprequest"/>
         <option value="beta.localserver" />
         <option value="beta.timer" />
         <option value="beta.workerpool"/>
       </options>
     </parameter>
     <returnType paramName="classToInstantiate" paramValue="beta.database" datatype="Database"/>
     <returnType paramName="classToInstantiate" paramValue="beta.desktop" datatype="Desktop"/>
     <returnType paramName="classToInstantiate" paramValue="beta.geolocation" datatype="Geolocation"/>
     <returnType paramName="classToInstantiate" paramValue="beta.httprequest" datatype="HttpRequest	"/>
     <returnType paramName="classToInstantiate" paramValue="beta.localserver" datatype="LocalServer"/>
     <returnType paramName="classToInstantiate" paramValue="beta.timer" datatype="Timer"/>
     <returnType paramName="classToInstantiate" paramValue="beta.workerpool" datatype="WorkerPool"/>
</method>

and furthermore suppose at runtime this method can be invoked by any of the following:

[1] var db = google.gears.factory.create('beta.database');
[2] var desktop = google.gears.factory.create('beta.desktop');
[3] var geo = google.gears.factory.create('beta.geolocation');
[4] var request = google.gears.factory.create('beta.httprequest');
[5] var localServer = google.gears.factory.create('beta.localserver');
[6] var timer = google.gears.factory.create('beta.timer');
[7] var wp = google.gears.factory.create('beta.workerpool');

If create() is invoked using [1] (i.e., when 'beta.database' is passed as the parameter), then the class factory returns an instance object from class Database, whereas using [7] (i.e., when 'beta.workerpool' is passed as the parameter), then the class factory returns an instance object from class WorkerPool.

Note that paramName and paramValue do not require the use of an enumeration (i.e., <options> and <option> elements). These attributes can also be used on parameters whose datatype is String that do not specify a discrete list of available options.

The metadata file is incorrectly formulated (i.e., in error) in the following situations: (a) if only one of paramName or paramValue is specified; (b) when paramName does not match one of the method's parameters; and (c) when a discrete enumeration is specified and paramValue does not match one of the enumerated values for the parameter.

Developer tools MUST first look to see if the specified datatype matches one of the parameter names, and then determine if the specified datatype matches other possible values (e.g., one of the ECMAScript core datatypes or the name of a JavaScript class).


<singleton>

The <singleton> element describes a JavaScript object that functions like a <class> in that it might include its own APIs, such as method and properties, but unlike <class>, does not include the ability to construct new instances of itself.

Schema

singleton_element = element singleton {
  singleton_content  &  singleton_attributes  &  foreign_nodes
}
singleton_content = (
  descriptive_elements  &  compatibility_elements  &  
  alias_element*  &  aliases_element*  &  ancestor_element*  &  ancestors_element*  &  
  config_element*  &  configs_element*  &  
  event_element*  &  events_element*  &  mix_element*  &  mixes_element*  &  
  method_element*  &  methods_element*  &  property_element*  &  properties_element*
)
singleton_attributes = (
  name  &  visibility?  &
  pattern_attributes  &  registerCallbackPattern?  &  unregisterCallbackPattern?    
)

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Absolute object name for the singleton. String yes none
pattern_attributes Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter.
registerCallbackPattern Specifies the name pattern for the event handler registration function. Defined in Properties chapter.
unregisterCallbackPattern Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter.
visibility Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.

Attribute details

'name' attribute

The name attribute specifies the absolute object name for the singleton. The name MUST be globally unique within the context of a particular JavaScript library.



<--previous       contents--^       next-->
Personal tools