Core Gadget - Gadget Lifecycle Events

This is a DRAFT PROPOSAL ... this is more than just a simple edit.. the current discussion of Gadget Lifecycle Events in the Core Gadget specification is pretty much pointless and useless as currently defined. The mechanism described here brings in new technical details and specifications but does so in a way that should be completely backwards compatible with whatever else is there... I think... it's hard to tell since the current stuff is pretty much useless....

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

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