Quick start

Also available in Spanish.

Install the needed tools

Download and install OpenXava (if not yet installed):
Download and install the JDK (if not yet installed):
Download and install Eclipse (if not yet installed):

Configure Tomcat

You have to indicate Tomcat where you have installed the JDK.
With Windows, add the next line at the beginning of catalina.bat in tomcat\bin folder:
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_45
Don't put C:\Program Files\Java\jdk1.8.0_45 put the real path where the JDK is installed in your system.
With Linux or Mac, add the next line at the beginning of catalina.sh in tomcat/bin folder:
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk
Don't put /usr/lib/jvm/java-8-openjdk put the real path where the JDK is installed in your system.

Start Tomcat

Start Tomcat, with Windows just double click on startup.bat of tomcat\bin:
quick-start_en020.png
If you use Linux or Mac run startup.sh located in the tomcat/bin folder of OpenXava:
quick-start_en030.png

Start Eclipse

Start Eclipse, it will ask you to choose the workspace, choose the one included in OpenXava:
quick-start_en010.png
If you already have Eclipse started use the option File >Switch Workspace. If you're using an old version of Eclipse it will ask you "Workspace ... was written with a newer version of the product and can be incompatible with this version. If you continue, this can cause unexpected behavior or data loss", don't worry, just click on OK.

Execute the example application

The OpenXava distribution comes with an example application called MySchool, in order to execute it follow the next steps.
Build and deploy the project:
quick-start_en040.png
Go to http://localhost:8080/MySchool/modules/Teacher using your browser to see the application in action:
quick-start_en050.png

Add another class

Add a new class to MySchool project:
quick-start_en060.png
Then type Pupil for the class name:
quick-start_en070.png
Copy the code below into your Pupil class:
package org.openxava.school.model;
 
import javax.persistence.*;
import org.openxava.annotations.*;
 
@Entity
public class Pupil {
 
    @Id @Column(length=2) @Required
    private int number;
 
    @Column(length=40) @Required
    private String name;
 
    public int getNumber() {
        return number;
    }
 
    public void setNumber(int number) {
        this.number = number;
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
}
Now we can deploy it:
quick-start_en040.png
Go to http://localhost:8080/MySchool/modules/Pupil to see Pupil in action:
quick-start_en080.png

Add a teacher reference to pupil

It is easy to make a pupil to have a reference to a teacher. Add the next code to Pupil class :
public class Pupil {
 
    ...
 
    // BEGIN CODE TO ADD
    @ManyToOne
    private Teacher teacher;
 
    public Teacher getTeacher() {
        return teacher;
    }
 
    public void setTeacher(Teacher teacher) {
        this.teacher = teacher;
    }
    // END CODE TO ADD
 
}
Deploy it:
quick-start_en040.png
Go to http://localhost:8080/MySchool/modules/Pupil and select detail mode:
quick-start_en090.png

Show teacher reference as a combo

If you want the reference to be displayed in combo format, you should add @DescriptionsList to teacher reference in Pupil, as following:
public class Pupil {
 
    ...
 
    @DescriptionsList // ADD THIS
    @ManyToOne
    private Teacher teacher;
 
    ...
 
}
Now deploy again:
quick-start_en040.png
Go to http://localhost:8080/MySchool/modules/Pupil:
quick-start_en100.png

Add a collection of pupils to teacher

Let's put a pupils collection in teacher. Put the collection declaration inside the Teacher class:
public class Teacher {
 
    ...
 
    // BEGIN CODE TO ADD
    @OneToMany(mappedBy="teacher")
    private Collection<Pupil> pupils;
 
    public Collection <Pupil> getPupils() {
        return pupils;
    }
 
    public void setPupils(Collection <Pupil> pupils) {
        this.pupils = pupils;
    }
    // END CODE TO ADD
 
}
And deploy again:
quick-start_en040.png
Go to http://localhost:8080/MySchool/modules/Teacher:
quick-start_en110.png

Create your own project

Well done! You have executed and modified and already existing project. Now you should create your own OpenXava project from scratch:

Follow the lesson: Getting started

Any problem with this guide? Ask in the help forum.