Package com.broadleafcommerce.dataimport.processor.specification

Interface ImportSpecification

All Known Subinterfaces:
GlobalImportSpecification
All Known Implementing Classes:
CampaignCodeSpecification, CompleteProductImportSpecification, CustomerSegmentMemberSpecification, CustomerSpecification, DefaultSpecification, OfferCodeSpecification, PriceDataSpecification, ProductSpecification, SkuInventoryImportSpecification, UpdatePricesSpecification
public interface ImportSpecification
Describes how an ImportProcessor can handle a particular import
Author:
Phillip Verheyden (phillipuniverse)

  • Field Details

  • Method Details

    • getImportType

      String getImportType()
      Which import type this specification is valid for
      Returns:
      the Import.getType() that should match this specification

    • canHandle

      boolean canHandle(String importType)
      Whether or not this specification can actually handle the given import. Checks will generally be based on the import type.
      Parameters:
      importType -
      Returns:
      whether or not this specification can actually handle the given import

    • getMainRecordType

      default String getMainRecordType()

      the "root level" record type for this file (ex: for product imports, this would be "PRODUCT"). Records that are found without an explicitly stated type are assigned this type by default.

      This also determines where batching lines are established when reading through an import file

      Returns:
      the record type used to determine default record types and batching

    • getDependencyMappings

      default Map<String,Set<String>> getDependencyMappings()
      Hints about how to organize records into a tree structure of dependents based on the information of the given record types. Keys correspond to a parent record type and values correspond to their direct dependents

    • isRequiresRowTypeHeader

      boolean isRequiresRowTypeHeader()
      Whether or not the import requires a header for row_type. This is generally only required when there are multiple record types in an import, but could also be used to dynamically determine the row type during processing
      Returns:
      whether or not this import requires a row type header

    • resolveAndRemoveRecordType

      @Nullable default String resolveAndRemoveRecordType(Map<String,String> row)
      Determines the row type for a row of data. This is not required as upstream processing can instead decide to simply default this to the getMainRecordType(), so null can be handled gracefully as an optional distinction, in which case all data in the file will be treated as if everything is getMainRecordType().
      Parameters:
      row - a parsed row of data from a file. Unlike resolveRecordTypeBeforePropertyMapping(Map), the given row is expected to have already undergone mapping from header names to property names.
      Returns:
      the record type for the given row. If it was found in the row map then this should also remove it. Can also return null if no type can be determined from just the row data
      See Also:

    • resolveRecordTypeBeforePropertyMapping

      @Nullable default String resolveRecordTypeBeforePropertyMapping(Map<String,String> row)
      Determines the row type for a row of data.
      Parameters:
      row - a parsed row of data from a file. Unlike resolveAndRemoveRecordType(Map), the given row is NOT expected to have already undergone mapping from header names to property names.
      Returns:
      the record type from the given row if found, else null
      See Also:

    • shouldAutoGenerateOperationTypeForEachRecord

      default boolean shouldAutoGenerateOperationTypeForEachRecord(String rowType)
      This method describes whether imports processed with this specification should have the BatchRecord.getOperation() eagerly auto-generated by the import service for each record if not explicitly supplied in the input file.

      In situations where the resource tier import handler is expected to automatically recognize which records represent updates and which records represent creates, it makes sense for this method to just return false.

      If this method returns true, then the import service will eagerly guess and set the operation type for each record that does not explicitly provide one. See OperationResolver.

      Parameters:
      rowType - the row type for which this method should return a preference. Allows for different behavior for different row types within an import
      Returns:
      whether operation type should be eagerly auto-generated by the import service if not explicitly requested for each record processed for this specification

    • shouldAutoGenerateResourceTierIdForEachRecord

      default boolean shouldAutoGenerateResourceTierIdForEachRecord(String rowType)
      This method describes whether imports processed with this specification should have BatchRecord.getResourceTierIdentifier() eagerly auto-generated by the import service for each record if not explicitly supplied in the input file.

      It's possible that an import type has heavy reliance on resource-tier identifiers for entities it imports and expects to deal with those values in the files it accepts. For example, an import may have records creating certain entities, and additional records that reference those entities by resource tier ID. Such a situation is a great candidate for use of correlation IDs, where the input file only provides and references correlation IDs which the import service will eagerly resolve into resource tier identifier values. However, in order to do this, the import service needs to be able to eagerly generate those resource tier IDs (assuming the input file is not expected to provide those directly). For such situations, this method should return true. See IdResolver.

      Conversely, some import types may not expect files to provide resource-tier identifiers or correlation IDs to identify or reference records. They may use a different approach altogether and entirely delegate all ID-related behavior to the resource tier import handler instead. In those cases, eager generation of resource tier IDs by the import service would be undesirable. For such situations, this method should return false.

      Parameters:
      rowType - the row type for which this method should return a preference. Allows for different behavior for different row types within an import
      Returns:
      whether resource tier IDs should be eagerly auto-generated by the import service if not explicitly requested for each record processed for this specification

    • shouldAllowUnmappedHeaders

      default boolean shouldAllowUnmappedHeaders(String rowType)
      This method describes whether imports processed with this specification should allow passthrough of headers with no explicit mapping.

      Essentially, when a record is being processed, if there is no explicit header-to-field mapping possible for a given input via getHeaderFieldConfigsByRowType(), or via mapDynamicHeaderToField(String, String), this method describes the behavior that should be used.

      Some import types may choose to allow such 'unmapped' fields to be passed through with just the raw unmapped header and its corresponding value. For those situations, this method should return true. Other import types may want to intentionally ignore any unmappable headers and exclude them to force strict adherence to the specification. For those, this method should return false.

      Note that 'meta' headers/fields such as DefaultImportProcessor.OPERATION_COLUMN have special meaning and thus may not be affected by this setting. See DefaultImportProcessor to understand how such fields are processed.

      Parameters:
      rowType - the row type for which this method should return a preference. Allows for different behavior for different row types within an import
      Returns:
      true if unmapped headers should be allowed, else false

    • getFieldConfigMap

      @Deprecated(since="1.8.1", forRemoval=true) LinkedHashMap<String,ImportFieldConfig> getFieldConfigMap()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This should represent field configuration that will apply to _all_ row types.

      Maintains a Map of ImportFieldConfig objects that will be used to process the cells within an import file.

      For configurations with a headerRow, the key of the Map should be a String representing the corresponding header value or pattern.

      For configurations without a headerRow, the key should be the numeric order of the column starting with 1 as the first column.

      Returns:
      a map from header name to the field config for it
      See Also:

    • getHeaderFieldConfigsByRowType

      default Map<String,Map<String,ImportFieldConfig>> getHeaderFieldConfigsByRowType()
      These represent the fields expected for this specification. For consistency, this map should ideally be backing the implementation of getRequiredHeaders(String). It should be instantiated in the constructor of the underlying specification object.

      The key of the top level map is the row type, and the value is itself a map from header name to field config. This enables validation to only enforce certain field requirements in specific row types. Implementations may decide to use ordered maps such as LinkedHashMap to force a certain iteration order behind the scenes.

      If the import type represented by this specification doesn't have the concept of multiple row types, then field configs should be added here under the getMainRecordType().

      The default implementation in this interface will be removed at the time getFieldConfigMap() is removed, with the expectation that a real map will be backing the implementation.

      Implementations that want to add custom mappings for 'meta' fields such as ROW_DETERMINATION_COLUMN should ensure to also update methods such as resolveAndRemoveRecordType(Map) and resolveRecordTypeBeforePropertyMapping(Map) for consistency.

      Returns:
      a map from row type to another map of headers to field configs. Ideally, the map should be fully immutable (including the nested maps) to prevent inadvertent modification by consumers.
      See Also:

    • mapDynamicHeaderToField

      @Nullable default String mapDynamicHeaderToField(String header, String rowType)
      The specification may support dynamic header-field mappings beyond any hardcoded configuration in getHeaderFieldConfigsByRowType(). If so, then this method should be overridden to attempt performing such mappings on the given header for the given row type. If the mapping is successful, the mapped field should be returned, else null.

      Typically, any hard-coded mappings in getHeaderFieldConfigsByRowType() should take precedence over this, so consumers should check for a mapping there first.

      Parameters:
      header - the raw input header that needs to be mapped to a field
      rowType - the row type that this mapping is being performed for
      Returns:
      the mapped field if supported, else null
      See Also:

    • mapDynamicFieldToHeader

      @Nullable default String mapDynamicFieldToHeader(String field, String rowType)
      Similar to mapDynamicHeaderToField(String, String), but for reverse mappings from field names back to header names.
      Parameters:
      field - the raw field that needs to be mapped back to a header
      rowType - the row type that this mapping is being performed for
      Returns:
      the mapped header if supported, else null
      See Also:

    • getRequiredHeaders

      @Deprecated(since="1.8.1", forRemoval=true) Set<String> getRequiredHeaders()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This should represent the required headers that will be validated for _all_ row types. For consistency, the implementation of this should be backed by getFieldConfigMap().
      Returns:
      the list of required headers for all row types
      See Also:

    • getRequiredHeaders

      default Set<String> getRequiredHeaders(String rowType)
      Gets all the required headers for the provided row type. Each row of the given type should be required to provide a value for each of the returned headers.

      For consistency, this should ideally be backed by the implementation of getHeaderFieldConfigsByRowType().

      The default implementation in this interface will be removed at the time getRequiredHeaders() is removed, with the expectation that a real getHeaderFieldConfigsByRowType() will be backing the implementation..

      Parameters:
      rowType - the row type to get the required headers for
      Returns:
      a list of required headers for the provided row type. Should be empty if there are no required headers.
      See Also:

    • getImportDataNormalizers

      default List<ImportDataNormalizer> getImportDataNormalizers()
      The list of ImportDataNormalizer that will be executed to pre-process the data parsed out from the file.
      Returns:
      the list of ImportDataNormalizer

    • getRequiredAuthorities

      List<String> getRequiredAuthorities()
      The list of required authorities necessary for carrying out a specific import. For example, a Product import requires you to be able to READ_PRODUCT, UPDATE_PRODUCT, and of course, CREATE_PRODUCT. So we need to be sure to check that a person has access to those authorities when they try to start a Product import.
      Returns:
      the list of required authorities

    • getRequiredScopes

      List<String> getRequiredScopes()
      The list of required scopes necessary for carrying out a specific import. This is required for the global-level imports to display the import types that match the current user's permissions.
      Returns:
      the list of required scopes

    • getName

      default String getName()
      This is an arbitrary name for the specification, potentially allowing more than one specification for a particular type for a particular tenant or application.

      It's possible for this to be used as the Import.getSpecificationRef().

      Returns:
      name of this ImportSpecification

    • isCatalogDiscriminated

      default boolean isCatalogDiscriminated()
      Whether or not the entity is catalog discriminated.
      Returns:
      true if the entity is catalog discriminated or false otherwise

    • isSandboxDiscriminated

      default boolean isSandboxDiscriminated()
      Whether or not the entity is sandbox discriminated.
      Returns:
      true if the entity is sandbox discriminated or false otherwise

    • parentEntityIdRequiredInRequest

      default boolean parentEntityIdRequiredInRequest()
      Certain imports support the concept of Import.getParentEntityId(). In some of these cases, it may be desirable to require a value be provided for this in ImportRequest.getParentEntityId().

      This method allows the specification to describe whether the initial ImportRequest.getParentEntityId() should be required to have a value. If this is set to true, then any requests that do not provide a value will be rejected.

      Returns:
      whether imports for this specification must supply ImportRequest.getParentEntityId()
      Since:
      1.8.2
      See Also: