Previously known as Value Object

Some entities contain a group of attributes that are always accessed together. Accessing these attributes in a fine-grained manner through a remote interface causes network traffic and high latency, and consumes server resources unnecessarily.

A transfer object is a serializable class that groups related attributes, forming a composite value. This class is used as the return type of a remote business method. Clients receive instances of this class by calling coarse-grained business methods, and then locally access the fine-grained values within the transfer object. Fetching multiple values in one server roundtrip decreases network traffic and minimizes latency and server resource usage.

See the Core J2EETM Patterns

• The OrderDetails and OrdersTO transfer objects.

  • Sample application class OPCAdminFacade (see Session Facade) has a method getChartInfo that returns an immutable, serializable collection of OrderDetails objects, each of which is a transfer object that represents data from an order. The collection returned by method getChartInfo is also a transfer object, because the values it contains are always accessed together where they are used. This hierarchical transfer object is implemented by class OrdersTO .

    Figure 1 shows the structure of the OrdersTO transfer object. Class MutableOrdersTO, which extends a serializable ArrayList, contains a collection of OrderDetails objects. But because MutableOrdersTO extends ArrayList, it is mutable. Transfer objects should be immutable so that clients do not unintentionally change their contents. Interface OrdersTO adapts the MutableOrdersTO collection, allowing read-only access to the collection while preventing modifications.

    Figure 1. Transfer object OrdersTO is an immutable, serializable collection

    The definition of the OrdersTO interface follows.

                    
    public interface OrdersTO extends Serializable {
        
        public Iterator iterator();
        public int size();
        public boolean contains(Object o);
        public boolean containsAll(Collection c);
        public boolean equals(Object o);
        public int hashCode();
        public boolean isEmpty();
        public Object[] toArray();
        public Object[] toArray(Object[] a);
    
        static class MutableOrdersTO extends ArrayList implements OrdersTO {
        }
    }
                  

    The OrdersTO interface is clearly a collection, since it defines the Java collection methods. The collection is immutable, because it has no methods that would allow the collection contents to be changed.

    An example of using OrdersTO appears in method OPCAdminFacadeEJB.getOrdersByStatus, shown below. The method constructs a OrdersTO.MutableOrdersTO object and populates it with OrderDetails instances. Note that the return type of getOrdersByStatus is OrdersTO, so callers can access only methods that read the collection contents, and not methods that would change them.

                    
    
    public OrdersTO getOrdersByStatus(String status) 
       throws OPCAdminFacadeException {
    
        OrdersTO.MutableOrdersTO retVal = new OrdersTO.MutableOrdersTO();
        PurchaseOrderLocal po;
        ProcessManagerLocal mgr = getProcMgr();
    
        try {            
            PurchaseOrderLocalHome pohome = getPO();
            Collection orders = mgr.getOrdersByStatus(status);
            Iterator it = orders.iterator();
            while((it!= null) && (it.hasNext())) {
                ... // Access and format data
                retVal.add(new OrderDetails(po.getPoId(), po.getPoUserId(),
                                            podate, po.getPoValue(), status));
            }
        } catch (FinderException fe) {
           ... // process exception
        } 
        return(retVal);
    }
    
                  

  • The details for a single order are contained in an immutable, serializable transfer object of type OrderDetails. It is a typical transfer object for a single composite value, containing private fields and public, read-only property accessors, as shown in the following code sample.

                    
    
    public class OrderDetails implements java.io.Serializable {
    
        private String orderId;
        private String userId;
        private String orderDate;
        private float orderValue;
        private String orderStatus;
    
        public OrderDetails(String oid, String uid, String date, float value,
                            String stat) {
            orderId = oid;
            userId = uid;
            orderDate = date;
            orderValue = value;
            orderStatus = stat;
        }
    
        public String getOrderId() {
            return(orderId);
        }
    
        // ...
    }