Handling the Create verb
When the business object handler obtains a Create verb
from the request business object, it must ensure that a new application
entity, whose type is indicated by the business object definition,
is created, as follows:
- For a flat
business object, the Create verb indicates that the specified entity
must be created.
- For a hierarchical
business object, the Create verb indicates that one or more application
entities (to match the entire business object) must be created.
The business object handler must set all the values in the new
application entities to the attribute values in the request business
object. To ensure that all required attributes in the request business
object have values assigned, you can call the initAndValidateAttributes() method, which assigns the attribute's default value
to each required attribute that does not have its value set (when
the UseDefaults connector configuration property is set to true). The initAndValidateAttributes() method is defined in the CWConnectorUtil class. Call initAndValidateAttributes() before performing the Create operation
in the application.
Note:
For a table-based application, the entire application
entity must be created in the
application
database, usually as a new row to the database table associated
with the business object definition of the request business object.
This section provides the following information to help process
a Create verb:
Note:
You can modularize your business object handler
so that each supported verb is handled in a separate Java method.
If you follow this structure, a Create method handles processing
for the Create verb.
Standard processing for a Create verb
The following steps outline the standard processing for
a Create verb:
- Create the application entity corresponding to the top-level
business object.
- Handle the primary key
or keys for the application entity:
- If the application generates its own primary key (or keys),
get these key values for insertion in the top-level business object.
- If the application does not generate
its own primary key (or keys), insert the key values from the request
business object into the appropriate key column (or columns) of
the application entity.
- Set foreign
key attributes in any first-level child business objects to the value
of the top-level primary key.
- Recursively create the application entities corresponding to
the first-level child business objects, and continue recursively
creating all child business objects at all subsequent levels in
the business object hierarchy.
In Figure 28,, a verb
method sets the foreign key attributes (FK) in child business objects
A, B, and C to the value of the top-level primary key (PK1). The method
then recursively sets the foreign key attributes in child business
objects D and E to the value of the primary key (PK3) in their parent
business object, object B.
Figure 28. Creating parent/child relationships
Implementation of a Create verb operation
A typical implementation of a Create operation first traverses
the top-level business object and processes the business object's
simple attributes. It gets the values of the attributes from the
business object and generates the application-specific action (such
as an API call or SQL statement) that inserts an entity in the application to
represent the top-level business object. Once this top-level entity
is created, the verb operation takes the following steps:
- Retrieve any primary keys for the entity from the application.
- Use the keys to set the foreign
key attributes in the first-level child business objects to the
value of the parent primary keys.
- Set the verb in each child business object to Create and recursively
create application entities to represent the child business objects.
A recommended approach for creating child business objects is
to design a submethod to recursively create child entities. The
submethod might traverse the business object, looking for attributes
of type OBJECT. If the submethod finds attributes that are objects, it calls
the main Create method to create the child entities.
The way that the main method provides primary key values to the
submethod can vary. For example, the main Create method might pass
the parent business object to the submethod, and the submethod can
then retrieve the primary key from the parent business object to
set the foreign key in the child business object. Alternatively, the
main method might traverse the parent object, find first-level children,
set the foreign key attributes in the child business objects, and
then call the submethod on each child.
In either case, the main Create method and its submethod interact
to set the interdependencies between the parent business object
and its first-level children. Once the foreign keys are set, the
operation can:
- Insert new rows into the application.
- Set foreign keys for the next level of child business objects.
- Create the child entities.
- Descend the business object hierarchy, recursively creating
child entities until there are no more child business objects to
process.
Note:
For a table-based application, the order of the
steps for setting the relationships between a top-level object and
its children may vary, depending on the database schema for the
application and on the design of the application-specific business
objects. For example, if foreign keys for a hierarchical business
object are located in the top-level business object, the verb operation
might need to process all child business objects before processing
the top-level business object. Only when the child entities are
inserted into the application database and the primary keys for
these entities are returned can the top-level business object be
processed and inserted into the application database. Therefore,
be sure to consider the structure of data in the application database
when you implement connector verb methods.
Outcome status for Create verb processing
The Create operation should return one of the outcome-status
values shown in Table 35..
Table 35. Possible outcome status for Java Create verb processing
Create condition |
Java outcome status |
If the Create operation is successful
and the application generates new key values, the connector:
- fills the business object with the new key values; this business
object is returned to the connector framework through the request
business object parameter.
- returns the "Value Changed" outcome status
to indicate that the connector has changed the business object
|
VALCHANGE |
If the Create operation is successful and
the application does not generate new key
values, the connector can simply return "Success". |
SUCCEED |
If the application entity already exists,
the connector can either of the following
actions: |
|
- Fail the Create operation.
|
FAIL |
- Return an outcome status that indicates the application entity
already exists.
|
VALDUPES |
If the Create operation fails, the verb
operation:
- fills a return-status descriptor with information on the failure
- returns the "Fail" outcome status
|
FAIL |
Note:
When the connector framework receives the
VALCHANGE outcome
status, it includes a business object in its response to InterChange Server.
For more information, see Sending the verb-processing response.
