Migrating from a VRaptor 3 project

Java 7 and CDI 1.1

To use VRaptor you need a JDK 7 and an Application Server or Servlet Container that supports Servlets 3.1.

IoC Containers

Now VRaptor uses CDI as container, so you don’t need to use Guice, Pico or Spring.

CDI spec requires managed classes with normal scope to have a no-arg constructor. If you have another constructor annotated with @Inject you still need to add a no-arg constructor.

public class MyController {

    private final MyComponent myComponent;

     * @deprecated CDI eyes only
    protected MyComponent() {

    public MyController(MyComponent myComponent) {
        this.myComponent = myComponent;

Static scanning

Since CDI can scan the classpath, this feature is not nedded anymore.

Startup events

Now to trigger some code when VRaptor starts, you need to observe the event VRaptorInitialized as shown below:

public class PrintLog {

    private Logger logger;

    public void whenApplicationStarts(@Observes VRaptorInitialized initialized) {
        logger.info("My application is UP");

Changes in classes and method signatures

Some classes and methods were changed or removed. If you overrode some internal behaviour, you need to checkout our Javadocs to see what has changed.

All methods and classes annotated with @Deprecated were removed.


OGNL support was removed. Now we use IOGI to instantiate parameters, that supports immutable objects, Sets and more.


The fluent validation was removed. From now we only support Bean Validation. For legacy compatibility you can use Validator.addIf(boolean, Message) or Validator.ensure(boolean, Message) to do simple validation.

The Validator interface was moved to br.com.caelum.vraptor.validator.Validator package.

The classes that used to inherit from Message were changed. ValidationMessage was renamed to SimpleMessage and the constructor was refactored to SimpleMessage(String category, String message, Object... params) to keep it compatible with other Message implementations.


All localized converters were merged with non-localized converters. From now on you don’t need to declare these converters in the web.xml.

All converters were refactored, and Converter#convert doesn’t have a ResourceBundle parameter anymore. If you need to use some localization features you can inject Locale in the class.

The Converter interface was moved to br.com.caelum.vraptor.converter package.

VRaptor scopes removed

All VRaptor scopes are removed in favor of CDI scopes under package javax.enterprise.context:


Component factories

The ComponentFactory interface doesn’t exist anymore. From now you can use @Produces from CDI spec. You can see more here.

Overriding components

Due to CDI behaviour you need to annotate your class with @Specializes annotation.

@Resource is now @Controller

The @Resource annotation was renamed to @Controller and has the same behaviour.

There is no Localization interface

Instead of using Localization and call .getLocale() or .getBundle() methods, from now on you can inject these objects directly like this:

public class MyClass {

    private Locale locale;

    private ResourceBundle bundle;



The LinkTo feature was updated, and now support method sintax. From now on, instead of using ${linkTo[Controller].metodo[0, 1]} you can use ${linkTo[Controller].metodo(0, 1)}. More information here.

To simplify migration, we shared a .sh script here.

Serialization and deserialization

To stay closer with HTML5 spec, all date and time used with serialization and deserialization uses the ISO8601 format.


It’s not supported anymore.