Code Generation Template¶
A code generation template is used when the source code is generated into deployable code. This means that all entities generated with the same code generation template (if you only consider the Base layer of the code) look the same, except when the model is changed with code generation properties. In each project only one code generation template should be used and it is forbidden to mix different templates, since it can give unwanted behavior. The code generation template to use, is set when you choose the target version in Developer Studio. The code generation template act as default code for all entities and it gives the generated code its base layer. The code is not exactly the same for all entities since it is affected by model properties and code generation properties.
The code generation template has code for different scenarios e.g.
- Code for Client Interaction.
- Code for Server to Server Interaction.
How the code generation template code is used, can be affected by model properties and code generation properties. Major changes to the code generation template happens more or less only between major releases of IFS Cloud. When IFS Cloud has been released only bug fixes are applied to the code generation template.
Working with records¶
The current code generation template is designed to work with PL/SQL records. Therefore it is very important that the code is written so it fits the code generation template by using records in the implementation. Following should be considered regarding usage of records:
- Records are defined as table_name%ROWTYPE, meaning that all columns in the table are included in the record. Note: Rowid is a pseudo column and therefore never included in a record.
- The code generation template code always inserts, updates and deletes the whole record.
Meaning all columns are included in every dml statement that is executed. So during an update of an instance all columns are always included. If a column doesn't have a value, null will be used. - If a record is copied, columns with unique values must be replaced manually in the code. Otherwise a duplicate error will be received during the insert.
Rowkey and Search Domain columns will always be set to new GUID values by the framework.
As the whole code generation template is designed for sending the record between the methods, the attribute string should not be used, except for calls from the client. In the code generation template there should exist a method with a record interface that fulfill the implementation needs.
Code Generation Template Description¶
The code generation template has code for:
- Implementation methods
Internal methods visible only for this entity - Private methods
Methods visible to clients that should interact with this entity - Public methods
Methods visible to other clients and other entities that should interact with this entity - Protected methods
These methods are like public ones, but may only be called from the component where the actual entity is used.
Explanation of the types above and the naming standard of them, see Method Protection Types. In order to understand the code generation template you also need to understand the Attribute String.
Note: Many of the code generation template methods are overridden in application code. A specific entity may have different or additional behavior than described below.
Server record (or %ROWTYPE record)¶
Many of the the methods is working with a server record, defined as table_name%ROWTYPE in PL/SQL. This is a standardized way of defining records in PL/SQL. If you define a record in this way then you get a record that holds every column in the table. Since many of our methods works with the server record, especially the ones that creates, modifies and removes data, it is very important that you set all columns in the record before using the methods. If a column doesn't have a value, null will be used.
Public record¶
The public record is a record that is available to other entities in the system. The public record has:
- All the public attributes in the entity
- All primary key attributes
- Rowid, rowversion and rowkey is always included
- A public method called Get(primary_key) that returns the public record
The purpose with the public record is to be able to get all public information in one server call from other entities.
Indicator record¶
The indicator record is a private record that has all attributes in one entity represented as Booleans. If a record value is TRUE then that attribute has a value in the attribute string, if FALSE no value exists in the attribute string. By default the indicator record is FALSE in all attributes.
The following methods returns the indicator record:
- Reset_Indicator_Rec___
Resets the indicator record to FALSE - Get_Indicator_Rec___
Gets the indicator record from either one record or the difference between a new record and an old record
The indicator record is used in lots of methods where the attribute string is used:
- Unpack___
- Check_Insert___
- Check_Common___
- Check_Update___
You can change the indicator record yourself, if you want to set an attribute value in the server code manually.
Error methods¶
To handle error messages there exists a lot of different error methods. These methods exists in order to make it easy to do a override of an error message. The methods always ends up with a call to Error_SYS system service. The Error_SYS methods always end up with raising an exception. The error methods raises an error message to be displayed in the calling client.
The following error messages methods exists:
- Raise_Too_Many_Rows___
- Raise_Record_Not_Exist___
- Raise_Record_Exist___
- Raise_Item_Format___
- Raise_Record_Modified___
- Raise_Record_Locked___
- Raise_Record_Removed___
Locking methods¶
To lock a record there exists several different types of methods. If you have locked a record no one else can change it until you are done and ends the transaction. These methods will return the full %ROWTYPE record.
- Lock_By_Id___
Is used to lock a record from a client. If you can't lock the record this method gives direct feedback by raising an error. - Lock_By_Keys___
Is used to lock a record from the server. This interface waits (hangs) until you can lock the record. - Lock_By_Keys_Nowait___
Is used to lock a record from the server. You can choose whether to wait or raise an error if you can't lock the record. - Lock__
This method is deprecated and will be removed in future releases.
Get methods¶
To retrieve data from the server there are several different types of get methods.
Get methods to get all the attributes in an entity and returns them in a record:
- Get_Object_By_Id___
Fetches the record by objid and objversion. This is a client interface. - Get_Object_By_Keys___
Fetches the record by the primary key. This is a server interface.
Get methods that retrieves the objversion and/or objid, if you need to fetch them:
- Get_Version_By_Id___
Fetches by objid. This is a client interface. - Get_Id_Version_By_Keys___
Fetches by primary key. This is a server interface.
Get methods that retrieves other important data:
- Get_Key_By_Rowkey
Gets the primary key and returns it in a record from rowkey. - Get_Objkey
Gets the objkey from the primary key. - Get
Gets all public attributes into the public record (public_rec). - Get_ <public attributes>
All public attributes gets a Get_ method that can be used to get the value for the attribute from the primary key.
Check methods¶
Check methods are used to check different things about an entity.
- Check_Exist___
Checks if a primary key value exists or not. - Check_Common___
Is used when we have things that should be checked both during insert and update. - Check_Insert___
Is used when we have things that should be checked during insert. - Check_Update___
Is used when we have things that should be checked during update. - Check_Delete___
Is used when we have things that should be checked during remove. - Exist
Checks whenever an entity instance (row) exists in the database. Throws Record_Not_Exists if it doesn't exist. - Exists
Checks whenever an entity instance (row) exists in the database. Returns TRUE if record exists, FALSE otherwise.
Attribute string methods¶
To handle the attribute string the following methods exists:
- Unpack___
Unpacks the attribute string, no validations are performed. Pass-through of extra attributes in the attribute string. - Pack___
Packs a record into an attribute string. This is intended to be the reverse of Unpack___. - Pack_Table___
Reads a record and packs its contents into an attribute string. Similar to Pack___ but just uses table column names and DB values.
Creating record methods¶
To create a new record in the database the following methods exists:
- Prepare_Insert___
Prepares server default values when client is to create a new row. - Prepare_New___
Prepares server default values when client is to create a new row. - Insert___
Inserts the row into the table. - New___
Create a new instance (row) an entity. This method uses a record (server) interface and is intended for scenarios where business logic needs to perform entity changes.
Note, the three underscores and the differences between client facing method. - New__
Client interface for creating new rows. Unpacks attribute string, validates record and inserts table row.
Updating record methods¶
To update an existing record in the database the following methods exists:
- Update___
Updates the row in the table. - Modify___
Modifies an existing instance (row) of an entity. This method uses a record (server) interface and is intended for scenarios where business logic needs to perform entity changes.
Note, the three underscores and the differences between client facing method. - Modify__
Client interface for modifying exists rows. Gets (and locks) the table row, unpacks attribute string, validates record and updates table row.
Removing record methods¶
To remove a record in the database the following methods exists:
- Delete___
Validates whenever entity instance can be removed (referential integrity) from either objid or primary key(s). - Remove___
Removes an instance (row) of an entity. This method is uses a record (server) interface and is intended for scenarios where business logic needs to perform entity changes.
Note, the three underscores and the differences between client facing method. - Remove__
Client interface for deleting rows. Performs reference integrity and removes table row.
Init method¶
- Init
Method used to elaborate the package if necessary, mostly done from a performance reason.
State methods¶
When you have an entity with a state machine, there are several methods used to manage the different states and events and updating the state.
Methods to decide what action to do as well as handling the attribute string:
- Finit_State_Machine___
Decide what action should be performed for a given state and event. This is the engine in the state machine. - Finit_State_Add_To_Attr___
Add the state to the attribute string. - <Event> methods
The event methods are generated from the different events you have modeled and it is those methods that calls the Finish_State_Machine___.
Methods for updating the database:
- Finit_State_Init_
Sets the initial state for the state machine. This particular method is protected and only used from server. - Finit_State_Init___
Set the initial state for the state machine. - Finit_State_Set___
Updates the database with the state.
Methods for handling list of states:
- Finit_State_Decode__
Fetch the server state value when giving the client state value. - Finit_State_Encode__
Fetch the client state value when giving the database state value. - Enumerate_States__
List all the states as named in the client. - Enumerate_States_db__
List all the states as named in the server. - Get_Db_Values___
Fetches the server values for a state. - Get_Client_Values___
Fetches the client values for a state.
Methods for handling list of events:
- Finit_State_Events__
List all the events that can be performed for a given state. - Enumerate_Events__
List all the events that can be performed at all.