annotations : Java Glossary

2008-02-17 by Roedy Green ©1996-2008 Canadian Mind Products
Go to : punctuation 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z (all)

annotations

Used in the form @interface or @Retention. These are annotations, a feature of JDK 1.6+, though they were partly implemented in JDK 1.5. You can use them to add metadata to your programs useful to various utilities that process the text, e.g. for persistent object store implementations. They can also be used for inserting boiler plate in programs. You use them as you would the attribute static, declaring a class, variable or method to be marked with a given annotation.

The Basics	Learning More
@SuppressWarnings	Links
@Override

The Basics

These @annotations not Javadoc tags! They are part of the program proper.

@Retention(RetentionPolicy.RUNTIME) means the following annotation should be retained in the class files.

@Target(ElementType.METHOD) means the following annotation only applies to methods in the class, not the whole class.

@Documents means the following annotation should show up in the Javadoc.

Now that you have defined it, you can annotate any class with it, which embeds the copyright notice in the class file, with otherwise changing the class file. It does not add any methods or fields to your class, though it is sometimes possible to get at the information through the java.lang.annotation package methods. Here is how you use it:

@SuppressWarnings

In JDK 1.5, Sun introduced an annotation called @SuppressWarnings. Unfortunately, it is ignored prior to JDK 1.5.0_06. You just insert the annotation prior to a class or method declaration telling which sort of warning you want suppressed. Further, you are not permitted to use them if you have -target 1.4 or earlier, not even @SuppressWarnings. You use them like this:

As well as classes and methods, @SuppressWarnings also applicable to enum, interface, constructor, field, parameter and local variable declarations.

Here are the sorts of warning you can suppress:

SuppressWarnings Options
Option	Notes
"all"	@SuppressWarnings( "all" ) means suppress all warnings
"allDeprecation"	deprecation even inside deprecated code
"allJavadoc"	invalid or missing javadoc
"assertIdentifier"	occurrence of assert used as identifier
"boxing"	autoboxing conversion
"charConcat"	when a char array is used in a string concatenation without being converted explicitly to a string
"conditionAssign"	possible accidental boolean assignment
"constructorName"	method with constructor name
"dep-ann"	missing @Deprecated annotation
"deprecation"	usage of deprecated type or member outside deprecated code
"emptyBlock"	undocumented empty block
"enumSwitch"	incomplete enum switch
"incomplete-switch"	incomplete switch
"fieldHiding"	field hiding another variable
"finalBound"	type parameter with final bound
"finally"	finally block not completing normally
"hiding"	shorthand for fieldHiding, localHiding, typeHiding and maskedCatchBlock
"indirectStatic"	indirect reference to static member
"intfAnnotation"	annotation type used as super interface
"intfNonInherited"	interface non-inherited method compatibility
"javadoc"	invalid javadoc
"localHiding"	local variable hiding another variable
"maskedCatchBlocks"	hidden catch block
"nls"	non-nls string literals
"noEffectAssign"	for assignment with no effect
"null"	missing or redundant null check
"over-ann"	missing @Override annotation
"pkgDefaultMethod"	attempt to override package-default method
"serial"	missing serialVersionUID
"semicolon"	unnecessary semicolon or empty statement
"specialParamHiding"	constructor or setter parameter hiding another field
"static-access"	shorthand for indirectStatic and staticReceiver
"staticReceiver"	if a non static receiver is used to get a static field or call a static method
"suppress"	enable @SuppressWarnings
"syntheticAccess"	when performing synthetic access for innerclass
"synthetic-access"	when performing synthetic access for innerclass
"tasks"	enable support for tasks tags in source code
"typeHiding"	type parameter hiding another type
"unchecked"	unchecked type operation
"unnecessaryElse"	unnecessary else clause
"unqualified-field-access"	unqualified reference to field
"unqualifiedField"	unqualified reference to field
"unused"	shorthand for unusedArgument, unusedImport, unusedLocal, unusedPrivate and unusedThrown
"unusedArgument"	unused method argument
"unusedImport"	unused import reference
"unusedLocal"	unused local variable
"unusedPrivate"	unused private member declaration
"unusedThrown"	unused declared thrown exception
"uselessTypeCheck"	unnecessary cast/instanceof operation
"varargsCast"	varargs argument need explicit cast
"warningToken"	unhandled warning token in @SuppressWarnings

Some of the options above are for Eclipse only, however Javac will quietly ignore them.

@Override

There is no override keyword to warn the compiler your method is intended to override a method in the base class. However, since JDK 1.6, (and partially in JDK 1.5), there is an @Override annotation. @Override serves as documentation for the reader and a double check in the compiler. The compiler will warn you if your method is not overriding properly, usually because the two method names are not spelled exactly the same way. Note it is @Override with capital O and double r, not @overide. Don’t confuse the @Override annotation with the unofficial @override Javadoc command. Here is how you would use the @Override annotation to indicate that a method is overriding another in the base class.

/**
 * Get String presentation for this Thing object.
 * @return human readable summary of fields in Thing object.
 */
@Override
public String toString()
  {
  return desc + " " + quantity + " " + losses;
  }

Learning More

Sun’s JDK Technote Guide on annotations : available:

on the web at java.Sun.com
in the JDK 1.6.0_06 on your local J: drive.

Sun’s Javadoc on Class.isAnnotationPresent : available:

on the web at java.Sun.com
in the JDK 1.6.0_06 or in the older JDK 1.5.0_15 or the even older JDK 1.4.2_17 on your local J: drive.

@Override
generics
JavaDoc
warnings

	Please email your feedback for publication, errors, omissions, broken/redirected link reports and suggestions to improve this page to Roedy Green :
	Canadian Mind Products
	mindprod.com IP:[65.110.21.43]
	Your face IP:[38.103.63.17]	The information on this page is for non-military use only.
	You are visitor number 15,712.	Military use includes use by defence contractors.
	You can get a fresh copy of this page from:	or possibly from your local J: drive (Java virtual drive/Mindprod website mirror)
	http://mindprod.com/jgloss/annotations.html	J:\mindprod\jgloss\annotations.html