Download as PDF, PPTX
![!
http://docs.oracle.com/javaee/1.4/tutorial/examples/jaxp/xslt/samples/
TransformationApp04.java
!
public
class
TransformationApp04
{
public
static
void
main(String[]
argv)
{
if
(argv.length
!=
1)
{
System.err.println("Usage:
java
TransformationApp
filename");
System.exit(1);
}
!
//
Create
the
sax
"parser".
AddressBookReader02
saxReader
=
new
AddressBookReader02();
var
json_data
=
JSON.stringify(obj);
try
{
File
f
=
new
File(argv[0]);
!
!
//
Use
a
Transformer
for
output
TransformerFactory
tFactory
=
TransformerFactory.newInstance();
Transformer
transformer
=
tFactory.newTransformer();
!
//
Use
the
parser
as
a
SAX
source
for
input
FileReader
fr
=
new
FileReader(f);
BufferedReader
br
=
new
BufferedReader(fr);
InputSource
inputSource
=
new
InputSource(fr);
SAXSource
source
=
new
SAXSource(saxReader,
inputSource);
StreamResult
result
=
new
StreamResult(System.out);
transformer.transform(source,
result);
}
catch
(TransformerConfigurationException
tce)
{
//
Error
generated
by
the
parser
System.out.println("n**
Transformer
Factory
error");
System.out.println("
"
+
tce.getMessage());
!](https://image.slidesharecdn.com/practicesandtoolsforbuildingbetterapisjfall-131106065639-phpapp01/75/Practices-and-tools-for-building-better-API-JFall-2013-8-2048.jpg)
Uploaded byPeter Hendriks
Practices and tools for building better API (JFall 2013)
The document discusses best practices and tools for building better APIs from a Java developer's perspective, emphasizing the importance of API design, usability, stability, and quality. It highlights the significance of examples in API documentation, the need for simplicity in design, and the avoidance of verbose constructs to enhance code usability and maintainability. The document also outlines various factors that contribute to API quality, including learnability, efficiency, and error handling, along with practical tips for implementation.
Practices and tools for building better API (JFall 2013)
- 1. Practices and Tools for Building Better APIs @PeterHendriks80, +PeterHendriks
- 2. Objectives of this talk • API from a Java app developer perspective ! • • • • Why API is important What makes a better API Practical tips and tools Measuring your existing codebase
- 3. Some API terminology •API Consumer: code that uses API • API: the interface • API Implementer: code that implements API API Consumer API API Implementer Data Access Object JDBC Database Driver
- 4. We are using a lot of API Bazillion Open Source Web Framework API’s Spring: 27 API’s Java EE: 37 API’s Java SE: 45 API’s Enterprise Service API’s Public Service API’s Cloud API’s Middleware API’s
- 5. We are building more of them, too • API is key to a succesful module design – Essential for agile teams at scale Customer Front-‐End Warehouse Front-‐End Order Management Shared code
- 6. Distance to API implementation is increasing • API quality increasing important when implementation becomes a black box Same team Different team Open source Binary only Other datacenter
- 7. The API we use shapes our code • Most code we write calls an API • Code that calls an API is shaped to fit the API • Therefore, APIs determine the shape of application code – In some ways, even more impactful than high level design, test driven development or code craftsmanship
- 8. ! http://docs.oracle.com/javaee/1.4/tutorial/examples/jaxp/xslt/samples/ TransformationApp04.java ! public class TransformationApp04 { public static void main(String[] argv) { if (argv.length != 1) { System.err.println("Usage: java TransformationApp filename"); System.exit(1); } ! // Create the sax "parser". AddressBookReader02 saxReader = new AddressBookReader02(); var json_data = JSON.stringify(obj); try { File f = new File(argv[0]); ! ! // Use a Transformer for output TransformerFactory tFactory = TransformerFactory.newInstance(); Transformer transformer = tFactory.newTransformer(); ! // Use the parser as a SAX source for input FileReader fr = new FileReader(f); BufferedReader br = new BufferedReader(fr); InputSource inputSource = new InputSource(fr); SAXSource source = new SAXSource(saxReader, inputSource); StreamResult result = new StreamResult(System.out); transformer.transform(source, result); } catch (TransformerConfigurationException tce) { // Error generated by the parser System.out.println("n** Transformer Factory error"); System.out.println(" " + tce.getMessage()); !
- 9. What makes a better API
- 10. API Quality: Value •Value = benefits -‐ costs • Benefits – Features – Data – ... • Costs – – – – License/pay per use Performance/footprint Security …
- 11. API Quality: Usability •API Design == Human Interface design – Although API is for machine/machine interaction, APIs need to be understood by programmers to write the code – Programmers are humans API is not just about capability and structural design, but also about human understanding
- 12. A simple model for API Usability Generic usability model by Ben Shneiderman: Learnability: How easy is it to accomplish basic tasks the first time? Efficiency: Once users learned the design, how quickly can they perform tasks? Memorability: When users return after a while, how easily can they re-‐establish proficiency? Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors? Satisfaction: How pleasant is it to use the design?
- 13. API Quality: stability Able to enhance/grow implementation without breaking existing consumer code Google AppEngine release notes: Version 1.7.5 -‐ February 13, 2013 The Conversion API, which was decommissioned last release, has been removed from the SDK. In a future release, the API will be removed from the runtime and applications that attempt to use it may stop working. Applications in production that import the library should be fixed as soon as possible. Version 1.8.4 -‐ September 9, 2013 The Conversion API, a decommissioned feature, has been removed from the SDK. In the next release, the API will be removed from the runtime and any attempt to import the API will raise an exception. Version 1.8.5 -‐ September 25, 2013 The Conversion API, a decommissioned feature, has been removed from the runtime. Applications in production that import the API should be fixed as soon as possible.
- 14. API Quality: A hierarchy of needs Stability only matters when API is valuable and usable Stable Usable Valuable
- 15.
- 16. API Design: start with examples • Examples most important in API documentation – Concrete use case, usability check • Make examples exemplary – Example code will be copy-‐pasted • Create a cheat sheet – Improves learnability – Shows design issues
- 17. API Design: multiple perspectives Names, Completeness, Grouping UML: public class Document { ! ! private List<Page> pages = new ArrayList<>(); Impl: Consumer: public Page addPage() { Page page = new Page(); pages.add(page); page.setPageNumber(pages.size()); return page; } public void report() {...} } Page page = document.addPage(); page.setContents("Once upon a time..."); Can it be built? Is it usable?
- 18. API practice: Keep it simple • Try to stick to just methods and constructors – Factories, Delegates, etc. not always necessary ! • “When in doubt leave it out” – Less classes, methods – Less parameters, return values Josh Bloch, Java API guru
- 19. API practice: avoid verbose constructs • Constructs that create verbose consumer code – Extending class/implementing interface – Checked exception – Required casting – Required generic type – Required if, for, while, try/finally – Required synchronization/locking – Hard coded parameter value
- 20. Example: doing some loggin’ • Demo: different styles of logging API
- 21. Why Lambdas are so much better than inner classes • Inner classes, or extending existing classes often needed – Resource handling – Looping/visiting collections – Event handling • Lambdas provide a much more usable construct – Shorter, safer, better footprint/performance
- 22. Example: Lambda benefits •Demo: Netbeans example
- 23. API practice: fail fast, fail hard • Fail immediately on wrong input • Limit the use of null as valid input/output public void save(String filename) { if (filename == null) { return; // bad api: error is ignored! } ... // save happens here } Better public void save(String filename) { Objects.requireNonNull(filename); // Throws NPE immediately ... // save happens here }
- 24. API Tool: checking for null • Tool: FindBugs, a static code analyzer – Reports errors at compile-‐time • Annotations for Software Defect Detection (JSR 305: Dormant) – @Nonnull: may never be null – @CheckForNull: should always be checked before dereferenced – @Nullable: caller decides if null check is needed • Java 8 will add more annotation options for tools
- 25. FindBugs demo in Eclipse
- 26. Finding API problems in your code • People – Team knowledge – Policy, “best practices”, conventions – Elaborate explanation, “hard to do” – Defect lists/exceptions/stack traces • Tools – Finding most used API: Dependency Structure Matrix (DSM)
- 27. How a Dependency Structure Matrix works Classes/Packages Document Document 2 TextBlock -‐ Page Page TextBlock -‐ 10 # of direct dependencies from Document to Page -‐
- 28.
- 29. API design cheat sheet API matters: Reuse 3rd party Modular design Distance to impl. A Better API is: 1. Valuable 2. Usable 3. Stable API usability: • Learnability • Efficiency • Memorability • Error rate • Satisfaction API Design Perspectives: UML: names, completeness, grouping Implementation: can it be built API usage: how usable is it Examples First JSR 305/FindBugs: @Nonnull: may never be null @CheckForNull: always check @Nullable: caller decides null check DSM: finding most used API Document Document 2 TextBlock -‐ Page Page TextBlock -‐ 10 @PeterHendriks80, +PeterHendriks -‐ API Design practices: When in doubt leave it out Limit API consumer code to a minimum • Extending class/interface • Checked Exception • Required casting • Required Generic Type • Hard coded parameter value • Required if, for, while, try • Required synchronization/locking ! Be predictable and obvious • Methods calleable in any order • Constructor should only construct • Don’t have surprising side effects • Limit null as input/output • Fail fast, fail hard Eval!