Modules:Copy Retail Store and Terminal - Developers Guide
Overview
This document explains how to change default behavior of Copy Retail Store and Copy Terminal processes.
It is targeted to developers with some experience in creating Openbravo modules as well as in Java development and basic DAL knowledge.
All the items explained here can be added within modules.
Default behavior
Copy processes do several copies of different records to new ones. When a record is copied all its properties are iterated, for each of them:
- Try to copy property from the original entity to the new one
- If the original property references to another entity that is not in the new tree of organizations, it is set as blank, in case it is mandatory the process fails
This default behavior can be overwritten. The base module provides a default overwrite for some cases, even this default modified behavior can be changed through modules.
How to Change Behavior for a Property
To change the behavior of a Property org.openbravo.retail.copystore.process.PropertyHandler needs to be extended. Its Qualifier needs to be [DAL Entity name].[Property Name]. The handleProperty(BaseOBObject originalObject, BaseOBObject newObject, CopyStoreProcess process) method receives both original object copying from and the new object copying to as well as the process instance being executed.
This example sets to the new store a different description:
@Qualifier("Organization.description")
public class OrgName extends PropertyHandler {
@Override
public void handleProperty(BaseOBObject originalObject, BaseOBObject newObject,
CopyStoreProcess process) {
newObject.set("description", "My new description");
}
}
In case of several classes with the same qualifier, only the one with the lowest priority will be executed.
How to Change Behavior for a all Foreign Key Properties to a Given Entity
It is possible to overwrite behavior for all properties in an entity that are foreign key to a given entity by extending org.openbravo.retail.copystore.process.FKPropertyHandler class. With its Qualifier being [Base Entity Name].[FK Entity Name]. The method handleProperty(String propertyName, BaseOBObject originalObject, BaseOBObject newObject, CopyStoreProcess process) works similarly to the one described in the section above, it also receives the name of the property being handlded.
This example sets to null all references from Organization to OBPOS_Print_Template entity.
@Qualifier("Organization.OBPOS_Print_Template") public static class SearchKey extends FKPropertyHandler { @Override public void handleProperty(String propertyName, BaseOBObject originalObject, BaseOBObject newObject, CopyStoreProcess process) { // Don't copy templates } }
In case of several classes with the same qualifier, only the one with the lowest priority will be executed.
How to Define null Properties
Implementing org.openbravo.retail.copystore.process.BlankProperties allows to define properties that will be set as null. Its method addBlankProperties(List<String> blankProperties); receives a List<String> with all the properties that will be set as null. The entries in this list must have the format [Entity Name].[Property Name].
This example forces Organization.socialName to be null regardless its original value.
public class MyBlanks implements BlankProperties { @Override public void addBlankProperties(List<String> blankProperties) { blankProperties.add("Organization.socialName"); } }
All the classes implementing this interface are taken into account, they do not define any priority.
How to Define Organization Required Handler
Implementing org.openbravo.retail.copystore.process.OrganizationRequiredHandler allows to execute logic and define when an organization property has to be copied. It can be copied after or before the organization has been created. Its method isCreatedOrganizationRequired(CopyStoreProcess process) receives the process instances being executing. It returns true or false depending on when it is wanted to copy the property.
public class DefaultOrganizationRequiredHandler { @Qualifier("Organization.oBRETCORetailOrgType") public static class RetailOrgType extends OrganizationRequiredHandler { @Override public boolean isCreatedOrganizationRequired(CopyStoreProcess process) { process.newStore.setOBRETCORetailOrgType(null); return true; } } }
In case of several classes with the same qualifier, only the one with the lowest priority will be executed.
How to Change Behavior for a Tab Handler
To change the behavior for a tab handler org.openbravo.retail.copystore.process.TabHandler<T extends BaseOBObject> needs to be extended. Its Qualifier needs to be the search key defined for the Tab Handler on Copy Store Configuration window. The initializeRecord(CopyStoreRecord record) and postProcessRecord(CopyStoreRecord record) methods receive the record processing.
@Qualifier("POSTerminals") public class POSTerminalsProcess extends TabHandler<OBPOSApplications> { @Override public void initializeRecord(CopyStoreRecord record) { origObject = getOrigTerminal(record, copyStoreProcess); newObject = OBProvider.getInstance().get(OBPOSApplications.class); } @Override public void postProcessRecord(CopyStoreRecord record) { // Do something after process the record } }
In case of several classes with the same qualifier, only the one with the lowest priority will be executed.
How to Change Behavior for a Column Handler
To change the behavior for a column handler org.openbravo.retail.copystore.process.ColumnHandler<T extends BaseOBObject> needs to be extended. Its Qualifier needs to be tabName = [sheet name], columnName = [column name].
@ColumnQualifier.Qualifier(tabName = "User Roles", columnName = "Username") public static class UsernameRole extends ColumnHandler<UserRoles> { @Override public void processColumn(CopyStoreProcess copyStoreProcess, CopyStoreField field, UserRoles origObject, UserRoles newObject) { newObject.setUserContact(myUserContact); } @Override public void validateColumn(CopyStoreField field, CopyStoreProcess copyStoreProcess) { // Validates the field value } }
In case of several classes with the same qualifier, only the one with the lowest priority will be executed.
How to Extend the Process
Once the copy processes are done, post processes are executed. These post process can do any action that extends the default behavior of the standard process, such as copying new entities, modifying existent ones, etc.
All classes extending org.openbravo.retail.copystore.process.PostProcessHandler are iterated at this point executing their execute(CopyStoreProcess process) method.
The order these classes are iterated is based on their priority.
Priorities
The PropertyHandler, FKPropertyHandler and PostProcessHandler classes explained above implement the PriorityHandler class that allows to manage the way they are executed, the method that determines the priority is int getPriority(), which is defaulted to 100 for all classes deployed by standard module.
For classes PropertyHandler and FKPropertyHandler with the same Qualifier it will be only executed the one for which priority is the lowest one. This allows, for example, to overwrite a property management defined in another module.
In the case of PostProcessHandler classes, they are all executed, priority determines the order of execution.