Systematische Konstruktion von API-Verträgen

337 Aufrufe

Veröffentlicht am

Vortrag auf dem 280. Treffen der GI Regionalgruppe HH am 12.11.2014

Veröffentlicht in: Software
0 Kommentare
0 Gefällt mir
Statistik
Notizen
  • Als Erste(r) kommentieren

  • Gehören Sie zu den Ersten, denen das gefällt!

Keine Downloads
Aufrufe
Aufrufe insgesamt
337
Auf SlideShare
0
Aus Einbettungen
0
Anzahl an Einbettungen
5
Aktionen
Geteilt
0
Downloads
1
Kommentare
0
Gefällt mir
0
Einbettungen 0
Keine Einbettungen

Keine Notizen für die Folie

Systematische Konstruktion von API-Verträgen

  1. 1. Systematische Konstruktion von API-Verträgen Vortrag auf dem 280. Treffen der GI-/ ACM-Regionalgruppe HH am 12.11.2014 Jan Christian Krause und Alexander Mills
  2. 2. Seite 2 Jan Christian Krause und Alexander Mills Agenda 1.Einführung Fallbeispiel Grundbegriffe Gestaltung von API-Verträgen 2.Identifikation von Lücken 3.Evaluierungsergebnisse 4.Automatisierte Lückenerkennung 5.Zusammenfassung
  3. 3. Seite 3 Jan Christian Krause und Alexander Mills Einführung
  4. 4. Seite 4 Jan Christian Krause und Alexander Mills Auswahl einer Verkaufsplattform (I) •A1: Integrierbar in selbstentwickelte Systeme •A2: Kundenbonität robust prüfbar •Beschreibung unter http://developer.ebay.com/ „eBay Trading API“ Zugriff auf Operationen von eBay über HTTP Bewertungssystem vorhanden (getFeedback()) Manipulierbar?
  5. 5. Seite 5 Jan Christian Krause und Alexander Mills Auswahl einer Verkaufsplattform (II) •Fachliche und technische Bezüge in Operationen •Leistungsbeschreibung •Bei Lücken drohen wirtschaftliche Konsequenzen Wie können Inhalte dieser Beschreibung systematisch abgeleitet werden?
  6. 6. Seite 6 Jan Christian Krause und Alexander Mills Grundbegriffe
  7. 7. Seite 7 Jan Christian Krause und Alexander Mills Prinzipien der Vertragsgestaltung •… ist das schriftlich fixierte Verhandlungsergebniszwischen Anbieter und Benutzer einer Komponente. •… schreibt fest, welche Leistungvon der Komponente unter welchen Bedingungenzu erbringen ist. •… enthält Zusicherungenund Erwartungen. •… wird geprägt durch das Geheimnisprinzip. Ein Vertrag …
  8. 8. Seite 8 Jan Christian Krause und Alexander Mills Qualitätskontrolle eines Herstellers Hersteller(im Kontext der Produktentwicklung) Stille-MessgerätEntsprechen meine API-Verträgemeinen eigenen Qualitätsansprüchen?API-VerträgePrüfberichtHabe ich die Bedingungen, unter denen ich für die korrekte Arbeitsweise meiner Komponente bürge, klar genug eingegrenzt?
  9. 9. Seite 9 Jan Christian Krause und Alexander Mills Qualitätskontrolle eines Auftragnehmers Hersteller / Auftragnehmer(im Kontext der Individualentwicklung) Stille-MessgerätHabe ich meinen Auftraggeberverstanden oder mussich ihm weitere Fragen stellen? API-VerträgePrüfberichtKäufer / AuftraggeberAPI-VerträgeFragen
  10. 10. Seite 10 Jan Christian Krause und Alexander Mills Qualitätskontrolle eines Käufers Käufer / AuftraggeberStille-MessgerätKann ich auf Basis derAPI-Verträge prüfen, ob die Komponente meine Anforderungen erfüllt? Falls nicht, welche Fragenmuss ich stellen? API-VerträgePrüfberichtHerstellerAPI-VerträgeFragenArbeitet der Hersteller sorgfältig?
  11. 11. Seite 11 Jan Christian Krause und Alexander Mills Gewährleistung von Vollständigkeit •Prüflistenbasierte Verfahren •Quelltextbasierte Verfahren Schrittweise, meist manuelle Vertragsprüfung Statische Liste festgelegter Prüfkriterien Automatische Vertragsprüfung Quelltextanalyse (geworfene Ausnahmen, Konfigurationen)
  12. 12. Seite 12 Jan Christian Krause und Alexander Mills Identifikation von Lücken
  13. 13. Seite 13 Jan Christian Krause und Alexander Mills Valenz eines Operationsbezeichners •Beobachtung aus der Linguistik: Prädikate können zusätzliche Angaben im Satz fordern (Valenz) •Bezeichner von Operationen können Prädikate enthalten, z.B. computeFeedback()oder findCustomerById() •Unser Ansatz: Rückschluss auf notwendige Vertragsinhalte aus dem Prädikat des Bezeichners
  14. 14. Seite 14 Jan Christian Krause und Alexander Mills Anwendung thematischer Raster (I) Operation (Signatur + Vertrag): publicintcomputeFeedback(Long userId, Long itemId, Long transactionId, Long orderLineItemId); Thematisches Raster „Berechnende Operation“: Compute [OBJECT] [OPERAND][FORMULA] Belegtes Thematisches Raster Compute [OBJECTFeedbackScore] [OPERANDuserId, itemId, transactionId, orderLineItemId] [FORMULA???]
  15. 15. Seite 15 Jan Christian Krause und Alexander Mills Anwendung thematischer Raster (II) /** * Use this call to retrieve the accumulated feedback left for a specified user, * or the summary feedback data for a specific item listing or order line item. * * @paramuserId[OPERAND] * Specifies the user whose feedback data is to be returned. If not specified, then * the feedback returned is for the requesting user. * @paramitemId[OPERAND] * Unique identifier for an eBay item listing. * @paramtransactionId[OPERAND] * Unique identifier for an eBay order line item (transaction). * @paramorderLineItemId[OPERAND] * OrderLineItemIDis a unique identifier for an eBay order line item and is based * upon the concatenation of ItemIDand TransactionID, with a hyphen in between * these two IDs. * @return [OBJECT] Indicates the total feedback score for the user. * * * */ public intcomputeFeedback(Long userId, Long itemId, Long transactionId, Long orderLineItemId); OPERAND OBJECT FORMULA @formula See <a href=“…”>Introduction to Feedback</a>
  16. 16. Seite 16 Jan Christian Krause und Alexander Mills Anwendung thematischer Raster (III)
  17. 17. Seite 17 Jan Christian Krause und Alexander Mills Rasterbasierte Regeln •Frage: Ableitung relevanter Inhalte aus bereits spezifizierten thematischen Rollen? •Beispiel: Sortierung im Fall mehrerer gefundener Kunden •Ansatz: Rasterbasierte Regeln Für jede Rolle eines Rasters existiert eine prädikatenlogische Formel, die die Empfehlung der Rolle steuert. Mögliche Prädikate in dieser Formel sind: exists(„ROLLE“) isPlural(„ROLLE“) isSingular(„ROLLE“) hasAttributes(„ROLLE“)
  18. 18. Seite 18 Jan Christian Krause und Alexander Mills Identifikation von Fehlerfällen •Thematische Raster unterstützen bei der Ableitung von CheckedExceptions. •Wie soll das Programm reagieren, wenn eine Rollenbelegung nicht verfügbar ist?
  19. 19. Seite 19 Jan Christian Krause und Alexander Mills Evaluierungsergebnisse
  20. 20. Seite 20 Jan Christian Krause und Alexander Mills Methodik •Testfälle definieren die erwarteten Ausgaben einer Operation bei bestimmten Eingaben. •Repräsentativer Abbildung des Operationsverhaltens als durch deren Signatur allein. •Messung des Umfangs von Stille: Wie viele durch Testfälle geforderte Ein-und Ausgaben sind im Vertrag enthalten? •Messung der Relevanz von Stille: Wie viele Testfälle beruhen auf den fehlenden Ein-und Ausgaben?
  21. 21. Seite 21 Jan Christian Krause und Alexander Mills Versuchsaufbau Operations- signaturenProbandenmodellierenjavadoc- KonventionenKatalog Thematischer RasterSzenarioDefiniert Rahmenbe- dingungen Prüfliste nach Clements et al. + Satz einfacher KonventionenOptimales JavadocOptimales Javadoc + Thematische RasterErwartungshorizontjavadoc- KonventionenVergleichVergleichSystematisch erzeugteTestfälle
  22. 22. Seite 22 Jan Christian Krause und Alexander Mills Umfang von Stille 0 1 2 3 4 5 6 7 8 9 10 Op. 1 Op. 2 Op. 5 Op. 16 Op. 6 Op. 7 Op. 8 Anzahl Eingaben 0 1 2 3 4 5 6 7 8 9 Op. 1 Op. 2 Op. 5 Op. 16 Op. 6 Op. 7 Op. 8 Erwartungshorizont Optimales Javadoc Optimales Javadoc + Thematische Raster Anzahl Ausgaben Op.1 = Lese Kundenaccountanhandder Kundennummer Op. 2 = PrüfeBonitätanhanddes Zahlungsverhaltens Op. 16 = SpeichereBestellung Op. 5 = ErzeugeAuftragsablehnung Op. 6 = BerechneRabatt Op. 7 = ErstelleRechnung Op. 8 = Druckeund packeRechnung
  23. 23. Seite 23 Jan Christian Krause und Alexander Mills Relevanz von Stille 0 10 20 30 40 50 60 70 80 90 100 Op. 1 Op. 2 Op. 16 Op. 5 Op. 6 Op. 7 Op. 8 Optimales Javadoc Optimales Javadoc + Thematische Raster Anteil entscheidbarerTestfälle in %
  24. 24. Seite 24 Jan Christian Krause und Alexander Mills Lessonslearned •Thematische Raster können den Umfang von Stille senken. •Erkannte Eingaben: Von 54% auf 94% •Erkannte Ausgaben: Von 51% auf 81% •Die durch thematische Raster identifziertenLücken sind relevant. EntscheidbareTestfälle: Von 62% auf 88% •Quantifizierung dieser Verbesserung nicht allgemeingültig.
  25. 25. Seite 25 Jan Christian Krause und Alexander Mills Automatisierte Lückenerkennung
  26. 26. Seite 26 Jan Christian Krause und Alexander Mills Automatisierte Belegung thematischer Raster Operation (Signatur + Vertrag): public voidcopyFileAsciiToUtf(File input, OutputStreamoutput); Thematisches Raster „Duplizierende Operation“: Copy [OBJECT] [SOURCE] [DESTINATION] [SOURCE_FORMAT] [DESTINATION_FORMAT]
  27. 27. Seite 27 Jan Christian Krause und Alexander Mills Automatisierte Belegung thematischer Raster (II) /** * Copies bytes from an ASCII File to an OutputStream. * The file will be converted from ASCII to UTF-8 * during this process. */ public void copyFileAsciiToUtf(File input, OutputStreamoutput); Belegtes Thematisches Raster Copy [OBJECT???] [SOURCE ???] [DESTINATION???] [SOURCE_FORMAT ???] [DESTINATION_FORMAT ???]
  28. 28. Seite 28 Jan Christian Krause und Alexander Mills Automatisierte Belegung thematischer Raster (III) /** * Copies bytes from an ASCII File to an OutputStream. * The file will be converted from ASCII to UTF-8 * during this process. */ public void copyFileAsciiToUtf(File input, OutputStreamoutput); Belegtes Thematisches Raster Copy [OBJECTbytes] [SOURCE from an ASCII File] [DESTINATIONto an OutputStream] [SOURCE_FORMAT from ASCII] [DESTINATION_FORMAT to UTF-8]
  29. 29. Seite 29 Jan Christian Krause und Alexander Mills Konzept für automatisierte Lückenerkennung API-Vertrag Operations- bezeichner Thematisches Raster Präpositional- phrasen Thematische Rollen Belegung des Rasters Fehlende Belegung = Hinweis auf Stille
  30. 30. Seite 30 Jan Christian Krause und Alexander Mills Demonstration des Prototypen
  31. 31. Seite 31 Jan Christian Krause und Alexander Mills Zusammenfassung und Ausblick
  32. 32. Seite 32 Jan Christian Krause und Alexander Mills Zusammenfassung •Aus Operationsbezeichnern können relevante Inhalte für API-Verträge abgeleitet werden. •Voraussetzung: Operationsbezeichner müssen Konventionen genügen. •Thematische Raster liefern Hinweise auf Lücken, bedürfen aber der verantwortungsvollen Interpretation durch Menschen. •Bei Einhaltung bestimmter Konventionen zur Formulierung können thematische Rollen teilweise automatisiert belegt werden.
  33. 33. Seite 33 Jan Christian Krause und Alexander Mills Vielen Dank für Ihre Aufmerksamkeit Haben Sie Fragen?
  34. 34. Seite 34 Jan Christian Krause und Alexander Mills Jan Christian Krause Software-Entwickler Mailjan-christian.krause@akra.de Twitter@iDocIt Blogidocit.blogspot.de Githubhttps://github.com/jankrause Alexander Mills Software-Entwickler Mailalexander.mills@akra.de Kontakt
  35. 35. Seite 35 Jan Christian Krause und Alexander Mills Ausgewählte Literatur •Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord und Judith Staord. Documenting Software Architectures -Views and Beyond. Addison- Wesley Verlag, Boston u.a., 2003. •Douglas Kramer. API Documentation from Source Code Comments: A Case Study of Javadoc. In: (ohneHerausgeber) SIGDOC '99: Proceedings of the 17th annual internationalconferenceon Computer documentation, Seiten147 -153, New York, 1999. Association for Computing Machinery. •Oracle Corp. How to Write Doc Comments for the Javadoc Tool, ohne Jahr. Dieser Artikel ist unter http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html verfügbar (letzter Abruf am 15.03.2013). •David LorgeParnas. Information distribution aspects of design methodology. In: C.V. Freiman, J.E. Grithund J.L. Rosenfeld (Hrsg.), Information Processing 71 -Proceedings of the IFIP Congress 71, Band 1, Seiten339 -344, Amsterdam, London, 1971. North Holland Publishing Company. •David LorgeParnas. On the Criteria To Be Used in Decomposing Systems into Modules. Communications of the ACM, Band 15 (Ausgabe 12): Seiten 1053 -1058, 1972. •Jan Christian Krause. Vermeidung von Lücken in API-Verträgen. Dissertation, Universität Hamburg, 2014. Diese Dissertation ist unter http://ediss.sub.uni- hamburg.de/volltexte/2014/7022verfügbar (letzter Abruf: 13.11.2014).
  36. 36. Seite 36 Jan Christian Krause und Alexander Mills Die 10 häufigsten Verben des seekda-Korpus Rang Verb Häufigkeit 1. get 74.790 2. add 6.105 3. create 4.929 4. delete 4.769 5. update 4.398 6. send 3.176 7. list 2.658 8. check 1.944 9. remove 1.861 10. is 1.845
  37. 37. Seite 37 Jan Christian Krause und Alexander Mills Thematische Raster Prüfende Operation Parsende Operation Schlussfolgernde Operation DeponierendeOperation Konvertierende Operation Löschende Operation Erzeugende Operation Rücksetzende Operation Beschreibende Operation Suchende Operation Duplizierende Operation Sendende Operation VerbindendeOperation InitiierendeOperation Lesende Operation Substituierende Operation Protokollierende Operation Traversierende OPeration Berechnende Operation ZusammenführendeOperation
  38. 38. Seite 38 Jan Christian Krause und Alexander Mills Evaluierung des Prototypen 33% 21% 18% 28% Gefundene Lücke Gefundene Belegung Nicht gefundene Belegung Nicht gefundene Lücke
  39. 39. Seite 39 Jan Christian Krause und Alexander Mills Fehlerklassifikation des Prototypen 41% 8% 16% 35% Rolle nicht mit Präposition erkennbar Falsche Belegung ausgewählt Fälschlicherweise als Lücke erkannt Lücke nicht erkannt
  40. 40. Seite 40 Jan Christian Krause und Alexander Mills Schwächen des Prototypen •Viele thematische Rollen teilen sich gemeinsame Präpositionen •Fehler des NL-Parsers bei Imperativsätzen •Viele thematische Rollen nicht durch Ansatz belegbar (z.B.: FORMULA, OPERAND) •Autor des API-Vertrags muss „Kochrezept“ befolgen damit Trefferrate möglichst hoch ist
  41. 41. Seite 41 Jan Christian Krause und Alexander Mills Empfehlungen zur Formulierung Thematische Rollen (bewusst) durch Präpositionen einleiten Richtig: grepsearches lines in the named input FILEs Falsch: grepsearches the named input FILEsfor lines
  42. 42. Seite 42 Jan Christian Krause und Alexander Mills Empfehlungen zur Formulierung (II) Kurze und prägnante Sätze formulieren Richtig: Reads a set of customer data from a database. The customer data is filtered by the given name and then ordered by id. Falsch: Reads a set of customer data with the given name from a database ordered by id.
  43. 43. Seite 43 Jan Christian Krause und Alexander Mills Empfehlungen zur Formulierung (III) Thematischen Rollen so früh wie möglich belegen Returns data from a file... ... ... Get more information from https://... Get more information from https://... ... ... Returns data from a file...

×