Tcl OData Documentation — Entity Handler Command Interface

OData Handler Command Interface Specifications

SYNOPSIS

command subcommand providerInstance entitySetName ?args...?

The following subcommands must be supported:

getEntity
getEntitySet
supports

The following subcommands may be supported:

destroy
createEntity
deleteEntity
getRelationshipSet
invokeAction
invokeFunction
patchEntity
updateEntity

DESCRIPTION

The handler for an entity set must conform to the API described in this interface. It is assumed that the handler is either a class or namespace ensembly -- but not requried to be so.

Required — Get an Entity

command getEntity providerInstance entitySetName keyDict

This subcommand fetches a single entity. It must return a dictionary with with the following format:

Headers: A dictionary whose keys are header properties and whose values are the corresponsding value. This is an optional entry.
Entity: A dictionary where the keys are the propteries and the value for the key is that property's value.

Required — Get an Entity Set

command getEntitySet providerInstance entitySetName queryDict

This subcommand fetches a set (aka collection, aka query result) of entities. It must return a dictionary with the following format:

Headers: A dictionary whose keys are header properties and whose values are the corresponsding value. This is an optional entry.
EntitySet: A list of dictionaries, where each dictionary represents a single entity. The keys of the dictionaries are the propteries and the value for the key is that property's value.

Required — Get Supported Options

command supports providerInstance entitySetName

This command returns a dictionary whose keys are as follows and whose values are a Boolean that if true indicate the feature is supported.

Create: Creation of Entities is supported.
Delete: Deletetion of an Entity is supported.
Update: A full record update on an Entity is supported.
Patch: A parial (aka patch) update on an Entity is supported.

Optional — Cleanup

command cleanup providerInstance entitySetName

This subcommand is invoked when the providerInstance is destroyed so that the handler can do any required cleanup.

Optional — Create an Entity

command createEntity providerInstance entitySetName entityDict

This subcommand creates the entity specified (depending on your particular implementation the keys may be specified or may be generated by you, i.e. an ID that is a sequence in yur database) and returns as its result a dictionary representing the entity (with keys filled in) with the following format:

Headers: A dictionary whose keys are header properties and whose values are the corresponsding value. This is an optional entry.
EntitySet: A list of dictionaries, where each dictionary represents a single entity. The keys of the dictionaries are the propteries and the value for the key is that property's value.

Optional — Delete an Entity

command deleteEntity providerInstance entitySetName keyDict ?changeSetTag?

This subcommand deletes the entity specified and returns an empty string for its result if successful. If the deletion failed, an appropriate error message should be returned as the result and an error raised.

Optional — Get a Relationship Set of an Entity

command getRelationshipSet providerInstance entitySetName keyDict relationshipName queryDict

This command is only optional if no Relastionships are defined for the Entity Set. If any Relationships are defined for the Entity Set, then this subcommand MUST be defined and MUST return a result for the defined relationships.

For the defined relationships, the subcommand fetches a set (aka collection, aka query result) of entities. It must return a dictionary with the following format:

Headers: A dictionary whose keys are header properties and whose values are the corresponsding value. This is an optional entry.
EntitySet: A list of dictionaries, where each dictionary represents a single entity. The keys of the dictionaries are the propteries and the value for the key is that property's value.

Optional — Invoke a Bound Action on an Entity

command invokeAction providerInstance entitySetName keyDict actionName parameterDict

This command is only optional if no Bound Actions are defined for the Entity Set. If any Bound Actions are defined for the Entity Set, then this subcommand MUST be defined and MUST return a result for the defined Bound Action.

For the defined Bound Action, the subcommand invokes the action on the specified entity. It must a return value of the type defined for that action, where if the type is:

Simple Type: A string value for that type.
Collection of Simple Type: A Tcl list of string value for that type.
Complex Type or Entity: A dictionary representing that type where the keys are the propteries and the value for the key is that properties' value.
Collection of Complex Type or Entity: A Tcl list of dictionaries representing that type where the keys are the propteries and the value for the key is that properties' value.

Optional — Invoke a Bound Function on an Entity

command invokeFunction providerInstance entitySetName keyDict FunctionName parameterDict

This command is only optional if no Bound Functions are defined for the Entity Set. If any Bound Functions are defined for the Entity Set, then this subcommand MUST be defined and MUST return a result for the defined Bound Function.

For the defined Bound Function, the subcommand invokes the function on the specified entity. It must a return value of the type defined for that function, where if the type is:

Simple Type: A string value for that type.
Collection of Simple Type: A Tcl list of string value for that type.
Complex Type or Entity: A dictionary representing that type where the keys are the propteries and the value for the key is that properties' value.
Collection of Complex Type or Entity: A Tcl list of dictionaries representing that type where the keys are the propteries and the value for the key is that properties' value.

Optional — Do a "Patch" Update of an Entity

command patchEntity providerInstance entitySetName keyDict changeDict ?changeSetTag?

This subcommand updates the entity specified with the values supplied in changeDict and returns an empty string for its result if successful. If the updated failed, an appropriate error message should be returned as the result and an error raised.

Optional — Do a "Full" Update of an Entity

command updateEntity providerInstance entitySetName keyDict entityDict ?changeSetTag?

This subcommand updates/replaces the entity specified with the values supplied in entityDict and returns an empty string for its result if successful. If the updated failed, an appropriate error message should be returned as the result and an error raised.

NOTE — the entityDict must have all of the properties of the entity specified even if a given property is not changing.