3.2 Resource Descriptions

   All DAF queries return results in the form of resource descriptions.

   module DAFDescriptions { // ... see the previous section for first part of the module

   // properties are represented by their resource identifiers typedef ResourceID PropertyID;

   // predicate and object for a resource description struct PropertyValue {

   PropertyID property;

   SimpleValue value; }; typedef sequence<PropertyValue> PropertyValueSequence;

   // resource description with one subject, multiple predicates struct ResourceDescription {

   ResourceID id;

   PropertyValueSequence values; }; typedef sequence<ResourceDescription> ResourceDescriptionSequence;

   // iterator for handling large numbers of resource descriptions interface ResourceDescriptionIterator {

   unsigned long max_left();

   boolean next_n( in unsigned long n, out ResourceDescriptionSequence descriptions );

   void destroy(); }; };

   PropertyValue, PropertyValueSequence

   A property value specifies a property by its resource identifier and its associated value for a given resource. The types ResourceID and SimpleValue are defined in the DAFBasic module.

   ResourceDescription, ResourceDescriptionSequence

   Each resource description identifies a single resource, by its resource identifier, and zero or more property values for that resource. The properties must be single valued, no provision is made for returning more than one value per property within a resource description. The class of the resource can be included in the resource description as the value of the type property (refer to the Schema chapter for details).

   ResourceDescriptionIterator

   Queries that return information about more than one resource return an iterator. The resource description iterator1 allows a client to access a large query result sequentially, several resources at a time. This is necessary where the ORB limits message sizes. It also enables implementations to overlap the client and server processing of query results, if necessary.

   The client and the data provider should cooperate to manage the lifetime of the iterator and the resources it consumes. The destroy() and next_n() methods allow the client and data provider respectively to indicate that the iterator may be destroyed.

   In addition, the data provider may autonomously destroy the iterator at any time (for resource management or other reasons). If a client detects that an iterator has been destroyed, it will not interpret this condition in itself as either an indication that the end of the iteration has been reached, or as a permanent failure of the data provider.

   next_n( )

   This operation returns possibly 0 and at most n resource descriptions in the form of a resource description sequence. In all cases the state of the iteration is indicated by the Boolean return value:

• True means that there may be more resource descriptions beyond those returned so far.

• False means all the resource descriptions have now been returned. No further calls are expected for this iterator and the data provider may destroy the iterator at any time after the call returns.

   destroy()

   This operation is used to terminate iteration before all the resource descriptions have been returned. After destroy() is invoked, no further calls are expected for this iterator. The data provider may destroy the iterator at any time after the call returns.

   max_left( )

   This operation returns an estimate of the number of resource descriptions remaining in the iteration. The result is intended to provide feedback in user interfaces or to select query strategies, but it cannot be used to detect the end of the iteration. Clients should allow that this operation might be expensive.