One minute tutorial

This is a simple guide to the basic features that VRaptor 2 introduces.

This shows how to create a basic logic component which adds and loads data from a database.

Installing VRaptor

Follow the installation instructions to get it working.

The model

We will play around with a model class called Person. Create the following class:

package org.vraptor.examples.first;

public class Person {

        private String name;

        private String address;

        private Long preferredNumber;
        
        // getters and setters

        @Override
        public String toString() {
                return "[Person " + name + "," + address + "," + preferredNumber + "]";
        }

}

The business logic component

Let's create our first component and business logic: creating a new Person...

Create a class called PersonLogic on the logic package.

As we are going to read a new person from the request let's create a method which contains our business logic:

package org.vraptor.examples.logic;

public class PersonLogic {

        public void add(Person person) {
                System.out.println("Adding " + person + " to the database!");
        }

}

The request parameters

VRaptor will call the add method passing a new Person as argument.

Another way to tell vraptor that we want to use the request's parameters to fill an object is to use the @Parameter annotation in a attribute.

If a parameter called person.name is found in the request, the method person.setName() will be called using the parameter value as its content. The same will happen with anything beginnig with person (our field's name). VRaptor will also try to apply some converters.

The URL: person.add.logic

Now let's go a step further and configure this business logic url.

Let's name annotate this class as a component and the business logic represented by the method add by add.

This means that when the url person.add.logic is called, our component will be instantiated, the person field filled with the request's parameters and after that the method add is called.

This is because your class is called PersonLogic.

package org.vraptor.examples.logic;

import org.vraptor.annotations.Component;

@Component
public class PersonLogic {

        public void add(Person person) {
                System.out.println("Adding " + person + " to the database!");
        }

}

Sending objects to the presentation layer

Now that we know our method will be invoked let's think about what shall be displayed after that. We want to show in our jsp view that the 'person' object has been added successfully.

Depending on the web based mvc implementation, this is accomplished by setting a request attribute... we will tell vraptor about our desire to outject the person field's value to the request by using the getter:

package org.vraptor.examples.logic;

import org.vraptor.annotations.Component;
import org.vraptor.annotations.Out;

@Component
public class PersonLogic {

        private Person person;

        public void add(Person person) {
                this.person = person;
                System.out.println("Adding " + person + " to the database!");
        }

        public Person getPerson() {
                return this.person;
        }
}

Because of the getter getPerson() the attribute person will be automatically outjected to the request.

Redirecting to the presentation layer

We will use the default target pattern: componentName/logicName.result.jsp

As the default result is ok we create a file called: person/add.ok.jsp

Success page

Now we display the result by using the outjected person field in a file called add.ok.jsp under the directory called person:

<html>
You have created a new person named ${person.name},
        who lives at ${person.address} and his/her
        preferred number is ${person.preferredNumber}.
</html>

Index page: /index.jsp

Let's create a simple index.jsp page that contains the desired form:

<html>
<form action="person.add.logic" method="get">
        Name: <input name="person.name"/><br/>
        Address: <input name="person.address"/><br/>
        Preferred number: <input name="person.preferredNumber"/><br/>
        <input type="submit"/>
</form>
</html>

Registering the component

Now let's create the xml file... the basic idea is... you do not need it. VRaptor will look for all components in the classpath annotated with @Component and register them automatically.

Directory Structure

So we get the following structure:

|-person
|    |--/add.ok.jsp
|-WEB-INF
     |--/web.xml
     |--/lib
     |    |--/jar files
     |--/classes
          |--/class files

Testing

  1. Start your web application
  2. access index.jsp: it shows a form
  3. fill the form with data:

    name: Guilherme
    address: Vergueiro
    preferred number: 7

  4. press submit

What happens?

  1. the url person.add.logic?person.name=Guilherme&person.address=Vergueiro&person.preferredNumber=7 is requested
  2. the vraptor servlet (controller) parses the url
    it discovers that the component named person, logic named add maps to class PersonLogic, method add.
  3. PersonLogic is instantiated
  4. person.setName, person.setAddress and person.setPreferredNumber are called
  5. the method add (our business logic) is called
  6. the field person is outjected (scope request)
  7. vraptor looks up the view person.add.ok and finds /person/add.ok.jsp
  8. redirection occurs and data is displayed

Conclusion

Go back from the start and take a look at your code... no xml configuration?

Is your business logic a simple POJO?

Do you import something related to javax.servlet? Like HttpServletRequest?

Did you have to convert Strings to int?

Did you write any weird XML file which is non-human, but computer based?

Any view configuration?