class ara::core::InstanceSpecifier

The class ara::core::InstanceSpecifier serves as a type-safe wrapper around an AUTOSAR shortName path for uniquely identifying model instances in the Adaptive Platform. The preferred creation is performed exception-safely via the static factory method Create [SWS_CORE_08032], which validates a path and returns an ara::core::Result. As an essential constraint, the method ToString [SWS_CORE_08041] guarantees the validity of the returned StringView only for the lifetime of the originally passed character string, since no separate buffer is managed. At runtime, the object supports complete comparison operations for model lookups and ordered storage in containers.

more ›

Context

The class ara::core::InstanceSpecifier serves as a representation of an AUTOSAR Instance Specifier and encapsulates a complete shortName path of a model element. Within the Adaptive Platform, it acts as a type-safe abstraction over path strings of the AUTOSAR metamodel. Instead of using unformatted character strings, this type encapsulates the syntactic path structures and ensures that instances can be addressed consistently. Application components and platform services that uniquely reference, compare, or manage model instances in collections act as primary interaction partners. Interpretation: Since the specification describes the class as a lightweight model path wrapper, it is likely intended primarily for identifying and assigning configuration to service instances and communication endpoints at runtime. Question Q-6574e1172032e6d9 (open)

Lifecycle

For creation, ara::core::InstanceSpecifier offers two paths with different error and exception semantics: the static factory method Create [SWS_CORE_08032] as well as the explicit constructor [SWS_CORE_08021]. The factory method Create accepts a ara::core::StringView, is specified as noexcept as well as thread-safe, and returns the result in an ara::core::Result<InstanceSpecifier>. In contrast, the direct constructor is declared with noexcept(false) and throws an ara::core::CoreException in case of invalid path structures, making it not exception-safe [SWS_CORE_08021].

Regarding lifetime and ownership, a crucial property exists: The method ToString returns a ara::core::StringView whose validity is explicitly bound to the lifetime of the memory that underlay the StringView originally passed during construction [SWS_CORE_08041]. Consequently, the class does not copy the underlying character string into an owned memory area, but refers to external data. Developers must therefore ensure that the source character string remains in memory throughout the entire period of use of the InstanceSpecifier and the StringViews derived from it.

For further management in the lifecycle, copy constructor [SWS_CORE_08022], move constructor [SWS_CORE_08023], copy assignment [SWS_CORE_08024], and move assignment [SWS_CORE_08025] are present. All four operations are declared as noexcept and guarantee exception safety. Regarding concurrency, however, it should be noted that only the copy constructor is classified as thread-safe. The move operations, assignment operators, and the destructor [SWS_CORE_08029] are not thread-safe and require external synchronization if the same instance is modified or destroyed concurrently.

Usage Path

A typical usage sequence comprises instantiation, querying the path representation, and comparison with other identifiers. Preferably, the non-throwing factory function Create is called [SWS_CORE_08032]. The application passes the qualified model path as ara::core::StringView and checks the resulting Result object for success.

Sequence diagram: Creation via the Create factory method and subsequent usage for path query or error handling. Sources: [SWS_CORE_08032], [SWS_CORE_08041]

After successful initialization, the identifier can be used in versatile ways:

• Retrieve string representation: Via ToString [SWS_CORE_08041], the caller obtains a StringView view of the modeled path.
• Equality and inequality check: Instances can be compared directly with other InstanceSpecifier instances via operator== [SWS_CORE_08042] and operator!= [SWS_CORE_08044]. Furthermore, overloads of operator== [SWS_CORE_08043] and operator!= [SWS_CORE_08045] permit direct comparison with a ara::core::StringView. Both checks yield equality only if exactly the same model element is designated.
• Sorting and container storage: Via the less-than operator operator< [SWS_CORE_08046], instances can be ordered lexicographically, enabling use as keys in ordered containers such as maps.

Error Scenarios

Error conditions for ara::core::InstanceSpecifier are strictly limited to the construction phase. If syntactic or semantic defects occur in the passed path, two specific errors are identified:

• CoreErrc::kInvalidMetaModelShortname: Signaled if path elements in the passed name are missing or contain inadmissible characters [SWS_CORE_08032], [SWS_CORE_08021].
• CoreErrc::kInvalidMetaModelPath: Occurs if the string does not form a valid path to a model element [SWS_CORE_08032], [SWS_CORE_08021].

The type of error signaling depends on the chosen creation path. When using the factory method Create [SWS_CORE_08032], the error code is returned in the ara::core::Result; rollback semantics without exceptions apply. If, on the other hand, the constructor InstanceSpecifier [SWS_CORE_08021] is called, an ara::core::CoreException with the corresponding error code is thrown. All subsequent operations such as ToString [SWS_CORE_08041], assignments, and the comparison operators [SWS_CORE_08042], [SWS_CORE_08044], [SWS_CORE_08046] have no defined error states and are declared as noexcept.