Upload
jan-christian-krause
View
84
Download
2
Embed Size (px)
Citation preview
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
Seite 2Seite 2Jan 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
Seite 4Seite 4Jan 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?
Seite 5Seite 5Jan 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?
Seite 7Seite 7Jan Christian Krause und Alexander Mills
Prinzipien der Vertragsgestaltung
• … ist das schriftlich fixierte Verhandlungsergebnis zwischen
Anbieter und Benutzer einer Komponente.
• … schreibt fest, welche Leistung von der Komponente
unter welchen Bedingungen zu erbringen ist.
• … enthält Zusicherungen und Erwartungen.
• … wird geprägt durch das Geheimnisprinzip.
Ein Vertrag …
Seite 8Seite 8Jan Christian Krause und Alexander Mills
Qualitätskontrolle eines Herstellers
Hersteller
(im Kontext der Produktentwicklung)
Stille-Messgerät
Entsprechen meine
API-Verträge
meinen eigenen
Qualitätsansprüchen? API-Verträge
Prüfbericht
Habe ich die Bedingungen,
unter denen ich für die korrekte
Arbeitsweise meiner Komponente
bürge, klar genug eingegrenzt?
Seite 9Seite 9Jan Christian Krause und Alexander Mills
Qualitätskontrolle eines Auftragnehmers
Hersteller / Auftragnehmer
(im Kontext der Individualentwicklung)
Stille-Messgerät
Habe ich meinen Auftraggeber
verstanden oder muss
ich ihm weitere Fragen
stellen?
API-Verträge
Prüfbericht
Käufer /
Auftraggeber
API-Verträge
Fragen
Seite 10Seite 10Jan Christian Krause und Alexander Mills
Qualitätskontrolle eines Käufers
Käufer /
Auftraggeber
Stille-Messgerät
Kann ich auf Basis der
API-Verträge prüfen, ob die
Komponente meine Anforderungen
erfüllt? Falls nicht, welche Fragen
muss ich stellen?
API-Verträge
Prüfbericht
Hersteller
API-Verträge
Fragen
Arbeitet der
Hersteller sorgfältig?
Seite 11Seite 11Jan 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)
Seite 13Seite 13Jan 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
Seite 14Seite 14Jan Christian Krause und Alexander Mills
Anwendung thematischer Raster (I)
Operation (Signatur + Vertrag):
public int computeFeedback(Long userId, Long itemId,
Long transactionId, Long orderLineItemId);
Thematisches Raster „Berechnende Operation“:
Compute
[OBJECT] [OPERAND] [FORMULA]
Belegtes Thematisches Raster
Compute[OBJECT FeedbackScore]
[OPERAND userId, itemId, transactionId, orderLineItemId]
[FORMULA ???]
Seite 15Seite 15Jan 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.
*
* @param userId [OPERAND]
* Specifies the user whose feedback data is to be returned. If not specified, then
* the feedback returned is for the requesting user.
* @param itemId [OPERAND]
* Unique identifier for an eBay item listing.
* @param transactionId [OPERAND]
* Unique identifier for an eBay order line item (transaction).
* @param orderLineItemId [OPERAND]
* OrderLineItemID is a unique identifier for an eBay order line item and is based
* upon the concatenation of ItemID and TransactionID, with a hyphen in between
* these two IDs.
* @return [OBJECT] Indicates the total feedback score for the user.
*
*
*
*/
public int computeFeedback(Long userId, Long itemId, Long transactionId, Long orderLineItemId);
OPERAND
OBJECT
FORMULA@formula See <a href=“…”>Introduction to Feedback</a>
Seite 17Seite 17Jan 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“)
Seite 18Seite 18Jan Christian Krause und Alexander Mills
Identifikation von Fehlerfällen
• Thematische Raster unterstützen bei der Ableitung von
Checked Exceptions.
• Wie soll das Programm reagieren, wenn eine
Rollenbelegung nicht verfügbar ist?
Seite 20Seite 20Jan 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?
Seite 21Seite 21Jan Christian Krause und Alexander Mills
Versuchsaufbau
Operations-
signaturen
Probanden
modellieren
javadoc-
Konventionen
Katalog
Thematischer
Raster
Szenario
Definiert
Rahmenbe-
dingungen
Prüfliste nach Clements et al.
+ Satz einfacher Konventionen
Optimales Javadoc
Optimales Javadoc +
Thematische Raster
Erwartungshorizont
javadoc-
Konventionen
Vergleich
Vergleich
Systematisch
erzeugte
Testfälle
Seite 22Seite 22Jan 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
An
zah
l Ein
ga
be
n
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
An
zah
l Au
sga
be
n
Op.1 = Lese Kundenaccount anhand der Kundennummer
Op. 2 = Prüfe Bonität anhand des Zahlungsverhaltens
Op. 16 = Speichere Bestellung
Op. 5 = Erzeuge Auftragsablehnung
Op. 6 = Berechne Rabatt
Op. 7 = Erstelle Rechnung
Op. 8 = Drucke und packe Rechnung
Seite 23Seite 23Jan 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
An
teil
en
tsc
he
idb
are
rTe
stfä
lle in
%
Seite 24Seite 24Jan Christian Krause und Alexander Mills
Lessons learned
• 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 identifzierten Lücken sind
relevant.
Entscheidbare Testfälle: Von 62% auf 88%
• Quantifizierung dieser Verbesserung nicht allgemeingültig.
Seite 26Seite 26Jan Christian Krause und Alexander Mills
Automatisierte Belegung thematischer Raster
Operation (Signatur + Vertrag):
public void copyFileAsciiToUtf(File input,
OutputStream output);
Thematisches Raster „Duplizierende Operation“:
Copy
[OBJECT]
[SOURCE] [DESTINATION]
[SOURCE_FORMAT] [DESTINATION_FORMAT]
Seite 27Seite 27Jan 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, OutputStream output);
Belegtes Thematisches Raster
Copy
[OBJECT ???]
[SOURCE ???] [DESTINATION ???]
[SOURCE_FORMAT ???] [DESTINATION_FORMAT ???]
Seite 28Seite 28Jan 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, OutputStream output);
Belegtes Thematisches Raster
Copy
[OBJECT bytes]
[SOURCE from an ASCII File] [DESTINATION to an OutputStream]
[SOURCE_FORMAT from ASCII] [DESTINATION_FORMAT to UTF-8]
Seite 29Seite 29Jan Christian Krause und Alexander Mills
Konzept für automatisierte Lückenerkennung
API-Vertrag
Operations-
bezeichner
Thematisches
Raster
Präpositional-
phrasen
Thematische
RollenBelegung des
Rasters
Fehlende
Belegung
=
Hinweis auf
Stille
Seite 30Seite 30Jan Christian Krause und Alexander Mills
Demonstration des Prototypen
Seite 32Seite 32Jan 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.
Seite 33Seite 33Jan Christian Krause und Alexander Mills
Vielen Dank für Ihre Aufmerksamkeit
Haben Sie Fragen?
Seite 34Seite 34Jan Christian Krause und Alexander Mills
Jan Christian Krause
Software-Entwickler
Mail [email protected]
Twitter @iDocIt
Blog idocit.blogspot.de
Github https://github.com/jankrause
Alexander Mills
Software-Entwickler
Mail [email protected]
Kontakt
Seite 35Seite 35Jan 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: (ohne Herausgeber) SIGDOC '99: Proceedings of the 17th annual
internationalconference on Computer documentation, Seiten 147 - 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 Lorge Parnas. Information distribution aspects of design methodology. In: C.V.
Freiman, J.E. Grith und J.L. Rosenfeld (Hrsg.), Information Processing 71 - Proceedings of
the IFIP Congress 71, Band 1, Seiten 339 - 344, Amsterdam, London, 1971. North Holland
Publishing Company.
• David Lorge Parnas. 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/7022 verfügbar (letzter Abruf: 13.11.2014).
Seite 36Seite 36Jan 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
Seite 37Seite 37Jan Christian Krause und Alexander Mills
Thematische Raster
Prüfende Operation Parsende Operation
Schlussfolgernde Operation Deponierende Operation
Konvertierende Operation Löschende Operation
Erzeugende Operation Rücksetzende Operation
Beschreibende Operation Suchende Operation
Duplizierende Operation Sendende Operation
Verbindende Operation Initiierende Operation
Lesende Operation Substituierende Operation
Protokollierende Operation Traversierende OPeration
Berechnende Operation Zusammenführende Operation
Seite 38Seite 38Jan Christian Krause und Alexander Mills
Evaluierung des Prototypen
33%
21%18%
28%
Gefundene Lücke Gefundene Belegung
Nicht gefundene Belegung Nicht gefundene Lücke
Seite 39Seite 39Jan 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
Seite 40Seite 40Jan 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
Seite 41Seite 41Jan Christian Krause und Alexander Mills
Empfehlungen zur Formulierung
Thematische Rollen (bewusst) durch Präpositionen einleiten
Richtig:
grep searches lines in the named input FILEs
Falsch:
grep searches the named input FILEs for lines
Seite 42Seite 42Jan 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.