3.3 Resource Query Service

   Resource descriptions are obtained from operations on the resource query service. The

   1.The use of an iterator and the details of its design in this specification are an attempt to follow the pattern established in other CORBA standards. However, there are slight differences between specifications in the way that the lifetime of the iterator is managed and the behavior of the next_n method.

   interface provides a family of three operations intended to be easy to use: get_values(), get_extent_values(), and get_related_values(). A fourth operation, get_descendent_values(), is a generalization of the other three and is capable of greater optimization.

   The resource query service is defined as follows:

   module DAFQuery

   { // properties and classes are represented by resource identifiers // imported from the identifiers module. typedef DAFIdentifiers::ResourceID ResourceID; typedef DAFIdentifiers::ResourceID ClassID; typedef DAFIdentifiers::ResourceID PropertyID; typedef DAFIdentifiers::ResourceIDSequence PropertySequence;

   // results are resource descriptions from the descriptions moduletypedef DAFDescriptions::ResourceDescription ResourceDescription;typedef DAFDescriptions::ResourceDescriptionIterator

   ResourceDescriptionIterator;

   // queries that perform navigation use the association conceptstruct Association{

   PropertyID property;ClassID type;boolean inverse;

   };typedef sequence<Association> AssociationSequence;

   // exceptions generated by queriesexception UnknownAssociation { string reason; };exception UnknownResource { string reason; };exception QueryError { string reason; };

   // the query serviceinterface ResourceQueryService {

   ResourceDescription get_values( in ResourceID resource, in PropertySequence properties) raises( UnknownResource, QueryError );

   ResourceDescriptionIterator get_extent_values(in PropertySequence properties, in ClassID class_id )raises (UnknownResource, QueryError);

   ResourceDescriptionIterator get_related_values( in PropertySequence properties, in Association assoc, in ResourceID source ) raises ( UnknownResource, UnknownAssociation, QueryError );

   ResourceDescriptionIterator get_descendent_values( in PropertySequence properties,

   in AssociationSequence path,

   in ResourceIDSequence sources,

   out AssociationSequence tail )

   raises ( UnknownResource, QueryError );

   }; };

   ResourceQueryService

   Each operation on this interface performs a single query. From a client’s perspective there is always exactly one resource query service in a given context. (The section on proxies describes how multiple data providers are handled. The section on service location defines what is meant by a context.)

   Each resource description returned by a query contains values for a subset of the properties requested. The property values appear in the same order as the properties that were passed to the query, although some may be omitted. A property value is omitted when it is not available from the data provider for the particular resource, or when the property identifier is unrecognized. This behavior makes it possible to federate multiple query services where each answers part of the query.

   On the other hand, if the property is recognized but the data provider detects that it is not a member of the resource’s class, the QueryError exception is raised. Similarly, QueryError is raised if the data provider determines that a property is many-valued (a resource description cannot represent multiple values for a property).

   get_values( )

   This query requests a resource description for a single resource given by its resource identifier. If the resource identifier is unknown to the data provider, the UnknownResource exception is raised.

   get_extent_values( )

   This query requests a description for each resource of a given class, that is, for each member of the class extent set. The class is given by its ClassID, which is a resource identifier.

• If the resource identifier is unknown to the data provider, the UnknownResource exception is raised.

• If it is recognized but does not represent a class, the QueryError exception is raised.

   get_related_values()

   This query requests a description for each resource associated with a given source resource. The source is specified by a ResourceID, and the association by an Association structure (defined below).

   The data provider evaluates the association for the source resource, which yields zero or more result resources. For each result resource the data provider evaluates the given properties and generates a resource description, which is returned through the iterator.

• If the source resource identifier is unknown to the data provider, the UnknownResource exception is raised.

• If the data provider does not recognize the property specified in the association, the UnknownAssociation exception is raised.

   Since data providers sometimes have only partial information, it is possible that the association is recognized but its value is not available for the given source resource. In that case, the UnknownAssociation exception is also raised. This distinguishes the case where no information is available from the case where the association value is empty.

   If the data provider detects an error in the association or determines that it is not type-compatible with the source resource (as defined below), the QueryError exception is raised.

   get_descendent_values()

   This query is a generalization of the foregoing queries and is designed for clients that form queries in a generic manner. It also provides the most opportunity for optimization on the part of the data provider.

   Comparison to other operations

   The inputs to the query are the properties, path, and sources sequences.

• When the path has length 0 and the sources sequence has length 1, this operation is equivalent to the get_values() operation.

• When the path and sources are both of length 1, this operation is equivalent to the get_related_values() operation. However, where get_related_values() would raise UnknownAssociation this operation returns a non-empty tail sequence.

• When path and sources are of length 1 and the path specifies the inverse of the rdf:type property, this operation is equivalent to the get_extent_values() operation.

   Normal Cases

   The get_descendent_values() operation requests a description for each resource in a result set. The result set is formed from the given set of source resources, by following a chain of associations. The source set is specified by a ResourceIDSequence, sources, and the chain of associations by an AssociationSequence path. If the length of the path argument is 0, the source set becomes the result set. Otherwise, the data provider evaluates the first association in the path for each source resource. This yields zero or more intermediate-result resources. For each intermediate-result the data provider evaluates the second association to yield another generation of intermediate-results. This process continues until the end of the association sequence is reached or an association is encountered that is not recognized or not available. In this way the query traverses a tree of resources.

   If all of the associations are recognized and available, the result set is the set of resources generated from the last association in the path. The data provider returns descriptions for the result set. For each, the data provider evaluates the given properties and generates a resource description, which is returned through the iterator. The query also returns an empty association sequence through its tail argument.

   Error Cases

   If an unknown or unavailable association is reached before the end of the path the query returns partial results. The result set is the set of resources generated from the last association in the path that was recognized and available. If the n’th association is unrecognized or unavailable for a particular resource, the result set is obtained from the

    n-1’th association. If the first association fails, the result set is the source set. A resource description containing no property values is generated for each resource in the result set and is returned through the iterator.

   An association sequence representing the failed part of the chain is returned through the tail argument. This tail sequence begins with the failed association and continues with the associations that follow it in the chain. The purpose of the tail is to enable proxy data providers (see Chapter 6) to complete the query by decomposing it and retrying the parts, through other data providers.

   Exceptions are raised in limited circumstances. If any of the source resource identifiers is unknown to the data provider, the UnknownResource exception is raised. If the data provider detects an error in the association sequence (as defined below) or detects that the first association is not type-compatible with the source resource, the QueryError exception is raised.

   Association

   An association is a mapping from source set of resources to a destination set of resources. It contains a property and a class, each represented by their resource identifier. The interpretation of the property depends on the inverse member, a boolean. In any case, the property range must be a resource, not a literal type. It may be single-valued or many-valued. An association may be evaluated in the context of a source resource to yield a set of zero or more destination resources. There are two cases:

   Inverse is false

   If inverse is false, the value or values of the property for the source resource are obtained. If the association class is not a null resource identifier, then the results are further restricted to be members of that class.

   The association is said to be type-compatible with the source resource if the type of the source resource is the same or a sub-class of the property’s domain class.

   Inverse is true

   If inverse is true, the inverse of the property is evaluated. All resources are obtained for which the property value is the source resource. If the association class is not a null resource identifier, then the results are further restricted to be members of that class.

   The association is said to be type-compatible with the source resource if the type of the source resource is the same or a sub-class of the property’s range class.

   The association class can be used to deal with a common pattern in schema which employ inheritance, such as the EPRI CIM, where the property range is a general class but the query addresses one of its more specific derived classes. If an EPRI CIM application wants all GeneratingUnits belonging to a given Substation, it must query the Substation.MemberOf property. But the range of this property includes all kinds of PowerSystemResource, so the association class can be used to limit the result to GeneratingUnits.

   AssociationSequence

   An association sequence defines a mapping from a source set of resources via zero or more intermediate sets, to a destination set of resources.

   An association sequence is evaluated by repeated application of the procedure defined for a single association. Beginning with the source resource, the first association in the sequence is evaluated yielding a set of intermediate resources. For each of these the second association is navigated and the results concatenated forming a multi-set. Duplicates may or may not be eliminated from this intermediate result reducing it to a proper set. The get_descendent_values() query does not eliminate duplicates. The next association is then evaluated and the procedure is repeated for each subsequent association.

   If any step in the sequence can yield resources that are not type-compatible with the next association in the sequence, then the association sequence is in error.