| Index: source/drafts/relation-reference.rst |
| === added file 'source/drafts/relation-reference.rst' |
| --- source/drafts/relation-reference.rst 1970-01-01 00:00:00 +0000 |
| +++ source/drafts/relation-reference.rst 2012-03-22 04:16:31 +0000 |
| @@ -0,0 +1,67 @@ |
| +Relation references |
| +=================== |
| + |
| +A service may **provide** an interface to multiple consuming services |
| +with the same relation name; each of these is a different established |
| +relation. For example, the ``mysql5`` service might provide the |
| +``mysql`` interface to multiple consuming clients using the relation |
| +name ``db``. When interacting with a given consuming client, relation |
| +hooks executing on ``mysql5`` service units in turn would be named |
| +``db-relation-joined``, ``db-relation-changed``, and |
| +``db-relation-departed``. In addition, the environment variable |
| +`$JUJU_RELATION` would be set to ``db``. |
| + |
| +This scenario implies that there is potential ambiguity in using the |
| +relation name to refer to the specific relation between a provider and |
| +a consumer. However, this ambiguity is currently rarely seen. This is |
| +because relation hooks are always executed in the context of a |
| +specific relation, as well as any settings on this relation. This |
| +locality avoids most ambiguity in actual usage. |
| + |
| +But ambiguity can arise in the following scenarios: |
| + |
| + * Relation hooks are used to change local state, so it is currently |
| + possible for the ambiguity in referring to a relation to become |
| + visible over cumulative hook executions. Using appropriate |
| + relation settings can be used to distinguish the consumer, so |
| + there is a workaround. |
| + |
| + * To enable the new feature of using relation hook commands to |
| + work with other relations, or for these hook commands to be used |
| + in nonrelation hooks, it is essential to have a nonambiguous |
| + reference. |
| + |
| +Therefore, to completely specify a relation, it is necessary to use |
| +its relation id, not the relation name. However, the use of relation |
| +ids is restricted: relation ids are only visible inside relation hooks |
| +and/or relation hook commands. |
| + |
| +To ensure readibility of the relation id, its format is specified to |
| +be:: |
| + |
| + <relation name>:<normalized internal relation id> |
| + |
| +Normalization removes any padding zeros from the internal id. |
| + |
| +Lastly, a new environment variable, `$JUJU_RELATION_ID`, will always |
| +be set to the relation id in the context of relation hooks. |
| + |
| +For example, if the relation is associated with relation name ``db`` and |
| +the specific interal relation id is ``relation-0000000042``, then the |
| +relation id is ``db:42``. The relation hooks ``db-relation-joined``, |
| +etc., will have `$JUJU_RELATION_ID` set to ``db:42``. In addition, |
| +this format further implies that relation id is not globally |
| +unique. If the provider uses the relation name ``db`` and a consumer |
| +uses the relation name ``database``, then for interal relation id |
| +``relation-0000000042``, ``db:42`` and ``database:42`` could both be |
| +in use. However, it is not intended that relation ids be shared, or |
| +even publicly visible to an admin, so this should not pose an issue. |
| + |
| + |
| +References |
| +---------- |
| + |
| +Motivation for relation ids is mentioned in `bug #767195: |
| +https://bugs.launchpad.net/juju/+bug/767195`_: Hooks must be able to |
| +enumerate and query relations. In addition, possible formats are |
| +discussed. |
