Product overview > Tutorials, examples, and samples > Entity manager tutorial

Entity manager tutorial: Order Entity Schema

Create four entity classes by using both single and bidirectional relationships, ordered lists, and foreign key relationships. The EntityManager APIs are used to persist and find the entities. Building on the Order and Customer entities that are in the previous parts of the tutorial, this tutorial step adds two more entities: the Item and OrderLine entities.

Figure 1. Order Entity Schema. An Order entity has a reference to one customer and zero or more OrderLines. Each OrderLine entity has a reference to a single item and includes the quantity ordered.


  1. Create the customer entity, which is similar to the previous examples.
    public class Customer
        @Id String id;
        String firstName;
        String surname;
        String address;
        String phoneNumber;

  2. Create the Item entity, which holds information about a product that is included in the store's inventory, such as the product description, quantity, and price.
    public class Item
        @Id String id;
        String description;
        long quantityOnHand;
        double price;

  3. Create the OrderLine entity. Each Order has zero or more OrderLines, which identify the quantity of each item in the order. The key for the OrderLine is a compound key that consists of the Order that owns the OrderLine and an integer that assigns the order line a number. Add the cascade persist modifier to every relationship on your entities.
    public class OrderLine
        @Id @ManyToOne(cascade=CascadeType.PERSIST) Order order;
        @Id int lineNumber;
        @OneToOne(cascade=CascadeType.PERSIST) Item item;
        int quantity;
        double price;

  4. Create the final Order Object, which has a reference to the Customer for the order and a collection of OrderLine objects.
    public class Order
        @Id String orderNumber;
        java.util.Date date;
        @ManyToOne(cascade=CascadeType.PERSIST) Customer customer;
        @OneToMany(cascade=CascadeType.ALL, mappedBy="order") 
                @OrderBy("lineNumber") List<OrderLine> lines; 

    The cascade ALL is used as the modifier for lines. This modifier signals the EntityManager to cascade both the PERSIST operation and the REMOVE operation. For example, if the Order entity is persisted or removed, then all OrderLine entities are also persisted or removed.

    If an OrderLine entity is removed from the lines list in the Order object, the reference is then broken. However, the OrderLine entity is not removed from the cache. You must use the EntityManager remove API to remove entities from the cache. The REMOVE operation is not used on the customer entity or the item entity from OrderLine. As a result, the customer entity remains even though the order or item is removed when the OrderLine is removed.

    The mappedBy modifier indicates an inverse relationship with the target entity. The modifier identifies which attribute in the target entity references the source entity, and the owning side of a one-to-one or many-to-many relationship. Typically, you can omit the modifier. However, an error is displayed to indicate that it must be specified if WebSphere eXtreme Scale cannot discover it automatically. An OrderLine entity that contains two of type Order attributes in a many-to-one relationship typically causes the error.

    The @OrderBy annotation specifies the order in which each OrderLine entity should be in the lines list. If the annotation is not specified, then the lines display in an arbitrary order. Although the lines are added to the Order entity by issuing ArrayList, which preserves the order, the EntityManager does not necessarily recognize the order. When you issue the find method to retrieve the Order object from the cache, the list object is not an ArrayList object.

  5. Create the application. The following example illustrates the final Order object, which has a reference to the Customer for the order and a collection of OrderLine objects.

    1. Find the Items to order, which then become Managed entities.

    2. Create the OrderLine and attach it to each Item.

    3. Create the Order and associate it with each OrderLine and the customer.

    4. Persist the order, which automatically persists each OrderLine.

    5. Commit the transaction, which detaches each entity and synchronizes the state of the entities with the cache.

    6. Print the order information. The OrderLine entities are automatically sorted by the OrderLine ID.
    static public void main(String [] args)
            throws Exception
            // Add some items to our inventory.
            // Create a new customer with the items in his cart.
            Customer cust = createCustomer();
            // Create a new order and add an order line for each item.
            // Each line item is automatically persisted since the 
                    // Cascade=ALL option is set.
            Order order = createOrderFromItems(em, cust, "ORDER_1", 
                        new String[]{"1", "2"}, new int[]{1,3});
            // Print the order summary
            order = (Order)em.find(Order.class, "ORDER_1");
        public static Customer createCustomer() {
            Customer cust = new Customer();
            cust.address = "Main Street";
            cust.firstName = "John";
            cust.surname = "Smith";
   = "C001";
            cust.phoneNumber = "5555551212";
            return cust;
        public static void createItems(EntityManager em) {
            Item item1 = new Item();
   = "1";
            item1.price = 9.99;
            item1.description = "Widget 1";
            item1.quantityOnHand = 4000;
            Item item2 = new Item();
   = "2";
            item2.price = 15.99;
            item2.description = "Widget 2";
            item2.quantityOnHand = 225;
        public static Order createOrderFromItems(EntityManager em, 
                Customer cust, String orderId, String[] itemIds, int[] qty) {
            Item[] items = getItems(em, itemIds);
            Order order = new Order();
            order.customer = cust;
   = new java.util.Date();
            order.orderNumber = orderId;
            order.lines = new ArrayList<OrderLine>(items.length);          
                 for(int i=0;i<items.length;i++){
                            OrderLine line = new OrderLine();
                line.lineNumber = i+1;
                line.item = items[i];
                line.price = line.item.price;
                line.quantity = qty[i];
                line.order = order;
            return order;
        public static Item[] getItems(EntityManager em, String[] itemIds) {
            Item[] items = new Item[itemIds.length];
            for(int i=0;i<items.length;i++){
                 items[i] = (Item) em.find(Item.class, itemIds[i]);
            return items;

    The next step is to delete an entity. The EntityManager interface has a remove method that marks an object as deleted. The application should remove the entity from any relationship collections before calling the remove method. Edit the references and issue the remove method, or em.remove(object), as a final step.

Parent topic:

Entity manager tutorial: Overview

Previous topic:

Entity manager tutorial: Forming entity relationships

Next topic:

Entity manager tutorial: Updating entries