The Business Component (BC) concept provides a way to use all the power of a Transaction object from other GeneXus objects.
It's very easy to use this concept, and it allows to update the database from any object, executing transactions in a 'silent' mode (without showing its forms) but taking advantage of all the benefits offered by them!
Most important benefits
- Database update guaranteeing data integrity
- Less coding: The business logic defined in the transaction is reused (rules and formulas are triggered, etc.)
- All GeneXus objects can update the database: For example in a Web Panel the only way to update directly the database (without calling a procedure) is using the business component concept.
- Rest: A Business Component may be exposed as a Rest web service.
- SOA interface: A Business Component may be defined as a SOAP web service, allowing updates via SOAP.
- EJB: A Business Component can be defined as a Enterprise Java Bean so you can execute it in an EJB Container of any J2EE Server.
Business Component definition and use
Every transaction has a property named Business Component.
When the developer sets the Business Component property of a transaction = True, a new data type named with the same name of the transaction is created in the Knowledge Base, and variables based on that new data type may be defined in any object.
For example, let's suppose the developer defines the Customer transaction as Business Component (by setting its Business Component property = True) :
Once he/she sets this property to True, a Business Component data type named Customer is automatically created in the Knowledge Base. Then, the developer will be able to define in any object a variable based on the new data type, as the following image shows (in the example in a Web Panel):
The variables based on a business component data type (as &customer in this example), have got a set of properties that correspond to the transaction attributes (so that the developer can assign them values). Also, a set of methods are available to apply to business components variables (in order to execute operations in the database as insertions, updates, etc.).
Important: After assigning values to the properties of a business component variable and executing methods to update the database, it is necessary to write explicitly the Commit command in the code, wherever the developer considers that all the operations made to the database make a complete Logical Unit of Work (LUW).
Now, let's see an example of code using the &customer variable, but before, let's suppose the Customer transaction has got the following rule:
and let's assume the CustomerId attribute has got its Autonumber property set to True.
The following code (included in the events section of the web panel where the &customer variable is defined) is inserting a customer by assigning values to the &customer variable properties (it means, the customer attributes), then the save method is applied to the variable, and finally the commit command is executed:
Event 'insert customer'
&Customer=new() //in this case the new operator can be ommited, but if more than one customer is inserted, it must be used
&Customer.CustomerName = 'John'
&Customer.CustomerLastName = 'Smith'
&Customer.CustomerAddress = '165 Ocean Drive'
&Customer.CustomerEmail = 'email@example.com'
Several explanations related to the previous code:
- When the save method is executed:
- The default rule defined in the Customer transaction rule is triggered, so the CustomerAddedDate attribute is assigned.
- The CustomerId attribute is autonumbered.
- The CustomerPhone was not assigned, so, the attribute in the table will not contain a value (it will be empty).
- If the transaction would have had the CountryId attribute and/or the CityId attribute as foreign keys, and the programmer assign by error values to them that not exist in the corresponding tables, when the save method try to record, it fails.
- The mode changes to update, and the records keep instantiated in memory.
- After applying a method to access the database, we recommend always handle the errors.
Let's see now what happens in the case of a two-level transaction declared as Business Component:
The transaction Business Component property was set with the True value, so GeneXus has created the Customer data type associated with the transaction. But since it is a 2-level transaction, GeneXus also has created the Customer.Trip data type associated with the lines (second level), which in this example correspond to the customer’s tours. It's important to know that the Customer.Trip data type comes from the level description and not from the name of the 2nd level.
Then, in a certain object we define:
- a variable named &Customer of the Customer type
- and a variable named &OneTrip of the Customer.Trip type.
If we want to add two trips to a certain customer, the following code solves it:
Note: The default rule defined in the transaction, assigns the present date for each trip inserted. This rule is triggered for each line inserted. If you want to assign another date for a certain trip, you have to assign it explicitly.
Data Base update with Business Components
Another example of database update using Business Components