Model verification

Model verification

Abstract

This document describes the usage of annotation processing for model verification. The verifying processor assists the developer with spotting incorrect model definitions by printing informative messages in the editor. Similar to a compiler that signals errors upon encountering illegal syntax, the verifying processor analyses the source code, but with a greater focus on semantics.

Initial setup

The verifying processor is packaged together with the meta-model processor, so the inital setup steps are identical to those described in MetaModels. To enable the verifying processor make sure to configure the maven-compiler-plugin in the pom.xml of the respective *-pojo-bl project:

<plugins>
    <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
            <encoding>UTF-8</encoding>
            <!-- to enable output of annotation processors -->
            <showWarnings>true</showWarnings>
            <generatedSourcesDirectory>${project.build.directory}/generated-sources/</generatedSourcesDirectory>
            <annotationProcessorPaths>
                <annotationProcessorPath>
                    <groupId>fielden</groupId>
                    <artifactId>platform-annotation-processors</artifactId>
                    <version>${platform.version}</version>
                </annotationProcessorPath>
            </annotationProcessorPaths>
            <annotationProcessors>
                <annotationProcessor>
                    ua.com.fielden.platform.processors.verify.VerifyingProcessor
                </annotationProcessor>
                <!-- YOUR OTHER PROCESSORS -->
            </annotationProcessors>
        </configuration>
    </plugin>
</plugins>

Eclipse IDE setup

For convenience it is recommended to configure a separate View window for messages reported by the verifier.

1. Create a new Problems View. In this example it's named "APT".

   

2. Configure filters for the new problems view to only display messages produced by annotation processors.

   

3. Configure filters for the original problems view to exclude messages produced by annotation processors.

   

Controlling verification of individual elements

Relaxing verification

In some cases it might be desirable to relax the verification, i.e., reduce the severity of reported messsages. For example, to ask the verifying processor to report a warning instead of an error. For this purpose the @RelaxVerification annotation can be used. Examples follow.

1. Report a warning instead of an error.

@RelaxVerification
@IsProperty
private int number; // Warning: int is an unsupported property type

2. Report an info instead of an error.

@RelaxVerification(RelaxationPolicy.INFO)
@IsProperty
private int number; // Info: int is an unsupported property type

3. Apply the effect to the annotated element and to all elements enclosed by it.

@RelaxVerification
@EntityTitle("Example entity")
// Warning: Entity is missing @KeyType
public class ExampleEntity extends AbstractEntity<String> {
    @IsProperty
    private int number; // Warning: int is an unsupported property type
}

4. Apply the effect only to the annotated element.

@RelaxVerification(enclosed = false) // by default enclosed = true
@EntityTitle("Example entity")
// Warning: Entity is missing @KeyType
public class ExampleEntity extends AbstractEntity<String> {
    @IsProperty
    private int number; // ERROR: int is an unsupported property type
}

Skipping verification

It's also possible to ask the processor to skip the verification of an element entirely by using the @SkipVerification annotation. Unlike @RelaxVerification, the effects of this one are always applied only to the target element. Although, given the nature of this concept, skipping an element is equivalent to excluding it from the verification process, meaning that its enclosed elements (its contents) will be excluded too. Examples follow.

1. Skip an entity element.

@SkipVerification
@EntityTitle("Example entity")
public class ExampleEntity extends AbstractEntity<String> {
    @IsProperty
    private int number;
}

2. Skip a property element.

// ERROR: Entity is missing @KeyType
@EntityTitle("Example entity")
public class ExampleEntity extends AbstractEntity<String> {
    @SkipVerification
    @IsProperty
    private int number;
}