Tcl OData Client Service class

The service class creates an object for an OData service. As part of the creation process the OData Service is queried for the types, entity sets, etc that are supported.

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

CONSTRUCTOR

The constructor of the odata::Service class takes a single argument which is the URL of the OData service. The URL must be accessible for the life of the created odata::Service object.

DESTRUCTOR

The odata::Service class' destructor will delete all remaining odata::EntitySet and odata::Entity instances created by this service.

This method is begins batch mode processing. From the time this method is invoked until a commit is done. All "writes" (i.e. inserts, updates/patches and deletes) are deferred and sent in as a single HTML transaction. NOTE -- begins may not be nested, an attempt to do so will cause an error to be raised.

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

This method sends deferred "writes" and takes the service out of "batch" mode. NOTE -- commit when not in "batch" mode will cause an error to be raised.

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.

svc count entitySetName ?restrictionDict?

This command is used to execute query on a entitySetName with the query and restrictions specified in restrictionDict and return the number of entities that would be in the entity set. 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.

Please note this is not the same as the restrictionDict $count key. Please also note that the $top and $top restriction key are removed when doing the query.

svc info subCommand ?arg ...?

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

ServiceAddress

Returns the URL of the service.

actions

Returns a list of unbound actions advertised by the service.

action unboundActionName

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

entitySet

Returns a list of collections advertised by the service.

entitySet entitySetName

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

Type: The type of items (aka entities) that compose the entity set.
Singleton: A boolean indicating if this entity sets represents a singleton.

functions

Returns a list of unbound functions advertised by the service.

function unboundFunctionName

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

types

Returns a list of types that the service uses.

type typeName item

This subcommand returns dictionary describing type. Valid keys are:

properties: Returns a list of the pairs that are the property name and its data type for this type.
relationships: Returns a list of other types that this type has a relationship to.
keys: Returns a list of the properties that are keys, if any, for this type.

unsaved

Returns a list of odata::Entity objects that have not been saved back to the OData Service.

svc insert entitySetName ?itemDict?

This creates a new odata::Entity instance, which is returned as the result of this method, of the type associated with entitySetName. The state of the instance is set to new and the mode is set to readwrite. Additionally the commit method is made visible on the object. If itemDict is present, then the properties of the instance are set to the values of itemDict. 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.

svc invoke action|function unboundName ?parameterDict? ?options...?

This command is used to invoke the action/function about the service and its components. The returned value is null for those action/functions that do not return a result, for those that do return a result it is the defined result (see the info command for information on how to query what the result of an action/function will be).

The following options are supported:

-callback command

This causes the action/function to be invoked asynchronously. When the action/function 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.

svc query entitySetName ?restrictionDict? ?options...?

This command is used to execute query on a entitySetName 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 and the value is the key value. This can be used to select an individual item 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 items to return in entity set. 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.

svc rollback

This method causes the rollback method to be invoked on all entities associated with this service that have changes pending. Future changes to entities associated with the service will not be batched (at least until another begin is issued).

NON-EXPORTED METHODS

While the odata::Service 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 and of an instance of that class.

set obj [::odata::Service new {http://services.odata.org/TripPinRESTierService/}]
puts stdout "The following entity sets are supported: [join [$obj info entityset] {,}]"

Tcl OData Documentation — OData Service Class

NAME

SYNOPSIS

CLASS HIERARCHY

DESCRIPTION

CONSTRUCTOR

DESTRUCTOR

EXPORTED METHODS

NON-EXPORTED METHODS

EXAMPLES

SEE ALSO

Parameter Dictionary