When to use DiscriminatorValue annotation in hibernate

What and when is the best scenario to use DiscriminatorValue annotation in hibernate?

These 2 links help me understand the inheritance concept the most:

http://docs.oracle.com/javaee/6/tutorial/doc/bnbqn.html

http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html?page=6

To understand discriminator, first you must understand the inheritance strategies: SINGLE_TABLE, JOINED, TABLE_PER_CLASS.

Discriminator is commonly used in SINGLE_TABLE inheritance because you need a column to identify the type of the record.

Example: You have a class Student and 2 sub-classes: GoodStudent and BadStudent. Both Good and BadStudent data will be stored in 1 table, but of course we need to know the type and that's when (DiscriminatorColumn and) DiscriminatorValue will come in.

Annotate Student class

@Entity
@Table(name ="Student")
@Inheritance(strategy=SINGLE_TABLE)
@DiscriminatorColumn(discriminatorType = DiscriminatorType.STRING,
    name = "Student_Type")
public class Student{
     private int id;
     private String name;
}

Bad Student class

@Entity
@DiscriminatorValue("Bad Student")
public class BadStudent extends Student{ 
 //code here
}

Good Student class

@Entity
@DiscriminatorValue("Good Student")
public class GoodStudent extends Student{ 
//code here
}

So now the Student table will have a column named Student_Type and will save the DiscriminatorValue of the Student inside it.

-----------------------
id|Student_Type || Name |
--|---------------------|
1 |Good Student || Ravi |
2 |Bad Student  || Sham |
-----------------------

See the links I posted above.

Let me explain to you with an example . Suppose you have an class called Animal and under Animal class there are many subclasses like Reptile, Bird ...etc.

And in the database you have table called ANIMAL

---------------------------
ID||NAME      ||TYPE	 ||
---------------------------
1 ||Crocodile ||REPTILE  ||
---------------------------
2 ||Dinosaur  ||REPTILE  ||
---------------------------
3 ||Lizard    ||REPTILE  || 
---------------------------
4 ||Owl       ||BIRD     ||
---------------------------
5 ||parrot    ||BIRD     ||
---------------------------

Here the column TYPE is called DiscriminatorColumn , because this column contains data that clearly separates Reptiles and Birds. And the data REPTILE and BIRD in column TYPE are the DiscriminatorValue.

So in the java part this structure would look like :

Animal class:

@Getter
@Setter
@Table(name = "ANIMAL")
@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(discriminatorType = DiscriminatorType.STRING, name = "TYPE")
public class Animal {

    @Id
    @Column(name = "ID")
    private String id;

    @Column(name = "NAME")
    private String name;

}

Reptile class :

@Entity
@DiscriminatorValue("REPTILE")
public class Reptile extends Animal {

}

Bird class :

@Entity
@DiscriminatorValue("BIRD")
public class Bird extends Animal {

}

When you have an entity inheritance using the single table strategy, and you want the value of the discriminator column to be something other than the name of the class of the entity concrete class, or when the type of the discriminator column is not STRING.

This is explained, with an example, in the javadoc.

Here is the explanation and one example on hibernate table per class hierarchy, consider we have base class named Payment and 2 derived classes like CreditCard, Cheque

If we save the derived class object like CreditCard or Cheque then automatically Payment class object will also be saved into the database, and in the database all the data will be stored into a single table only, which is base class table for sure.

But here we must use one extra discriminator column in the database, just to identify which derived class object has been saved in the table along with the base class object, if we are not using this column hibernate will throw the exception