Archive

Archive for the ‘releases’ Category

GContracts 1.1.3 Released!

November 16, 2010 2 comments

I am proud to announce that GContracts 1.1.3 has just been released and is available now in the Central Maven repository [0] and at Github [1].

The release includes bug fixes and advanced support Spring bean classes annotated with GContracts’ annotations.

Concrete AssertionError types

In parallel with @Invariant, @Requires and @Ensures GContracts 1.1.3 provides separate exception types which all are descendants of AssertionError and I guess do not need further explanation:

ClassInvariantViolation, PreconditionViolation and PostconditionViolation.

Advanced Support for Spring Beans

One of the problems with GContracts is its lack of compatibility especially with Grails artifact classes, i.e. controllers, services, domain classes etc. This topic has been brought to me a few times and if you just want to apply let’s say class invariants on Spring bean classes the Spring application container’s initialization lifecycle can quickly become your enemy.

Let’s consider the following service:

@Invariant({ anotherService != null })
class MyService {

    def anotherService

    static transactional = true

    // ...
}

MyService is a simple Grails service class, annotated with a class invariant which ensures that the reference to anotherService will never be null, during the entire life-time of the MyService bean. Sadly enough, whenever the Spring application container tries to create a new instance of a MyService bean it fails because GContracts checks the class invariant directly after the object’s constructor has completed successfully. By that time, the Spring application container is not yet done with object construction.

From a theoretical perspective throwing a ClassInvariantViolation in this place is completely reasonable since an object’s class invariant needs to be fulfilled by the object instance during its entire life-time. But from a practical perspective, this is kind of pain. It means that you have to duplicate the class invariant to all methods in the service class, e.g.

// avoid invariant checks during construction
class MyService {

    def anotherService

    static transactional = true

    @Requires({ anotherService != null })
    def myServiceMethod()  {
        // ...
    }

    @Requires({ anotherService != null })
    def yetAnotherServiceMethod()  {
        // ...
    }
}

It is not that Design by Contract can not be applied here, it is that Spring simply does define its own rules for object creation and destruction, meaning that whenever an object is created with its constructor the initialization process is not done in the case of the Spring application container.

This circumstance confuses programmers who simply want to apply DbC on their bean classes without thinking about Spring initialization mechanisms and GContracts assertion injection.

GContracts 1.1.3 is the starting point for a bunch of features which are targeted to iron out such integration issues with Spring/Grails applications. Of course it might be questionable whether it makes sense to focus primarily on the Spring framework, but that has been a practical decision (GContracts is for Groovy, Grails uses Groovy, Grails uses Spring…). Furthermore, I tried to make the integration as light as possible without actually introducing a classpath dependency on Spring framework classes.

The first feature which comes with 1.1.3 is a solution for the problem described above: class invariant checks on Spring beans. Henceforth, GContracts will not make class invariant checks on Spring beans during constructor calls, but will create a synthetic @PostConstruct method which overtakes the class invariant check. Since GContracts has no mechanism to know that the given class is a Spring-managed class at runtime, programmers need to annotate their artifact classes with appropriate stereotype annotations [2], e.g. a service class with @Service, a controller with @Controller, etc.

@Service
@Invariant({ anotherService != null })
class MyService {

    def anotherService

    static transactional = true

    // ...
} 

The @Service stereotype annotation above triggers GContracts’ “Spring compliance mode”. Whenever the service bean above has been constructed by the Spring application container it will automatically check the class invariant.

The programmer clearly needs to make a compromise in this case, because the class invariant won’t be checked after a construction call anymore (e.g. in a test-case where the programmer simply creates an instance of this service class). But this is a consequence of outsourcing object creation to the application container.

Hint: GContracts supports the -ea/-da VM parameters [3] which you can use to deactivate assertion checking during application execution, whereas activating assertion checking only during test-cases.

Changes

ISSUE-25: better support for Spring component classes with class invariants
ISSUE-24: wrong class invariant placement with inherited invariant
ISSUE-23: @Requires on constructor with super statement causes compilation error
ISSUE-22: Separate Exception Types for Pre-, Postconditions and Class Invariant
ISSUE-17: remove direct reference to PowerAssertionError

[0] GContracts 1.1.3 in Central Maven Repository
[1] GContracts at Github
[2] Spring Stereotype Annotations and Classpath Scanning
[3] GContracts VM Parameter Support


Flattr this

Advertisements
Categories: gcontracts, groovy, releases

GContracts 1.1.2 Released!

July 12, 2010 2 comments

I am proud to announce that GContracts 1.1.2 has just been released and is available now in the Central Maven repository [0] and at Github [1].

The release mainly includes internal refactorings, bug fixes and support for Groovy’s power assertions [2].

Therefore, 1.1.2 upwards depends on Groovy 1.7. If there is the demand to maintain a separate Groovy 1.6 branch, I will certainly do that – just let me know.

Groovy Power Assertions & GContracts

Before 1.1.2, GContracts custom handling of assertion messages prevented triggering of Groovy’s power assertion rewriting transformation. Certain parts of GContracts have been rewritten to support power assertions know. The greatest advantage of power assertions are certainly there expressiveness:

import org.gcontracts.annotations.*

@Invariant({ speed >= 0 && speed <= 100 })
class Rocket  {
    int speed
    boolean started

    @Requires({ !started })
    def start() { started = true }

    @Requires({ started })
    @Ensures({ old -> (speed - old.speed) > 0 })
    def accelerate()  { speed += 10 }
}

class BetterRocket extends Rocket {
    @Override
    def accelerate() {
      speed += 20
    }
}

def betterRocket = new BetterRocket()
betterRocket.accelerate()

Output:

Assertion failed: 

<inherited precondition> Rocket.accelerate()

{ started }
  |
  false

	at Rocket.precondition_java_lang_Object_accelerate(ConsoleScript0:11)
	at BetterRocket.super$2$precondition_java_lang_Object_accelerate(ConsoleScript0)

Let’s say we would introduce a bug in BetterRocket‘s implementation that will violate the parent’s postcondition:

class BetterRocket extends Rocket {
    @Override
    def accelerate() {
      speed = 20
    }
}

def betterRocket = new BetterRocket()
betterRocket.start()
betterRocket.accelerate()
// ...
betterRocket.accelerate()

Output:

Assertion failed: 

<inherited postcondition> Rocket.accelerate()

{ old -> (speed - old.speed) > 0 }
          |     | |   |      |
          20    0 |   20     false
                  {speed=20}

	at Rocket.postcondition_java_lang_Object_accelerate(ConsoleScript3:12)
	at BetterRocket.super$2$postcondition_java_lang_Object_accelerate(ConsoleScript3)

The assertion message shows what assertion got violated and has visual pointers to the computed expression values – assertion messages can’t be more readable than that.

Changes

ISSUE-7: use Groovy power asserts as an alternative to AssertionStatement
ISSUE-16: old variables gets cleared on inherited postcondition

[0] GContracts 1.1.2 in Central Maven Repository
[1] GContracts at Github
[2] Groovy Power Assertions

Categories: gcontracts, releases

GContracts 1.1.0 Released!

June 12, 2010 1 comment

After a short break, I am happy to tell you that GContracts 1.1.0 has been released and was pushed to the central Maven repository.

Grab GContracts 1.1.0 by defining a Maven dependency [0] or by direct download from github’s download section [1].

This release marks an important milestone since inheritance of class invariants, preconditions and postconditions is supported by now. The basic principles found in Design by Contract(tm) can therefore be fully utilized in Groovy/Grails projects.

GContracts’ test suite currently holds more than 100 test cases for regression and feature testing. There will be is a separate blog post on how to test and implement Groovy AST transformations, with all my experiences so far with GContracts [4].

Changes

GContracts 1.1.0 fixes the following issues:

  • ISSUE-14: fix class invariant inheritance with default class invariant – a class with a class invariant in its heir must be equipped with a default class invariant chaining the method call to the super class invariant.
  • ISSUE-1: pre- and postcondition inheritance – class invariants, pre- and postconditions are now inherited. inheritance support does not include pre/postcondition support in interfaces, but there is a separate ISSUE on this topic. More about pre/postcondition inheritance will follow in a separate blog post [3].
  • ISSUE-10: all uses of getTypeClass() were removed with valid alternatives. this was done due to issues with the Groovy Eclipse plugin.
  • ISSUE-13: Cleanup the generated AST: a few optimizations have been made to the AST node generating components.
  • Bug fixes and a lot more bug fixes.

Special thanks for your contributions!

[0] GContracts – Central Maven Repository
[1] GContracts Available in Central Maven Repository
[2] GContracts – Github Download Section
[3] GContracts: Inheritance of Pre- and Postconditions
[4] Grails Inside – Unit Testing Groovy AST Transformations


Flattr this

Categories: gcontracts, releases

gcontracts 1.0.2 Released!

I am proud to tell you that gcontracts 1.0.2 was released and pushed to the central Maven repository [0].

Grab gcontracts 1.0.2 by defining a Maven dependency [0] or by direct download from github’s download section [1].

Changes

gcontracts 1.0.2 fixes the following issues:

  • ISSUE-5: better AssertionError messages – the closure source of the invariant or pre/postcondition that failed has been added to the AssertionError message.
  • ISSUE-6: line numbers were added in the AssertionError stacktrace. Whenever an assertion fails the last line number guides directly to the condition that caused the AssertionError.
  • Bug fixes.

Special thanks to Hamlet D’Arcy and others for your contributions!

[0] gcontracts – Central Maven Repository
[1] gcontracts Available in Central Maven Repository
[2] gcontracts – Github Download Section


Categories: gcontracts, releases

gcontracts 1.0.1 Released

I am proud to tell you that gcontracts 1.0.1 was released and pushed to the central Maven repository [0] yesterday.

You can get gcontracts 1.0.1 by defining a Maven dependency [0] or in github’s download section [1].

Changes

gcontracts 1.0.1 is a maintenance release fixing several issues highly requested by users:

  • POGO support – invariants are checked when setting Groovy bean properties/executing default constructor.
  • Advanced old variable support in Ensures annotation – added support for GString, String, Number, etc.
  • Refined AssertionError exception messages.
  • Other bug fixes.

[0] gcontracts – Central Maven Repository
[1] gcontracts Available in Central Maven Repository
[2] gcontracts – Github Download Section


Categories: gcontracts, releases

gcontracts 1.0 released

I am happy to tell you that gcontracts version 1.0 has just been released and is available for download on github, licensed under BSD.

Bugs, enhancements and feature requests should be reported over github’s issue tracking system.

About gcontracts

As I’ve already mentioned in a previous blog-post “Contract-Oriented Programming with Groovy”, I started a github project called gcontracts which aims to enable “contract-oriented” programming aka “design by contract” in Groovy. This is done by relying on Groovy’s ability to transform the abstract syntax tree (AST) during the compilation process and is mainly based on intelligent injection of  Java assert statements.

If you aren’t familiar with contract-oriented programming, I advice to take a look at my blog-post Contracts in the Domain Model [0] which explains the principle idea of contracts, assertions and todays role of contract-oriented programming in software development processes.

Be warned, there is still a long way ahead, especially in fields of performance improvements, configurability and more advanced topics like loop invariants, pre- and postcondition inheritance and configurability, although the basic features are tested and working.

Features

gcontracts comes with a set of Java annotations whereas each annotation represents a particular assertion type. Each annotation has a single parameter which is used at declaration-time to specify a closure with a boolean expression, representing the assertion on the actual object’s state. gcontracts 1.0 comes with the following assertion type annotations:

  • Class-Invariants with @Invariant

    In order to specify a class-invariant use the @Invariant annotation e.g.

    @Invariant({ someProperty.size() > 0 && anotherProperty == someMethod() })

    An @Invariant annotation’s closure has access to:

    instance variables instance variables of any scope
    methods methods of any access scope (although it is recommended to use public methods only)
    static fields static fields of any access scope
    static methods static methods of any access scope
  • Preconditions with @Requires

    In order to specify preconditions on methods, use the @Requires annotation e.g.

    @Requires({ someProperty.size() > 0 && anotherProperty == someMethod() })

    A @Requires annotation’s closure has access to:

    instance variables instance variables of any access scope
    methods methods of any access scope (although it is recommended to use public methods only)
    static fields static fields of any access scope
    static methods static methods of any access scope
    arguments all arguments of the current method scope
  • Postconditions with @Ensures

    In order to specify postconditions on methods, use the @Ensures annotation e.g.

    @Ensures({ someProperty.size() > 0 && anotherProperty == someMethod() })

    An @Ensures annotation’s closure has access to:

    instance variables instance variables of any access scope
    methods methods of any access scope (although it is recommended to use public methods only)
    static fields static fields of any access scope
    static methods static methods of any access scope
    arguments all arguments of the current method scope
    method result the method’s return value (if not void) is available as closure parameter result. Thus, to access the return value of the current method specify a closure parameter result, e.g.

    @Ensures({ result -> result >= 0 })
    old attribute values a map containing all attribute values before method execution is available as closure parameter old. Thus, to access the value of instance variables before method execution, specify a closure parameter old, e.g.

    @Ensures({ old -> old.field1 != field1 })

    Of course, the variable map does not contain copies of you domain’s entity classes, it works with Java’s built-in data types only, e.g. primitive values, reference types like Integer, Boolean, Calendar, Date and so on.

    By the way, you can even use both closure parameters in the same closure, e.g.

    @Ensures({ old, result -> old.field1 != field1 && result != field1 })

    or

    @Ensures({ result, old -> old.field1 != field1 && result != field1 })
  • Class-Invariant Point Cuts

    In the case of pre- and postconditions the validation is done either at a method’s start or end. In the case of class-invariants, gcontracts injects the invariant’s condition at multiple point cuts.If a class contains a class-invariant definition, at run-time the class-invariant is checked at the following pointcuts:

    1. at the end of each constructor call
    2. at the end of each method call
    3. at the beginning of each method call
  • Class-Invariant Inheritance

    Whenever class A specifies a class-invariant and class B extends A and specifies a class-invariant again, A’s class-invariant is said to be inherited to class B’s class invariant. In this context inherited means that A’s invariant and B’s invariant are logically combined with a boolean AND.Class Invariant Inheritancegcontracts analyses the class inheritance line and links all class-invariants appearing in there. E.g. in the class inheritance line C – B – A (from bottom to top), C’s class-invariant is linked with B and A ( C AND B AND A), B’s class-invariant is linked with A’s (B AND A).

gcontracts > 1.0

Upcoming features in next versions of gcontracts will include:

  • bug fixes
  • pre- and postcondition inheritance
  • performance tweaking
  • configurability

Using gcontracts in your project

The easiest way of getting a gcontracts.jar is to get it from github’s download section. In addition, the project’s root directory provides a Maven pom.xml for comfortable generation of the gcontracts.jar file. The library itself will be published to a public Maven repository soon.

Once you got a copy of the jar, add it to the project’s classpath. This should be enough to let the Groovy compiler detect it and execute it during compilation.

Hint: If you decide to pull the repository from github, take care that you can’t compile gcontracts and your project in a single compilation pass. This means, you need to ensure that your build process (let it be your IDE, or Ant, or Maven, …) already has access to a compiled gcontracts.jar!

[0] Contracts in the Domain Model
[1] gcontracts wiki on github

Categories: gcontracts, groovy, releases