ALF/CommonServices/Relationship

ALF Wiki Home

Introduction

The purpose of this service is to provide a mechanism for temporarily but robustly storing relationships between entities that are in use in an ALF application such that these relationships can be accessed across the span of the multiple service flows that might make up an ALF application.

Relationships

For the purpose of the Alf Relationship service, a relationship is a uniquely named collection of properties. Each relationship has a name which is scoped to the application in which it is created and an identity which is scoped to the relationship facility. The content of a relationship is a set of name value pair based properties. The name part of each property must be unique within the relationship. The value part of the property is typically set dynamically during the execution of the application and is arbitrary. By convention, separate properties that have the same name and the same value are considered identical and may be used to correlate across relationships within an application. That is, it is possible to find all the relationships within an application that contain a property that has a particular name and a particular value. To use this facility the application designer must be careful to use property names judiciously such that a relationship property with the same name has the same precise meaning wherever it occurs within the application definition.

Note: Is the idea of a “named relationship type” useful? That is, a named, predefined record of the names that can occur in the name value pair list. Two relationships that have the same type will have the same set of names in their property list. The values in the respective lists may differ. The typing of relationships would allow runtime enforcement of the set of names ensuring consistency and the ability to find all relationships of a certain type within an application. Relationship types may also be useful at design time as a way to coordinate usage of a set of names across the various Service Flow definitions that make up an application. The definition of relationship types would be set a deployment time when the application is registered with the Relationship service.

Lifespan of records

The intent of this store is to provide mechanism to enable dynamic relationship creation and lookup. It is not the intent to provide a permanent record of application activity. Applications should arrange to store their permanent record in some other system of record of their own choosing. The ALF relationship service records will store relationships by ALF application. As such they may be considered permanent for the lifespan of a particular application deployment. It is the responsibility of the application to remove any record it creates once that record is no longer required. The records will become invalid when the particular application is un-deployed. Depending on the implementation, un-deploying the application from the ALF event manager should typically result in deletion of the records created by the application in the ALF Relationship Service.

Relationship Service Operations

Add Relationship

string addRelationship(string applicationId, string relationshipName, nameValue[] properties)

The relationship is added to the relationship service as belongin to the given application. The relationship will have the given name and contain the set of given properties. If the applicationId given is not registered with the relationship service then ALFError.NoApplication is raised. If the relationshipName is not unique within the application then ALFError.RelationshipNotUnique is raised If there are duplicate names in the property list then ALFError.DuplicateProperties is raised

Update Relationship

void updateRelationship (string relationshipId, nameValue[] properties)

void updateRelationship (string applicationId, string relationshipName, nameValue[] properties)

A relationship may be identified by its unique ID or a by a combination of the application ID and relationship name. The properties of the identified relationship are updated to include the given properties. Where a property of the same name already exists, the value of the existing property is updated to reflect the new value. Otherwise the new property is added to the stored relationship. If the relationship does not exist ALFError.NoRelationship is raised. If the applicationId given is not registered with the relationship service then ALFError.NoApplication is raised.

Get Relationship

relationship getRelationship (string relationshipId)

relationship getRelationship (string applicationId, string relationshipName)

A relationship may be identified by its unique ID or a by a combination of the application ID and relationship name. The identified relationship is returned. If the relationship does not exist ALFError.NoRelationship is raised If the applicationId given is not registered with the relationship service then ALFError.NoApplication is raised.

Find Relationship

string[] findRelationships (string applicationId, nameValue property)

All the relationships within the identified application that contain a property with the same name and value are returned as an array of relationship IDs. The array will be empty if no relationships are found with a matching property. If the applicationId given is not registered with the relationship service then ALFError.NoApplication is raised.

Delete

void deleteRelationship (string relationshipId)

void deleteRelationship (string applicationId, string relationshipName)

A relationship may be identified by its unique ID or a by a combination of the application ID and relationship name. The identified relationship is deleted from the Relationship store. If the identified relationship does not exist in the relationship store, no action is taken If the applicationId given is not registered with the relationship service then ALFError.NoApplication is raised.

Relationship Service Admin Operations

Register Application

void registerApplication(string applicationID, string description)

The application is registered with the relationship store If the applicationId given is already registered with the relationship service then ALFError.DuplicateApplication is raised.

Un-Register Application

void unregisterApplication(string applicationID)

The application is unregistered from the relationship store. All stored relationships that belong to the identified application will be deleted

Get Applications

applicationDescriptor[] getApplications()

The applications registered with the relationship store is returned as an array of application descriptors. An application descriptor contains the application Id and the application description set when the application was registered.