Retrieve a known business object from a collection.

• Name: read
• Alternate name(s): retrieve
• Other name(s): get

• e-Framework Service Genre Version: v1.0

The read service genre describes the process by which an application retrieves (reads) a business object, represented in a specified form, from a collection of such business objects. It is an example of a simple, request-response process.

A read service interface for the collection provides a mechanism for an external client to request the service instance to read and return a business object from the collection. The collection holds business objects with a common representation and structure, each of which can be accessed through a label associated with the business object in the collection. The label for the business object in the collection is denoted the access label.

The representation and encoding of the business object to be returned from the collection is fixed by the service expressions that specialise the read service genre. Within the read service genre, the business object is treated as a non-decomposable entity.

This is a general description of a read service genre, independent of application end point, collection, business object representation, or underlying communications protocols and service models. The service genre assumes the business object has a fixed representation but that representation is not specified by the service genre. The business object representation and encoding is defined in the service expressions that specialise the read service genre. All business objects in the collection shall have the same representation, as specified in the service expressions that specialise the service genre. The service genre does not include a mechanism to authenticate clients.

The read service genre is part of a set of related service genre, denoted collection services (add, read, replace, remove) that provide core functionality to maintain collections of business objects.

There is no expectation that all service implementations will be interoperable. Different service expressions MAY take different approaches to defining interfaces and data models.

Read services are typically used by an application that retrieves business objects from a maintained, structured collection of business objects that are known by and accessed through their associated access labels within the collection. A prototypical example of a collection is the rows (the business objects) in a database table (the collection) or a set of data objects (individual data instances) in a structured storage collection (an aggregate data type).

Read services are used in conjunction with other services that maintain the collection, such as adding, replacing (updating), or removing (deleting) business objects from the collection. The collection provides managed, persistent storage of the business objects in the collection. The collection services are used in the collection SUMs or an application to maintain the collection and to provide persistent storage of the collection of business objects and to support the other business functions defined in a SUM or application design.

Read services use the access label associated with each business object in the collection. The client is responsible for recording and communicating the access label to other collection services that maintain and access the business object in the collection.

The read service genre is applicable for retrieving one business object from a collection at a time. The read service genre is not applicable for retrieving multiple business objects from the collection in the same request.

The read service genre requires the association of a single access label with a business object in the collection so that the business object can be accessed within and retrieved from the collection. The read service genre is independent of how the access label is created and associated with the business object. These access labels need to be scoped only to the collection. Access labels that are unique within a broader scope or context, or persistent labels, may be used, but this is not a requirement. Multiple access labels for a single business object are not supported. There are no other requirements on the access label.

The read service genre does not define the meaning of identifiers, locators or labels associated with business objects in the collection. Service expressions that specialise the read service genre MAY choose to align access labels with meaningful attributes of business objects, but such alignment is not a requirement.

The business objects have a defined data representation in the collection. The read service genre is applicable when there is a single representation and a single encoding of a business object for all business objects in the collection. These representations and encodings are specified in service expressions that specialise the read service genre. The read service genre is not applicable where distinct representations or encodings are required for different business objects in the collection or when the service instance must transform between the business object representation of the collection and that of the client (such transformations may be performed by the client after retrieving the business object from the service instance).

The read service genre is applicable only when the service instance in bound to a single collection. The read service genre does not provide a way to use multiple collections via a single service instance.

The read service genre is applicable when multiple copies or identical instances of the business object are stored in the collection as long as each instance has a unique access label. The read service genre is applicable only when the access label identifies one business object in the collection.

The read service genre is applicable only when the business object is considered as non-decomposable; business objects are retrieved as a whole from the collection. Behaviour of the read service genre is not defined when parts of a business object in the collection are requested, but only when an entire business object is retrieved from the collection. Access to and maintenance of parts of a business object in a collection SHOULD be defined in separate service genres.

Use of a read service expression presupposes that the client and the service implementation have a common understanding of both the access label and the business object representation.

The read service genre assumes that the access labels associated with business objects in the collection are maintained and persisted by the clients that access the collection. There is no mechanism to retrieve or access the access labels associated with business objects in the collection. The read service genre is not defined when there is a requirement to discover, directly access or manage the access labels associated with business objects in the collection.

Behaviour of the read service genre is not defined when transactional integrity is required across multiple clients and collection operations. A SUM that combines the collection service genres MAY define transactional behaviours. As described there is no mechanism to provide ACID-safe (atomic, consistent, isolated and durable) transaction management of the collection.

Behaviour of the read service genre does not define how the collection is provisioned, instantiated or managed as a whole. Any provisioning and management model MAY be implemented.

Behaviour of the read service genre is not defined when the service instance requires authentication credentials be included in a service request. A SUM that combines the collection service genre with AAAI (authenticate, authorise, audit, identity) service genres MAY be defined to support an authenticated service request.

Behaviour of the read service genre is not defined when the collection requires its own authentication or authorisation processes to permit access to the collection. A SUM that combines the collection service genres with AAAI service genres MAY be defined to support authenticated and authorised access to the collection.

Behaviour of the read service genre is not defined if communications need to be secure.

The read service genre supports only a single function to retrieve a single business object from a collection.

A request SHALL specify:

• An access label associated with the business object to be retrieved from the collection (the access label was associated with the business object when it was added to the collection) [REQUIRED].

No other functionality is defined. The functionality that is defined MAY be extended. Major new or additional functionality SHOULD NOT be included in the service expressions that specialise the read service genre; extended capabilities SHOULD be defined in other service genres. In particular, logical business functions applied to a part of a business object in the collection, more complex collection models, batch and transactional behaviours, or operations applied to the collection as a whole SHOULD be defined in separate service genres.

The format and definitions for requests and responses SHALL be defined by the service expressions that specialise the read service genre. The specification of the behaviours required to support the requests and behaviours SHALL be defined in the service implementation designs for a service expression.

Requests and behaviours SHALL meet the following conditions:

• One Read Request SHALL be defined:
  
  Request Description:
  • The request SHALL include a single access label that is used to specify the single business object (or copy of it) to be returned from the collection.
    • The service expression SHALL specify the maximum size of the access label.
    • The service expression SHALL specify the representation of the access label.
  • The access label SHALL be necessary and sufficient to identify and access the business object in the collection, i.e., a client attempting to retrieve the business object from the collection need only specify the access label for the business object.
  
  Response Description:
  • If the requested business object exists in the collection, the response SHALL return a copy of the requested business object from the collection.
    • The service expression SHALL define the maximum size of a business object that can be returned from the collection.
  • The response SHOULD include a version identifier indicating the version of the service implementation being used.
    • The service expression SHALL specify the representation of the version identifier.
  • The response SHALL include error indicators or other needed control information.
    • Both success and failure indicators SHALL be provided.
  
  Behaviour Description:
  • The request SHALL fail if the access label provided in the request is not of the proper form (structural and representational validation, not a business rule validation).
  • The request SHALL fail if the access label provided in the request is not associated with a business object in the collection.
    • A business object SHALL be considered to exist in the collection if its access label is not associated with a business object in the collection.
  • A copy of the business object SHALL be returned by the service instance without transformation from the representation used in the collection. An identifier or locator that resolves to the business object SHALL NOT be returned.
    • The original business object SHALL be maintained in the collection. The collection SHALL NOT change.

The model for a client to interact with a service implementation SHALL be defined by the service expressions that specialise the read service genre.

The read service genre assumes the following logical data model for the collection:

• Business objects are stored within a managed collection. The physical manifestation of storage of the collection is hidden behind the service interface and is unknown to the client. Only the perception of managed, persistent storage is required. The storage manifestation and how the business objects in the collection are persisted is relevant only to the service implementation design. As such, an actual storage model SHALL NOT be specified in a service expression that specialises the read service genre.
• The collection SHALL support consistent behaviours across the other collection services bound to the same collection, e.g., other clients may add, replace or remove business objects in the collection. Behaviours are NOT REQUIRED to be ACID safe.
• Each business object in the collection SHALL be associated with an access label that discriminates the business object from all other business objects held in the collection.
  • An access label SHALL uniquely identify a single business object in the context of the collection.
  • A business object SHALL be considered to exist in the collection if its access label is associated with a business object in the collection.
  • For the purposes of management and access, the business object in the collection is opaque, i.e., copies of the same business object may be stored multiple times in the collection, each with a different access label.
• All business objects in the collection SHALL have the same representation:
  • The stored business object representation SHALL be the same as the representation used when reading the business object from the collection. No transformation of representation SHALL be provided when reading the business object from the collection. Converting encodings required to transmit messages from the service instance MAY be performed.
  • The representation of the business object SHALL be specified in the service expressions that specialise the service genre.
  • The transmission message encoding SHALL be specified in the service expressions that specialise the service genre.
  • A service instance SHALL be bound to an actual collection. The read service genre does not define how this collection is provisioned or managed. Provisioning, management and instantiation of the collection SHALL be defined in a SUM or application design.

The structure of the service that provides the perceived collection access, maintenance and persistence behaviour SHALL be defined by the service expressions that specialise the read service genre.

The overall flow of interactions with and structure of the service is illustrated in the diagram.

The read service genre is designed to provide simple data collection services. Thus, there are several intentional simplifications in the scope of the service genre:

• The read service genre does not define either authenticated access to the service or authenticated and authorised access to the business objects in the collection. Authentication and authorisation may be combined with the read service genre in SUMs that build upon the read service genre or the collection SUMs.
• The read service genre is defined only for getting one business object at a time from the collection, not getting multiple business objects. Batch operations would require additional features to define batch sizes and limits and to support flow control when the batch size exceeds the defined limits.
• The read service genre is defined only for collections where all business objects in the collection have the same representation. Many collections contain only one type of business object. Supporting collections that contain business objects with different representations or types requires additional features to specify the business object type in the response and may make representation and storage of the collection as a whole more complex.
• The read service genre is defined only when the business object is treated as a non decomposable, opaque whole. Operations on parts of a business object in the collection or operations on the collection as a whole are deferred to separate service genres.
• The read service genre deals only with retrieving business objects from the collection, not how the collection itself is instantiated, provisioned or managed. Operations on the collection as a whole may be defined in SUMs that use the read service genre.
• The read service genre and it specialisations in service expressions do not specify the structure or storage representation of the collection. There is no requirement to specify the storage model, only that the service genre be perceived to provide the defined functionality. Specification of a storage model SHALL be deferred to a service implementation design.
• The read service genre does not include an "inspect" function that could be used to query the service to determine the possible representation of the business object supported in the collection. Only a single representation is supported and this representation SHALL be defined in the service expressions that specialise the service genre.
• The read service genre does not specify how to support transactional behaviours. Support for transactional behaviours would require a collection service genre supporting multiple functions in conjunction with transactional behaviours.
• The read service genre does not provide mechanisms to discover, retrieve or directly access the access labels associated with business objects in the collection. A search service genre in one of the collection SUMs MAY be able to retrieve the access labels.

The following design decisions apply to the service expressions that specialise the read service genre.

Structure and Design:

• The access label only needs to be unique within the scope of the collection. It need not be globally unique.
• The access label need not be externally actionable: it MAY be defined as a key through an ad hoc, one-off arrangement between the client and the service instance, with no expectation that the access label will be stored and maintained externally to the client or be actionable by other services. The access label however, SHALL support consistent behaviours when collection service instances are bound to the same collection.
• All design decisions related to the meaning of access labels, their context and how they are associated with business objects in the collection are deferred to the design of the service expression or the corresponding service implementation designs.
• While the service implementation is bound to a specific collection of business objects, the collection itself MAY be a separately managed collection business object (i.e., managed by a different service). A service expression MAY specify that the collection resides in a single physical storage system or it MAY specify that the collection is a distributed collection. All design decisions related to realisation and storage of the collection are deferred to the service implementation design.
• Intrinsically a business object maintained in the collection, the corresponding business object passed in a response, and the corresponding business object maintained by the client are copies. Service expressions and the corresponding service implementation designs SHOULD indicate when copies are created and used.
• Transport-level encodings (e.g., UTF8 over HTTP) of results SHALL be defined by the service expressions that specialise the service genre.

Consistency:

• The service implementation SHALL ensure that all labelled (identified) business objects are stored in the collection and can be accessed by their access label at a later time.
• When multiple clients maintain and persist the access labels, the association of access labels to business objects MAY NOT be synchronized across all the clients.
• If different collection service instances are bound to the same collection, the service implementation SHALL use the access label to ensure consistent behaviour across all the service instances.
• When using caches in combination with multiple collection service instances bound to the same collection, returning values from the cache MAY result in inconsistent or out-of-date results being returned to the client.
• Since the business object stored by the client and that stored in the collection are separate copies and not references to the same business object, the client and service instance copies MAY be unsynchronized.
• A service implementation SHOULD insure transactional integrity within a single service request, i.e., overlapping requests (one is not completed before the next is started) SHOULD be serialized to provide consistent, repeatable transactional behaviour.

Performance:

• A service implementation SHALL be capable of handling simultaneous requests from different clients.
• A service implementation SHOULD implement an indexing scheme or equivalent method to permit efficient access to the business object in the collection.
• Load balancing and distributed storage SHOULD be considered for large collections.

Security and Privacy Considerations:

• Service instances MAY be subject to denial-of-service attacks.
• Service expressions or service implementation designs may choose to provide error messages that indicate the existence of business objects in the collection or may obscure the existence of business objects in the collection (e.g., when adding a business object to the collection, the error MAY indicate that a business object with the associated access label already exists in the collection, thus disclosing the existence of the business object, or a simple error indicating an undifferentiated failure to add the business object to the collection MAY be returned without disclosing that the access label is already associated with a business object in the collection).
• Care should be taken to maintain privacy of any personal data or other data that MAY disclose usage patterns.

None. No standards are directly applicable to the read service genre as a whole.

The service expressions that specialise the read service genre SHALL be defined in terms of standards:

• Service expressions SHALL specify applicable representation standards for the business object to be retrieved from the collection.
• Service expressions SHALL specify applicable data encoding standards for the business object to be retrieved from the collection.
• Service expressions SHALL specify applicable communications, encoding and transport protocol standards.

• access label [cross-ref-link]. A placeholder for a label associated with a business object in a collection.
• business object [cross-ref-link]. Any business object.
• collection [cross-ref-link]. A logical grouping of one or more business objects.

• add [V2.0]. Put a new business object into a collection.
• remove [V1.0] . Disassociate a known business object from a collection.
• replace [V1.0] . Substitute a new business object for an existing business object in a collection.

• simple collection maintenance SUM [V1.0]. The read service genre is used in the simple collection maintenance SUM.

• simple collection maintenance SUM [V1.0]. The read service genre is used in the simple collection maintenance SUM.
• searchable collection maintenance SUM [V1.0] . Through the simple collection maintenance SUM, the searchable collection maintenance SUM uses the read service genre.

The words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document (in the typographic convention shown [all uppercase, Arial font]) are to be interpreted as described in [RFC 2119].

The notation "collection SUMs" (plural, using the typographic convention of a mixed-case Arial font) denotes any of the SUMs that provide functions to support access to and maintenance of collections, including the simple collection maintenance SUM and the searchable collection maintenance SUM.

The notation "collection" (using the typographic convention of a mixed-case Arial font) without any further qualification is a placeholder for an instance of a collection business object, i.e., it represents an unnamed, generic business object that has not been bound to a specific business object of type collection.

The notation "business object" (using the typographic convention of a mixed-case Arial font) without any further qualification is a placeholder for any instance of any single business object, i.e., it represents a single unnamed, generic business object that has not been bound to any specific business object of a particular type.

Unless otherwise noted above, a term using the typographic convention of a mixed-case Arial font is the name of a specific business object, service genre or SUM (e.g., add is a service genre).

Access Label – A label associated with a single business object within a collection for the purposes of distinguishing the business object from all others when accessing the business object in the collection.

Collection – The whole of a logical structuring and persistent storage grouping of one or more instances of business objects. The business objects or elements in the collection are each associated with an access label used to distinguish one business object from another. The collection does not imply a particular storage structure or representation, nor does it have any requirements to conform to any formal abstract data structure [see ISO 11404], e.g., it is not limited to being an array, a bag, a set, etc. Formally a collection is a business object, i.e., it is a "collection business object".

Collection Business Object – A business object that is a collection (the whole). See collection.

Collection Services – Collection services and any of its variant terms, such as collection service genres, denotes the set of four services: add, read, replace, remove (or their respective variant terms, e.g., add service implementation, read service implementation,...).

Business Object – An undifferentiated generic business object that has not been bound to any specific business object of a particular type.

NB:
The term business object is used in context in this service genre and must be interpreted within the context. In particular, there is no specific term to denote one of the business objects in a collection (a business object of some unspecified type that is accessed from or stored and maintained in a collection).

The term "manage" is used to describe processes applied to the collection as a whole, such as its provisioning. Such operations are outside of the scope of this service genre.

The term "maintain" is used to describe processes applied to the business objects in the collection. i.e., add, read, replace, remove.

© Copyright, The e-Framework Partners 2009

Attribute this work as:
Read Genre, The e-Framework Partners, 2009. Derived from...

Attribution History:

1. Derived from Read Genre authored and submitted by Daniel Rehak on behalf of the e-Framework Partners, 2009