Een belangrijke voorwaarde om goede en leesbare Java code te schrijven is om gebruik te maken van een goede API. Een goede API helpt ontwikkelaars om sneller hoogwaardige code te schrijven. Het ontwerp van een API is daarom belangrijk, zeker als er grotere systemen worden gerealiseerd in teamverband. Moderne ontwikkeltools als Eclipse, IntelliJ IDEA en FindBugs helpen met het schrijven van goede API, en het detecteren van slecht gebruik. Deze sessie gaat in op de laatste ontwikkelingen en mogelijkheden, inclusief nieuwe taalmogelijkheden in Java 8. Er wordt hierbij gebruik gemaakt van praktische situaties en concrete codevoorbeelden, gebaseerd op echte ervaringen in grote codebases. Met praktische tips en toegankelijke tools kan al een grote stap gemaakt worden om in de praktijk beter met API ontwerp om te gaan!
The Role of Taxonomy and Ontology in Semantic Layers - Heather Hedden.pdf
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());
!
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
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
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
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
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
-‐
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!