com.surelogic
Annotation Type NotContainable

@Documented
@Target(value=TYPE)
public @interface NotContainable

The class to which this annotation is applied is not containable. That is, instances of the class can not be safely encapsulated via region aggregation into other objects because methods of this class leak references to themselves or other objects that they reference, transitively.

This annotation primarily exists for clarifying the non-containability of a class that might otherwise be assumed to be containable, despite the fact that it is a bad idea to assume a class is containable without good reason.

This annotation is trusted, i.e., it is not verified. Its use is for documentation.

A type may not be annotated with both @Containable and @NotContainable.

Semantics:

Documenting that a type is not containable does not constrain the implementation of the program, it simply clarifies the programmer's intent.

Examples:

The Swing panel ControlPanel listed below is not containable. The implementation registers with the Swing framework to be called back when the exit button is pressed. This registration aliases the ControlPanel object and makes the implementation not containable.

 import java.awt.*;
 import java.awt.event.*;
 import javax.swing.*;
 
 @NotContainable
 public final class ControlPanel extends JPanel implements ActionListener {
 
   public ControlPanel() {
     final JButton exit = new JButton("Press to Exit");
     add(exit, BorderLayout.CENTER);
     exit.addActionListener(this);
   }
 
   private boolean f_exitPressed = false;
 
   public void actionPerformed(ActionEvent e) {
     f_exitPressed = true;
   }
 
   public boolean exitPressed() {
     return f_exitPressed;
   }
 }
 

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 NotContainable
  */
 public final class ControlPanel extends JPanel implements ActionListener {
   ...
 }
 

See Also:

Containable