Package org.odpi.openmetadata.frameworks.integration.bitol.mapping

Class BitolMapperBase

java.lang.Object
org.odpi.openmetadata.frameworks.integration.bitol.mapping.BitolMapperBase
Direct Known Subclasses:
DataContractMapper, DataProductMapper
public abstract class BitolMapperBase extends Object
BitolMapperBase holds the mapping logic that is shared by the Open Data Contract Standard (ODCS) and Open Data Product Standard (ODPS) mappers: the fundamentals of a document (identity, status, description, tags), custom properties, authoritative definitions, support channels and teams. The mappers work through the connector context clients so that they can run inside an integration connector (through the IntegrationContext) or inside a view service that builds a ConnectorContextBase for the calling user.

Every element created from a document has a deterministic qualifiedName built from the document's identifier and version, so that republishing a document updates the existing elements rather than duplicating them, and each version of a document is a distinct element. The document identifier is also recorded as an ExternalId shared by all versions.

  • Field Details

    • ADDITIONAL_PROPERTY_PREFIX

      public static final String ADDITIONAL_PROPERTY_PREFIX
      Prefix used in additionalProperties for values that have no home in the open metadata types.
      See Also:

    • EGERIA_VENDOR

      public static final String EGERIA_VENDOR
      Vendor attribution given to the custom properties that carry Egeria's own properties in a Bitol document. These entries are restored to their open metadata properties when the document is catalogued, rather than being kept as additional properties.
      See Also:

    • EGERIA_CATEGORY

      public static final String EGERIA_CATEGORY
      See Also:

    • EGERIA_DEPLOYMENT_STATUS

      public static final String EGERIA_DEPLOYMENT_STATUS
      See Also:

    • EGERIA_USER_DEPLOYMENT_STATUS

      public static final String EGERIA_USER_DEPLOYMENT_STATUS
      See Also:

    • EGERIA_MATURITY

      public static final String EGERIA_MATURITY
      See Also:

    • EGERIA_SERVICE_LIFE

      public static final String EGERIA_SERVICE_LIFE
      See Also:

    • EGERIA_INTRODUCTION_DATE

      public static final String EGERIA_INTRODUCTION_DATE
      See Also:

    • EGERIA_NEXT_VERSION_DATE

      public static final String EGERIA_NEXT_VERSION_DATE
      See Also:

    • EGERIA_WITHDRAW_DATE

      public static final String EGERIA_WITHDRAW_DATE
      See Also:

    • EGERIA_PRODUCT_FAMILIES

      public static final String EGERIA_PRODUCT_FAMILIES
      See Also:

    • EGERIA_QUESTIONS

      public static final String EGERIA_QUESTIONS
      See Also:

    • EGERIA_LICENSE_TYPES

      public static final String EGERIA_LICENSE_TYPES
      See Also:

    • EGERIA_SERVICE_LEVELS

      public static final String EGERIA_SERVICE_LEVELS
      See Also:

    • EGERIA_PROCESS_QUALIFIED_NAME

      public static final String EGERIA_PROCESS_QUALIFIED_NAME
      See Also:

    • EGERIA_PROCESS_TYPE

      public static final String EGERIA_PROCESS_TYPE
      See Also:

    • EGERIA_ASSEMBLES

      public static final String EGERIA_ASSEMBLES
      See Also:

    • DATA_LINEAGE_TYPE_NAMES

      public static final List<String> DATA_LINEAGE_TYPE_NAMES
      The lineage relationships that carry data from a process into the data it assembles, and into a process from the data it reads. The data flows from end 1 to end 2 of each of them.

    • INPUT_CONTRACT_SUFFIX

      public static final String INPUT_CONTRACT_SUFFIX
      Suffix of the identifier of the draft data contract created for the data that a process reads.
      See Also:

    • DRAFT_CONTRACT_VERSION

      public static final String DRAFT_CONTRACT_VERSION
      Version of a draft data contract.
      See Also:

    • CUSTOM_PROPERTIES_JSON

      public static final String CUSTOM_PROPERTIES_JSON
      Name of the additional property that holds the full custom properties list as JSON when an entry carries a vendor, description or id.
      See Also:

    • CONTEXT_JSON

      public static final String CONTEXT_JSON
      Name of the additional property that holds the AI context block as JSON.
      See Also:

    • SYNONYMS_JSON

      public static final String SYNONYMS_JSON
      Name of the additional property that holds the synonyms as JSON.
      See Also:

    • DEPRECATED

      public static final String DEPRECATED
      Name of the additional property that records that an element is deprecated.
      See Also:

    • SEPARATOR

      public static final String SEPARATOR
      See Also:

    • context

      protected final ConnectorContextBase context

  • Constructor Details

    • BitolMapperBase

      protected BitolMapperBase(ConnectorContextBase context)
      Constructor.
      Parameters:
      context - connector context providing access to the open metadata clients

  • Method Details

    • getDocumentQualifiedName

      public static String getDocumentQualifiedName(String kind, String id, String version)
      Build the qualified name for the element that represents a document version.
      Parameters:
      kind - kind of document
      id - document identifier
      version - document version (may be null)
      Returns:
      qualified name

    • getExternalIdQualifiedName

      public static String getExternalIdQualifiedName(String kind, String id)
      Build the qualified name for the ExternalId that carries a document identifier. It is shared by all versions.
      Parameters:
      kind - kind of document
      id - document identifier
      Returns:
      qualified name

    • findElementGUID

      protected String findElementGUID(String qualifiedName) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return the unique identifier of the element with the supplied qualified name, or null if there is none.
      Parameters:
      qualifiedName - qualified name to look for
      Returns:
      guid or null
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • findElementsByDocumentId

      protected List<OpenMetadataRootElement> findElementsByDocumentId(String kind, String id) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return the elements identified by a document identifier, found through the ExternalId that all versions of the document share.
      Parameters:
      kind - kind of document
      id - document identifier
      Returns:
      list of elements (empty if none)
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • getLatestVersion

      protected OpenMetadataRootElement getLatestVersion(List<OpenMetadataRootElement> elements)
      Return the element with the highest version identifier from the supplied list. Versions are compared as dot-separated numbers where possible, otherwise as strings.
      Parameters:
      elements - candidate elements
      Returns:
      chosen element or null if the list is empty

    • fillFundamentals

      protected void fillFundamentals(BitolDocument document, AuthoredReferenceableProperties properties, String qualifiedName)
      Copy the fundamentals of a document into the properties of the element that represents it.
      Parameters:
      document - document
      properties - properties to fill
      qualifiedName - qualified name for the element

    • setContentStatus

      protected void setContentStatus(String status, AuthoredReferenceableProperties properties)
      Map a Bitol status onto the content status of an element. Values outside the standard set are recorded as OTHER with the original value in userDefinedContentStatus.
      Parameters:
      status - status from the document
      properties - properties to update

    • isRetired

      protected boolean isRetired(BitolDocument document)
      Return whether the document has been retired, in which case its element is deleted rather than maintained.
      Parameters:
      document - document
      Returns:
      boolean

    • addDescriptionDetails

      protected void addDescriptionDetails(BitolDescription description, Map<String,String> additionalProperties)
      Copy the limitations and usage of a description into additional properties.
      Parameters:
      description - description structure (may be null)
      additionalProperties - map to add to

    • addCustomProperties

      protected void addCustomProperties(List<BitolCustomProperty> customProperties, Map<String,String> additionalProperties)
      Copy custom properties into additional properties. Values that are not simple strings are rendered with toString so that lists and structures are still visible.
      Parameters:
      customProperties - custom properties from the document (may be null)
      additionalProperties - map to add to

    • isEgeriaProperty

      protected static boolean isEgeriaProperty(BitolCustomProperty customProperty)
      Return whether a custom property carries one of Egeria's own properties.
      Parameters:
      customProperty - custom property from a document
      Returns:
      boolean

    • getEgeriaValues

      protected static Map<String,Object> getEgeriaValues(List<BitolCustomProperty> customProperties)
      Return the values of the custom properties attributed to Egeria, keyed by property name.
      Parameters:
      customProperties - custom properties from a document (may be null)
      Returns:
      map of property name to value (empty if there are none)

    • getEgeriaString

      protected static String getEgeriaString(Map<String,Object> egeriaValues, String name)
      Return a string value from the Egeria custom properties.
      Parameters:
      egeriaValues - values from getEgeriaValues
      name - property name
      Returns:
      value or null

    • getEgeriaDate

      protected static Date getEgeriaDate(Map<String,Object> egeriaValues, String name)
      Return a date value from the Egeria custom properties. Dates are written as ISO-8601 instants.
      Parameters:
      egeriaValues - values from getEgeriaValues
      name - property name
      Returns:
      date or null if absent or unreadable

    • canonical

      protected static <E extends Enum<E>> String canonical(String value, E standard)
      Return the standard spelling of a vocabulary value when it is one of the standard values, otherwise the value as written in the document. The enumerations are also registered as valid metadata values by the Core Content Pack, so a standard value stored this way matches the valid value exactly.
      Type Parameters:
      E - enumeration type
      Parameters:
      value - value from the document (may be null)
      standard - the enumeration matched from the value, or null if it is not a standard value
      Returns:
      canonical value or the original

    • putIfPresent

      protected static void putIfPresent(Map<String,String> additionalProperties, String name, String value)
      Add a value to the additional properties under the bitol prefix if it is present.
      Parameters:
      additionalProperties - map to add to
      name - property name (without prefix)
      value - value (may be null)

    • toJSON

      protected String toJSON(Object bean)
      Format a bean (or list of beans) from a document as a JSON fragment for an additional property, so that it can be regenerated without loss.
      Parameters:
      bean - bean (may be null)
      Returns:
      json text or null

    • toStringValue

      protected String toStringValue(Object value)
      Return a value from a document as a string for additionalProperties.
      Parameters:
      value - value (may be null)
      Returns:
      string or null

    • linkExternalId

      protected void linkExternalId(String kind, String id, String elementGUID, String source) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Record the document identifier as an ExternalId linked to the element. The ExternalId is shared by all versions of the document, so it is created once and linked to each version's element.
      Parameters:
      kind - kind of document
      id - document identifier
      elementGUID - element representing this version
      source - description of where the document came from
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • addSearchKeywords

      protected void addSearchKeywords(List<String> tags, String elementGUID) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Attach the document's tags to the element as search keywords.
      Parameters:
      tags - tags from the document (may be null)
      elementGUID - element to tag
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • getSearchKeywords

      protected Set<String> getSearchKeywords(String elementGUID) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return the names of the search keywords attached to an element.
      Parameters:
      elementGUID - element to query
      Returns:
      set of keyword names (may be empty)
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • getLinkedElementGUIDs

      protected Set<String> getLinkedElementGUIDs(String elementGUID, int startingAtEnd, String relationshipTypeName) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Return the unique identifiers of the elements linked to an element by a type of relationship.
      Parameters:
      elementGUID - element to query
      startingAtEnd - the end of the relationship where the element sits (1 or 2)
      relationshipTypeName - type of relationship
      Returns:
      set of guids (may be empty)
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • linkTenantOrganization

      protected void linkTenantOrganization(String tenant, String elementGUID) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Link the element to the organization named as the document's tenant, creating the organization profile if it is not already known. The element is scoped by the organization.
      Parameters:
      tenant - tenant from the document (may be null)
      elementGUID - element to link
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • linkAuthoritativeDefinitions

      protected void linkAuthoritativeDefinitions(List<BitolAuthoritativeDefinition> authoritativeDefinitions, String elementGUID) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Link the element to external references for the document's authoritative definitions, creating each reference if its URL is not already known.
      Parameters:
      authoritativeDefinitions - definitions from the document (may be null)
      elementGUID - element to link
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • linkSupportChannels

      protected void linkSupportChannels(List<BitolSupportChannel> supportChannels, String elementGUID, String elementQualifiedName) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Create contact details for each of the document's support channels and link them to the element. The contact details are anchored to the element so they are removed with it.
      Parameters:
      supportChannels - channels from the document (may be null)
      elementGUID - element to link
      elementQualifiedName - qualified name of the element (used to build the contact details' names)
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • getContactMethodType

      protected ContactMethodType getContactMethodType(String tool)
      Map a Bitol support tool onto a contact method type.
      Parameters:
      tool - tool from the document (may be null)
      Returns:
      enum

    • linkTeam

      protected void linkTeam(BitolTeam team, String elementGUID, String elementQualifiedName, BitolMappingResult result) throws InvalidParameterException, PropertyServerException, UserNotAuthorizedException
      Create the team and the roles for the team members described in the document. The team is a Team profile named from the document; each member becomes a PersonRole scoped to the element (ScopedBy). Where the member's username is known to Egeria as a user identity with a profile, the profile is appointed to the role; otherwise the username and name are recorded on the role's additional properties and reported as a warning.
      Parameters:
      team - team from the document (may be null)
      elementGUID - element that the roles are scoped to
      elementQualifiedName - qualified name of the element (used to build the roles' names)
      result - result to record warnings in
      Throws:
      InvalidParameterException - invalid parameter
      PropertyServerException - problem with the metadata store
      UserNotAuthorizedException - security problem

    • parseDate

      protected Date parseDate(String value)
      Parse an ISO date (yyyy-MM-dd) from the document.
      Parameters:
      value - date string (may be null)
      Returns:
      date or null if missing or malformed