Tcl OData Item Class

This class is used by an instance of the OData service class, odata::Service, to create objects representing the results of queries on entity sets that are part of the service.

When entity sets are queried, the service class creates odata::Entity objects for each entity returned.

CONSTRUCTOR

The constructor of this class is private and should not be used except by an instance of the odata::Service class.

DESTRUCTOR

The destructor of this class is private and should not be used other than by an instance of the odata::Service class.

Please see the delete method.

EXPORTED METHODS

entity commit ?as patch|update? ?options...?

Writes any changed/new values of the object to the store as either a patch or update. Then sets the state to clean and hides the commit and rollback methods.

The following options are supported:

-callback command

This causes the commit to be invoked asynchronously. When the commit completes, the command is invoked with the following appended to it:

The http numeric return code.
The result, i.e. the http body, of the invocation.

entity delete

Request the OData Service to delete the entity (aka entity) and deletes this instance.

entity get propertyName

Returns the current value of the specified property.

entity info subCommand ?arg ...?

This command is used to query information about the service and its components. Valid subCommand are:

actions

Returns a list of bound actions for this entity.

action boundActionName

Returns a dictionary (see parameter dictionary) describing the parameters and return value of the action with the name boundActionName. If no such action exists, an error will be raised.

changed

This subcommand returns a list of which properties have been changed Each element in the list is a list consisting of:

propertyName — the name of the property that has been changed
oldValue — the value of the property as it was retrieved from the store
newValue — the current value of the property in the object

functions

Returns a list of bound functions for this entity.

function boundFunctionName

Returns a dictionary (see parameter dictionary) describing the parameters and return value of the function with the name bounFunctionName. If no such function exists, an error will be raised.

mode

Returns the mode of the object, which is either readonly or readonly.

properties

Returns a list of properties the entity.

property propertyName

Returns a dictionary that describes the specified property. The format of the dictionary is:.

Value

The value of the property.

Attributes

The value is a dictionary of attribute information where the key is the property name with the following structure:

Value: The value of the property.
Alias: The namespace alias of the property.
Namespace: The URI of the namespace of the property.

relationships

Returns a list of relationships for this entity.

relationship relationshipName

Returns a dictionary describing relationshipName. The dictionary is structured as follows:

Type: The type of entities (aka entities) that compose the relationship.

state

Returns the state of the entity, which is new, clean or dirty.

type

Returns the type of the entity.

entity invoke action|function boundName ?parameterDict?

Executes the action/function specified by boundName against this entity on the OData server with the arguments specified by parameterDict.

entity query relationshipName ?restrictionDict? ?options...?

This command is used to execute query on a relationshipName with the query and restrictions specified in restrictionDict. The keys and values of restrictionDict can be any of the query options (note that the leading "$" is part of the query option) as specified by OData Specification.

Additionally, the key Key is supported whose values is a dictionary where the keys are a property name of a key of the entity (aka entity) and the value is the key value. This can be used to select an individual entity (aka entity).

The following options are supported for easy of use:

-callback command: This causes the query to be performed asynchronously. When complete, the command will be called with the instance of the odata::EntitySet class containing the results appended to it.
-headers headerDict: This allows protocol header options, as defined by OData Protocol Specification, to be passed. The keys to the dictionary are the header item and the value for a key is the value for that header item.
-pageSize resultSetSize: This is basically the same as specifying the $top restriction key in the restrictionDict. It specifies the maximum number of entities to return. Note that you
-pageNumber startingPage: This option is only valid when -pageSize is specified. Page numbers start at zero (0). This is the same as specifying $skip as the result of resultSetSize multiplied by startingPage.
-sortBy propertyList: This is basically the same as specifying the $orderby restriction key in the restrictionDict except that the list of property names is a proper Tcl list instead of a comma separated list.

NOTE -- if the query that returned entity had an $expand entry in the restrictionDict and this relationship was in the list of relationships to expand and no restrictionDict or options are specified to this query subcommand, then the EntitySet for the relationship that was returned in the original query shall be returned as the result of the query subcommand (i.e. the server will not be "hit" with a query). If any of those conditions do not hold true, then a new query will be issued to the server.

entity propertyDict

This returns a dictionary describing all of the properties of the entity. The format of the dictionary is:.

Properties

The value is a dictionary of property information where the key is the property name with the following structure:

Value: The value of the property.

Attributes

The value is a dictionary of attribute information where the key is the property name with the following structure:

Value: The value of the property.
Alias: The namespace alias of the property.
Namespace: The URI of the namespace of the property.

entity refresh ?command?

Re-excute the query on the OData server and replaces the current contents of the entity with the results. If command is specified, the query to be performed asynchronously. When complete, the command will be called with the entity instance appended to it.

entity rollback

This method causes all pending changes to the entity to be discard. If the entity's state is new then the entity will be destroyed, otherwise the entity's state set to clean.

entity set propertyName value

An error will be raised if propertyName does not exist and the type of the entity does not allow for properties to be added. If propertyName does not exist and the type of the entity allows for properties to be added, then propertyName will be added as a property of the entity. Sets the value of the property to the specified value. Also sets the state to dirty, if it was clean, and makes visible the commit and rollback methods.

NON-EXPORTED METHODS

While the odata::Entity class has several non-exported methods, the are considered "private" and as such their APIs are subject to change without notice and not supported; thus the non-exported methods should not be used.

EXAMPLES

This example uses one of the sample services from the OData.org site show the use of the odata::Service class, an instance of that class and an instance of the odata::Entity class.

package require TclOO
set svc [odata::Service http://services.odata.org/TripPinRESTierService]
set entitySet [$svc query People {$orderby {LastName,FirstName}}]
foreach entityObj [$entitySet entities] {
    set lastName [$entityObj get LastName]
    set firstName [$entityObj get firstName]
    set userName [$entityObj get UserName]
    puts stdout "$firstName $lastName's user name is $userName"
}