See the WebSphere eXtreme Scale Wiki for links to eXtreme Scale Version 7.0 documentation.
If you log in with your developerWorks ID, you can leave comments and feedback for the development team.

This tutorial illustrates how to develop a local, in-memory ObjectGrid that stores order information for an online retail store.

Step 3 demonstrates how to 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 these entities. Building on the Order and Customer entities that are featured in step 2, this step adds two more entities:

• Item
• OrderLine

As illustrated in the following graphic, 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.

Order Entity Schema

The following sections provide examples of the code for each entity:

Customer object

The following example illustrates the Customer entity, which is basically similar to the example that is featured in step 2:

@Entity
public class Customer
{
    @Id String id;
    String firstName;
    String surname;
    String address;
    String phoneNumber;
}

Item object

An Item holds information about a orderable product that is included in the store's inventory, such as the product description, quantity, and price.

@Entity
public class Item
{
    @Id String id;
    String description;
    long quantityOnHand;
    double price;
}

OrderLine object

The following example illustrates the OrderLine entity:

@Entity
public class OrderLine
{
    @Id @ManyToOne(cascade=CascadeType.PERSIST) Order order;
    @Id int lineNumber;
    @OneToOne(cascade=CascadeType.PERSIST) Item item;
    int quantity;
    double price;
}

Every Order now has zero or more OrderLines, which simply identifies the quantity of the item in the order. The key for the OrderLine is a compound key that consists of the Order that owns it and an integer numbering the order line. Add the cascade persist modifier to every relationship on your entities.

Order object

The following example illustrates the final Order object, which now has a reference to the Customer for the order and a collection of OrderLines.

@Entity
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 instance, if the Order entity is persisted or removed, then all OrderLine entities will also be 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 ObjectGrid cannot discover it automatically. An OrderLine entity that contains two of type Order attributes in a many-to-one relationship usually causes the error.

The @OrderBy annotation specifies the order in which each OrderLine entity should appear in the lines list. If 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.

Application

This example illustrates how to persist two Item entities in the inventory and create a customer. An Order object for the customer and two OrderLine entities, each with a reference to a different Item entity, is then created. The references for each Item entity are included in the following list:

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.
        em.getTransaction().begin();
        createItems(em);
        em.getTransaction().commit();

        // Create a new customer with the items in his cart.
        em.getTransaction().begin();
        Customer cust = createCustomer();
        em.persist(cust);

        // 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});
        em.persist(order);
        em.getTransaction().commit();

        // Print the order summary
        em.getTransaction().begin();
        order = (Order)em.find(Order.class, "ORDER_1");
        System.out.println(printOrderSummary(order));
        em.getTransaction().commit();
    }

    public static Customer createCustomer() {
        Customer cust = new Customer();
        cust.address = "Main Street";
        cust.firstName = "John";
        cust.surname = "Smith";
        cust.id = "C001";
        cust.phoneNumber = "5555551212";
        return cust;
    }

    public static void createItems(EntityManager em) {
        Item item1 = new Item();
        item1.id = "1";
        item1.price = 9.99;
        item1.description = "Widget 1";
        item1.quantityOnHand = 4000;
        em.persist(item1);

        Item item2 = new Item();
        item2.id = "2";
        item2.price = 15.99;
        item2.description = "Widget 2";
        item2.quantityOnHand = 225;
        em.persist(item2);

    }

    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;
        order.date = 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;
            order.lines.add(line);
        }
        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.

Previous Step Next Step

Wiki Disclaimer and License

© Copyright IBM Corporation 2007,2009. All Rights Reserved.