Page added by Karan Singh Malhi

Summary

Validation is a critical and integral part of the project. If you are writing some code which validates some rules, you should definitely write a test for it. A little validation test framework is available to write tests specifically for Validation. This page explains the details of writing such tests using example snippets.

The Validation Framework

org.apache.openejb.config.ConfigurationFactory uses a chain of org.apache.openejb.config.DynamicDeployer implementations. One of the implementations in the chain is org.apache.openejb.config.ValidateModules. ValidateModules is conditionally added to the chain if the property openejb.validation.skip=false. If this property is false, then ValidateModules is used to kick off the Validation Framework.
```
if (!options.get(VALIDATION_SKIP_PROPERTY, false)) {
    chain.add(new ValidateModules());
} else {
    DeploymentLoader.logger.info("validationDisabled", VALIDATION_SKIP_PROPERTY);
}
```

Internally ValidateModules uses the AppValidator.validate() method.

public class ValidateModules implements DynamicDeployer {


    public AppModule deploy(AppModule appModule) throws OpenEJBException {
        AppValidator validator = new AppValidator();
        return validator.validate(appModule);
    }

}

This method then performs validation using a number of rules. A validation rule/s is represented by a class implementing ValidationRule. In fact, all the classes checking the validation rules , implement ValidationBase, which further implements ValidationRule. The list of rules being executed can actually be found in the following method of AppValidator.

protected ValidationRule[] getValidationRules() {
    ValidationRule[] rules = new ValidationRule[]{
            new CheckClasses(),
            new CheckMethods(),
            new CheckCallbacks(),
            new CheckAssemblyBindings(),
            new CheckInjectionTargets(),
            new CheckPersistenceRefs(),
            new CheckDependsOn(),
            new CheckUserTransactionRefs()
    };
    return rules;
}

The above rules are then executed one by one

    public AppModule validate(final AppModule appModule) {
        try {
            ValidationRule[] rules = getValidationRules();
            for (int i = 0; i < rules.length; i++) {
                rules[i].validate(appModule);
            }
        } catch (Throwable e) {
            e.printStackTrace(System.out);
            ValidationError err = new ValidationError("cannot.validate");
            err.setCause(e);
            err.setDetails(e.getMessage());
            appModule.getValidation().addError(err);
        }
        return appModule;
    }
    protected ValidationRule[] getValidationRules() {
        ValidationRule[] rules = new ValidationRule[]{
                new CheckClasses(),
                new CheckMethods(),
                new CheckCallbacks(),
                new CheckAssemblyBindings(),
                new CheckInjectionTargets(),
                new CheckPersistenceRefs(),
                new CheckDependsOn(),
                new CheckUserTransactionRefs()
        };
        return rules;
    }
    public void printResults(ValidationResults set) {
        if (!set.hasErrors() && !set.hasFailures() && (!PRINT_WARNINGS || !set.hasWarnings())) {
            return;
        }
        System.out.println("------------------------------------------");
        System.out.println("JAR " + set.getJarPath());
        System.out.println("                                          ");

        printValidationExceptions(set.getErrors());
        printValidationExceptions(set.getFailures());

        if (PRINT_WARNINGS) {
            printValidationExceptions(set.getWarnings());
        }
    }

    protected void printValidationExceptions(ValidationException[] exceptions) {
        for (int i = 0; i < exceptions.length; i++) {
            System.out.print(" ");
            System.out.print(exceptions[i].getPrefix());
            System.out.print(" ... ");
            if (!(exceptions[i] instanceof ValidationError)) {
                System.out.print(exceptions[i].getComponentName());
                System.out.print(": ");
            }
            if (LEVEL > 2) {
                System.out.println(exceptions[i].getMessage(1));
                System.out.println();
                System.out.print('\t');
                System.out.println(exceptions[i].getMessage(LEVEL));
                System.out.println();
            } else {
                System.out.println(exceptions[i].getMessage(LEVEL));
            }
        }
        if (PRINT_COUNT && exceptions.length > 0) {
            System.out.println();
            System.out.print(" " + exceptions.length + " ");
            System.out.println(exceptions[0].getCategory());
            System.out.println();
        }

    }

    public void printResultsXML(ValidationResults set) {
        if (!set.hasErrors() && !set.hasFailures() && (!PRINT_WARNINGS || !set.hasWarnings())) {
            return;
        }

        System.out.println("<jar>");
        System.out.print("  <path>");
        System.out.print(set.getJarPath());
        System.out.println("</path>");

        printValidationExceptionsXML(set.getErrors());
        printValidationExceptionsXML(set.getFailures());

        if (PRINT_WARNINGS) {
            printValidationExceptionsXML(set.getWarnings());
        }
        System.out.println("</jar>");
    }

    protected void printValidationExceptionsXML(ValidationException[] exceptions) {
        for (int i = 0; i < exceptions.length; i++) {
            System.out.print("    <");
            System.out.print(exceptions[i].getPrefix());
            System.out.println(">");
            if (!(exceptions[i] instanceof ValidationError)) {
                System.out.print("      <ejb-name>");
                System.out.print(exceptions[i].getComponentName());
                System.out.println("</ejb-name>");
            }
            System.out.print("      <summary>");
            System.out.print(exceptions[i].getMessage(1));
            System.out.println("</summary>");
            System.out.println("      <description><![CDATA[");
            System.out.println(exceptions[i].getMessage(3));
            System.out.println("]]></description>");
            System.out.print("    </");
            System.out.print(exceptions[i].getPrefix());
            System.out.println(">");
        }
    }

    public void displayResults(ValidationResults[] sets) {
        if (PRINT_XML) {
            System.out.println("<results>");
            for (int i = 0; i < sets.length; i++) {
                printResultsXML(sets[i]);
            }
            System.out.println("</results>");
        } else {
            for (int i = 0; i < sets.length; i++) {
                printResults(sets[i]);
            }
            for (int i = 0; i < sets.length; i++) {
                if (sets[i].hasErrors() || sets[i].hasFailures()) {
                    if (LEVEL < 3) {
                        System.out.println();
                        System.out.println("For more details, use the -vvv option");
                    }
                    i = sets.length;
                }
            }
        }
    }
    
    public static void main(String[] args) throws SystemExitException {
        CommandLineParser parser = new PosixParser();

        // create the Options
        Options options = new Options();
        options.addOption(AppValidator.option("v", "version", "cmd.validate.opt.version"));
        options.addOption(AppValidator.option("h", "help", "cmd.validate.opt.help"));

        CommandLine line = null;
        try {
            line = parser.parse(options, args);
        } catch (ParseException exp) {
            AppValidator.help(options);
            throw new SystemExitException(-1);
        }

        if (line.hasOption("help")) {
            AppValidator.help(options);
            return;
        } else if (line.hasOption("version")) {
            OpenEjbVersion.get().print(System.out);
            return;
        }

        if (line.getArgList().size() == 0) {
            System.out.println("Must specify an module id.");
            AppValidator.help(options);
        }
        
        DeploymentLoader deploymentLoader = new DeploymentLoader();

        try {
            AppValidator validator = new AppValidator();
            for (Object obj : line.getArgList()) {
                String module = (String) obj;
                File file = new File(module);
                AppModule appModule = deploymentLoader.load(file);
                validator.validate(appModule);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    private static void help(Options options) {
        HelpFormatter formatter = new HelpFormatter();
        formatter.printHelp("validate [options] <file> [<file>...]", "\n"+ AppValidator.i18n("cmd.validate.description"), options, "\n");
    }

    private static Option option(String shortOpt, String longOpt, String description) {
        return OptionBuilder.withLongOpt(longOpt).withDescription(AppValidator.i18n(description)).create(shortOpt);
    }

    private static Option option(String shortOpt, String longOpt, String argName, String description) {
        return OptionBuilder.withLongOpt(longOpt).withArgName(argName).hasArg().withDescription(AppValidator.i18n(description)).create(shortOpt);
    }

    private static String i18n(String key) {
        return AppValidator._messages.format(key);
    }
}

Each module has an attached ValidationContext , which maintains a list of failures, warnings and errors. As the above rules are being invoked, the failure/errors/warnings for a module are being added to its ValidationContext. Every Validation failure has an associated message which can be found in org/apache/openejb/config/rules/messages.properties. A message has three levels as explained below:

Format for the different levels follows this spirit:

1. Should be short and fixed such that someone could search/grep for it
without having to know/use regular expressions.  These tend to be similar
to the message key.

2. Intended to contain the issue expressed in 1 with only the essential
details, should not line wrap if possible.  Be terse.

3. Teacher's assistant.  A much more conversational and possibly more detailed
explanation of the issue, should tell the user what to do to fix the problem.
I.e. don't just point out what is wrong, also point out what is right.  Use
several lines if needed.

Here is an example validation message

# 0 - method name
# 1 - full method
# 2 - remote|home
# 3 - interface name
# 4 - EJB Class name
1.no.busines.method       No such business method
2.no.busines.method       Business method {0} not implemented.
3.no.busines.method       Business method {1} not implemented. The method was declared in the {2} interface {3}, but not implemented in the ejb class {4}

The validation framework does not stop processing on the first validation failure, but keeps going and checking for other validation errors and reports them all to the user. This allows the user to fix all errors in one go and re-attempt deploying the application.

The Validation Test Framework

The test framework is specifically written with the following goals in mind:
1. It should be easy to write the test, and the framework should do the boiler-plate work, the test author just needs to provide the relevant info
2. It should report the test coverage i.e. the framework should generate a report regarding which keys in messages.properties have tests written for them and what is the corresponding Test class/es which test for the validation rule associated with that key
3. It should ensure that if a test is being written for a specific message key, then that key should exist in the messages.properties file

Lets break down the framework by using an example:

Error formatting macro: snippet: java.lang.IndexOutOfBoundsException: Index: 20, Size: 20

The first thing to note is that we are running the test using our own custom runner i.e. @RunWith(ValidationRunner.class). This runner ensures that the keys we are testing, actually exist in the messages.properties file. It does a lot more, as we shall see later
The test method
1. Can be given any name
2. Must be annotated with @Keys and CANNOT be annotated with @Test. The rest of the JUnit annotations can be used
3. Must return one of EjbJar / EjbModule / AppModule. The returned EjbJar/EjbModule/AppModule will be specifically created to cause one or more validation errors/warnings/failures.

Following annotations are provided by the framework

@Keys : is a collection of zero or more @Key

@Key : represents a key for which this test is being written. A @Key can be of type FAILURE or WARNING or ERROR. Default value is FAILURE. As seen in the example above, the test() method is expecting two warnings for the key injectionTarget.nameContainsSet. If count is not equal to 2 or some other Validation Failure/Warning/Error was also thrown from the method, then the test fails.

Be Careful
The test must cause a Validation Failure otherwise the test framework does not get invoked. For example, in the above code, a Key of type WARNING is being tested, however the test is purposely being failed by putting an @AroundInvoke around the method with zero arguments

Once you have written the test and successfully run it, you now need to generate the report. Simply invoke the following maven command
```
mvn test -Dtest=ValidationKeysAuditorTest -DconfluenceUsername=YourConfluenceUsername -DconfluencePassword=YourConfluencePassword
```
The above command will create a complete test coverage report and post it to this location Validation Keys Audit Report

Change Notification Preferences

View Online | Add Comment

[CONF] OpenEJB > Writing Validation Tests

Writing Validation Tests

Page added by Karan Singh Malhi

Summary

The Validation Framework

The Validation Test Framework

Reply via email to