Category Archives: grails

Quest for (persistable) Groovy immutability

This is my first post about how to implement DDD concepts with Groovy and deliver them with Grails. My goal is to have real domain logic, without any (or as few as possible) dependencies on surrounding frameworks.

Grails is, at first glance, very pervasive and induces you to mix your business logic with concerns that should be treated separately. On the other hand, the framework is more modular with every release – which means you can disable some parts of it. Under the hood uses some popular libraries (which can be used directly by circumventing the framework).

This article is about implementing immutable Value Objects in Groovy and plugging in the persistence in a Grails application. First part discusses strategies of achieving immutability with Groovy. Second part describes how to persist our Value Object with in a relational database with Hibernate and in document-oriented database (MongoDB).

Create an immutable Value Object class

Value Objects, a building block of DDD should be implemented as immutable. Which options do we have in Groovy?

  • annotate your VO with @Immutable annotation
    • very straightforward, however, no customization options. You get a tuple/map constructor for free, but it sets all your VO properties to null by default. No way to specify mandatory properties and validate them.
  • declare all fields as final (with the default Groovy visibility). Fields will have getters but no setters. Then:
    • use @TupleConstructor
      • no boilerplate code
      • map constructor provided by this annotation is useless with final fields. It calls first the no-arg constructor and then tries to set fields with provided values. As there no setters, you will get a nice groovy.lang.ReadOnlyPropertyException exception.
      • all parameters of the tuple constructor have a default null value. As for @Immutable, no way to enforce mandatoriness.
    • implement custom constructor(s)
      • some boilerplate code, reduced with AST transformations GContracts
      • fully customizable

Example of an immutable Value Object with custom constructor:

Persist the FullName Value Object inside an aggregate

Our sample FullName VO is a part of a larger Person aggregate:

To persist it, I won’t use GORM (at least not directly).

Relational DB, Hibernate

I’m going to use external Hibernate mapping. With this approach my Person aggregate won’t be coupled at the source code level to any persistence configuration.

Hibernate imposes some restrictions on what your objects should provide in order to be persistable. The ORM must be able to instantiate an empty object. It requires a default constructor, although it can be protected.

At this point I have to make a small concession to Hibernate and add a default constructor1 to FullName:

protected FullName() {}

For filling the object with values read from the database, it doesn’t require to have setters. Hibernate is able to ‘reach’ a field through Java reflection (even if it’s final).

I map the VO as Hibernate component (an object mapped to the same table as the aggregate). As there are no setters, I instruct Hibernate to access VO properties directly with access="field":

As the gateway to the persistence I use a repository, an object that can provide the illusion of an in-memory collection (Eric Evans, Domain-Driven Design). As a rule of thumb, there is one repository per aggregate.

I don’t define an explicit interface; I’m going to use a duck type thorough the domain. The implementation is a delivery detail and I put it in the infrastructure layer.

By mapping the Person aggregate as an external Grails entity, it gets all persistence and query methods provided by GORM. However, the rest of domain and infrastructure code doesn’t notice them. The repository (PersonGormRepository) is the only component allowed to use the GORM API on Person.

Result: GORM becomes a plugin to the domain, totally unaware of it. There is only one place where the coupling application – GORM happens – in the implementation of the repository.

The code is pretty straightforward:

MongoDB

Mongo is a document-oriented database perfectly suited for storing objects modelled with composition – one document per each aggregate instance, together with all contained entities and value objects.

There is a MongoDB GORM plugin for Grails. I won’t use it, since I had to pollute my aggregate with mapping configuration (and it should be oblivious to the persistence). I’m going to use GMongo library, a Groovy wrapper over the official MongoDB driver. MongoDB for GORM offers no such thing like external MongoDB mapping.

My repository implementation uses quite a low-level API (compared to GORM). I don’t have to tweak my FullName value object. I can use all-property constructor when filling the VO from the Mongo document.

findById method is quite simple:

save method is more complex comparing with the Hibernate repository. It has to deal with the insert and update semantics.

Additionally, it’s in charge of generating numerical ids (in case of a relational database, we relied on the DB engine). I copied the implementation from the GORM MongoDB plugin source code. It uses a collection with single document containing the recently used ID. When obtaining it I use the Mongo atomic operation findAndModify, increasing the id by one and getting the increased value.

Summary

It is relatively easy to decouple your domain from persistence and make the latter a pluggable detail. You are leaving a well-trodden path of GORM, but the journey outside of it is not scary. You enter other safe routes guarded with decade old patterns and implementation techniques. Sometimes there are few signposts. You have to dig inside blogs and scarce documentation in order to move forward. Sometimes you just wander around and need to make some experiments in order to find the right way.

As reward you will get a cohesive object-oriented domain code that focuses only on one thing: solve problems of your/your customer’s business. Code that shifts data back and forth is strictly separated. Two worlds meet together at the repository frontier. And that’s fine, why should your business deal with database quirks?

Full source code

You find the complete source code in grails-ddd GitHub repo:
* master branch does not implement any persistence (yet)
* MongoDB and Hibernate (with H2 embedded database) repositories are implemented in mongo and hibernate branches, respectively.


  1. before adding a default protected constructor, I tried implementing a CompositeUserType and a custom tuplizer. Unfortunately, both need to create an empty object before filling it from the database result set. 

XML rendering in Grails

Notes taken when researching how to render efficiently a possibly large object tree resulting in complex XML.

Disclaimer: tested with Grails 1.3.7, but it should be valid in more recent framework versions

Convert object to XML string using XML converter

def ping = {
    def result = new Result(response: 'OK')
    def xml = new XML(result)
    render text: xml, contentType: 'text/xml', encoding: 'UTF-8'
}
  • adds explicit <class>…</class> element to the output
  • double transformation – object -> XML string -> ServletResponse output stream
  • relies on poorly documented Grails contracts – here be dragons

Variation – deep conversion

XML.use('deep') {
    def xml = new XML(result)
    render text: xml, contentType: 'text/xml', encoding: 'UTF-8'
}

Variation – customize conversion with a custom marshaller

class ResultMarshaller implements ObjectMarshaller {
    @Override
    boolean supports(object) {
        object instanceof Result
    }

    @Override
    void marshalObject(object, Converter converter) {
        // converter is an instance of XML
        converter.build {
            response object.response
        }
    }
}

class ResultRootElementCustomizingMarshaller extends ResultMarshaller implements NameAwareMarshaller {
    @Override
    String getElementName(o) {
        'wynik'
    }
}

Unit tests

def 'ping, no marshaller'() {
    when:
    controller.ping()

    then:
    XmlAsserts.xmlsEqual controller.response.contentAsString, """<result>
    <class>${Result.name}</class>
    <response>OK</response>
</result>"""
}

def 'ping, marshaller'() {
    given:
    XML.registerObjectMarshaller new ResultMarshaller()

    when:
    controller.ping()

    then:
    XmlAsserts.xmlsEqual controller.response.contentAsString, '<result><response>OK</response></result>'
}

def 'ping, marshaller customizing root element name'() {
    given:
    XML.registerObjectMarshaller new ResultRootElementCustomizingMarshaller()

    when:
    controller.ping()

    then:
    XmlAsserts.xmlsEqual controller.response.contentAsString, '<wynik><response>OK</response></wynik>'
}

Render object to the response using XML converter

def pingConverterRendersToResponse = {
    def xml = new XML(new Result(response: 'OK'))
    xml.render response
}

Unit tests

def 'ping, converter renders to response'() {
    when:
    controller.pingConverterRendersToResponse()

    then:
    XmlAsserts.xmlsEqual controller.response.contentAsString, """<result>
<class>${Result.name}</class>
<response>OK</response>
</result>"""
}

Convert object to XML string using StreamingMarkupBuilder

def pingViaBuilder = {
    def res = new Result(response: 'OK')
    render contentType: 'text/xml', encoding: 'UTF-8', {
        result {
            response res.response
        }
    }
}
  • feature provided by render method
  • direct write into ServletResponse writer
  • could lead to repeated rendering code

Unit tests

def 'ping, direct render'() {
    when:
    controller.pingViaBuilder()

    then:
    XmlAsserts.xmlsEqual controller.response.contentAsString, '<result><response>OK</response></result>'
}

Common objects/helper methods used in examples

class Result {
    String response
}

class XmlAsserts {
    static void xmlsEqual(String actual, String expected) {
        XMLUnit.ignoreWhitespace = true
        def diff = new Diff(actual, expected)
        assert diff.similar(), "${diff.toString()}\nActual XML: $actual\n\nExpected XML: $expected"
    }
}

cut + grep + awk + sed in action; prerequisite: Git repository:

git status -s | \
cut -c4- | \
grep "$test_type.*[Test|Spec]" | \
awk 'BEGIN { FS = "/" } ; { print ($(NF)) }' | \
sed 's/\.groovy//' | tr '\n' ' '

Find all dirty Grails tests

Asynchronous tests with GPars (Osoco test gallery, part 4)

If you wrote multithreaded code in Groovy/Grails, I’m sure you stumbled upon the GPars library. It simplifies parallel processing – sometimes it’s as easy as wrapping a code fragment with a GPars closure, changing the iteration method (in our example from each to eachParallel) and passing the closure to a GPars pool. The library implementation handles the executor pool creation and adds new methods to collections.

Whenever I deliberately add multithreading, I always separate responsibilities (processing logic and concurrency handling). I wrap the single-threaded class with a new one, handing the parallel execution (creating a pool, managing threads, handling cancellation, etc.):

class MultithreadedProcessorService {
    ProcessorService processorService
    def threadPoolSize = ConfigurationHolder.config.threadPool.size

    void processMultithreaded(batches) {
        GParsPool.withPool(threadPoolSize) {
            batches.eachParallel { batch ->
                processorService.process(batch)
            }
        }
    }
}

class ProcessorService {
    void process(batch) {
        // some processing
    }
}

To test the multithreaded class you can you use Spock interactions. As opposed to Groovy and Grails mocks, they are thread-safe and you won’t get any weird and unstable results:

class MultithreadedProcessorServiceSpec extends UnitSpec {
    private MultithreadedProcessorService multithreadedProcessorService
    // Using Spock mocks because they are thread-safe
    private ProcessorService processorService = Mock(ProcessorService)

    def setup() {
        mockConfig('threadPool.size=2')
        multithreadedProcessorService = new MultithreadedProcessorService(
            processorService: processorService
        )
    }

    def 'processes batches using multiple threads'() {
        given:
        def batches = [[0, 1], [2, 3, 4], [5]]
        def processedBatches = markedAsNotProcessed(batches)

        when:
        multithreadedProcessorService.processMultithreaded(batches)

        then:
        batches.size() * processorService.process({ batch ->
            processedBatches[batch] = true
            batch in batches
        })
        assertAllProcessed(processedBatches)

    }

    private markedAsNotProcessed(batches) {
        batches.inject([:]) { processed, batch ->
            processed[batch] = false
            processed
        }
    }

    private void assertAllProcessed(batches) {
        assert batches*.value == [true] * batches.size()
    }
}

This post series present the best of Osoco tests – tests that were tricky or we are just proud of. You can find a runnable source code for this test and more in the Grails Test Gallery project shared on GitHub.

Grails base persistence specification (Osoco test gallery, part 3)

In our projects we include at least one integration test per domain class. We want to assure us that the GORM mapping is correct and the class is persistable in the target database.

The test plan is simple:

  • create a valid persistable sample of the domain object
  • save it
  • clear Hibernate first level cache (i.e. flush and clear current session)
  • retrieve the object once again and compare it with the previously saved object. They must be equal as by equals() but be different object references

We put the steps above in a base abstract specification. In concrete specifications we implement merely the factory method spawning a persistable object instance.

abstract class PersistenceSpec extends IntegrationSpec {
    SessionFactory sessionFactory

    protected abstract createPersistableDomainObject()
    
    def 'persistable domain object should be able to be saved and retrieved'() {
        given:
        def persistableDomainObject = createPersistableDomainObject()

        when:
        def savedDomainObject = persistableDomainObject.save()

        then:
        savedDomainObject.id != null

        when:
        clearFirstLevelCache()

        def retrievedDomainObject = persistableDomainObject.class.get(savedDomainObject.id)

        then:
        savedDomainObject == retrievedDomainObject
        !savedDomainObject.is(retrievedDomainObject)
    }

    private clearFirstLevelCache() {
        sessionFactory.currentSession.flush()
        sessionFactory.currentSession.clear()
    }
}

This post series present the best of Osoco tests – tests that were tricky or we are just proud of. You can find a runnable source code for this test and more in the Grails Test Gallery project shared on GitHub.

Follow

Get every new post delivered to your Inbox.

Join 383 other followers