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

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. 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. Seite 3
Jan Christian Krause und Alexander Mills
Einführung

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. 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. Seite 6
Jan Christian Krause und Alexander Mills
Grundbegriffe

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. 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. 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. 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. 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. Seite 12
Jan Christian Krause und Alexander Mills
Identifikation von Lücken

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. 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. 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. Seite 16
Jan Christian Krause und Alexander Mills
Anwendung thematischer Raster (III)

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. 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. Seite 19
Jan Christian Krause und Alexander Mills
Evaluierungsergebnisse

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. 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. 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. 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. 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. Seite 25
Jan Christian Krause und Alexander Mills
Automatisierte Lückenerkennung

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. 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. 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. 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. Seite 30
Jan Christian Krause und Alexander Mills
Demonstration des Prototypen

31. Seite 31
Jan Christian Krause und Alexander Mills
Zusammenfassung und Ausblick

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. Seite 33
Jan Christian Krause und Alexander Mills
Vielen Dank für Ihre Aufmerksamkeit
Haben Sie Fragen?

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. 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. 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. 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. 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. 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. 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. 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. 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. 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...