org.mutabilitydetector.unittesting
Class AllowedReason

java.lang.Object
  org.mutabilitydetector.unittesting.AllowedReason

public final class AllowedReason
extends Object

Provides ways to suppress false positives generated by Mutability Detector.

Regretfully, Mutability Detector may produce false positives, which cause your unit tests to fail, even though your class is immutable. In order to get around this fault in Mutability Detector, you can provide an "allowed reason" for mutability. This is preferable to deleting the test, or marking it as ignored, as it allows checking for all other violations except those you have explicitly sanctioned.

All types returned from the static methods on AllowedReason are implementations of Hamcrest Matcher, generic on the type MutableReasonDetail.

For more information on configuring a mutability assertion, see MutabilityAssert.

See Also:

MutabilityAssert, MutableReasonDetail, ProvidedOtherClass, AllowingForSubclassing, AllowingNonFinalFields, FieldAssumptions, NoReasonsAllowed

Method Summary

static AllowingForSubclassing	allowingForSubclassing() Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.
static AllowingNonFinalFields	allowingNonFinalFields() Insists that non-final fields are acceptable.
static FieldAssumptions	assumingFields(Iterable<String> named) Allowed reasons for mutability warnings related to fields.
static FieldAssumptions	assumingFields(String firstFieldName, String... otherFieldNames) Allowed reasons for mutability warnings related to fields.
static ProvidedOtherClass	provided(Class<?>... classes) Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.
static ProvidedOtherClass	provided(Class<?> clazz) Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.
static ProvidedOtherClass	provided(String dottedClassName) Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

provided

public static ProvidedOtherClass provided(String dottedClassName)

Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.

See Also:

MutabilityAssert

provided

public static ProvidedOtherClass provided(Class<?> clazz)

Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.

See Also:

MutabilityAssert

provided

public static ProvidedOtherClass provided(Class<?>... classes)

Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.

See Also:

MutabilityAssert

allowingForSubclassing

public static AllowingForSubclassing allowingForSubclassing()

Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.

See Also:

MutabilityAssert

allowingNonFinalFields

public static AllowingNonFinalFields allowingNonFinalFields()

Insists that non-final fields are acceptable.

Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.

Example usage:

 @Immutable
 public final class HasNonFinalField {
   private int someValue;
   
   public HasNonFinalField(int value) {
     this.someValue = value;
   }
   
   // may have getter methods, but definitely no setter methods or reassignments.
 }
 
  // a warning will be raised because field 'someValue' is not declared final
  assertInstancesOf(HasNonFinalField.class, areImmutable());
  
  // use AllowingNonFinalFields to permit this
  // must be used if matching result with areEffectivelyImmutable()
  assertInstancesOf(UsesInternalMapForCaching.class, 
                    areImmutable(),
                    allowingNonFinalFields());
 

Must be used if matching with MutabilityMatchers.areEffectivelyImmutable().

See Also:

MutabilityAssert

assumingFields

public static FieldAssumptions assumingFields(String firstFieldName,
                                              String... otherFieldNames)

Allowed reasons for mutability warnings related to fields.

Please see the JavaDoc listed with MutabilityAssert for an introduction on using this method.

Several warnings raised by Mutability Detector relate to the definition, or the use, of a field in a class. For example: the definition of a field may include declaring that the type of the field is mutable; or the use of a field may include reassigning it outwith the constructor. FieldAssumptions provides several methods which allow this category of reasons.

Reasons are allowed by matching the field by it's name and then matching the reasons that particular field causes mutability.

Example usage:

 @Immutable
 public final class UsesInternalMapForCaching {
   private final Map internalCache = new HashMap();
   // ... constructor, and methods which mutate the map for caching
 }
 
  // a warning will be raised because field 'internalCache' is a mutable type.
  assertInstancesOf(UsesInternalMapForCaching.class, areImmutable());
  
  // use FieldAssumptions to insist the usage is safe
  assertInstancesOf(UsesInternalMapForCaching.class, 
                    areImmutable(),
                    assumingFields("internalCache").areModifiedAsPartOfAnUnobservableCachingStrategy());
 

This method is also available in Iterable$lt;String> form #assumingFields(Iterable)).

See Also:

MutabilityAssert

assumingFields

public static FieldAssumptions assumingFields(Iterable<String> named)

Allowed reasons for mutability warnings related to fields.

Several warnings raised by Mutability Detector relate to the definition, or the use, of a field in a class. For example: the definition of a field may include declaring that the type of the field is mutable; or the use of a field may include reassigning it outwith the constructor. FieldAssumptions provides several methods which allow this category of reasons.

Reasons are allowed by matching the field by it's name and then matching the reasons that particular field causes mutability.

Example usage:

 @Immutable
 public final class UsesInternalMapForCaching {
   private final Map internalCache = new HashMap();
   // ... constructor, and methods which mutate the map for caching
 }
 
  // a warning will be raised because field 'internalCache' is a mutable type.
  assertImmutable(UsesInternalMapForCaching.class, areImmutable());
  
  // use FieldAssumptions to insist the usage is safe
  assertImmutable(UsesInternalMapForCaching.class, 
                  areImmutable(),
                  assumingFields(Arrays.asList("internalCache")).areModifiedAsPartOfAnUnobservableCachingStrategy());
 

This method is also available in varargs form assumingFields(String, String...).

See Also:

MutabilityAssert