Hello, Jim.
Today we're going to learn with you what annotations are, how to work with them and how to create new
ones.
Before we start this lesson, I must say that it is critically important you watching previous lesson
about Reflection API.
If you skip that one, please make sure you watch it, because in this lesson, we are going to use
Réflexion API to work with annotations.
Basically, there is not so much as a ways for us to take advantage from annotations without knowing
the Reflection API.
In this lesson, we're going to learn everything.
The related to annotations will start from the definition of annotation, make you understand what annotations
are on the standard banner.
We are going to discuss use cases when annotations may be applied and for what purposes.
After that, we will start reviewing of the source code examples.
I will explain you what targets annotation is and what retention annotation is.
We are going to create our own custom annotation and you are going to understand how to create it and
process it.
And at the end of the lesson, I will also explain you how to create repeatable annotations.
Let's stop.
And the first question that we have to answer sounds like this.
What is annotation?
Annotation as a form of metadata provides data about programs.
It is not part of the program itself.
Annotations have no direct effect on the operation of the court.
They annotate the understands this definition.
The know what is metadata.
Metadata is a data that provides information about other data or similar data about data in program,
and we can annotate types, colossus and interfaces, fields, masses, parameters, constructors,
local variables, packages, modules and others.
We can even annotate annotation itself.
Basically, there might be cases when you need to provide more information about your code and use this
information on different stages on the level of the source code during compilation and at this stage
of the runtime.
Late in the lesson we are going to learn this case are some examples I will show you where notation
can be applied and how long it will be retained.
You already understood what metadata is and what annotation is, but probably it is still not clear
for you how this can be helpful and when we need to use annotations in which cases.
The first one is information for the compiler.
Annotations can be used by the compiler to detect errors or suppress warnings, for example, such popular
annotation as override.
I am sure you used it already is on purpose or it just added it instead of you overwrite annotation
discarded by the compiler during the compilation.
And there is a specific purpose of this net information.
As you remember, annotation tells us that this method should override method from parent type.
Thus, there are specific requirements to access modify which that matter signature and the list of
potential exceptions.
There is a logical place in juju that analyzes this matter information basically for all methods marked
with overrides, this logic is applied.
Compile time and deployment time.
Processing software tools can process annotation information to generate code, XML files and so forth.
For example, such book in the library and do as number in case you have never worked with.
No.
I will tell you about it.
It generates getters and setters for you and also helps you with generating other things.
This mechanism also built on top of annotations and reflection API.
Basically, you can annotate type was information about methods if you need to be generated, for example.
And when you compile your application and upload classes into Java, those masses that you want it to
be generated are there on place.
Is that clear?
And that's a use case of using annotations is runtime processing.
Some annotations are available to be excellent at runtime.
You can set configuration to retain annotations.
Zero zero runtime I will show you is this an example?
But let's understand why do we need this?
You may need to keep annotations during the runtime to build some logic around this meta information.
You're in the program execution.
Your homework will be related to this case.
I believe that we have learned enough basics to start review and examples.
Anyway, I will explain examples as we go and the true.
Who believes that understanding of this topic will be easier with source code and the real good examples,
rather than with slides for the sake of the demo and this lesson, I created a separate package and
separate them a file.
You can find them a file in annotations package.
Let's start from basics.
Let's discuss annotation format.
Each annotation is started with at sign, followed by some meaningful name.
Z Sign character indicates as a compiler that what follows is an annotation.
The annotation can include elements which can be named and zem values.
For those elements, elements may contain additional information like in this case, you can see that
are used to suppress warnings.
Annotation and element value has value types.
This is basically for compiler to remove warnings for parameterized, at least in case I would Corman's
this annotation.
There will be warnings you as a compilation that I am using parameter types without parameter Ryzens.
You see this OK and other possible syntax of the similar annotation in case there is only one element
is declared inside the annotation.
You can omit element key and just put value like in this example.
It is also possible to use multiple annotations at once and from Java version eight zero even supports
of repeatable annotations.
As you can see in this example, a little bit later in our lesson, one will comp the creation of our
custom annotations.
I will explain you how to create repeatable annotations.
Let's open the source code of any annotation.
For example, let's look at suppress warnings annotation.
As you can see, there is no end in logic and code here.
There is no any algorithm or data processing or anything else.
Some students ask me then how annotations work, how overwrite annotation works, and all this basically
annotations are nothing more than just an information and what you can do.
Learn this information.
This is up to you, and this logic is programmed in a separate place.
OK, that was annotations basics.
Now, you know, at least on the high level, what annotations are us?
Know known annotations deeper and to learn them better?
Let's create our own annotation.
If you are already familiar with G-Unit will implement our own kind of test annotation if you are not
familiar with your units yet.
Just a few words.
G-Unit is a framework for unit testing.
It provides a lot of different features and the Mournes impossibility to run specific methods separately
to execute separate test cases.
The purpose of that massive is to reproduce the state of the system as a specific moment of time, and
the Cert is expected to be here.
All examples will be stored under this package, so you will easily found them in attachments to this
lesson in case you want to run examples on your computer.
Let's start.
I create test annotations.
First, I declare annotation in a separate file, and you can see in this example that the use interface
here was at sign.
The second important step is to add matter annotations to specify the scope and the target of our custom
annotation.
I'm talking about annotations, zero retention and target.
Let's run.
What are they?
So what do we need to target annotation for?
This annotation indicates a context in which an annotation type is applicable.
In simple words, where you can use the sanitation target, annotation can take array of any values
of element type enum.
So even in case you forgot where you can use annotations.
Just open element type in them and you would find enum for each possible placement of your annotation.
Even despite the fact is, a on annotation may take array of elements in our specific example, we would
use only one in a message because in our specific business context, we don't want to allow our client
use it in other places is an exhortation is retention.
This information indicates how long annotations was annotated.
Time are to be retained.
That is exactly what we have discussed at the beginning of our lesson.
When I explained that annotation may be used during Zabeel time by the compiler and discarded from the
class on the glass level but discarded during the anthem, one class is uploaded in.
And during runtime, this annotation can take any value of retention policy in them, even in case you
forgot what's retention levels for annotations are, you always can open the source code of this in
them and explore this.
As I said, there's three possible options here.
They are source Closs, and one time in our case, we use runtime retention policy because we need this
annotation to be retained.
That's a runtime.
Now, at this time, to add custom elements, imagine that you want to specify expected exception in
order we can test negative scenarios, for example, in case we expect exception to be thrown.
But there was no any exception.
Drone zones This particular test should be considered as field and the stanzas declare an element in
annotation.
We have to declare mass was the name of the element itself.
Return type will be the type of the element.
For example, in this specific case, we would like to specify loss of the expected exception.
Thus, returns type for this message will be close when we declare this matter.
We should remember important things, since this massive can throw an exception.
There is a restriction on the return types.
Basically, you can return on your primitives string class in them, annotations and arrays of these
types.
Also, this must has default value.
For example, in this particular case, default exception, to be certain is of non plus.
This is our custom clause that extends Roble and that basically is empty.
This is needed because I can't have default no values.
But in case I wouldn't specify, a default value client will be forced to parse the value for this element.
But what clients should Boston in case there is no expected exception?
That's why I have default non clause here.
Similar example of default value in our other element.
Each test can be named and default name is empty string.
But the client of this code can pass any custom name.
One of the restriction was regards the default value.
It can't be null.
Is that clear?
We are done with annotation creation.
Let's now understand how to use it.
As you can notice, there is no logic defined in the annotation.
That means that I should have some place where logic for annotation process is described in this particular
example.
It can be some tests around the class similar to the G unit, where we have separate runners that can
execute my tests.
I open tests around the class.
It has run tests massive that takes class.
It contains tests to run as mass argument.
I use this reference to a class object to get the array of all masses.
After that, I feel the masses to keep in-stream only masses that have test annotation.
After that, I filter all static masses to keep only non static masses in the stream.
And now I need to call test my asset on the object.
I create new instance using test class.
After that, I need to speak logic for annotations that have expected exception and those who don't.
You remember that annotations results?
Bits of fired by client exception still has exception was not by default.
I use this information during implementation of my logic because in case I expect any exceptions specified
by client other than default, I need to check that the expected exception has been thrown come back
losses of exceptions thrown.
Here is the logic for that.
By the way, in a reflection API in case exception has been thrown on the invoked received in the invocation
target exception that serves as a wrapper for a regional exception.
That's why I need to get course massive here to get the reference to the exception that caused invocation
target exception in case I don't expect exception to this rule.
Massad just should be executed successfully, and I just invoke mass differently.
This is not the full replica of test annotation from G-Unit, but we have a goal in this lesson not
to run G-Unit, but to understand how to work with annotations and process zap.
Now let me show you class with tests.
I open the glass, such as code test samples.
This class contains.
Is different mascots that are marked with test annotation.
Each test has name for the sake of the current demo.
I have two test cases here mascots that is executed without exception and massive that throws exception
of expected type.
Nothing complex here.
And now let's write a code that will use my test runner to run these test cases.
I open another clause at the so-called test annotation demo.
I read instance of test runner.
I could run test method and the person's glass that contains my test cases that so let's run this program
and console.
You can see that test without exception has been passed because we received exception that we expect
and test without exception also has been passed because it was executed without any exception.
I recommend you to look through the source code that I left in attachments to the lesson.
Run it on your local computer to understand better how it works.
And the last thing for the desert I'd like to share with you is repeatable annotations.
To be honest, in my opinion, this is a very rare case because in case you need to pass multiple values,
you always can define additional elements in the original annotation or declare array of values for
some element.
Anyway, it was hard for me to come up with real life example in this case, but I just want to demonstrate
use a feature that was added in Java version eight.
Let me open our demo example.
Can they see that I have Orser annotation here duplicated?
Normally it is not accepted, and to be able to use the same annotation twice for the same element,
you need to perform additional actions.
The first thing to do is to add annotation, repeatable annotation definition, like I did for Orser
annotation.
The second thing to do is to create container for repeatable annotations for compatibility reasons.
Repeating annotations are stored in a container annotation.
In order for the compiler to do this, two declarations are required in your code.
That's why another annotation that we need to create is here.
I call it Auster's container annotation must have element value that returns array with objects of repeatable
annotation type that we want to repeat.
In this case, value element will contain array of Orser annotations.
Is that clear?
Basically, that's all what I wanted to share with you.
Let's review what we have learned in this lesson.
In this lesson, we have learned what annotation is also explained to you, why we might need an addition
and when we can use it.
Now, you know where annotations may be applied.
You know why we need targeted annotation and you know what element type in them is.
Also, you learned what retention annotation is and what retention policy in them is.
In the lesson.
We created our custom annotation, and at the end of the lesson, I explained to you how to create repeatable
annotations.
Basically, that's a summary of all what we have learned today.
I have a homework for you in order you can practice in creation of annotations.
You also can find a link to the whole in attachment to the lesson.
Let's understand what you need to do in this task.
You need to create to do annotation that will allow us to track the progress of note.
Implement that message.
To do annotation has different elements such as author, priority and stages.
Some of them have default values and also Element doesn't have annotation can be applied only to masses
and should be available under on that.
We'll see to create separate classes at the school to do analyzer in that class, we should have massive
three chance string value that is generated to do report pay attention that in order your homework would
be considered to be done.
You need to follow specific partners for each method analysis.
One is described here.
You should specify method name or search priority on stages.
Is it clear any way you will be able to find my solution also in attachments does assessment, but try
to solve this task without any help and by yourself first and only in case solution is not on this for
you.
Use my solution as a reference and as always, in case you have any questions, feel free to add your
questions in comments on this video.
Thanks a lot you for your attention.
Have a great day and see in the next lesson.