org.oclc.da.gdfr.registryprototype.exceptions
Class Assertor

java.lang.Object
  org.oclc.da.gdfr.registryprototype.exceptions.Assertor

public class Assertor
extends java.lang.Object

This class implements pre/post-condition checking. There are two types of conditions: Validating and Testing. Validating pre/post-conditions cannot be turned off, whereas Testing pre/post-conditions can.

Author:

AMS

Nested Class Summary

static interface

Assertor.DeferredCondition This interface is used to defer execution of the pre/post-condition expression until the TESTING boolean can be checked.

Field Summary

static int	POST Static variable identifying the condition as post-condition.
static int	PRE Static variable identifying the condition as pre-condition.
boolean	TESTING Instance variable determining whether or not Testing Pre/Post-conditions are turned on or off.

Constructor Summary

Assertor()
Public constructor.

Method Summary

void	post(boolean valid, int type, java.lang.String[] msgArgs) This method enforces Validating Post-Conditions, which cannot be turned off and cannot be resolved by the client, but by the support staff.
void	pre(boolean valid, int type, java.lang.String[] msgArgs) This method enforces Validating Pre-Conditions, which cannot be turned off and must be resolved by the client.
void	test(int cond, Assertor.DeferredCondition valid, int type, java.lang.String[] msgArgs) This method is a deferred version of test.
void	test(int cond, boolean valid, int type, java.lang.String[] msgArgs) This method enforces Testing Pre/Post-Conditions, which may be turned off.

Methods inherited from class java.lang.Object

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

Field Detail

PRE

public static final int PRE

Static variable identifying the condition as pre-condition.

See Also:

Constant Field Values

POST

public static final int POST

Static variable identifying the condition as post-condition.

See Also:

Constant Field Values

TESTING

public boolean TESTING

Instance variable determining whether or not Testing Pre/Post-conditions are turned on or off.

Constructor Detail

Assertor

public Assertor()

Public constructor. It checks the environment variable org.oclc.da.gdfr.registryprototype.exceptions.Assertor.TESTING to determine if testing pre/post-conditions should be turned on or off.

Method Detail

pre

public void pre(boolean valid,
                int type,
                java.lang.String[] msgArgs)
         throws RegistryException

This method enforces Validating Pre-Conditions, which cannot be turned off and must be resolved by the client. Methods using this call must declare the RegistryException in the throws clause.

Parameters:

valid - The boolean condition to be checked.

type - The condition identifier (see org.oclc.da.gdfr.registryprototype.exceptions.RegistryExceptionCodes).

msgArgs - A string array of arguments to be substituted into the assertion exception, if needed.

Throws:

RegistryException - Validation exception if condition is false.

post

public void post(boolean valid,
                 int type,
                 java.lang.String[] msgArgs)

This method enforces Validating Post-Conditions, which cannot be turned off and cannot be resolved by the client, but by the support staff. The exception thrown is RegistrySystemException and does not need to be declared in the throws clause.

Parameters:

valid - The boolean condition to be checked.

type - The condition identifier (see org.oclc.da.gdfr.registryprototype.exceptions.RegistryExceptionCodes).

msgArgs - A string array of arguments to be substituted into the assertion exception, if needed.

Throws:

RegistrySystemException - Validation exception if condition is false.

test

public void test(int cond,
                 boolean valid,
                 int type,
                 java.lang.String[] msgArgs)

This method enforces Testing Pre/Post-Conditions, which may be turned off. Default is ON, but can be turned off by specifying the environment variable org.oclc.da.gdfr.registryprototype.exceptions.Assertor.TESTING.

Parameters:

cond - The condition type: PRE or POST.

valid - The boolean condition to be checked.

type - The condition identifier (see org.oclc.da.gdfr.registryprototype.exceptions.RegistryExceptionCodes).

msgArgs - A string array of arguments to be substituted into the assertion exception, if needed.

Throws:

RegistrySystemException - Validation exception if condition is false.

test

public void test(int cond,
                 Assertor.DeferredCondition valid,
                 int type,
                 java.lang.String[] msgArgs)

This method is a deferred version of test. This method enforces Testing Pre/Post-Conditions, which may be turned off. Default is ON, but can be turned off by specifying the environment variable org.oclc.da.gdfr.registryprototype.exceptions.Assertor.TESTING. How to use the inner class DeferredCondition is shown in the example below. This example shows how to check that the new thread was started properly, but the verification conditional is deferred to ensure that testing post-conditions are turned on.

      // the final qualifier is required in order for the inner class
      // to call methods on this variable
      String threadName = this.toString()+"::Runner";
      final Thread t = new Thread(new Runnable()
      {
          public void run()
          {
              l.load();
          }
      }, threadName);
      t.start();
   
      // post-conditions
      // 1. in this format, the expression is executed before the 
      //    TESTING system variable is checked, and so, it may execute
      //    unnecessarily.
      tester.test(Assertor.POST, t.isAlive(), DAExceptionCodes.MUST_EXIST,
          new String[] { "THREAD", threadName });
 
      // 2. in this second format, the expression is executed after the 
      //    TESTING system variable is checked, inside the test() method
      //    itself.
      tester.test(Assertor.POST, 
          new Assertor.DeferredCondition()
          {
              public boolean test() 
              {
                  return t.isAlive();
              }
          },
          DAExceptionCodes.MUST_EXIST, 
          new String[] {"THREAD", threadName});
      return true;
    
 

see test(int, boolean, int, java.lang.String[]);

Parameters:

cond - The condition type: PRE or POST.

valid - The expression condition to be checked.

type - The condition identifier (see org.oclc.da.gdfr.registryprototype.exceptions.RegistryExceptionCodes).

msgArgs - A string array of arguments to be substituted into the assertion exception, if needed.

Throws:

RegistrySystemException - Validation exception if valid.check() evaluates to false.