annotation
1. What is Annotation? (Annotation or Comments)
Annotation, the accurate translation should be -- annotation. It's completely different from comments.
Annotation is a feature introduced by JDK5.0 and later versions. It is at the same level as classes, interfaces, and enumerations and can become a type of Java.
The syntax starts with @,
Comments are some memorization or prompt descriptions made by programmers of the source code classes, methods, properties, etc. (such as what this method is used for), and are for people to see.
The annotation is the part that the Java compiler can understand and is for the compiler to see.
Let’s give a simple example to see the use and function of annotations.
@Override is a common Java built-in annotation. Its function is to check whether the methods defined in the subclass are correct when compiling the code.
package annotation; public abstract class Animal { public abstract void eat(); } package annotation; public class Cat extends Animal{ @Override public void eat(String food) { } } Here, in the subclass Cat, the eat method is annotated as a method that overwrites the parent class, but it has one more parameter than the parent class method.
If you are editing in Eclipse, there will be a red cross prompt. (Code compilation will not be passed).
If you remove the @Override annotation, there is no problem with compiling, but the eat method in Cat is a new method of this class, not inherited from the parent class.
2. Common Java built-in annotations
Including @Override, what other common Java built-in annotations?
1. @Deprecated
The annotation is not recommended and can be used on methods and classes.
Basically, this method and class are abandoned and not recommended for some reasons such as upgrade or performance, but must be retained for compatibility or other reasons.
So put this annotation on it.
There are many such examples in the Java itself API. If you put this annotation on the method, you will see which new alternative method is.
When writing code in eclipse, the method that adds this annotation will add strikethroughs to both declaration and call.
2.@Override
3.@SuppressWarnings
Ignore warnings.
If your code has some warnings in transformation or other parts, but you want to ignore these warnings, you can use this annotation.
1) Warning when deprecation uses a class or method that is not favored
2) Unchecked Warning when unchecked conversion is performed
3) Fallthrough Warnings appear when the break operation is not added after the case is used, causing the program to continue to execute other case statements
4)path Warning when setting an incorrect classpath or source file path
5) serial warning when serialVersionUID definition is missing on serializable class
6) Fianally Warning if any finally clause cannot be completed normally
7)all Warnings about all the above situations
3. Custom annotations
In addition to the built-in annotations provided by Java itself, Java also provides the function of customizing custom annotations.
The way to define annotations is to use annotations to define annotations. The annotations used to define annotations are called meta annotations.
The main meta annotations are as follows: @Target; @Retention; @Documented; @Inherited
1. @Target indicates where the annotation is used, and may be used on classes, methods, or attributes. Possible ElemenetType parameters include:
ElemenetType.CONSTRUCTOR constructor declaration
ElemenetType.FIELD domain declaration (including enum instances)
ElemenetType.LOCAL_VARIABLE Local variable declaration
ElemenetType.METHOD method declaration
ElemenetType.PACKAGE package statement
ElemenetType.PARAMETER parameter declaration
ElemenetType.TYPE class, interface (including annotation type) or enum declaration
2. @Retention indicates at what level to save the annotation information. The optional RetentionPolicy parameters include:
RetentionPolicy.SOURCE annotation will be discarded by the compiler
RetentionPolicy.CLASS annotation is available in the class file, but will be discarded by the VM.
RetentionPolicy.RUNTIME VM will also retain comments during runtime, so the annotation information can be read through the reflection mechanism.
3. @Documented, whether to include this annotation when generating doc, include this annotation in javadoc
4. @Inherited
Let subclasses inherit the annotations in the parent class see some simple definition examples:
package annotation; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; @Target(ElementType.METHOD) public @interface MyAnnotation { String value(); } @Retention(RetentionPolicy.SOURCE) @interface MyAnnotation1 { } @Retention(RetentionPolicy.CLASS) @interface MyAnnotation2 {} @Retention(RetentionPolicy.RUNTIME) @interface MyAnnotation3 {} @Documented @interface MyAnnotation4 {} @Inherited @interface MyAnnotation5 { }4. Use examples:
package annotation; import java.lang.annotation.Annotation; @MyAnnotation3 public class TestAnnotation { public static void main(String[] args) { // TODO Auto-generated method stub Annotation annotation = TestAnnotation.class.getAnnotation(MyAnnotation3.class); System.out.println(annotation.toString()); } } Print out the result: @annotation.MyAnnotation3()
If MyAnnotation1 and MyAnnotation2 are replaced in the above example, the value of the annotation obtained is empty, which is the difference between RetentionPolicy.
V. The role of Annotation
At this point, we can summarize the role of Annotation.
The basics can be roughly divided into three categories:
1. Write a document
2. Code analysis
3. Compilation check However, open source frameworks give it more functions, such as:
Hibernate, annotation configuration,
@Column("aa") private String xx; This is similar to XML configuration, which simplifies the configuration in the program and moves a part of the metadata from the XML file to the code itself, and manages and maintains it in one place.
How is it implemented internally? -- java reflection mechanism, similar to the above example.
Comments
Although the annotations and comments are only one word different, the usage is very different.
The same sentence is true, the annotations are for the compiler to see, and the annotations are for people to see.
Based on this, for a method:
1. Just describe the function of this method clearly, input and output. You can add more information such as authors and versions.
2. Just do these two things with a beautiful comment arrangement. For example:
/********************************************************************************************************************* * NAME: usage * DESCRIPTION: XXX * ARGUMENTS: N/A * RETURN: * AUTHOR: oscar999 * VERSION: V0.1 ************************************************************************************
It looks like this is a good note^^.
But for Java language, comments are given more functions. That is, you can use the javadoc function to export comments in the code to the html file.
If your code is code with high commonality, this document is an API reference document, similar to Java API.
Therefore, to generate such a document, you must follow some annotation specifications defined by java in order to produce a standardized document.
1. Standard comments on Java class methods
Let's start with the comments on the class method.
/** * Read a line of text. A line is considered to be terminated by any one * of a line feed ('/n'), a carriage return ('/r'), or a carriage return * followed immediately by a linefeed. * * @param ignoreLF1 If true, the next '/n' will be skipped <pre code_snippet_id="74911" snippet_file_name="blog_20131120_2_8365599" name="code"> * @param ignoreLF2 If true, the next '/n' will be skipped</pre> * * @return A String containing the contents of the line, not including * any line-termination characters, or null if the end of the * stream has been reached * * @see java.io.LineNumberReader#readLine() * * @exception IOException If an I/O error occurs */ (Don't pay attention to the meaning of the above comments, just focus on the style of its definition)
1. First look at the top "Read a line of text. A line .. ". This paragraph is a description of this method.
The part before the first period, which is "Read a line of text." will appear in "Method Summary"
2. @param defines the input parameters of the method, which (multiple can be added) appears in "Method Details". (The parameter and parameter description are separated by spaces, and converted to - in the generated document)
3. @return Description of return value
4. @see Reference description
5. The description of @exception thrown by exception is beautiful. Different types of tags can be displayed in one line, such as @param and @return directly empty one line.
2. Java class standard comments
The format of class annotations and method annotations is basically the same. What's the difference:
1. The placement is different. Class annotations are placed above the class definition, and method annotations are placed above the method definition.
2. Class annotation comparison uses tags like @version @author @since.
Look at the template
/** will buffer the input from the specified file. Without buffering, each * invocation of read() or readLine() could cause bytes to be read from the * file, converted into characters, and then returned, which can be very * inherent. * * Test Description * * <p> Programs that use DataInputStreams for textual input can be localized by * replacing each DataInputStream with an appropriate BufferedReader. * * @see FileReader * @see InputStreamReader * * @version 0.1, 11/20/13 * @author oscar999 * @since JDK1.5 */
The effects displayed in doc are:
Similarly, the first sentence of the description appears in the "Classary".
The details of the class are displayed as follows:
It is worth noting that the use of <p> in description. If <p> is not added, no matter whether there is a new line in the java code, the generated doc will not be new. If <p> is added, a new line appears in doc.
3. Supplement
To add, the method to generate javadoc:
1. Named line method: javadoc + parameters
2. Use the Eclipse IDE to export If in the Eclipse IDE, right-click on the source file or project, select Export --->
Java --> Javadoc can be generated.