-
Notifications
You must be signed in to change notification settings - Fork 19
import framework notes
The import framework provides a mechanism for creating, comparing, updating, and deleting CDB domain objects from Excel spreadsheets, and writing domain objects to Excel spreadsheets. That includes "official" CDB domains like inventory, catalog, machine design and the cable analogs cable inventory, cable catalog, and cable design, as well as "supplemental" domains like locations and sources.
The framework includes generic view components for the import and export wizards, and Java controller classes that handle requests from the wizard views, processing the input Excel file and manipulating domain objects as specified by the wizard. The view components and Java class framework are described in more detail below.
The import and export wizard views live in the following locations:
- views/item/private/importWizard/importWizard.xhtml
- views/item/private/exportWizard/exportWizard.xhtml
Each wizard directory includes a "templates" subdirectory that includes the definition for of the wizard's tabs. The tabs are pretty simple and self-explanatory.
To use the import or export wizards for a particular domain, import.xhtml and export.xhtml files are created in the directory for the domains views. For example, the cable design domain view directory views/itemDomainCableDesign contains those files for opening the corresponding wizard view for that domain. This is covered in the task-oriented document link below adding import support for a CDB domain
The wizard controller and import helper framework classes are in subdirectories of the base package gov.anl.aps.cdb.portal.import_export. Here is a brief description of important classes and hierarchies:
-
ItemDomainImportWizard.java - This is a simple view controller for the import wizard gui. It provides models for the view components, and its primary responsibility is dispatching actions to its import helper object, described in more detail below.
-
ItemDomainExportWizard.java - Similar to the import wizard controller, this is a simple view controller for the export wizard gui, providing models for view components and dispatching actions to its helper.
-
ImportHelperBase.java - This is the key class of the Java import framework. It's a bit bloated, as the requirements have evolved, but it gets the job done. It provides the "engine" for the import and export processes, reading/writing the Excel spreadsheet file and coordinating actions on the domain objects. To provide a new import or export spreadsheet format for a particular domain, a new subclass of ImportHelperBase is created. The main responsibilities of that subclass are described in more detail below.
-
ColumnSpec.java - One of the primary responsibilities of the helper subclass is to specify the columns utilized in the spreadsheet format. To do this, the method override initColumnSpecs() returns a list of ColumnSpec objects, one for each column in the spreadsheet. The column spec maps a column in the spreadsheet to a bean property (method) on the domain object. This is the base class of a hierarchy which specialized subclasses for handling different types like boolean, float, integer, and string values, as well as an IdRefColumnSpec hierarchy for referring to objects in other domains by id or name. A CustomColumnSpec base class allows new column spec implementations to be developed for specific purposes.
-
InputHandler.java - InputHandler subclasses handle the parsed value for a column. The key methods in doing so are handleInput(), which is passed the Excel library row object, a map of cell values, and a map of named objects parsed for the row, and updateEntity(), which applies the parsed data to a domain object. The InputHandler hierarchy mirrors the ColumnSpec hierarchy. The ColumnSpec abstract method getInputHandler() returns the appropriate handler for the column. Many InputHandler subclasses are derived from the intermediate base class SimpleInputHandler, which uses reflection in updateEntity() to invoke methods on the domain class (specified in the ColumnSpec definition) to apply values parsed from the input spreadsheet.
-
OutputHandler.java - Analogous to the InputHandler for importing data, the OutputHandler generates cell values in handleOutput() for spreadsheet columns. Each ColumnSpec returns its OutputHandler via getOutputHandler(). The default output handler, SimpleOutputHandler, uses reflection in getColumnValue() to call a method (specified in the ColumnSpec definition) on the domain object to retrieve a value for the output column.
The framework provides many classes, and hopefully most of them will not need to change much (unless new requirements come along...). To define a new spreadsheet import or export format, a new subclass of ImportHelperBase is created. Some helper classes are very simple (e.g., ImportHelperSource) and simply specify columns that map the spreadsheet to the domain object, without defining any custom handling. More complex helpers (ImportHelperMachineHierarchy) define custom handling in addition to specifying column mappings. Here are descriptions of some of the key methods and features:
-
domain controller registration - A domain object controller overrides methods to specify the spreadsheet formats / helpers supported for the domain. initializeDomainImportInfo() and initializeDomainExportInfo() return a DomainImportExportInfo object that contains a list of supported spreadsheet formats, each with a description and helper subclass. The methods getEntityDisplayImportButton() and getEntityDisplayExportButton() tell the list view for the domain to display import/export buttons to initiate the appropriate wizard.
-
class definition - classes derive from ImportHelperBase, and specify template parameters for the domain object class to be manipulated by the helper and the controller for the domain class
-
initColumnSpecs() - the most important method, returns a list of ColumnSpecs which map the input spreadsheet columns to domain object methods
-
getEntityController() - returns the controller instance for use by the framework to retrieve, create, and update domain objects
-
supportsMode-Create, Update, Delete, Export, Transfer() - these methods specify the "modes" supported by the helper
-
getFilenameBase() - returns the base filename for exported items
-
createEntityInstance() - creates and initializes a domain object using the map of column values read for the row. Some domain updates can be done automatically by the InputHandler by reflection or in updateEntity(), but custom domain handling for new objects is performed in this method. This might include validation or updating fields of the domain objects based on the values read from the spreadsheet.
-
updateEntityInstance() - like createEntityInstance(), this method performs custom updating of a domain item in update mode using the values read from a spreadsheet row. Some updates happen automatically via the input handler.
-
preImport() - defines a process to run before importing the spreadsheet. For example, the cable domains use the "core metadata framework" to define standard metadata properties for the domain. The import helpers preImport() call createOrMigrateCoreMetadataPropertyType() on the controller to migrate the metadata property definition in case there have been changes to the field definitions.
In addition to the core requirement to create a subclass of ImportHelperBase to define a spreadsheet format and map that format to domain operations, a developer might want to use other features of the import framework for customized behavior. Some of these are described in more detail below.
-
custom column specs and input/output handlers - Custom ColumnSpec and InputHandler/OutputHandler classes can be created to meet special requirements not covered by the existing hierarchies. For example, MachineItemRefColumnSpec and MachineItemRefInputHandler were developed with special features for processing columns from the input spreadsheet that are references to machine design items and we want to constrain lookups to a specified machine hierarchy. LocationHandler is a special RefInputHandler for handling input spreadsheet columns with locations where the value might include the word "parent" (which is ignored) or a reference to a location item by name or id.
-
hierarchical domain object helper - The intermediate helper base class ImportHelperTreeViewBase is intended for hierarchical imports (like for locations and machine design hierarchy) and adds a tree view widget to the validation tab of the import helper for viewing the hierarchy to be created by the import process. The intermediate class ImportHelperHierarchyBase provides support for parsing Ned's hierarchical spreadsheet format which uses multiple columns to show the indented levels of a hierarchy and is used in the machine hierarchy and location import formats.
A list of import helper subclasses by domain is shown below. One of these is probably a good starting point for adding a new import helper.
- ImportHelperItemCategory - Core format for creating technical systems.
- ImportHelperItemType - Core format for creating functions.
- ImportHelperUserInfo - Core format for creating user items.
- ImportHelperUserGroup - Core format for creating user groups.
- ImportHelperSource - Core format for creating, updating, and deleting source items.
- ImportHelperLocation - Hierarchical format for creating location items.
- ImportHelperConnectorType - Core format for creating connector type items.
- ImportHelperCatalog - Core format for creating, updating, and deleting catalog items.
- ImportHelperCatalogAssembly - Format for creating assemblies of catalog items.
- ImportHelperCatalogPorts - Format for adding ports to catalog items.
- ImportHelperInventory - Core format for creating, updating, and deleting inventory items.
- ImportHelperMachineHierarchy - Core hierarchical format for creating machine design items.
- ImportHelperMachineTemplateInstantiation - Format for creating machine items by instantiating templates.
- ImportHelperMachineAssignTemplate - Format for assigning templates to existing machine items.
- ImportHelperMachineItemUpdate - Format for updating machine items.
- ImportHelperCableCatalog - Core format for creating, updating, and deleting cable catalog items.
- ImportHelperCableCatalogConnectors - Format for adding, updating, or deleting connectors from cable catalog items.
- ImportHelperCableInventory - Core format for creating, updating, and deleting cable inventory items.
- ImportHelperCableDesign - Core format for creating, updating, and deleting cable design items.
- ImportHelperCableDesignConnections - Format for adding and editing cable design device connections.
- ImportHelperCableDesignPullList - Format for extracting pull list data.
The links below provide examples of how to accomplish specific tasks in the import framework.
adding import support for a CDB domain
adding export, transfer, update, and delete support for a CDB domain