com.surelogic

Annotation Type Utility

@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface Utility

The class to which this annotation is applied is a utility, meaning it only has static methods and state. This annotation is similar to the UML stereotype «utility» which is applied to a class that does not have instances, but whose attributes and operations have class scope. Joshua Bloch in Effective Java (Second Edition) (Addison-Wesley 2008) refers to such classes as utility classes, (in Item 4) which implies that

• the class is declared public;
• all the class's fields and methods are declared static;
• the class has only one constructor that is private, takes no parameters, and does nothing except, optionally, throw AssertionError (i.e., {} or {throw new AssertionError();}); and
• this constructor is not invoked by the class's implementation.

It is recommended that a utility class be declared final to convey the intent that subclasses are prohibited. However this is not required because the private no-arg constructor ensures noninstantiability of the utility class and makes it impossible to subclass.

It is recommended that a utility class extend only Object. However this is not required because the noninstantiability of the utility class makes its parent irrelevant. Further, some security coding standards require all classes to extend a common base class—including utilities.

Note that there are no restrictions on nested classes within a utility class. A utility provides an interface that makes a subsystem or some piece of the program's functionality easy to use and may use nested types to achieve its objective.

Utility classes may be, but not required, to be immutable, in which case the Immutable annotation should be added to the class (for example, if the utility class declares no fields). In general, a utility class may have mutable state.

It is a modeling error to apply this annotation to an interface.

Semantics:

The class to which this annotation is applied is not allowed to have any instances—all the class's attributes and operations have class scope. Further, the class is not allowed to be subclassed. The class may have mutable state.

Examples:

The internalization class below is a utility.

 @Utility
 public final class I18N {
 
   private static final ResourceBundle ERR = ResourceBundle.getBundle(I18N.class.getPackage().getName() + ".Err");
 
   private static final String ERROR_FORMAT = "(Timing Framework #%d) %s";
 
   private static String getString(final ResourceBundle bundle, final String keyTemplate, final Object... args) {
     return bundle.getString(String.format(keyTemplate, args));
   }
 
   public static String err(final int number, Object... args) {
     return String.format(I18N.err(number), args);
   }
 
   // Suppress default constructor for noninstantiability
   private I18N() {
     throw new AssertionError();
   }
 }
 

Javadoc usage notes:

This annotation may placed in Javadoc, which can be useful for Java 1.4 code which does not include language support for annotations, via the @annotate tag.

 /**
  * @annotate Utility
  */
 public final class I18N {
   ...
 }