| Foundation1 / Development Guide / Core Server / Services Layer Dev / Mechanisms / Entity Handler 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.
The get method returns a single entity instance from persistent 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.
//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.
The exist method checks if an entity instance exists in persistent storage.
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"); }
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.
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.
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.
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
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.
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
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
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);
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.
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).
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".
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.
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);
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.
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
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).
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.
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.
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.
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);
