Ann: A domain-specific language for the effective design and validation of Java annotations

TL;DR

This paper introduces Ann, a domain-specific language and Eclipse tool for designing and validating Java annotations, enabling explicit modeling of complex annotation dependencies and constraints, demonstrated with Java Persistence API annotations.

Contribution

The paper presents Ann, a novel modeling language and tool that enhances Java annotation design and validation, addressing Java's native limitations and supporting complex dependency constraints.

Findings

Ann effectively models complex annotation dependencies.

The tool detects unsatisfiable constraints among annotations.

Applied to JPA annotations, Ann reveals rich semantics not supported by Java.

Abstract

This paper describes a new modelling language for the effective design and validation of Java annotations. Since their inclusion in the 5th edition of Java, annotations have grown from a useful tool for the addition of meta-data to play a central role in many popular software projects. Usually they are not conceived in isolation, but in groups, with dependency and integrity constraints between them. However, the native support provided by Java for expressing this design is very limited. To overcome its deficiencies and make explicit the rich conceptual model which lies behind a set of annotations, we propose a domain-specific modelling language. The proposal has been implemented as an Eclipse plug-in, including an editor and an integrated code generator that synthesises annotation processors. The environment also integrates a model finder, able to detect unsatisfiable constraints between different annotations, and to provide examples of correct annotation usages for validation. The language has been tested using a real set of annotations from the Java Persistence API (JPA). Within this subset we have found enough rich semantics expressible with Ann and omitted nowadays by the Java language, which shows the benefits of Ann in a relevant field of application.

Tables

Table 1. Table 1: Translating basic Ann annotation constraints (requirements) into OCL.

Ann (scheme)	New meta-model elements and OCL
⬇ 1annotation <ANN> { 2 require 3 <MODS1> <TYPE1> 4 … 5 require 6 <MODSn> <TYPEn> 7}	⬇ 1– Assoc. created for each distinct type 2association <ANN>target<ANN><TYPEi> between 3 <TYPEi> [0..1] role target<ANN><TYPEi> 4 <ANN> [0..*] role annotations<ANN> 5end 6 7context <ANN> inv redefs: 8 self.target.isUndefined() 9 10– if some modifier is not empty 11context <ANN> inv <inv_name>: 12 self.target<ANN><TYPEi>->notEmpty() 13 implies ( 14 – and-catenation of the expressions 15 – of the subcases below 16 )
Subcases:
⬇ 1if (public or package or 2 private or protected) 3 in <MODSi>	⬇ 1 self.target<ANN><TYPEi>.visibility = 2 # <public|package|private|protected>
⬇ 1if abstract 2 in <MODSi>	⬇ 1 self.target<ANN><TYPEi>.isAbstract
⬇ 1if static 2 in <MODSi>	⬇ 1 self.target<ANN><TYPEi>.isStatic
⬇ 1if final 2 in <MODSi>	⬇ 1 self.target<ANN><TYPEi>.isFinal

Table 2. Table 2: Translating Ann co-occurrence constraints for annotations (requirements) into OCL.

Subcases (co-occurrence requirements):
⬇ 1annotation <ANN> { 2 … 3 require <ANN1> 4 … 5}	⬇ 1– Invariant created for each distinct type 2context <ANN> inv <inv_name>: 3 self.target<ANN><TYPEi>->notEmpty() implies 4 self.target<ANN><TYPEi> 5 .annotations<ANN1>->notEmpty()
⬇ 1annotation <ANN> { 2 … 3 require <ANN1> 4 <MODS1> 5 <TYPE> 6 … 7}	⬇ 1context <ANN> inv <inv_name>: 2 self.target<ANN><TYPE>->notEmpty() implies 3 (self.target<ANN><TYPE> 4 .annotations<ANN1>->notEmpty() 5 and condition(<TYPE>, <MODS1>))
⬇ 1// <TYPE1> is contained 2// in <TYPE> 3annotation <ANN> { 4 … 5 at <TYPE> : 6 require <ANN1> 7 <MODS1> 8 <TYPE1> 9 … 10}	⬇ 1context <ANN> inv <inv_name>: 2self.target<ANN><TYPE>.notEmpty() implies 3 <ANN1>.allInstances()->exists( 4 t | t.target<ANN1><TYPE1>.owner = 5 self.target<ANN><TYPE> 6 and condition(<TYPE1>, <MODS1>))
⬇ 1// <TYPE> is contained 2// in <TYPE1> 3annotation <ANN> { 4 … 5 at <TYPE> : 6 require <ANN1> 7 <MODS1> 8 <TYPE1> 9 … 10}	⬇ 1context <ANN> inv <inv_name>: 2 self.target<ANN><TYPE>.notEmpty() implies 3 <ANN1>.allInstances()->exists( 4 t | t.target<ANN1><TYPE1> = 5 self.target<ANN><TYPE>.owner 6 and condition(<TYPE1>, <MODS1>))

Table 3. Table 3: Translating Ann “at” constraints (requirements) into OCL.

“at” requirements for method and constructor targets
⬇ 1annotation <ANN> { 2 … 3 at <TYPE1>: 4 require all 5 <MOD> method 6 … 7}	⬇ 1context <ANN> inv <inv_name>: 2 self.target<ANN><TYPE1>->notEmpty() implies 3 self.target<ANN><TYPE1>.methods->forAll( m | 4 condition(Method, <MOD>))
⬇ 1annotation <ANN> { 2 … 3 at <TYPE1>: 4 require all 5 <MOD> 6 constructor 7 … 8}	⬇ 1context <ANN> inv <inv_name>: 2 self.target<ANN><TYPE1>->notEmpty() implies 3 self.target<ANN><TYPE1>.methods->forAll( m | 4 m.isConstructor implies condition(Method, <MOD>))
⬇ 1annotation <ANN> { 2 … 3 at <TYPE1>: 4 require 5 <MOD> method 6 … 7}	⬇ 1context <ANN> inv <inv_name>: 2 self.target<ANN><TYPE1>->notEmpty() implies 3 self.target<ANN><TYPE1>.methods->exists( m | 4 condition(Method, <MOD>))
⬇ 1annotation <ANN> { 2 … 3 at <TYPE1>: 4 require 5 <MOD> 6 constructor 7 … 8}	⬇ 1context <ANN> inv <inv_name>: 2 self.target<ANN><TYPE1>->notEmpty() implies 3 self.target<ANN><TYPE1>.methods->exists( m | 4 m.isConstructor and condition(Method, <MOD>))

Table 4. Table 4: Solving time results (time in ms).

	# annotations
# constraints	2	4	8	16	32	64
SAT-2	86	140	286	874,8	2850,6	18802,8
UNSAT-2	88	86	162,8	600,4	2727,4	16458,2
SAT-4	76,2	112,6	239,4	844	4571,8	25017
UNSAT-4	71,2	76,4	175,6	566,4	2687,8	16355,6
SAT-8	82,6	163,8	246,4	942,6	6199,4	21004
UNSAT-8	74,4	89,8	173	544	2876,8	16327,8

Full text

To overcome its deficiencies and make explicit the rich conceptual model which lies behind a set of annotations, we propose a domain-specific modelling language. The proposal has been implemented as an Eclipse plug-in, including an editor and an integrated code generator that synthesises annotation processors. The environment also integrates a model finder, able to detect unsatisfiable constraints between different annotations, and to provide examples of correct annotation usages for validation. The language has been tested using a real set of annotations from the Java Persistence API (JPA). Within this subset we have found enough rich semantics expressible with Ann and omitted nowadays by the Java language, which shows the benefits of Ann in a relevant field of application.

††journal: Computer Languages, Systems and Structures

captionpos=b, basicstyle=, keywordstyle=, xleftmargin=15pt, stringstyle=, commentstyle=, numberstyle=, morecomment=[s][]/*/, numbers=left, nolol=true, tabsize=4, showspaces=false, showstringspaces=false numberbychapter=false, numbersep=5pt, columns=[l]fullflexible, **

basicstyle=, keywordstyle=, stringstyle=, commentstyle=, morecomment=[s][]/***/, tabsize=4, showspaces=false, showstringspaces=false

captionpos=b, basicstyle=, keywordstyle=, xleftmargin=15pt, stringstyle=, commentstyle=, numberstyle=, morecomment=[s][]/*/, numbers=left, nolol=true, tabsize=4, showspaces=false, showstringspaces=false numberbychapter=false, numbersep=5pt, columns=[l]fullflexible, **

1 Introduction

In 2004 the possibility of adding custom meta-data to programs was added to the Java language in the form of annotations111http://docs.oracle.com/javase/1.5.0/docs/guide/language/annotations.html. Predefined annotations were available previously for very specific tasks, however, the huge amount of boilerplate code that many Application Programming Interfaces (APIs) required motivated their establishment as another general tool in the language. Schildt [33] suggests other reasons as motivation to the appearance of annotations in Java: the increasingly growing tendency of including the meta-data associated with a program within the program itself instead of keeping it in separate files; and the pressure from other programming languages which already included similar features, like C#.

Since their introduction in the language, annotations have become a success and are widely used in many important projects within the software development scene. We find them in frameworks like Seam222http://docs.jboss.org/seam/latest/reference/html/annotations.html and Spring333http://spring.io/, in the Object Relation Mapping of Hibernate444http://hibernate.org/orm/, and also in proper Sun Java standards such as the Java Persistence API (JPA)555http://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html.

However, despite this success, the native support that Java provides for their construction is very poor. This is so as Java annotations are not defined using a specialized syntax, but reusing the syntax to create interfaces. This lack of specialized syntax greatly limits the ability to specify the elements where an annotation can be placed and further correctness conditions. Moreover, annotations are rarely conceived in an isolated way; instead they are usually part of a set with dependencies and integrity constraints. Currently there is no effective way in Java for making explicit the constraints underlying a set of annotations at design time, and validate that they are not conflicting. Instead, the usual path taken to overcome these deficiencies is to develop an extension to the Java compiler (called annotation processor) to ensure that such constraints are complied with, and rely on extensive manual testing of such processor.

As a first step towards the alleviation of this situation, we propose Ann, a textual Domain-Specific Language (DSL) [36] aiming to provide a more expressive and suitable syntactic support for the design of sets of annotations and their associated integrity constraints. We have developed an Integrated Development Environment (IDE) as an Eclipse plug-in, which integrates seamlessly with the Java IDE. The environment includes a code generator to translate the design and constraints expressed using Ann into Java code, which can be fully integrated into projects in such language. Moreover, Ann makes use of a constraint solver over models (a model finder [25]), which is able to detect whether the constraints posed by a set of annotations are unsatisfiable, and provide examples (annotated class mock-ups) of usages of the annotations. These examples could be used by designers to validate whether the encoded integrity constraints defined with Ann are according to their intentions. Ann has been tested using a real set of annotations from JPA, demonstrating that it can capture a wide set of the constraints in its specification, and showing advantages with respect to other approaches with similar goals in the state of the art. More information and the source code of the project can be found at http://github.com/irenecordoba/Ann.

This paper is an extended version of [6, 7], where we have added validation mechanisms based on constraint solving, and integrated such mechanisms with the environment. Additionally, all sections have been enlarged with additional explanations and more details.

The rest of the paper is organised as follows. Section 2 analyses related work. Section 3 gives a more detailed overview on the current limitations of Java annotations. Section 4 introduces the main concepts of Model-Driven Engineering (MDE) and the different choices when building a DSL. Section 5 provides an overview of our approach. Section 6 describes the proposed DSL, Ann. Section 7 explains our approach to validate annotations. Section 8 contains the evaluation of Ann, including a detailed real case study and an evaluation of the efficiency of the model finder for annotation validation. Finally, section 9 summarises the conclusions and future development. Two appendices detail the description of the textual concrete syntax of Ann, and the generated OCL invariants for the JPA case study.

2 Related research

Some research has been made in order to improve and expand the functionality of Java annotations. For example, Phillips in [28] aims at conciliating object oriented principles with the design of annotations by the introduction of a new one: composite. With it, he manages to support composition, allowing encapsulation and polymorphism of annotations.

A Java extension, @Java, is proposed by Cazzola and Vacchi [4] in order to expand the range of application of an annotation to code blocks and expressions, although some improvement in this respect has also been made natively in the latest version of Java666Java 8 at the time of writing.

The expressiveness limitations of Java annotations are recognised in [5], where a proposal is made to embed DSLs into Java, with a more natural and flexible syntax. JUMP [1] is a tool to reverse engineer Java programs (with annotations) into profiled UML class diagrams.

Although the aforementioned approaches expand the features of Java annotations, they do not facilitate their design, nor address the limitations with respect to expressing integrity constraints within an annotation or between the annotations in an annotation set, which is the main goal of our work.

Just a few works are aimed at improving the design of annotations. Darwin [11] suggests a DSL, called AnnaBot, based on claims about a set of existing annotations, with a concrete syntax very similar to Java. With these claims, interdependency constraints can be expressed within a set of annotations. However, there is no possibility of characterising the valid targets of an annotation type (i.e., the valid elements in a program where the annotation can be placed). Moreover, no improvement is made with respect to the syntax for defining annotations in Java, given its heavy focus on existing sets of annotations and constraints between them, and not on isolated ones. Finally, the approach uses reflection to check the statements of its claims, which could and should be avoided.

Another approach is AVal [27], a set of meta-annotations (annotations which are placed at other annotations) to add integrity constraints at the definition of the annotation type. The drawback of this approach is that its expressiveness is rather restricted, given the limited flexibility which the structural characteristics of meta-annotations provide.

Pluggable type systems [2], provide a way to support improved analysis of programs by ensuring stronger type checking. Implementation of these systems exist for Java, like the JavaCOP framework [26]. Java 8 improves the support for such systems via type annotations. Pluggable type systems provide a customized semantics to sets of programming elements via the use of annotation sets. However, they normally do not provide a unified way to describe and validate the syntax and integrity constraints of a set of annotations.

Regarding constraint validation, constraint solving strategies are extensively used in connection with program testing [13]. Many times, constraint solving is used as a means to generate interesting test data for programs, perhaps derived from specifications [19], or making the program execute a certain path [8]. In [21] constraint solving is used to generate both test cases and mock-up classes, considering advanced features like reflection and annotations. Hence, while they can generate mock-up programs with annotations, they need to derive the needed constraints from the analysis of reflective Java code (i.e., at runtime), with the consequent loss of precision and drawbacks of runtime checking. Instead, for our purposes, it would be more desirable to have a language making explicit the annotation constraints at design time, which then can be analysed before such annotations are used.

Hence, as we have observed, there is currently a need for: (i) better syntactical support for the specification of Java annotations; (ii) explicit, high-level means to describe constraints for an annotation (e.g., regarding its valid targets), and between a set of annotations (e.g., expressing their dependencies); and (iii) ways to analyse such constraints to find inconsistencies, at design time. For this purpose, in the rest of the paper, we describe Ann, a DSL directed to describe both the syntax and well-formedness constraints of annotation families, to validate the correctness of the annotation constraints and to make explicit the design of such annotation set, allowing their immediate use on Java projects thanks to the code generation facility.

3 Java annotations

To help understanding the current limitations of Java annotations, in this section we describe how they are defined in Java (subsection 3.1), their usage and limitations (subsection LABEL:sec:ann_usage) and how their correct use is checked (subsection LABEL:sec:ann_proc).

3.1 Defining Java annotations

Java annotations do not constitute a type of their own. Instead, they are defined as special interfaces. There are many differences between annotations and interfaces, however we will only review those necessary to understand the design of Ann.

Listing LABEL:java_def shows an example of the definition and usage of a simple annotation called Person. Such annotation definition is called an annnotation type. As it can be noticed, the special nature of annotations is indicated by the @ character before the interface keyword (line 7). The zero-argument methods inside the container (lines 7-9) are the fields (the parameters) of the annotation. To assign a default value to those fields, the keyword default must be used. An annotation can have an arbitrary number of fields, which can be of primitive type, Class, String, an annotation type, or an array of the previous types.

It is important not to confuse annotation processing with reflection. While the former takes place at compile time, the latter is at execution time. The values of an annotation at a given program element can be checked at execution time via the Java Reflection API (if the annotation type is properly marked, as explained in Section 3.1), but it has several disadvantages, like an overhead in performance, the requirement of runtime permission (which may not be granted), and the possibility of breaking object-oriented abstractions.

In the context of checking the correctness of annotations, it is more appropriate to do it via annotation processors, because they can find and signal the errors without the need to execute the program. However, coding and testing such processors is tedious, cumbersome and error prone. It requires long cycles for coding, installing the processor, and testing. Moreover, we believe it would be advantageous to make explicit the underlying annotation constraints at a higher level, together with the annotation structure. In addition, this would facilitate the analysis of annotation conflicts at design time, with no need to install the processor to make those tests. For this purpose, we have created Ann, a DSL to define the structure and integrity constraints of Java annotations, and validate their correctness.

4 Model-Driven Engineering and Domain Specific Languages

For the development of Ann we have followed what is called Model-Driven Engineering (MDE) [3, 10], which is characterised by the use of models as the main component of the development process. A model is a simplified or partial representation of reality, defined in order to carry out a specific task or reach an agreement on some matter. A great advantage of MDE is that it fills the communication gap between the requirements and analysis phase and the implementation phase in a software project.

Modelling languages are extensively used in MDE, and are conceptual tools to describe reality in an explicit way, at some level of abstraction and from a certain point of view. They are composed and defined by three key elements:

• •

Abstract syntax. It describes the structure of the language and the way in which the different elements can be combined.

• •

Concrete syntax. It describes the particular representation of the modelling language, covering features such as the codification or visual appearance, and hence it determines how users visualize or create models. It can be graphical [24, 29, 32] or textual [36, 14].

• •

Semantics. It describes the meaning of the language elements and also the meaning of the different ways of combining them.

Modelling languages can be classified depending on their domain of application. A Domain-Specific Modelling Language (DSML) is a modelling language designed for a specific domain or context, with the purpose of easing the task of describing the elements in such domain. In contrast, General-Purpose Modelling Language (GPML) can be applied to a much broader context. This distinction is not always easy to draw as it depends on what we consider as a domain (e.g., we could consider the general problem of modelling as a specific domain).

Given that models play a key role in MDE, and they constitute an abstraction of the real world, a natural step is to represent them as instances of higher levels of abstraction, i.e., higher levels of models or meta-models. Consequently, using this definition, meta-models describe the set of models considered valid. They define the abstract syntax of a modelling language, since they are a way of describing all the types of models that can be represented with such language. We could iterate this abstraction levels and obtain meta-meta-models and so on. However, in practice, it has been shown that meta-meta-models are enough to describe themselves (see Figure 1) [3].

The two main alternatives for defining the semantics of modelling languages are code generation and model interpretation [20]. They can be thought of as the analogous for compilers and interpreters in the case of programming languages, respectively. A code generator can be thought of as a model compiler, that generates executable code from a high level model in order to create a functional application. This generation of code is usually done by using template languages like Acceleo777http://www.eclipse.org/acceleo/ or the Epsilon Generation Language [31]. On the other hand, model interpretation is based on implementing a general tool that translates and executes the model on the fly.

Figure 2 shows a feature model [23] summarizing the possible choices when designing a modelling language. The diagram is not meant to be exhaustive, but to gather the most common and typical choices. In the first place, a language can be designed taking as a basis a GPML, or a general purpose programming language. Using a GPML like the UML, one can design a profile [15], with stereotypes annotating the different UML elements and providing domain-specific concepts. This is the approach taken by JUMP [1]. A DSML can also be embedded in a general purpose programming language (the so called internal languages). The flexible syntax and dynamic features of languages like Ruby, make them especially amenable for this task [9]. Alternatively, one can use a GPML “as is”, but then domain-specific concepts have to be expressed as conventions (e.g., naming conventions), programming idioms, or remain at the level of APIs in the case of general purpose programming languages.

The alternative is the definition of a DSML independent of a base GPML. These are called external DSMLs. To define the abstract syntax, a meta-model can be used, as previously explained. While this is the standard choice when using MDE, it is not the only alternative. For example, it is possible to define a (Chomsky) grammar instead (especially if the language has a textual concrete syntax) [36], or a graph-grammar that defines the set of admissible models [16]. Deciding between graphical and textual concrete syntax is not exclusive, and there are languages featuring both [18]. Finally, interpretation and code generation are normally alternative choices. The figure shows in colour the choices made for Ann, whose rationale will be explained in Section 6.

5 Overview of the approach

Since the goal of Ann is to make explicit the conceptual model behind a set of annotations, using a modelling language is a robust choice, because that is what they are precisely designed for. We have decided to restrict the domain to Java annotations, and that is why we have developed a Domain-Specific Language (DSL).

Figure 3 shows the working scheme of our approach to solve the problems outlined in Section 3 by using the DSL. The main idea is to describe the syntax and static semantics of the family of annotations to be built in a declarative way (label 1 in the scheme). The Ann DSL provides appropriate primitives for this task, beyond those natively offered by Java.

We have incorporated a model finder in our approach, in order to check conflicts between the integrity constraints of the different annotations. A model finder is a constraint solver over models [25]. This way, its goal is trying to find a model satisfying a number of constraints. In our implementation, we use the USE validator [25] (label 2), a model finder that takes as input a meta-model and a set of invariants expressed in the Object Constraint Language (OCL)888http://www.omg.org/spec/OCL/. As output, it produces a model, a valid instance of the meta-model that satisfies all OCL constraints. In our case, the sought model is a Java program that contains annotations satisfying all the designed integrity constraints. If a model does not exist, then there is some conflict in the annotation set. As the sought models are fragments of Java programs (in the form of models) containing the designed annotations (label 3), we can render them as textual Java programs. These could serve designers as a means for validation, as they can check whether the produced example fulfils their requirements and expectations about the designed constraints. Actually, this approach is very natural to be used in an iterative process, where the model finder is used to check conflicts and generate examples, and the results of the validation are used to re-design the annotation set, if needed.

Once the annotation design is satisfactory, the designer can make use of a code generator (label 4) that produces plain Java files with the annotation type definition and the annotation processors for the defined annotation (label 5). Then, the annotations can be safely used (label 6), because their definition does not contain conflicts, and their correct use in Java programs is checked by the generated annotation processors.

Altogether, using Ann has several advantages, including: (i) it allows to make explicit the structure and integrity constraints of a set of annotations in a high-level, declarative way; (ii) it provides automatic check of conflicts between constraints at design-time, as well as a generator of annotated example Java programs; and (iii) it automatically produces the annotation processors to check the correct use of annotations.

The next section explains the Ann DSL, including its supporting environment, while the details on how to express Ann constraints in OCL and the interaction with the model finder are left to Section 7.

6 The Ann DSL

Figure 2 showed the different options when designing a DSML, showing in colour the design choices for Ann.

First, Ann has been designed as an external language. We could have opted for a UML profile, which could be a sensible choice, but we preferred a tighter integration with Java programming environment. An internal language within Java was also discarded, as the Java syntax currently does not offer great flexibility for language embedding.

Given that one of the goals of Ann is to give a more user-friendly syntax for Java developers defining annotations, mitigating the incoherences that can be found nowadays in the Java language, a textual concrete syntax has been chosen for it. An alternative graphical concrete syntax to facilitate expressing and visualizing the integrity constraints within an annotation set could be interesting, but is left for future work. The abstract syntax was designed using a meta-model, which is the standard choice when using MDE.

For the semantics of Ann, code generation has been the adopted solution. While an interpreter was also possible, we opted for code generation in order to be able to use the generated annotation processors independently of Ann and its tooling. Moreover, the generated processors would normally be more efficient than processors based on interpretation of Ann models.

The next three subsections describe the abstract, concrete syntax and semantics of the Ann DSL.

6.1 Abstract syntax

The simplified meta-model that describes the abstract syntax of Ann can be found in Figure 4.

The Annotation meta-class contains both the attributes of an annotation and its associated constraints. Note that an annotation with no constraints is allowed, as in the Java language.

Details concerning attributes are shown in Figure 5. Meta-class ExternalAttr represents attributes declared externally to Ann, including enumerated types and other annotations. We also consider all possible primitive types for attributes, the possibility of default values and arrays.

Constraints are split into two types: requirements (class Require in Figure 4) and prohibitions (class Forbid in Figure 4). Multiple constraints over the same annotation type have AND semantics. In Figure 6 we can see an expanded section of the meta-model of Figure 4, in particular the one concerning the constraints.

Each statement represents a description of a Java element (like class, interface or field) over which the annotation is (dis-)allowed. Ann supports the characterization of elements regarding their visibility, and whether they should be final, static or abstract. In order to enhance the expressive power of Ann, several statements are possible within the same constraint (e.g., if the same annotation can be applied to several targets). This is why in the case of requirements multiple statements have OR semantics; whereas AND semantics are applied in the case of prohibitions. Note that AND semantics for requirements would not add any additional expressive power since this is already granted by the multiplicity of Require objects. In the case of prohibitions, the expressive power is enhanced by allowing to forbid simultaneous characteristics in a Java target element: this kind of constraints are only violated if all the statements are satisfied by such element.

There is also the possibility of expressing constraints for specific target types (e.g., a field), which indicates that the given constraint only applies when the annotation is attached to that target type (e.g., a field). This corresponds to the attribute t_type of Constraint. An annotation is thus correctly placed at a target type if it satisfies some of the statements of the requirements whose t_type coincides with the given target, and none of the respective prohibition statements.

For these restricted types of constraints, there is a conceptual distinction depending on whether t_type is a Java container or inner type, since the statements will refer to characteristics of its inner or containing elements, respectively. For example, if the target type is field, then the statements will constrain the classes, interfaces or annotations that contain it; that is, the attribute t_type of an Statement inside such Constraint can only be one of class, interface or annotation999This conceptual remark is also checked when validating the constraints..

These two types of constraints, and their combinations, provide enough expressive power to cover a large scope of the conceptual model behind a set of dependent annotations; as it will be shown in Section 8, in a real use case.

Figure 7 shows an example annotation in abstract syntax. The annotation has Person as name and declares three attributes: name, age and weight. It declares two constraints: one requiring a public class and another one forbidding the class to have final fields. This is an example of an annotation placed at a container Java type (class) with statements that constrain its inner components (fields are forbidden to be final).

6.2 Concrete syntax

We have designed a textual concrete syntax for Ann. An excerpt of the concrete syntax definition for the constraints within an annotation can be found in Listing 1, represented in Extended Backus-Naur Form (EBNF). Appendix A includes the full definition.

Listing 2 shows how the Java annotation type Person previously shown in Listing LABEL:java_def, and in Figure 7, is described using the concrete syntax of Ann. A new keyword (annotation) is used on its declaration (line 3). Instead of using methods to define the annotation parametrs (c.f. Listing LABEL:java_def), we use the regular Java syntax for definining class attributes (lines 4–6 of Listing 2).

Regarding the restriction of the allowed targets, we can now express some more elaborated constraints, in this case that Person can only annotate public classes (line 8) with no final fields (line 10). We recall that with Java the closest we can get to this statement is that the annotation could have as targets classes, interfaces and enumerations, which is less specific than what we obtain with this annotation type definition.

In the concrete syntax for requirements, we also note the special keyword all. This would apply if, for instance, we would want that all the methods of the classes annotated with Person were also public. Then we would add the clause at class: require all public method.

6.3 Semantics: code generation

In order to fully specify the semantics of Ann it is necessary to generate on the one hand the Java code associated with the definition of the annotations; and on the other hand the code of the processors. The latter will ensure that the constraints specified for each of the defined annotations are fulfilled.

For each of the annotations defined at most two processors will be generated, one for checking the requirements and the other for checking the prohibitions. The structure of the annotation processors generated complies with the one presented in Section 3: each of the relevant elements of the Java program is looked up to check whether its properties satisfy the specified requirements or prohibitions.

6.4 Tool support

The different components of the Ann DSL have been developed using the Eclipse Modelling Framework (EMF) [34].

The meta-model has been described with the meta-modelling language Ecore101010http://www.eclipse.org/ecoretools/, which is based on a subset of UML class diagrams for the description of structural aspects. The Xtext111111http://www.eclipse.org/Xtext/ framework, integrated with EMF and able to generate a fully customisable and complete editor for the defined language, has been used to define the textual concrete syntax. Finally, the code generator has been developed using Xtend121212https://eclipse.org/xtend/, a dialect of the Java language included in Xtext. Xtend is more expressive and flexible than Java and has facilities for model navigation. It also allows creating generation templates, what makes it specially useful for code generation. The tool also integrates the USE validator, in order to check constraint conflicts. The use of such model finder will be explained in section 7.

The result is an Eclipse plug-in, which is seamlessly integrated within the Eclipse Java Development Tools (JDT)131313http://www.eclipse.org/jdt/. A screenshot of the IDE is shown in Figure 8.

7 Annotation validation

The advantage of using a high-level language, like Ann, to make explicit the integrity constraints of a set of annotations, is that they are amenable to analysis. We use model finding techniques for this purpose [22, 25]. Model finders are tools supporting a high-level notation to describe features of models, and use constraint solving to find a model exhibiting such features. Typically, model features are described using structural data models (e.g., class diagrams with OCL constraints [25], or relational logic [22]), and rely on lower-level SAT or SMT solver engines (like KodKod [35] or Z3 [12]). Solvers typically perform a bounded search, so that only models up to a given size are sought. Nonetheless, according to the “small scope” hypothesis [22], a large proportion of errors in a system can be identified by considering only instances within a small scope. We use the USE model finder, which accepts as input a meta-model plus OCL invariants.

In order to perform the analysis, we have created a simplified meta-model of Java, containing only the elements that we consider in the Ann language. Then, annotation constraints are translated into OCL, and USE is employed to search for an instance of the previous Java meta-model satisfying all constraints. If no such model is found, then the annotation constraints are incompatible. Moreover, we can also search for Java models containing a combination of annotations of interest. This can be done by another OCL constraint explicitly demanding the occurrence of the desired combination of annotations.

Figure 9 shows the Java meta-model we use for the validation and verification of annotations. A few OCL constraints have been added to different classes, for example restricting the visibility of Class to be default or public; demanding abstract methods to reside in abstract Classes; and forbidding cycles of class and interface inheritance.

For the analysis, the main idea is to enrich such meta-model with classes and constraints generated from the annotation definitions. If the resulting meta-model is satisfiable, then there is no conflict in the annotation definition. For example, Figure 9 shows two classes: Person and Employee generated from two annotation definitions. The first one from the definition in Listing 2, while the second one just requires classes with package visibility and with a Person annotation. In Figure 9, these generated classes are shown encircled in a dotted region. For class Person we generate an association to Class, which is its only allowed target. If an instance of Person is created, it needs to annotate a Class and therefore the cardinality of role targetPerson is 1. Similarly, another association is created for Employee. Additionally, the OCL constraints of Listing 3 are generated for both classes.

The two invariant named redefs in lines 2-4 and 14-16 emulate the redefinition of the target role by targetPerson and targetEmployee in classes Person and Employee respectively. This is necessary, because for both annotations, Class is their only allowed target. Note that the target role is useful for annotations that do not explicitly declare a target, so that they can be placed anywhere. For Person we require the target class to be public (invariant require_public_class in lines 5-7), and to have no final fields (invariant at_class_forbid_final_field in lines 9-11). For Employee we require the target class to have package visibility (invariant require_annPerson_package_class, line 19), and be also annotated with the Person annotation (invariant require_ annPerson_package_class, line 20).

Feeding the meta-model of Figure 9 and the generated constraints in Listing 3 to USE, it returns no model, and hence the constraints are unsatisfiable. On reflection, we realize that the designed constraints for the annotations are in conflict, because annotation Employee demands classes with package visibility, and to be annotated with the Person annotation, which requires classes with public visibility. Designers can then modify the constraints, for example requiring Employee to annotate public classes. Alternatively, they might drop the constraint on visibility, because it would be redundant with the similar constraint from Person. While this example is simple, in more complex cases, the user has the burden to find the reasons for the conflict. This is typically done by systematically trying all combinations of constraints within the considered set (by manually disabling combinations of constraints). Automated, more efficient support for this task (e.g., like the method proposed in [30]) is left for future work. Similarly, constraint redundancy can be (manually) investigated with solvers like USE [17], but automating this task is also left for future work.

Once the constraint for package visibility is deleted from Employee, USE would return a model like the one in Figure 10(a), proving that there is no conflict, and provide the designer with an example of use of the designed annotation. Figure 10(b) shows a representation of the USE model in the textual syntax of Java, which could be useful to the designer, to see an example of use of the designed annotations.

We next provide a systematic description of how the Java meta-model is to be extended and how the OCL invariants are generated given an Ann model. For each Ann annotation named $\langle$ANN$\rangle$, we create a subclass of Annotation named $\langle$ANN$\rangle$. Then, additional OCL code is generated for the annotation’s require and forbid constraints.

7.1 Generation of target requirements

The code generation scheme for require constraints is shown in Table 7.1. The second column of the table shows the generated OCL, as well as the extra elements to be created in the meta-model (using the textual notation of USE for class diagrams).