com.surelogic
Annotation Type Vouch

@Documented
@Target(value={TYPE,METHOD,CONSTRUCTOR})
public @interface Vouch

Vouches for any inconsistent analysis result within the scope of code that the annotation appears on. This means that any inconsistent result will be changed to a consistent result. Its use is for documentation and to quiet overly conservative analysis results.

This annotation is trusted, i.e., it is not verified by analysis.

The annotation requires a brief programmer explanation for the vouch being made.

Examples:

In the example code below an init method is used to set state, perhaps due to an API restriction about using constructors, and then CentralControl instances are safely published. A Vouch is used to explain that the init method needs to be an exception to the lock policy.

 @Region("private ControlRegion")
 @RegionLock("ControlLock is lock protects ControlRegion")
 public class CentralControl {
 
   private final Object lock = new Object();

   @InRegion("ControlRegion")
   private String f_id;
 
   @Vouch("Instances are thread confined until after init(String) is called.")
   public void init(String id) {
     f_id = id;
   }
 
   public String getId() {
     synchronized (lock) {
       return f_id;
     }
   }
 
   public void setId(String value) {
     synchronized (lock) {
       f_id = value;
     }
   }
 }
 

A Vouch is used to explain that the SmokeTest class is test code.

 @Vouch("Test code that is intentionally inconsistent with models")
 public class SmokeTest extends ... {
   ...
 }
 

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 Region("private ControlRegion")
  * @annotate RegionLock("ControlLock is lock protects ControlRegion")
  */
 public class CentralControl {
 
   private final Object lock = new Object();

   /**
    * @annotate InRegion("ControlRegion")
    */
   private String f_id;
 
   /**
    * @annotate Vouch("Instances are thread confined until after init(String) is called.")
    */
   public void init(String id) {
     f_id = id;
   }
   ...
 }
 

Required Element Summary

String

value A brief programmer explanation of why the annotated code should have its inconsistent assurance results suppressed.

Element Detail

value

public abstract String value

A brief programmer explanation of why the annotated code should have its inconsistent assurance results suppressed.