Figure 9.45: Interfaces for file access

1. Diagrammtyp & Architektur-Kontext

• Klassifikation: UML-Klassendiagramm / Schnittstellendiagramm (mit Komponenten-Kontext) kombiniert mit einer API-Methodenübersicht der Persistency-Schnittstelle FileStorage.
• Architektur-Kontext: AUTOSAR Adaptive Platform (AP), Functional Cluster Persistency (ara::per), Dokument AUTOSAR_AP_EXP_SWArchitecture, Release R25-11.
• Technischer Zweck: Spezifikation der objektorientierten C++-Zugriffsschnittstellen (Accessor-Hierarchie) für den dateibasierten Speicherzugriff (File Storage) durch eine Adaptive Application. Das Diagramm trennt Navigations-, Lese- und Schreibfähigkeiten strikt nach dem Interface-Segregation-Prinzip, um rollenspezifischen, typsicheren und minimal-privilegierten Datei-I/O bereitzustellen.

2. Komponenten, Entitäten & Schnittstellen

Entitäten & Stereotypen

• Adaptive Application (Komponente): Konsument der Datei-I/O-Schnittstellen. Greift über vier differenzierte Zugriffsmodi via Abhängigkeitsbeziehung («use») auf die Schnittstellen zu.
• Persistency («aapFunctionalCluster»): Implementierender AUTOSAR-Adaptive-Plattform-Basisdienst. Realisiert (gestrichelte Realisierungspfeile mit geschlossener, nicht ausgefüllter Dreiecksspitze) alle vier nativen C++-Schnittstellen.

C++-Schnittstellen («aapAPI,aapNativeInterface») & Vererbungshierarchie

• FileAccessor (Basisklasse für Dateipositionierung/Metadaten):
  • Kapselt die Cursor- und Größenverwaltung.
  • Methoden: + GetPosition(), + GetSize(), + IsEof(), + MovePosition(), + SetPosition().
• ReadAccessor (Leseschnittstelle):
  • Spezialisierung von FileAccessor (Generalisierungsbeziehung / Vererbung ReadAccessor → FileAccessor).
  • Stellt zeichen-, zeilen- und blockbasierte Leseoperationen bereit.
  • Methoden: + GetByte(), + GetChar(), + PeekByte(), + PeekChar(), + ReadBinary(), + ReadLine(), + ReadText().
• WriteAccessor (Schreibschnittstelle):
  • Kapselt schreibende I/O-Operationen und Synchronisation.
  • Methoden: + operator<<(), + SetFileSize(), + SyncToFile(), + WriteBinary(), + WriteText().
• ReadWriteAccessor (Kombinierte Lese-/Schreibschnittstelle):
  • Mehrfach-Spezialisierung: Erbt direkt von WriteAccessor (horizontale Generalisierung) sowie von FileAccessor (unterer Vererbungspfad) und aggregiert damit Positionsmanagement, Schreib- und Lesezugriff.

Übergeordnete Factory-Methoden (FileStorage):

Die im oberen Tabellenabschnitt dargestellten Methoden bilden die Erzeuger-/Verwaltungs-API des übergeordneten FileStorage-Handles:

• OpenFileReadOnly: Erzeugt eine Instanz/Smart-Pointer auf ReadAccessor.
• OpenFileWriteOnly: Erzeugt eine Instanz/Smart-Pointer auf WriteAccessor.
• OpenFileReadWrite: Erzeugt eine Instanz/Smart-Pointer auf ReadWriteAccessor.
• GetFileInfo: Liefert Datei-Metadaten ohne Öffnen eines Datenstroms.
• RecoverFile / ResetFile: Redundanz- und Wiederherstellungsmechanismen zur Fehlerbehebung oder Rücksetzung auf Auslieferungszustand (Initial State).

3. Dynamisches Verhalten & Sequenzablauf

1. Storage- & File-Allokation:
   • Die Adaptive Application öffnet über die ara::per-Factory (OpenFileReadOnly, OpenFileWriteOnly oder OpenFileReadWrite) eine Datei innerhalb eines konfigurierten FileStorage.
2. Handle-Rückgabe:
   • Der Functional Cluster instanziiert intern den entsprechenden Accessor und liefert einen RAII-gekapselten Zeiger/Referenz (ara::core::Result<std::unique_ptr<...Accessor>>) zurück.
3. Synchrone I/O-Ausführung:
   • Lesepfad: Prüfung auf Dateiende via IsEof(), sequentielles Lesen mittels ReadBinary() oder atomarer Zeichenabruf via GetByte()/PeekByte().
   • Schreibpfad: Inkrementelles Schreiben via Stream-Operator operator<< oder WriteBinary(). Positionszeiger wird implizit oder explizit über MovePosition()/SetPosition() manipuliert.
4. Persistierung & Konsistenz:
   • Pufferinhalte werden erst durch den synchronen Aufruf von SyncToFile() verbindlich auf das nichtflüchtige Speichermedium (Flash/eMMC/NVRAM) durchgeschrieben (Flush/Fsync-Semantik).
5. Fehlerbehandlung:
   • Tritt eine Dateibeschädigung (z. B. CRC-Fehler, unvollständiger Block) auf, bricht die I/O-Operation mit einem entsprechenden ara::core::ErrorCode ab. Die Applikation triggert daraufhin RecoverFile (Wiederherstellung aus Redundanzkopie) oder ResetFile (Fallback auf Factory-Default).

4. Normative Relevanz & Entwickler-Hinweise

• Zugriffsrestriktion & Safety: Entwickler müssen den Accessor-Typ strikt nach dem Least-Privilege-Prinzip wählen. Read-Only-Workloads dürfen nur OpenFileReadOnly verwenden, um versehentliche Modifikationen und Race Conditions auf Dateisystemebene auszuschließen.
• RAII & Flush-Garantie: SyncToFile() ist obligatorisch vor dem Schließen oder vor kritischen Zustandswechseln (z. B. Shutdown/Suspend-to-RAM via Execution Management), da das Schließen des Accessor-Objekts alleine kein garantiert synchronisiertes Schreiben auf die physische Partition erzwingt.
• Zero-Copy & Binary Streams: Für echtzeitkritische und datenintensive Payloads (z. B. Logging-Traces, Sensorkalibrierungsdaten) sind ReadBinary() und WriteBinary() unter Verwendung von ara::core::Span<const ara::core::Byte> zu bevorzugen, um unnötige Allokationen und String-Kopien via ReadLine()/operator<< zu vermeiden.
• Redundanz- und Recovery-Konfiguration: Die Wirksamkeit von RecoverFile() und ResetFile() setzt eine entsprechende Deklaration im AUTOSAR-Manifest (PersistencyFileStorageInterface, Redundanz- und Update-Strategien) voraus; fehlen dort Backups oder Default-Images, schlagen diese API-Aufrufe zur Laufzeit fehl.