Modules:Copy Entity Process-Developers Guide
Contents |
Overview
This document explains how to implement a process in charge of creating a copy of an object with its same type. The Copy Entities Process module will provide the core functionality to create this process.
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.
Define copy process
Base action handler
The copy process module provides a specific base action handler to be extended in order to implement the process used to copy an entity in a simply way.
The org.openbravo.copyprocess.process.CopyBaseActionHandler needs to be extended. The class that implements the main functionality of the copy process will be defined on its extension.
This example will show how to extend the base process with a generic class:
public class CopyActionHandler extends CopyBaseActionHandler<CopyObjectProcess> {
}
Process functionality
As mentioned in the previous step a class where the main logic of the process is going to be defined needs to be created. This module provides a base class that needs to be extended for this purpose, org.openbravo.copyprocess.process.CopyEntityProcess. Once this class has been extended the following abstract methods will be implemented.
/** * Abstract method used to implement the validation step of the copy process * * @return true in case the validations has succeded */ public abstract boolean validate(); /** * Abstract method used to implement the main logic of the copy process * */ public abstract void doExecute();
Also common procedures in the copy object proces will be accesible on the copy entity process class, some of them are as follows.
/** * Generic process to clone objects. * * It iterates over all properties and executes this logic: * * Primitive properties are directly copied from original to new object * FK properties are copied just in case the referenced object is in the new organization * tree, if it is not the property is set as {@code null} * * * This default logic can be overwritten for concrete properties: * * Having this property as blank in {@link BlankProperties} * Implementing a {@link PropertyHandler} with its qualifier being [EntityName].[PropertyName] * <li>In case of FK defining a {@link FKPropertyHandler} with its qualifier being * [EntityName].[ReferencedEntityName]. In this case all FK properties linking to that entity will * be processed by this handler * * * @param originalObject * original object to copy from * @param newObject * destination object to copy to * @param save * should OBDal.save be performed on new object */ public void cloneObject(BaseOBObject originalObject, BaseOBObject newObject, boolean save) /** * Returns the value of a given process parameter * * @param paramName * Parameter name * @return String Parameter value */ public String getParam(String paramName)
There are a few methods that needs to be called to make a trace of all the created objects during the copy process
/** * Add a new object to the list of created objects during the process * * @param key * Object key that will follow this format ([Entity name]-[Object ID]) * @param object * Object to be added */ public void addNewObject(String key, BaseOBObject object) /** * Returns an specific object that has been created during the process * * @param key * Object key that will follow this format ([Entity name]-[Object ID]) * * @return Object linked to the provided key */ public BaseOBObject getNewObject(String key)
On the copy process a log with all the performed steps can be shown.
/** * Adds logs to be displayed to user after process execution * * @param level * log level * @param message * message to display. Note the String message will be displayed as is, so translations * should be managed befor invoking this method */ public void addLog(LogLevel level, String message) /** * Same as {@link CopyEntityProcess#addLog(LogLevel, String)} but including a link to a * BaseOBObject. Note this link will be only shown in case the whole process has no errors. * * @param level * @param message * @param link */ public void addLog(LogLevel level, String message, BaseOBObject link) /** * Returns all the generated log to be shown in the UI * * @return {@link JSONArray} to be shown in the UI */ public JSONArray getLog() /** * Provides a proper name to be displayed on the process log * * @param obj * The object from the name is going to be obtained * @return the object name */ public String getEntityNameForLog(BaseOBObject obj)
Copy Objects 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 being extended through modules.
How to Change Behavior for a Property
To change the behavior of a Property org.openbravo.copyprocess.process.handlers.PropertyHandler needs to be extended. Its Qualifier needs to be [DAL Entity name].[Property Name]. The handleProperty(BaseOBObject originalObject, BaseOBObject newObject, CopyEntityProcess 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 implements PropertyHandler {
@Override
public void handleProperty(BaseOBObject originalObject, BaseOBObject newObject,
CopyEntityProcess 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.copyprocess.process.handlers.FKPropertyHandler class. With its Qualifier being [Base Entity Name].[FK Entity Name]. The method handleProperty(String propertyName, BaseOBObject originalObject, BaseOBObject newObject, CopyEntityProcess 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 implements FKPropertyHandler { @Override public void handleProperty(String propertyName, BaseOBObject originalObject, BaseOBObject newObject, CopyEntityProcess 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.copyprocess.process.handlers.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.
Import files data
The copy process also provide the main logic to process data from a file.
How to implement a File Entity Data Handler
The data file handler org.openbravo.copyprocess.process.handlers.FileEntityDataHandler<T extends BaseOBObject> needs to be extended.
In the first place the Qualifier needs to be the search key defined for the File Entity Data Handler extension on CopyEntityProcess class. The mapping between the name provided on the file section and the search key will be stored while the process is initialized as follows.
CopyEntityProcess.setParam(FILE_SECTIONS, [{ SECTION_NAME: fileSectionName SECTION_SEARCHKEY: searchkey }]);
The abstract initializeRecord(CopyStoreRecord record) and postProcessRecord(CopyStoreRecord record) methods receive the record processing.
@Qualifier("POSTerminals") public class POSTerminalsProcess extends TabHandler<OBPOSApplications> { @Override public void initializeRecord(CopyProcessRecord record) { origObject = getOrigTerminal(record, copyEntityProcess); newObject = OBProvider.getInstance().get(OBPOSApplications.class); } @Override public void postProcessRecord(CopyProcessRecord 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.copyprocess.process.fileimport.CopyProcessFileColumnHandler<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 implements CopyProcessFileColumnHandler<UserRoles> { @Override public void processColumn(CopyEntityProcess copyEntityProcess, CopyProcessField field, UserRoles origObject, UserRoles newObject) { newObject.setUserContact(myUserContact); } @Override public void validateColumn(CopyProcessField field, CopyEntityProcess copyEntityProcess) { // 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 copy process execution
Just before, after or at the finally clause of the copy process external processes are executed. These processes can do any action that extends the default behavior of the standard process, such as copying new entities, modifying existent ones, etc.
Before the process execution all classes extending org.openbravo.copyprocess.process.handlers.PreProcessHandler are iterated at this point executing their execute(CopyEntityProcess process) method.
After the process execution all classes extending org.openbravo.copyprocess.process.handlers.PostProcessHandler are iterated at this point executing their execute(CopyEntityProcess process) method.
On the catch finally clause all classes extending org.openbravo.copyprocess.process.handlers.FinalProcessHandler are iterated at this point executing their execute(CopyEntityProcess process) method.
The order these classes are iterated is based on their priority.
Priorities
The PropertyHandler, FKPropertyHandler, CopyProcessFileColumnHandler, FileEntityDataHandler, PreProcessHandler, PostProcessHandler and FinalProcessHandler 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, CopyProcessFileColumnHandler, FileEntityDataHandler 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 PreProcessHandler, PostProcessHandler and FinalProcessHandler classes, they are all executed, priority determines the order of execution.
Copy Entity Qualifier
Also it is posible to define a qualifier while extending the previous mentioned handlers in order to decide on witch process they are going to be executed.
This qualifier needs to be defined as follows
@CopyEntityQualifier(CopyObjectProcess.class)
Where CopyObjectProcess will be a class that extends CopyEntityProcess