Entity Handler Standard Operations

This page gives a few examples of using the standard entity handler operations. Other concepts, such as excluding attributes and setting/getting attribute values are also shown.

Contents

get

The get method returns a single entity instance from persistent storage.

Examples:

Retrieve a complete entity instance from storage

Get a complete instance (including all detail views) of an entity:

//Get a reference to the entity handler for the PersonInfo entity         
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();        
                                                                          
//Create a new PersonInfo view to be used as a template for the get-method
PersonInfo person = new PersonInfo();                                     
                                                                          
//Set the primary key attribute value                                     
person.personId.setValue("ALEX");                                         
                                                                          
//Get the PersonInfo instance from the persistent storage                 
PersonInfo result = (PersonInfo) handler.get(person);

If the entity instance is not available, an exception is thrown.

Retrieve parts of an entity instance from storage

//Get a reference to the entity handler for the PersonInfo entity         
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();        
                                                                          
//Create a new PersonInfo view to be used as a template for the get-method
PersonInfo person = new PersonInfo();                                     
                                                                          
//Don't get person addresses                                              
person.addresses.exclude();                                               
                                                                          
//Set the primary key attribute value                                     
person.personId.setValue("ALEX");                                         
                                                                          
//Get the PersonInfo instance from the persistent storage                 
PersonInfo result = (PersonInfo) handler.get(person);

This has the same result as the previous example, except that the addresses array attribute will not contain any records, even if there are some addresses available. Fetching detail records (such as person addresses) and long attributes (such as BLOBs/CLOBs) is quite expensive and should be avoided if possible. Only include the attributes you really need.
 

A good design pattern is to always exclude all attributes first and then include the ones you really need:

PersonInfo person = new PersonInfo();           
                                                
//Exclude all attributes in the PersonInfo view 
person.excludeQueryResults();                   
                                                
//Include the attributes we need                 
person.personId.include();                      
person.name.include();                          
person.objVersion.include();                    

Note: As a side-effect, the input record passed to get method may be modified.

exist

The exist method checks if an entity instance exists in persistent storage.

Examples:

Check if a specific entity instance exists

This example checks if an instance of PersonInfo with the primary key (personId) "ALAIN" exists in storage.

//Get a reference to the entity handler for the PersonInfo entity
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

//Create a new PersonInfo view to be used as an input to the exist-method
PersonInfo person = new PersonInfo();

//Set the primary key attribute value
person.personId.setValue("ALAIN");

//Check if the PersonInfo instance exists in the persistent storage
if(handler.exist(person)) {
   System.out.println("The person exists");
}

bulkGet

The bulkGet method returns an array of entity instances, it should be used as a way to group multiple calls to the same entity get-method (you can get multiple instances in a single call).

The argument to the bulkGet method is an array. Each view in the array should have it's primary key attribute set. Include and exclude flags will be used from the first element only.

Examples:

Retrieve multiple entity instances in a single call

PersonInfo person1 = new PersonInfo();
PersonInfo person2 = new PersonInfo();

//Include only the attributes we need
person1.excludeQueryResults();
person1.personId.include();
person1.name.include();
person1.country.include();

//Set primary key value on the first person
person1.personId.setValue("ALEX");

//Set primary key value on the second person
person2.personId.setValue("ALAIN");

//Create an empty array and the two instances to the array
PersonInfoArray arr = new PersonInfoArray();
arr.add(person1); //include/exclude flags on the first element are important
arr.add(person2);

PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();
PersonInfoArray result = (PersonInfoArray) handler.bulkGet(arr);

Note: As a side-effect of bulkGet operation, the views contained in the input array may be modified.

prepare

The prepare method gets the default values for an LU entity view by calling the corresponding PL/SQL method New__ with parameter action = "PREPARE". The default values will be fetched for every record in the master-detail structure marked with the defaulting flag (see the example below). The standard prepare method called on a non-LU view does nothing.

Examples:

Get the default values for an LU entity

This example gets the default values for a new instance of PersonInfo entity.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

//Create a new instance of PersonInfo and set the defaulting flag on it
PersonInfo person = new PersonInfo();
person.defaulting(true);

//Get the default values from the database
handler.prepare(person);

//Now the PersonInfo instance contains the default values

save

The save method stores an entity instance in persistent storage. Depending on the entity view state, the entity instance will be created, modified or removed, which corresponds to INSERT, UPDATE and DELETE statements in a database. In case of an LU entity, save method delegates work to the entity's PL/SQL procedures New__, Modify__ and Remove__ respectively.

Examples:

Add a new entity instance to persistent storage

This example adds a new PersonInfo instance to storage.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

PersonInfo person = new PersonInfo(); //newly created views have state NEW_RECORD

person.personId.setValue("JOSMUS");
person.name.setValue("John Smith");
person.partyType.setValue(PartyTypeEnumeration.PERSON);
person.isProtected.setValue(true);
person.defaultDomain.setValue("TRUE");
person.creationDate.setValue(new java.util.Date());

//State of the PersonInfo (person) is NEW_RECORD at this point

//Save the person (create a new PersonInfo instance in the database)
handler.save(person);

//State of the PersonInfo (person) is QUERY_RECORD at this point

Modify an existing entity instance

This example gets a PersonInfo instance from storage, modifies it and then saves it.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

PersonInfo person = new PersonInfo();
person.personId.setValue("JOSMUS"); //Set primary key attribute value

//Get the PersonInfo instance from storage
PersonInfo result = (PersonInfo) handler.get(person);

//State of the returned PersonInfo (result) is QUERY_RECORD at this point

//Modify the title attribute value
result.title.setValue("Software Engineer");

//State of the PersonInfo (result) is MODIFIED_RECORD at this point

//Save (update) the PersonInfo instance in the database
handler.save(result);

//State of the PersonInfo (result) is QUERY_RECORD at this point

Delete an existing entity instance

This example gets a PersonInfo instance from storage, marks it for removal and then saves it.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

PersonInfo person = new PersonInfo();
person.personId.setValue("JOSMUS"); //Set primary key attribute value

//Include only the primary key, objId and objVerion (no details)
person.excludeQueryResults();
person.personId.include();
person.objId.include();
person.objVersion.include();

//Get the PersonInfo instance from the database
PersonInfo result = (PersonInfo) handler.get(person);

//Set state of the PersonInfo to REMOVED_RECORD
result.setState(FndRecordState.REMOVED_RECORD);

//Remove the PersonInfo entity (and its details) from the database
handler.save(result);

bulkSave

The bulkSave method saves multiple entity instances in a single call (similar to bulkGet). The array of entity instances to save may contain views of different states, REMOVED views will be saved first, then MODIFIED views and finally NEW views.

Examples:

Modify an existing instance and create a new instance

This example sends two instances of PersonInfo to bulkSave. The first one is a new instance filled with data. The second one is fetched by get operation and then modified.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

//New instance to save
PersonInfo person1 = new PersonInfo();
person1.personId.setValue("JOSMUS");
person1.name.setValue("John Smith");
person1.partyType.setValue(PartyTypeEnumeration.PERSON);
person1.isProtected.setValue(true);
person1.defaultDomain.setValue("TRUE");
person1.creationDate.setValue(new java.util.Date());

//Existing instance to modify
PersonInfo person2 = new PersonInfo();
person2.excludeQueryResults();
person2.personId.include();
person2.objId.include();
person2.objVersion.include();
person2.personId.setValue("ALAIN"); //Set primary key attribute value

//Get the PersonInfo instance from storage
person2 = (PersonInfo) handler.get(person2);

//Modify the title attribute value
person2.title.setValue("Software Engineer");

//Create an empty PersonInfo array and add the two instances
PersonInfoArray arr = new PersonInfoArray();
arr.add(person1);
arr.add(person2);

//Save both PersonInfo instances
handler.bulkSave(arr);

A new PersonInfo instance with personId "JOSMUS" will be added (inserted). The existing PersonInfo with personId "ALAIN" will have it's title attribute modified (updated).

batchSave

The batchSave method performs a query based on the condition record and updates every entity in the result set with the attribute values defined in the value record. This can also be used to remove set of entity instances queried based on the condition record. If so value record must be set to state REMOVED.

For native entity which consist of states, method contains additional third parameter to modify the entity state attribute.

For additional information and examples refer batchSave method under the "Using Cursors and Bulk Operations".

query

The query method is used to find multiple entity instances satisfying a query condition specified on the argument view. There are two kinds of query conditions - simple and advanced. Simple conditions are the same kind of condition used when calling the get method (setting a value on an attribute). When calling the get method, only the primary key attribute is used to form a condition, if, when calling query, multiple attributes have values, the result would be ANDs between the attribute conditions.

Example:
firstName set to "John", title set to "Software Engineer" would return all persons where both conditions are satisfied.

Advanced conditions can generate conditions other than the simple attribute-equals-value condition. Advanced and simple conditions can be used in combination as well.

The argument for the query method is a FndQueryRecord object. A FndQueryRecord contains an entity view (initialized in the constructor). Conditions are specified on the entity view, not the query record. FndQueryRecord also contains a few attributes that can be used to limit the number of rows returned, skip a few rows in the result set or sort the returned records. These attributes are primarily used by a client application but can also be set by business logic.

There are more information on the available query functionality. Only the basic principles will be shown here.

Examples:

Return all persons with default language "en" and title "Software Engineer"

Only simple conditions used in this example, condition values will be combined using AND.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

PersonInfo person = new PersonInfo();

//Set include/exclude flags
person.excludeQueryResults();
person.personId.include();
person.name.include();
person.title.include();
person.addresses.include();

//Set condition values
person.defaultLanguage.setValue("en");
person.title.setValue("Software Engineer");

//Create and initialize a FndQueryRecord
FndQueryRecord qry = new FndQueryRecord(person);

//Invoke the query method
PersonInfoArray arr = (PersonInfoArray) handler.query(qry);

Return all persons with default language "en" and title containing word "Engineer"

In order to create a like condition on a title attribute we need to use an advanced condition. We will use both simple and advanced conditions in this example.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

PersonInfo person = new PersonInfo();

//Set include/exclude flags
person.excludeQueryResults();
person.personId.include();
person.name.include();
person.title.include();
person.addresses.include();

//Set condition values
person.defaultLanguage.setValue("en");

//Create a LIKE condition on the title attribute
FndCondition cond = person.title.createLikeCondition("%Engineer%");

//FndCondition is simply an object representing a condition.
//This condition will not be used as long as it is not added to the view

//Add the condition to the PersonInfo view
person.addCondition(cond);

//Create and initialize a FndQueryRecord
FndQueryRecord qry = new FndQueryRecord(person);

//Invoke the query method
PersonInfoArray arr = (PersonInfoArray) handler.query(qry);

Note: As a side-effect of query operation, the entity view contained in the query record may be modified.

queryCursor

The queryCursor method is used in the same way as the normal query method, but without having to read the entire result set from the database in one go. Using  queryCursor method may reduce memory consumption significantly in certain cases.

Example:
Make a 'comma' separated string of all persons in the database.

The argument for the queryCursor method is a FndQueryRecord object. A FndQueryRecord contains an entity view (initialized in the constructor). Conditions are specified on the entity view, not the query record. queryCursor returns a cursor or pointer to the current view (entity instance) in the result set. The cursor's next method is used to iterate over entity instances in the result set

Examples:

Make a 'comma' separated string of all persons in the database

No conditions used in this example. But this method behave same as the standard query method as described in this document.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

PersonInfo person = new PersonInfo();

//Set include/exclude flags
person.excludeQueryResults();
person.name.include();

//Create and initialize a FndQueryRecord
FndQueryRecord qry = new FndQueryRecord(person);

//Invoke the query cursor method
PersonInfoCursor cursor = handler.queryCursor(qry);
PersonInfo p = null;
StringBuffer str = new StringBuffer();

//Loop over person cursor and append person name to the str
while((p = cursor.next() != null){
   if(str.length>0)
      str.append(", ");
   str.append(p.name.getValue());
}
cursor.close();

Note: As a side-effect of queryCursor operation, the entity view contained in the query record may be modified

Just like for the standard query operation, FndQueryRecord's attribute orderBy may be used to control the ordering of returned records. It may be set directly or via setOrderBy method. Note however that two other attributes of FndQueryRecord: skipRows and maxRows are ignored by queryCursor operation.

Note also the following limitation of orderBy functionality in queryCursor. The standard query operation sorts records in memory if the sorting cannot be performed in SQL. It happens when orderBy clause contains a joined attribute and join cannot be used because of custom storage implementation. queryCursor cannot sort records, because it returns one record at a time. So remember: If you define an orderBy that cannot be implemented in SQL then queryCursor  will throw an exception at runtime. See description for class FndQueryRecord for more details about using setOrderBy and sorting on joined attributes (attributes contained in aggregated detail records).

populate

The populate method populates an entity with data. It retrieves from storage included parts of a view structure. The method is quite similar to get. Typically it is called directly from a client application, which retrieves from the database only needed parts of a master-detail hierarchy.

Examples:

Populate an entity detail with data

This example gets an instance of PersonInfo without details. Then populate is called to fetch the person addresses.

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

//Create a new PersonInfo view to be used as a template for the get-method
PersonInfo person = new PersonInfo();
person.excludeQueryResults();
person.objId.include();
person.objVersion.include();
person.personId.include();
person.name.include();

//Set the primary key attribute value
person.personId.setValue("ALEX");

//Get the PersonInfo instance from the persistent storage (without details)
person = (PersonInfo) handler.get(person);

//Set include flag on the addresses array only
person.excludeQueryResults();
person.addresses.include();

//Populate the addresses array with data
person = (PersonInfo) handler.populate(person);

Note: As a side-effect, the input record passed to populate method may be modified.

importEntity

The importEntity operation recreates an entity structure previously fetched from the database by get or query. The operation is similar to save working on NEW records. Only importable entities may be imported. An importable entity is an entity that has a standard storage operation of type Import generated from the model. Before importing an entity the previous version the entity, if any, must be removed explicitly.

Typically an entity master-detail structure is exported by saving it to an XML file. Then the whole structure is recreated, in the same or another database, by calling importEntity.

Note: If an entity has a state diagram then importEntity will properly recreate the entity state only if this entity is a non-LU entity.

Examples:

Get, remove and import an entity instance

This example gets an instance of PersonInfo including details and stores it in a temporary variable. Then the instance is removed from the database. Finally the stored instance is imported (recreated).

//Get a reference to the entity handler for PersonInfo
PersonInfoHandler handler = PersonInfoHandlerFactory.getHandler();

//Get a PersonInfo instance from database
PersonInfo person = new PersonInfo();
person.personId.setValue("JOSMUS"); //Set primary key attribute value
person = (PersonInfo) handler.get(person);

//Store a copy the fetched entity structure
PersonInfo exported = (PersonInfo) person.clone();

//Remove the PersonInfo entity (and its details) from the database
person.setState(FndRecordState.REMOVED_RECORD);
handler.save(person);

//Now import the exported instance of PersonInfo
handler.importPerson(exported);