Finishing the Annotation - Targets and Elements4:01 with Chris Ramacciotti
During this video we will continue writing our annotation, first by specifying the targets. These configure which Java components can be "decorated" with our annotation, for example classes, methods, fields, etc. We'll wrap up the annotation by defining elements or attributes. Think of these elements as instance fields for the Java component that's been annotated.
Valid Locations for Annotations
While creating our annotation, we used the following to indicate that we want developers to be able to apply the
@Doc annotation to classes and methods:
To see a list of all your options, check out the official docs for the ElementType enum.
To continue writing our own annotation, 0:00 the next thing we want to do is indicate where our annotation can be used. 0:02 This is accomplished using the Target() annotation. 0:06 When we include the Target() annotation, we need to specify element types. 0:12 What we're doing here is telling the compiler about the valid places that 0:16 our annotation can be used. 0:19 In our case we want programmers to use doc annotation on classes and methods, so 0:20 we'll specify those element types and 0:25 since there is more than one, we will use array notation. 0:27 We want to allow our annotation to be used on classes so 0:31 that's ElementType.TYPE as well as methods ElementType.METHOD. 0:37 And since we've now used an new annotation, Target(), and 0:45 referenced a new class, ElementType, we'll add import statements for each of those. 0:48 So for the annotation, java.lang.annotation.Target. 0:53 And the element type class will import java.lang.annotation.ElementType. 0:59 Great, I've linked to the Java doc of the ElementType enum in the teacher's notes so 1:06 that you can see all possible options available. 1:12 The last task in our doc annotation, is to add what are called elements. 1:16 Think of these as the attributes of the annotation itself. 1:20 In our case, 1:23 they're the pieces we want our programmers to include when using our doc annotation. 1:24 I have comments listed for 1:28 three such elements, though you could probably come up with more. 1:30 In general, you'll declare element names as zero parameter, non-void methods. 1:33 You won't need to add public, 1:38 since all interface methods in Java are public by default. 1:40 Let's start with the first one listed, the description. 1:43 We'll abbreviate this one desc(), whose return type is String. 1:46 Though this is technically an interface method declaration, they behave a bit more 1:53 fields whose values are set when the annotation is added to a class or method. 1:57 With this in mind, we can specify a default value for each element. 2:01 If we do this, we are saying that the annotation, when added to a class or 2:05 method, doesn't have to include a value for this element. 2:08 Let's go ahead and add defaults to all our elements. 2:11 In the case of the description, we'll set the default as an empty string. 2:14 Moving right along to the description of parameters, we'll need this one to be 2:20 a bit more flexible, since a method could contain any number of parameters. 2:24 Let's specify the return type of this one to be a String whose default is 2:28 an empty array. 2:32 So we'll define it as a String, we'll call is params(), and 2:36 we'll default it to an empty array. 2:40 And remember, 2:43 when you initialize an array, you can specify the elements in curly braces, 2:43 since we want to default to an empty array, we'll use empty curly braces. 2:48 Great, two down, one to go. 2:53 This one will be a lot like the description, 2:55 in that it'll simply be a string value. 2:57 I'll call it returnval and default it to an empty String. 2:59 And that's it. 3:11 Defining the annotation is not a lengthy process. 3:14 In an industry project, 3:17 you'd probably spend more time planning than actually coding the annotation. 3:19 Though, to be fair, this is probably true for designing and 3:23 coding any software component. 3:26 Now that we've coded the annotation, we can apply it to classes and methods. 3:29 We're going to do that in the MathUtils class in the next video. 3:34 But before you go there, why not try adding our new annotation yourself? 3:37 Try adding it to the class and to each method, and then come back and 3:41 see how I do it. 3:45 Remember that not all the elements will apply to the class. 3:47 And, since we didn't name any of our elements value, 3:51 you'll have explicitly list the element names in your annotations. 3:55 Give it a shot and meet me right back here. 3:59
You need to sign up for Treehouse in order to download course files.Sign up