Page Comparison

#. Gadget Lifecycle Events
 
The Gadget Lifecycle Event capability allows an OpenSocial
server and container to send notifications to a remote endpoint
of the gadget developer's choosing whenever events significant
to the lifecycle of an individual instance of the gadget occur.
Such notifications can be used for a variety of purposes, including,
but not limited to, the provisioning of additional resources external
to the container that instances of the gadget require to operate.
 
Every instance of a gadget processed and rendered by a container 
follows the same basic general lifecycle:
 
  Pending
    occurs prior to a gadget specification document
    being "Registered" with the container. This is an intermediate step in
    a gadget's lifecycle that occurs, for example, when a gadget developer
    first submits the gadget specification to the container, or when an
    Embedded Experience that references a previously unknown gadget specification
    is encountered, and that specification has not yet been processed. This
    phase in the lifecycle implies that additional action might be required
    before the gadget specification can be considered to be "Registered".


  Rejected
    occurs when "Registration" of a "Pending" 
    gadget specification cannot be completed for any reason. For instance, 
    if the registration of the gadget is rejected by an administrator.


  Registered
    occurs after the container first becomes
    aware of the Gadget Specification Document. For instance, when an 
    administrator adds a gadget specification to a catalog of available 
    gadget's, or when a previously unknown gadget specification is 
    referenced within an Embedded Experience currently being processed
    by a container.

  Available
    occurs when the gadget specification becomes
    available for use by the container. In order to be considered 
    "Available", a gadget specification MUST have first passed
    through the "Registered" phase. There are a number of actions 
    that can trigger the availability of a gadget specification such 
    as an administrator approving the registration or adding the gadget
    to a "whitelist" of acceptable gadgets.

  Unavailable
    occurs when the gadget specification becomes
    unavailable for use by the container. Unavailable gadgets are known 
    to the container ("Registered") but cannot be used for some reason. 
    Examples include gadgets that have been added to a "blacklist" or 
    have otherwise been disabled for some reason.

  Updated
    occurs whenever the gadget specification known
    to the container has been updated. This can happen whenever a new 
    version of the gadget specification is provided to the container.


  Installed
    occurs when a specific instance of a gadget 
    is provisioned for use. For instance, when an instance is added to a 
    page. Only "Available" gadgets can be "Installed". Installing a gadget
    is not the same as "opening" or "rendering" the gadget.

  Configured
    occurs whenever the configuration details for 
    an installed gadget have been modified.

  Restriction
    occurs whenever the functionality of a particular
    instance of the gadget has been restricted in some way. For instance, 
    if the operation of the gadget has caused it to exceed request rate 
    limitations or quotas and the container responds by limiting the 
    actions the gadget instance is permitted to perform. Another example
    could be when the container has limited the security policy permissions
    underwhich the instance of the gadget is operating.


  Opened
    occurs whenever an "Installed" instance of a 
    gadget is opened or rendered by the container.

  Closed
    occurs whenever an "Installed" instance of a 
    gadget is closed by the container. Note that closing a gadget is not the 
    same as uninstalling it. A closed gadget can be reopened later.

  Uninstalled
    occurs when a provisioned instance of a 
    gadget is destroyed. This lifecycle event implies that all resources
    associated with a specific gadget instance are to be deallocated.


  Unregistered
    occurs when a "Registered" gadget specification
    is removed from the container.
 
A gadget developer can indicate interest in receiving notification 
whenever any of these lifecycle events occur by using the <Link>
element. Containers are not, however, required to send lifecycle event 
notifications and MAY ignore any &lt;Link&gt; element specifying an
event identifier.
 
The optional "method" attribute can be specified on the <Link>
element to indicate the HTTP request method to be used when sending 
the event notification. Valid values are either "GET" or "POST". When
not specified, the default is assumed to be "GET".
 
For example,

  <Module>
    <ModulePrefs>
      ...
      <Link rel="org.opensocial.event" href="http://example.org/event" method="POST" />
      <Link rel="org.opensocial.event.registered" href="http://example.org/event/registered" />
      <Link rel="org.opensocial.event.unregistered" href="http://example.org/event/unregistered" />
      ...
    </ModulePrefs>
    <Content type="html">
      ...
    </Content>
  </Module>

The "rel" attribute on the <Link> element identifies the type 
of event the gadget developer is interested in receiving. The event 
identifier syntax used as the value of the rel is:
 
  segment = 1*( ALPHA / DIGIT )
  prefix = segment *("." segment ) "."
  name = segment *("." segment)
  event = [prefix] "event" [ "." name ]
 
This specification defines the following event identifiers:
 
  org.opensocial.event.pending
      Identifies the "Pending" lifecycle event.


  org.opensocial.event.rejected
      Identifies the "Rejected" lifecycle event.


  org.opensocial.event.registered
      Identifies the "Registered" lifecycle event.


  org.opensocial.event.available
      Identifies the "Available" lifecycle event.


  org.opensocial.event.unavailable
      Identifies the "Unavailable" lifecycle event.


  org.opensocial.event.updated
      Identifies the "Updated" lifecycle event.


  org.opensocial.event.installed
      Identifies the "Installed" lifecycle event.


  org.opensocial.event.configured
      Identifies the "Configured" lifecycle event.


  org.opensocial.event.restriction
      Identifies the "Restriction" lifecycle event.


  org.opensocial.event.opened
      Identifies the "Opened" lifecycle event.


  org.opensocial.event.closed
      Identifies the "Closed" lifecycle event.


  org.opensocial.event.uninstalled
      Identifies the "Uninstalled" lifecycle event.


  org.opensocial.event.unregistered
      Identifies the "Unregistered" lifecycle event.


  org.opensocial.event
      A specially defined "wildcard" that represents all other events using the "org.opensocial." prefix.
 
Use of the "org.opensocial." prefix is reserved by this specification.
Implementations MUST NOT use event identifiers that use the "org.opensocial."
prefix other than those defined above. Implementations are free to 
define additional event type identifiers that use prefixes other than 
"org.opensocial.".
 
#.# Lifecycle Event Notifications
 
Whenever a significant lifecycle event occurs for a particular
gadget specification, the container MAY send an event notification
to the IRI identified by any &lt;Link&gt; element provided by that 
gadget specification whose "rel" attribute values identifies the 
event. If the container supports sending event notifications, one
notification SHOULD be sent for each matching <Link> element.
 
For instance, given the following partial gadget specification:
 
  <Module>
    <ModulePrefs>
      ...
      <Link rel="org.opensocial.event" href="http://example.org/event" method="POST" />
      <Link rel="org.opensocial.event.registered" href="http://example.org/event/registered" />
      <Link rel="org.opensocial.event.unregistered" href="http://example.org/event/unregistered" />
      ...
    </ModulePrefs>
    <Content type="html">
      ...
    </Content>
  </Module>
        ]]>
 
When the gadget specification is registered within the container, 
two event notifications will be sent:

  - One to the endpoint "http://example.org/event" identified by
    the "org.opensocial.event" rel value, and
  - One to the endpoint "http://example.org/event/registered" identified
    by the "org.opensocial.event.registered" rel value.
 
Each event notification is sent as an HTTP request message using the
method declared by the <Link> elements "method" attribute. If the
"method" attribute is not specified, then the HTTP GET method is used.
 
The container MUST add the additional "eventtype" query string parameter
to the IRI specified by the <Link> element. The value MUST be 
the name part of the event identifier provided in the "rel" attribute
(e.g. if rel="org.opensocial.event.registered", then "eventtype" will 
equal "registered"). If the event identifier does not have a name 
component (as is the case with the special identifier 
"org.opensocial.event") then value of "eventtype" MUST be set to
a name specific to event that triggered the notification.
 
All event notification requests MUST be signed as specified by 
[SignedFetch].
 
In the example given, the notification sent to 
"http://example.org/event" will utilize the HTTP POST method:

  POST /event?eventtype=registered HTTP/1.1
  Host: example.org
 
  TODO: Finish Example


 
The notification sent to "http://example.org/event/registered"
will utilize HTTP GET:

  GET /event?eventtype=registered HTTP/1.1
  Host: example.org
 
  TODO: Finish Example

Responses to event notification requests are considered to be 
insignificant by this specification.
 
#.# Legacy Support

Previous version of this specification defined the following 
deprecated event identifiers that MAY continued to be supported
by containers for backwards compatibility:

  event
      Equivalent to "org.opensocial.event".


  event.addapp
      Equivalent to "org.opensocial.event.installed"

  event.removeapp
      Equivalent to "org.opensocial.event.uninstalled"

  event.app
      Provides an indication that some action
      has been performed on the gadget. The specific action performed
      is identified by adding an additional "action" parameter to the 
      GET or POST request. The valid "action" values are "enabled", 
      "disabled", "approved", "submitted", "rejected", "new" and 
      "banned".