Java APIs - the missing manual

@HendrikEbbers
Karakun DevHub_
dev.karakun.com

@HendrikEbbers
JavaAPIsThe missing manual

Karakun DevHub_
@HendrikEbbersdev.karakun.com
About me
• Karakun Co-Founder
• Lead of JUG Dortmund
• JSR EG member
• JavaOne Rockstar, Java Champion
• JavaLand Programm Chair

Karakun DevHub_
About me

Karakun DevHub_
Service Provider Interface
• Based on Interfaces it's quite easy to deﬁne a
general service and several implementations in
Java

Karakun DevHub_
public interface MathOperation {
String getSign();
double calc(double valA, double valB);
}

Karakun DevHub_
• We can provide several implementations of math
operations
•AddOperation
•SubtractOperation

Karakun DevHub_
public class Multiply implements MathOperation {
public String getSign() { return "*";}
double calc(double valA, double valB){
return valA * valB;
}
}

Karakun DevHub_
• Instances of the implementations can be accessed
by using the general interface
• All instances can simply be stored in a collection

Karakun DevHub_
List<MathOperation> operations = new ArrayList<>();
operations.add(new MultipyOperation());
operations.add(new AddOperation());
operations.add(new DivideOperation());
operations.add(new SubtractOperation());
operations.forEach(o -> {
System.out.println("Supported Operation: " + o.getSign());
});

Karakun DevHub_
• Let's pimp our interface ;)
• With Java 8 default methods we can even deﬁne
default logic for some parts of the service
• Use defaults only if it really makes sense!

Karakun DevHub_
String getSign();
default String getHelp() {
return "No help text for sign" + getSign();
}
}

Karakun DevHub_
• Let's think about a bigger application
• Often based on several modules / jars
• Several jars contains several service
implementations

Karakun DevHub_
Application
Basic Math
Module
Math Def
Module
Special Math
Module
contains the interface

Karakun DevHub_
Application
Basic Math
Module
Math Def
Module
Special Math
Module
contains implementations

Karakun DevHub_
Application
Basic Math
Module
Math Def
Module
Special Math
Module
use implementations

Karakun DevHub_
Application
Basic Math
Module
Math Def
Module
Special Math
Module
depends on
depends on
depends ondepends on

Karakun DevHub_
Application
Basic Math
Module
Math Def
Module
Special Math
Module
depends on
depends on
depends ondepends on
One Million
Dollar Question

Karakun DevHub_
• Where should we deﬁne the following method?
public List<MathOperation> getAllImplInClasspath();
?

Karakun DevHub_
• We can't deﬁne it in the "Math Def Module" since
this module has no dependency to any
implementation
• Method would return 
an empty list

Karakun DevHub_
• We can't deﬁne it in the "Basic Math" or the
"Special Math" since this modules don't know all
implementations.
• Method would not return  
all implementations

Karakun DevHub_
• Only the "Application" module knows all
implementations since it's the only module that
depends on all other modules

Karakun DevHub_
That was easy, bro!

Karakun DevHub_
• Let's add some complexity
Basic Math
Module
Math Def  
Module
Special Math
Module
Algebra Math
Module
Geometry Math
Module

Karakun DevHub_
Basic Math
Module
Math Def  
Module
Special Math
Module
Algebra Math
Module
Geometry Math
Module
Customer A
App
Customer B
App
Customer C
App

Karakun DevHub_
Headline
• We don't want to implement the 
 
method for each application
• We need something new that loads all
implementations dynamically

Karakun DevHub_
• Service Provider Interface (SPI) provides a simple
API to solve this issue
• Could be used to create a minimal but powerful
Plug In API

Karakun DevHub_
• Start by creating an interface
String getSign();
}
we already have it

Karakun DevHub_
• Each module that provides implementations of
the interface most provide a service ﬁle
• File must be located under META-INF/services/
before
Java 9

Karakun DevHub_
• Name of the ﬁle must be equals to the interface
name
META-INF/services/com.canoo.math.MathOperation
File name
before
Java 9

Karakun DevHub_
• File simply contains names of all implementations
com.canoo.basic.AddOperation 
com.canoo.basic.MinusOperation
define one
implementation per
line
before
Java 9

Karakun DevHub_
• The Service Provider Interface (SPI) will
automatically ﬁnd all implementations at runtime
• Instances of the classes will automatically be
created
• Default constructor is needed

Karakun DevHub_
• You can simply iterate over all implementations
Iterator<MathOperation> iterator = ServiceLoader
.load(MathOperation.class)
.iterator();
 
while (iterator.hasNext()) { 
MathOperation operation = iterator.next(); 
}

Karakun DevHub_
• At the end we can implement the 
 
method simple in the "Math Def Module"
• The service provider  
will automatically ﬁnd 
all implementations

Karakun DevHub_
Annotations
• Let's start with a quiz :)
• How many Java annotations are used in the code?
?

Karakun DevHub_
Annotations
/** 
* A helper class 
* @see Class#getModifiers() 
* 
* @author Hendrik Ebbers
* @deprecated 
*/
@Deprecated
public class Helper {
@Important
private Logger logger = new Logger();
/** 
* Return {@code true} if the integer argument includes the {@code private} modifier, {@code false} otherwise. 
* 
* @param mod a set of modifiers 
* @return {@code true} if {@code mod} includes the {@code private} modifier; {@code false} otherwise. 
*/
@Static(false) 
public static boolean isPrivate(@Param int mod) { 
return (mod & 0x00000002) != 0; 
}
}

Karakun DevHub_
Annotations
/** 
* A helper class 
* 
* @deprecated 
*/
@Deprecated
@Important
/** 
* 
*/
@Static(false) 
return (mod & 0x00000002) != 0; 
}
}
@Deprecated
annotation is defined
in the JRE

Karakun DevHub_
Annotations
/** 
* A helper class 
* 
* @deprecated 
*/
@Deprecated
@Important
/** 
* 
*/
@Static(false) 
return (mod & 0x00000002) != 0; 
}
}
the @Important annotation is not defined in
the JRE but it's easy to create your own
custom annotations (like @Autowired in
Spring)

Karakun DevHub_
Annotations
/** 
* A helper class 
* 
* @deprecated 
*/
@Deprecated
@Important
/** 
* 
*/
@Static(false) 
return (mod & 0x00000002) != 0; 
}
}
the @Static annotation is
configured by a boolean parameter

Karakun DevHub_
Annotations
/** 
* A helper class 
* 
* @deprecated 
*/
@Deprecated
@Important
/** 
* 
*/
@Static(false) 
return (mod & 0x00000002) != 0; 
}
}
the @Param annotation is another
custom annotation that is used to
annotate a method param

Karakun DevHub_
Annotations
• Annotations can be used to add metadata to the
code
• Annotations can be added to diﬀerent points of the
code
• Annotation can be parametrable
• Custom annotations can be deﬁned

Karakun DevHub_
Annotations
public @interface MyAnnotation {
}

Karakun DevHub_
Annotations
}
access modifier name
annotation keyword

Karakun DevHub_
Annotations
@Documented
@Retention(RUNTIME)
@Target(METHOD)
}

Karakun DevHub_
Annotations
?
@Documented
@Retention(RUNTIME)
@Target(METHOD)
}

Karakun DevHub_
@Documented
@Retention(RUNTIME)
@Target(ANNOTATION_TYPE)
public @interface Documented {
}
Annotations

Karakun DevHub_
Annotations
• If an annotation is annotated with @Documented
the usage of the annotation will be shown in
JavaDoc
• The usage of @Documented has no eﬀect at
runtime

Karakun DevHub_
Annotations
• The @Target annotation deﬁnes where an
annotation can be used.
• The enum ElementType deﬁnes all supported
types

Karakun DevHub_
Annotations
• TYPE
• FIELD
• METHOD
• PARAMETER
• CONSTRUCTOR
• LOCAL_VARIABLE
• ANNOTATION_TYPE
• PACKAGE
• TYPE_PARAMETER
• TYPE_USE[ [

Karakun DevHub_
Annotations
@Target(METHOD)
}
@MyAnnotation
public void sqrt(int value) {
return 1;
}

Karakun DevHub_
Annotations
@Target(METHOD)
}
public void sqrt(@MyAnnotation int value) {
return 1;
}

Karakun DevHub_
Annotations
@Target(PARAMETER)
}
return 1;
}

Karakun DevHub_
Annotations
@Target({PARAMETER, METHOD})
}
@MyAnnotation
return 1;
}

Karakun DevHub_
Annotations
• The @Retention annotation deﬁnes how long an
annotation will be retained.
• The enum RetentionPolicy deﬁnes all
supported types

Karakun DevHub_
Annotations
SOURCE CLASS RUNTIME
remove annotation at
compiletime
remove annotation at
runtime
do not remove
annotation

Karakun DevHub_
Annotations
SOURCE CLASS RUNTIME
general meta
information like
@Override
for example the
annotations of findbugs
All annotations
that are used at
runtime

Karakun DevHub_
Annotations
• There are several ways how annotations can be
used
• Annotations like @Deprecated deﬁne useful
information for the developer (IDE support) and
compiler

Karakun DevHub_
Annotations
• Projects like Lombok use annotations for
annotation processing at compile time
• Annotations like @Inject are used to modify
objects at runtime

Karakun DevHub_
Annotations
• All annotations that have a @Retention policy
that is deﬁned as RUNTIME can be accessed by
using reﬂection.
• In general this is one of the tricks that make DI or
Spring work

Karakun DevHub_
Annotations
• How can I check for annotations in my code at
runtime
?

Karakun DevHub_
Reﬂections

Karakun DevHub_
Annotations
Class cls = MyCustomClass.class; 
boolean val = cls.isAnnotationPresent(MyAnnotation.class);
• We will see more samples later

Karakun DevHub_
Annotations
• But there is more
• Annotations can be "conﬁgured"
• Java provides some nice language features here

Karakun DevHub_
Annotations
• Annotations can contain parameters
public @interface Column {
String name();
}
@Column(name="Description")
private String desc;

Karakun DevHub_
Annotations
• Annotations can deﬁne multiple parameters
• The following types are allowed:
• primitive
• String
• Class
• an Enum
• another Annotation
• an array of any of the types

Karakun DevHub_
Annotations
• If an Annotations only needs one param it should
be named as "value"
• By doing so the name must not be speciﬁed when
using the annotation

Karakun DevHub_
Annotations
String value();
}
@Column("Name")
private String name;

Karakun DevHub_
Annotations
• Annotations can deﬁne a default value for a
parameters
String name() default "";
}
@Column
private String name;

Karakun DevHub_
Annotations
• Access annotation parameters
final Class cls = MyCustomClass.class;
 
if(cls.isAnnotationPresent(MyAnnotation.class)){
final MyAnnotation a = cls.getAnnotation(MyAnnotation.class);
final String name = a.name();
System.out.println("Name: " + name);
}

Karakun DevHub_
Annotations
• Additional topics:
•@Inherited
• Lists of annotations
• Meta annotations
• Annotation Processor

Karakun DevHub_
Streams
• Classes to support functional-style operations on
streams of elements, such as map-reduce
transformations on collections.
Stream.of("A", "B", "C")
.forEach(s -> System.out.println(s));

Karakun DevHub_
Streams
• Sequence of elements
• Aggregate operations (ﬁlter, map, limit, reduce…)
• Pipelining − Most of the stream operations return
stream itself
Filter Map Reduce

Karakun DevHub_
Streams
• Let's create a stream that converts String values
to int values

Karakun DevHub_
Streams
Stream.of("1", "2", "3")
.map(s -> Integer.parseInt(s))
.forEach(i -> System.out.println("INT " + i));

Karakun DevHub_
Streams
• Let's see if this is really the perfect solution…
Stream.of("1", "2", "3", "X")
.map(s -> Integer.parseInt(s))

Karakun DevHub_
Exceptions in Streams
• Stream operations are not made to handle
exceptions
• To be more clear the functional interfaces in
java.util.function can not handle
exceptions.

Karakun DevHub_
• Let's ﬁnd a solution
Stream.of("1", "2", "3", "X")
.map(s -> {
try {
return Integer.parseInt(s)
} catch(Exception e) {
return -1;
}
})

Karakun DevHub_
Stream.of("1", "2", "3", "X")
.map(s -> {
try {
return -1;
}
})
Nope! That is not
what we want…

Karakun DevHub_
Stream.of("1", "2", "3", "X")
.map(s -> {
try {
throw new RuntimeException("…",e);
}
})

Karakun DevHub_
public int convert(String s) {
try {
throw new RuntimeException("Can not convert to int!"e);
}
}
Stream.of("1", "2", "3", "X")
.map(s -> convert(s))

Karakun DevHub_
• The current approach looks ok but is far away
from a general solution
• We need to be more generic

Karakun DevHub_
Checked functions
• Let's create or custom functional interface
• Libraries like VAVR do exactly this
@FunctionalInterface
public interface CheckedFunction<T, R> {
R apply(T t) throws Exception;
}

Karakun DevHub_
Checked functions
@FunctionalInterface
public interface CheckedFunction<T, R> {
R apply(T t) throws Exception;
static <T,R> Function<T,R> wrap(CheckedFunction<T,R> f) {
Objects.requireNonNull(f, "Function must not be null");
return t -> {
try {
f.apply(t);
throw new RuntimeException(e);
}
};
}
}

Karakun DevHub_
Checked functions
• Now we have a general solution to handle
exceptions in streams…
Stream.of("1", "2", "3", "X")
.map(s -> CheckedFunction.wrap(s -> Integer.parseInt(s)))

@HendrikEbbers
Result
1 2 3 Error

Karakun DevHub_
Checked functions
• Let's just change 2 chars…
Stream.of("1", "X", "3", "4")
.map(s -> CheckedFunction.wrap(s -> Integer.parseInt(s)))

Karakun DevHub_
Additonal (functional) types
• The exception stops the stream
• But we can not return a default value
• We need to ﬁnd a way to handle the complete
stream with exception support
• Again libraries like VAVR have some solutions

Karakun DevHub_
Stream.of("1", "2", "A", "4").map(Result.of(s ->Integer.parseInt(s)))
.forEach(r -> {
if(r.isSuccessfull()) {
System.out.println(r.getInput() + " -> " + r.getResult());
} else {
System.out.println("Error for " + r.getInput());
Integer.parseInt("");
}
});

Karakun DevHub_
public void handle(final Result<String, Integer> result) {
if(result.isSuccessfull()) {
System.out.println(result.getInput() + " -> " + result.getResult());
} else {
System.out.println("Error for " + result.getInput());
}
}
Stream.of("1", "2", "A", "4")
.map(Result.of(s ->Integer.parseInt(s)))
.forEach(r -> handle(r));

Karakun DevHub_
Result<INPUT, OUTPUT>
Sucess<INPUT, OUTPUT> Fail<INPUT, OUTPUT>
Extends Extends

Karakun DevHub_
Input Result

Karakun DevHub_
Input
Exeption

@HendrikEbbers
Karakun AG @
• Web-APIs: Das ultimative Handbuch
• Progressive Web Apps mit der Service Worker API
• Free React nighthacking in the oﬃce space of Eppleton
https://goo.gl/1wX3t3
dev.karakun.com | @HendrikEbbers

Java APIs - the missing manual

More Related Content

What's hot

Similar to Java APIs - the missing manual

More from Hendrik Ebbers

Recently uploaded

Java APIs - the missing manual