1
00:00:00,350 --> 00:00:02,130
Okay, we're ready to begin.

2
00:00:02,130 --> 00:00:05,080
Let's now switch to the doc annotation.

3
00:00:05,080 --> 00:00:10,730
The first thing you'll notice is that the
annotation is declared with at interface.

4
00:00:10,730 --> 00:00:13,560
It's not a traditional interface that
would need to be leveraged by using

5
00:00:13,560 --> 00:00:16,850
the implements keyword,
this one is different.

6
00:00:16,850 --> 00:00:21,170
The use of this at sign here
tells the Java compiler that

7
00:00:21,170 --> 00:00:23,540
this will be an annotation.

8
00:00:23,540 --> 00:00:27,410
In general, we'll want to do three things
when we declare an interface in Java.

9
00:00:27,410 --> 00:00:30,960
Number one is declare the interface
itself, I have done this for you.

10
00:00:30,960 --> 00:00:35,210
Number two, specify what
are called retention and targets.

11
00:00:35,210 --> 00:00:37,679
And number three,
add elements or attributes.

12
00:00:39,060 --> 00:00:44,060
Now these first two steps involve adding
other annotations to our own annotation.

13
00:00:44,060 --> 00:00:47,780
This might seem a little cyclic at first,
but you'll see that these new annotations

14
00:00:47,780 --> 00:00:50,260
are part of the Java
annotation framework itself.

15
00:00:51,550 --> 00:00:55,730
The first thing we'll do is specify what's
called the retention of this annotation.

16
00:00:55,730 --> 00:01:00,590
That is, how long will the doc annotation
be retained in Java files that use this?

17
00:01:00,590 --> 00:01:04,909
In order to add this,
we will use the retention annotation.

18
00:01:06,699 --> 00:01:10,640
Now in parentheses here,
we have three choices.

19
00:01:10,640 --> 00:01:15,864
Number one, RetentionPolicy.SOURCE,
number 2 two RetentionPolicy.CLASS,

20
00:01:15,864 --> 00:01:18,890
or number three, RetentionPolicy.Runtime.

21
00:01:20,150 --> 00:01:21,660
If we choose source,

22
00:01:21,660 --> 00:01:25,870
we're telling the Java compiler to throw
away the annotation upon compiling.

23
00:01:25,870 --> 00:01:28,880
This is how the override and
suppress warnings annotations are defined.

24
00:01:28,880 --> 00:01:34,176
The compiler uses them to help it in
compiling, and then throws them away.

25
00:01:34,176 --> 00:01:36,690
We might want to choose it
if it's only important for

26
00:01:36,690 --> 00:01:41,190
compiler messages, but the annotations
themselves wouldn't be available during

27
00:01:41,190 --> 00:01:44,500
run time to analyze their presence,
so we won't be using source.

28
00:01:45,820 --> 00:01:49,940
If we choose class, we're telling
the compiler to retain the annotations in

29
00:01:49,940 --> 00:01:52,310
the byte code that the compiler produces.

30
00:01:52,310 --> 00:01:53,730
But with this option,

31
00:01:53,730 --> 00:01:57,550
the annotations are not loaded into
the JVM while running the program.

32
00:01:57,550 --> 00:02:01,450
This means that, again, they're not
available for analysis at run time.

33
00:02:01,450 --> 00:02:03,040
We'll pass up the CLASS option as well.

34
00:02:04,570 --> 00:02:08,280
Finally we can choose runtime,
which is exactly what it sounds like.

35
00:02:08,280 --> 00:02:10,700
It means they're included
in the compiled code and

36
00:02:10,700 --> 00:02:14,540
made available to the JVM
upon running our application.

37
00:02:14,540 --> 00:02:18,500
We'll pick runtime because it will allow
us to examine the MathUtils class for

38
00:02:18,500 --> 00:02:20,160
the presence of annotations,

39
00:02:20,160 --> 00:02:23,560
using an approach called reflection,
more on reflection later.

40
00:02:23,560 --> 00:02:25,810
Let's add the runtime
retention policy now.

41
00:02:25,810 --> 00:02:30,790
So in parentheses of
the retention annotation,

42
00:02:30,790 --> 00:02:34,230
we will add RetentionPolicy.RUNTIME
in all caps.

43
00:02:35,580 --> 00:02:39,753
Now, in order to use both the retention
annotation and reference the retention

44
00:02:39,753 --> 00:02:43,501
policy class, we'll need to add
import statements for both of those.

45
00:02:43,501 --> 00:02:52,052
So import java.lang.annotation.retention.

46
00:02:52,052 --> 00:02:59,210
Also, import
java.lang.annotation.retentionpolicy.

47
00:03:01,320 --> 00:03:02,210
As a side note,

48
00:03:02,210 --> 00:03:06,560
the deprecated annotation is defined using
the runtime as its retention policy.

49
00:03:07,710 --> 00:03:11,470
Also, I want to point out that when you
put things in parentheses while adding

50
00:03:11,470 --> 00:03:15,980
annotations, kind of like we did with
suppressed warnings in a previous video,

51
00:03:15,980 --> 00:03:20,560
or like we're doing here with
the retention policy.runtime,

52
00:03:20,560 --> 00:03:25,690
we're actually passing a value to what's
called an element of the annotation.

53
00:03:25,690 --> 00:03:28,560
To drive that point home, we could
type the actual name of the element,

54
00:03:28,560 --> 00:03:30,630
which in this case is value.

55
00:03:31,730 --> 00:03:35,000
If there were more elements in the
annotation we'd create a comma separated

56
00:03:35,000 --> 00:03:39,840
list of name value pairs, according
to how the annotation is defined.

57
00:03:39,840 --> 00:03:44,890
For example, we could write
something equal stuff comma,

58
00:03:44,890 --> 00:03:49,530
something else equals things,
if the annotation itself

59
00:03:49,530 --> 00:03:52,460
happened to have elements named
something or something else.

60
00:03:53,820 --> 00:03:56,450
This annotation does not, so
I'll go ahead and remove and remove those.

61
00:03:57,770 --> 00:04:00,720
Java does allow you to leave
out the name of an element,

62
00:04:00,720 --> 00:04:04,690
if the element's name is exactly value.

63
00:04:04,690 --> 00:04:08,740
So when we leave out this
value equals right here,

64
00:04:08,740 --> 00:04:10,830
we're actually using shorthand.

65
00:04:10,830 --> 00:04:13,180
We'll continue to use this
shortened syntax, but

66
00:04:13,180 --> 00:04:14,640
now you know what it really means.