7.8 Working Programmatically with Entity-Based View Objects

From the point of view of a client accessing your application module's data model, the API's to work with a read-only view object and an entity-based view object are identical. The key functional difference is that entity-based view objects allow the data in a view object to be fully updatable. The application module that contains the entity-based view objects defines the unit of work and manages the transaction. This section presents four simple test client programs that work with the SRService application module to illustrate:

Iterating master/detail/detail hierarchy
Finding a row and updating a foreign key value
Creating a new service request
Retrieving the row Key identifying a row

7.8.1 Example of Iterating Master/Detail/Detail Hierarchy

Example 7-1 performs the following basic steps:

Finds the StaffList view object instance
Executes the query
Iterate over the resulting StaffList rows
Print the staff member's full name by getting the value of the calculated FullName attribute
Get related row set of ServiceRequests using a view link accessor attribute
Iterate over the ServiceRequests rows
Print out some service request attribute values
If the status is not Closed, then get the related row set of ServiceHistories using a view link accessor attribute
Iterate over the ServiceHistories rows
Print out some service request history attributes

Note:

Other than having one additional level of nesting, this example uses the same API's that you saw in the TestClient2 program that was iterating over master/detail read-only view objects in Section 5.10.4.2, "How to Access a Detail Collection Using the View Link Accessor".

Example 7-1 Iterating Master/Detail/Detail Hierarchy

package devguide.client;
import oracle.jbo.ApplicationModule;
import oracle.jbo.Row;
import oracle.jbo.RowSet;
import oracle.jbo.ViewObject;
import oracle.jbo.client.Configuration;
public class TestClient {
  public static void main(String[] args) {
    String        amDef = "devguide.model.SRService";
    String        config = "SRServiceLocal";
    ApplicationModule am =
      Configuration.createRootApplicationModule(amDef,config);
    // 1. Find the StaffList view object instance.
    ViewObject staffList = am.findViewObject("StaffList");
    // 2. Execute the query
    staffList.executeQuery();
    // 3. Iterate over the resulting rows
    while (staffList.hasNext()) {
      Row staffMember = staffList.next();
      // 4. Print the staff member's full name
      System.out.println("Staff Member: "+staffMember.getAttribute("FullName"));
      // 5. Get related rowset of ServiceRequests using view link accessor
      RowSet reqs = (RowSet)staffMember.getAttribute("ServiceRequests");
      // 6. Iterate over the ServiceRequests rows
      while (reqs.hasNext()) {
        Row svcreq = reqs.next();
        // 7. Print out some service request attribute values
        System.out.println(" ["+svcreq.getAttribute("Status")+"] "+
                               svcreq.getAttribute("SvrId")+": "+
                               svcreq.getAttribute("ProblemDescription"));
        if(!svcreq.getAttribute("Status").equals("Closed")) {
          // 8. Get related rowset of ServiceHistories
          RowSet hists = (RowSet)svcreq.getAttribute("ServiceHistories");
          // 9. Iterate over the ServiceHistories rows
          while (hists.hasNext()) {
            Row hist = hists.next();
            // 10. Print out some service request history attributes
            System.out.println("  "+hist.getAttribute("LineNo")+": "+
                               hist.getAttribute("Notes"));
          }          
        }
      }
    }
    Configuration.releaseRootApplicationModule(am,true);
  }  
}

Running the program produces the following output:

Staff Member: David Austin
 [Open] 104: Spin cycle not draining
  1: Researching issue
Staff Member: Bruce Ernst
 [Closed] 101: Agitator does not work
 [Pending] 102: Washing Machine does not turn on
  1: Called customer to make sure washer was plugged in...
  2: We should modify the setup instructions to include...
 [Open] 108: Freezer full of frost
  1: Researching issue
Staff Member: Alexander Hunold
 [Closed] 100: I have noticed that every time I do a...
 [Closed] 105: Air in dryer not hot
   :

7.8.2 Example of Finding a Row and Updating a Foreign Key Value

Example 7-2 performs the following basic steps:

Finds the ServiceRequests view object instance
Constructs a Key object to look up the row for service request number 101
Uses findByKey() to find the row
Prints some service request attribute values
Tries to assign the illegal value Reopened to the Status attribute

Since view object rows cooperate with entity objects, the validation rule on the Status attribute throws an exception, preventing this illegal change.
Sets the Status to a legal value of Open
Prints the value of the Status attribute to show it was updated successfully
Prints the current value of the assigned technician's email
Reassigns the service request to technician number 303 (Alexander Hunold) by setting the AssignedTo attribute
Shows the value of the reference information (TechnicianEmail) reflecting a new technician
Cancels the transaction by issuing a rollback

Example 7-2 Finding and Updating a Foreign Key Value

package devguide.client;
import oracle.jbo.ApplicationModule;
import oracle.jbo.JboException;
import oracle.jbo.Key;
import oracle.jbo.Row;
import oracle.jbo.ViewObject;
import oracle.jbo.client.Configuration;
public class TestFindAndUpdate {
  public static void main(String[] args) {
    String        amDef = "devguide.model.SRService";
    String        config = "SRServiceLocal";
    ApplicationModule am =
      Configuration.createRootApplicationModule(amDef,config);
    // 1. Find the ServiceRequests view object instance
    ViewObject vo = am.findViewObject("ServiceRequests");
    // 2. Construct a new Key to find ServiceRequest# 101
    Key svcReqKey = new Key(new Object[]{101});
    // 3. Find the row matching this key 
    Row[] reqsFound = vo.findByKey(svcReqKey,1);
    if (reqsFound != null && reqsFound.length > 0) {
      Row svcReq = reqsFound[0];
      // 4. Print some service request information
      String curStatus = (String)svcReq.getAttribute("Status");
      System.out.println("Current status is: "+curStatus);
      try {
        // 5. Try setting the status to an illegal value
        svcReq.setAttribute("Status","Reopened");
      }
      catch (JboException ex) {
        System.out.println("ERROR: "+ex.getMessage());
      }
      // 6. Set the status to a legal value
      svcReq.setAttribute("Status","Open");
      // 7. Show the value of the status was updated successfully
      System.out.println("Current status is: "+svcReq.getAttribute("Status"));
      // 8. Show the current value of the assigned technician
      System.out.println("Assigned: "+svcReq.getAttribute("TechnicianEmail"));
      // 9. Reassign the service request to technician # 303
      svcReq.setAttribute("AssignedTo",303); // Alexander Hunold (technician)
      // 10. Show the value of the reference info reflects new technician
      System.out.println("Assigned: "+svcReq.getAttribute("TechnicianEmail"));
      // 11. Rollback the transaction
      am.getTransaction().rollback();
      System.out.println("Transaction cancelled");      
    }
    Configuration.releaseRootApplicationModule(am,true);
  }  
}

Running this example produces the following output:

Current status is: Closed
ERROR: The status must be Open, Pending, or Closed
Current status is: Open
Assigned: bernst
Assigned: ahunold
Transaction cancelled

7.8.3 Example of Creating a New Service Request

Example 7-3 performs the following basic steps:

Find the ServiceRequests view object instance
Creates a new row and inserts it into the row set
Shows the effect of entity object related defaulting for Status attribute
Sets values of some required attributes in the new row
Commits the transaction
Retrieves and displays the trigger-assigned service request ID

Example 7-3 Creating a New Service Request

package devguide.client;
import java.sql.Timestamp;
import oracle.jbo.ApplicationModule;
import oracle.jbo.Row;
import oracle.jbo.ViewObject;
import oracle.jbo.client.Configuration;
import oracle.jbo.domain.DBSequence;
import oracle.jbo.domain.Date;
public class TestCreatingServiceRequest {
  public static void main(String[] args) throws Throwable {
    String amDef = "devguide.model.SRService";
    String config = "SRServiceLocal";
    ApplicationModule am =
      Configuration.createRootApplicationModule(amDef, config);
    // 1. Find the ServiceRequests view object instance.
    ViewObject svcReqs = am.findViewObject("ServiceRequests");
    // 2. Create a new row and insert it into the row set
    Row newSvcReq = svcReqs.createRow();
    svcReqs.insertRow(newSvcReq);
    // 3. Show effect of entity object defaulting for Status attribute
    System.out.println("Status defaults to: "+newSvcReq.getAttribute("Status"));
    // 4. Set values for some of the required attributes
    newSvcReq.setAttribute("CreatedBy",308); // Nancy Greenberg (user) 
    Date now = new Date(new Timestamp(System.currentTimeMillis()));
    newSvcReq.setAttribute("RequestDate",now);
    newSvcReq.setAttribute("ProdId",119); // Ice Maker
    newSvcReq.setAttribute("ProblemDescription","Cubes melt immediately");
    // 5. Commit the transaction
    am.getTransaction().commit();
    // 6. Retrieve and display the trigger-assigned service request id
    DBSequence id = (DBSequence)newSvcReq.getAttribute("SvrId");
    System.out.println("Thanks, reference number is "+id.getSequenceNumber());
    Configuration.releaseRootApplicationModule(am, true);
  }
}

Running this example produces the following results:

Status defaults to: Open
Thanks, reference number is 200

7.8.4 Example of Retrieving the Row Key Identifying a Row

Example 7-4 performs the following basic steps:

Finds the ServiceRequests view object
Constructs a key to find service request number 101
Finds the ServiceRequests row with this key
Displays the key of the ServiceRequests row
Accesses the row set of ServiceHistories using the view link accessor attribute
Iterates overs the ServiceHistories row
Displays the key of each ServiceHistories row

Example 7-4 Retrieving the Row Key Identifying a Row

package devguide.client;
import oracle.jbo.ApplicationModule;
import oracle.jbo.Key;
import oracle.jbo.Row;
import oracle.jbo.RowSet;
import oracle.jbo.ViewObject;
import oracle.jbo.client.Configuration;
public class TestFindAndShowKeys {
  public static void main(String[] args) {
    String amDef = "devguide.model.SRService";
    String config = "SRServiceLocal";
    ApplicationModule am =
      Configuration.createRootApplicationModule(amDef, config);
    // 1. Find the ServiceRequests view object
    ViewObject vo = am.findViewObject("ServiceRequests");
    // 2. Construct a key to find service request number 101
    Key svcReqKey = new Key(new Object[] { 101 });
    // 3. Find the ServiceRequests row with this key
    Row[] reqsFound = vo.findByKey(svcReqKey, 1);
    if (reqsFound != null && reqsFound.length > 0) {
      Row svcReq = reqsFound[0];
      // 4. Display the key of the ServiceRequests row
      showKeyFor(svcReq);
      // 5. Access row set of ServiceHistories using view link accessor
      RowSet histories = (RowSet)svcReq.getAttribute("ServiceHistories");
      // 6. Iterate over the ServiceHistories row
      while (histories.hasNext()) {
        Row historyRow = histories.next();
        // 7. Display the key of the current ServiceHistories row
        showKeyFor(historyRow);
      }
    }
    Configuration.releaseRootApplicationModule(am, true);
  }
  private static void showKeyFor(Row r) {
    // get the key for the row passed in
    Key k = r.getKey();
    // format the key as "(val1,val2)"
    String keyAttrs=formatKeyAttributeNamesAndValues(k);
    // get the serialized string format of the key, too
    String keyStringFmt = r.getKey().toStringFormat(false);
    System.out.println("Key "+keyAttrs+" has string format "+keyStringFmt);
  }
  // Build up "(val1,val2)" string for key attributes
  private static String formatKeyAttributeNamesAndValues(Key k) {
    StringBuffer sb = new StringBuffer("(");
    int attrsInKey = k.getAttributeCount();
    for (int i = 0; i < attrsInKey;i++) {
      if (i > 0 ) sb.append(",");
      sb.append(k.getAttributeValues()[i]);
    }
    sb.append(")");
    return sb.toString();
  }
}

Running the example produces the following results. Notice that the serialized string format of a key is a hexadecimal number that includes information in a single string that represents all the attributes in a key.

Key (101) has string format 000100000003313031
Key (101,1) has string format 000200000003C2020200000002C102
Key (101,2) has string format 000200000003C2020200000002C103