BatchElementError Class Reference

Structure representing per-element batch operation errors. More...

#include <BatchElementError.hpp>

Public Types
enum	ErrorCode {   kUnknown = internal::errors::kBatchElementUnknownError, kInvalidEntityReference = internal::errors::kBatchElementInvalidEntityReference, kMalformedEntityReference = internal::errors::kBatchElementMalformedEntityReference, kEntityAccessError = internal::errors::kBatchElementEntityAccessError,   kEntityResolutionError = internal::errors::kBatchElementEntityResolutionError, kInvalidPreflightHint = internal::errors::kBatchElementInvalidPreflightHint, kInvalidTraitSet = internal::errors::kBatchElementInvalidTraitSet, kAuthError = internal::errors::kBatchElementAuthError }
	Possible classes of error. More...

Public Member Functions
constexpr bool	operator== (const BatchElementError &other) const
	Compares two instances to see if they match. More...
constexpr bool	operator!= (const BatchElementError &other) const
	Compares two instances to see if they do not match. More...

Public Attributes
ErrorCode	code {ErrorCode::kUnknown}
	Error code indicating the class of error. More...
Str	message
	Human-readable error message. More...

Detailed Description

Structure representing per-element batch operation errors.

Many OpenAssetIO API functions take multiple inputs, i.e. a batch of elements, in order to allow the manager backend to optimise bulk queries. The results of such queries are usually returned element-by-element via a callback.

It is possible for the whole batch to fail due to some catastrophic error, in which case a standard exception workflow is expected. Using HTTP status codes as an analogy, a client error (4xx) would likely correspond to a BatchElementError, whereas a server error (5xx) would likely cause the whole batch to fail with an exception.

However, it is also possible for a subset of elements in the batch to fail, whilst the remainder succeed. An exception workflow doesn't work so well here, and so every success callback is paired with an error callback, allowing per-element errors to be communicated back to the original caller (i.e. the host application).

The information for these per-element errors is bundled in instances of this simple BatchElementError structure for passing to error callbacks.

This structure provides an error code, for control flow, and an error message, for more (human-readable) detail.

Member Enumeration Documentation

enum ErrorCode

strong

Possible classes of error.

Enumerator
kUnknown	Fallback for uncommon errors.
kInvalidEntityReference	Error code used whenever an entity reference is not one that is known to the manager. In the case of a manager that uses standard URIs, then it could be that the scheme is that of another manager.
kMalformedEntityReference	Error code used whenever an entity-based action is performed on a malformed Entity Reference. Entity references are initially validated as part of constructing an EntityReference object. However, that is a naive check intended to validate the general format of a reference string is one belonging to the manager. It does not validate that all aspects of the reference are valid, as that may be situational, based on the target entity and the context of the API call. For example, assuming entity references are encoded as URIs, a kMalformedEntityReference could indicate that a required query parameters is missing for a given operation, or a supplied parameter is not relevant to that particular operation/entity.
kEntityAccessError	Error code used when the reference is valid, but the supplied Context access is invalid for the operation. A common example of this would be resolving a read-only entity with a write access Context, or during preflight or register when the target entity s read-only and does not support updating.
kEntityResolutionError	Error code used during entity resolution when the reference itself is valid, but it is not possible to retrieve data for the referenced entity. This could be because it does not exist, or some other entity-specific reason that this data cannot be resolved for a specific entity. This code should not be used if an entity does not have a requested trait - simply do not set that trait in the resulting data. Fatal runtime errors during resolution (eg: server connection errors) should be raised as exceptions, rather than per-entity errors. This code is also used during finalisation and any other entity-based operations on a valid Entity Reference that fail for some reason.
kInvalidPreflightHint	Error code response from preflight if the provided traits data hint holds insufficient or invalid information. This will occur when the manager requires information that the host owns to be passed to preflight, but the host did not provide it.
kInvalidTraitSet	Error code used whenever a trait set is not one that is known to the manager.
kAuthError	Error code indicating that the host is not authorized for a pariticular request. The operation may be valid if attempted again, once the authorization issue is resolved. This can be due to insufficient or incomplete authentication as well as authorization, and could be specific to a particular action, or a particular entity. The error message should provide details of the reason.

Member Function Documentation

constexpr bool operator!= ( const BatchElementError &  other ) const

inline

Compares two instances to see if they do not match.

Returns

true if the batch elements errors do not match, otherwise false.

constexpr bool operator== ( const BatchElementError &  other ) const

inline

Compares two instances to see if they match.

Returns

true if the batch elements errors match, otherwise false.

Member Data Documentation

ErrorCode code {ErrorCode::kUnknown}

Error code indicating the class of error.

Str message

Human-readable error message.

---

The documentation for this class was generated from the following file:

• /src/src/openassetio-core/include/openassetio/errors/BatchElementError.hpp