Relationship Resource Providers

Relationships between resources can be modeled as relationship resource providers. Each relationship resource provider handles the relationship between resources playing specified roles.

For instance, you might have an Ownership relationship between an Owner role and an Ownables role. Relationship resource providers that provide an Ownership relationship are tagged with a Relationship:Ownership model tag that denotes this. Similarly, resource providers whose resources can play Owner and Ownables roles are tagged with Role:Owner and Role:Ownables tags, respectively. Resource providers handle Role and Relationship model tags differently by inheriting these tags from all parent thing templates and thing shapes (model tags are normally not inherited).

For instance, in the Ownership relationship example, if the Owner role providers provide Id and Name fields and the Ownables role providers provide Id and Number fields, then the relationship resource provider provides Id, Owner-Id, Owner-Name, Ownables-Id, and Ownables-Number fields.

Relationship resource providers are themselves, resource providers. However, in addition to the base data fields specified by Resource Provider (for example, "Id"), relationship resource providers also provide the fields of the resources which play a role in the relationship.

Note

The dash ("-") character is used as a separator between role names and normalized role field names. As such, use of the dash character in role names is not supported.

Services common to all resource providers also apply to relationship resource providers, unless specifically noted. These services allow you to query for, create, and delete relationships between other resources.

Relationship providers support the use of a "joinType" entry in "extraParams" with the Get() and GetById() services. Supported (case-insensitive) values are: "inner", "leftouter", "rightouter", and "full_outer". This entry modifies the results as you would expect with a SQL join. The default behavior when this entry is not specified is that of an inner join.

For other resource providers, it is appropriate to address a specific resource provider when creating resources. However, for relationship resources, this is not recommended. If you have a collection of Owner and Ownable resource pairs from several disparate resources providers, you should not have to determine which specific relationship resource provider instance handles the relationship for each pair of role providers. Instead, you can use the CallServiceByCriteria service on the Resource Manager to call Create on all Ownership relationship resource providers (by model tag) and each relationship resource provider then in turn create the relationships it is responsible for.

Relationship resource providers also provide additional services beyond other resource providers. The GetRoles service provides information about the relationship's roles. The InflateFromRole service takes a set of resources of one role and returns the corresponding relationship resources.

Key-Based Relationship Resource Provider

KeyBasedRelationshipResourceProvider handles one-to-many (and one-to-one) relationships where the relationship is represented as one or more equi-joined key fields in the role resources. In the Ownership example, the Owner role resources can have a Name field, and the Ownables role resources can have an OwnerName field equi-joined to it.

As part of configuring a key-based relationship resource provider, you can specify the roles using a model tag, with one side of the one-to-many relationship specified first. In the Ownership example, this means that the Owner tag should be specified first. You must also specify the fields in each role that are to serve as join keys, being sure to keep the same relative order in the case of a multi-field join. The relationship resource provider will only be applied to role providers which provide (as reflected by their GetResourceDataShape() service) the key fields required for that role. You can further restrict the applicable role resource providers by specifying additional model tags the role resource providers are required to have.

KeyBasedRelationshipResourceProvider currently does not support the Update service. Also, its Create service only creates relationships; it will neither create new role resources or modify non-key fields in role resources, so you must only pass fields for the ID of each role resource to Create.

Link-Based Relationship Resource Provider

LinkTableBasedRelationshipResourceProviderTemplate handles many-to-many relationships where the relationship is represented in a link-table (also known as join-table) like resource. It can also be used to represent a one-to-many or even one-to-one relationship in cases where the relationship cannot be reflected directly in either role resource. Since a separate link resource is used, it can convey as many attributes about the relationship as necessary.

To configure a LinkTableBasedRelationshipResourceProvider, specify two KeyBasedRelationshipResourceProviders. Each one should join one side of the relationship and the link resource and each should denote the link resource as its second role. The two KeyBasedRelationshipResourceProviders should be configured to share common resource providers for their second role. The first roles of the KeyBasedRelationshipResourceProviders become the roles (in the order specified) of the LinkTableBasedRelationshipResourceProvider. This approach avoids limiting this provider to specific join keys or link-table storage mechanisms. Otherwise, the LinkTableBasedRelationshipResourceProvider behavior is very similar to that of the KeyBasedRelationshipResourceProvider.

Expands

Data from the other side of a relationship can be incorporated into a Resource Provider service result through the use of the "expands" terms. For more information, see extraParams Service Parameter.