Programming with contracts.

• About the property file
• Enable / disable contracts for packages and classes
• Example for the usage of Pre- and Postconditions

The Property File

The contracts are enabled and disabled by settings in a property file.

Default: If no property file is being found, all contracts are disabled.

The property file can be provided in some ways:

• Classpath: Place the property file "contract.properties" into a folder that is accessible by your classpath.
• -D option (or java system property): Provide file name (plus path) as argument to the -D option. For example: java -Dcom.softwareag.common.instrumentation.contract.ConfigFileName=yourFileName ... yourApplication
• JUnit: Place the properties file "contract.properties" into your testsuite\junit\src folder. It is copied at compile time to the debug folder and found by the tests via classpath.

Enable / Disable Contracts

The properties file for the contracts contains the list of classes whose contracts have to be checked during runtime.

The format allows you to set the check for a class or for a package. Defined for a package the check option is defined recursively for all of the sub-packages and classes of this package. The format of a definition is:

GLOBAL={enabled, enabledByDefault, disabledByDefault, disabled}
<package name>={enabled, enabledByDefault, disabledByDefault, disabled}
<class name>={enabled, enabledByDefault, disabledByDefault, disabled}

Example:

GLOBAL=enabledByDefault
myPackage1=disabledByDefault
myPackage1.myPackage2.MyClass=enabled

The rules:

1. The definition GLOBAL is related to the root package.
2. The values 'enabled' or 'disabled' can not be overwritten by another more specific definitions, e.g. checking is enabled for all of a packages sub-packages and classes if it's check option is 'enable'.
3. The values 'enabledByDefault' and 'disabledByDefault' can be overwritten by more specific definitions, e.g. the check option for classes of a package is disabled since the package has a definition 'disabledByDefault', then, the checking of a class is enabled if the class has a definition 'enabled' or 'enabledByDefault' (see example above).
   

Example for the usage of Pre and Postconditions

/*
* Copyright (c) 2001 SOFTWARE AG, All Rights Reserved.
*/

package com.softwareag.xtools.common.mycomponent;

// import Pre and Postconditions, copy this
import com.softwareag.common.instrumentation.contract.Precondition;
import com.softwareag.common.instrumentation.contract.Postcondition;

/**
** Demonstrate the usage of Pre and Postconditions.
**
** @author lem@softwareag.com
** @version 0.0.
**/

public class ContractUser{

   // Just copy this two field declarations and adjust the class name

   /**
    ** Enables/disables precondition testing due to a global setting.
    **/
   private static final boolean PRE_CHECK = Precondition.isEnabled(ContractUser.class);

   /**
    ** Enables/disables postcondition testing due to a global setting.
    **/
   private static final boolean POST_CHECK = Postcondition.isEnabled(ContractUser.class);

   /**
    ** My constructor gets some parameters as input. The pre and post tags will be added to the javadoc automatically,
    ** because the sagdoclet is used in the build process.
    **
    ** @pre    param1 != null
    ** @pre    param1 in {"I like contracts", "Contracts are fine"}
    **
    ** @param    param1    A string that shows that the user likes contracts.
    **/
   public ContractUser(String param1){
      // Precondition.check() throws a ViolatedPrecondition error with the String given, if the 
      // condition is false.
      if (PRE_CHECK) Precondition.check("param1 is not null", param1 != null); 
      if (PRE_CHECK) Precondition.check("param1 has to be a kind of enthusiasm about contracts", param1.equals("I like contracts") || param1.equals("Contracts are fine"));

      // No processing is performed because this is an example.
   }

   /**
    ** This method is designed to return null !!
    ** The user might learn this by reading the javadoc postcondition:
    **
    ** @post result == null
    **
    ** @return     Almost always null. This is guaranteed by a post condition.
    **/
   public Object createNull(){

      // Follow the convention and store your return value in "result".
      Object result = null;

      // This was not a difficult processing, now it will be checked, if this method can hold its promises:
      // Postcondition.check() throws a ViolatedPostcondition error with the String given, if the 
      // condition is false.
     if (POST_CHECK) Postcondition.check("Result is null", result == null);
     return result;
   }
} // end of example