Package com._1c.g5.v8.dt.compare.core

Interface IComparisonSession

  • All Superinterfaces:
    IProgressMonitorContainer
    public interface IComparisonSession
extends IProgressMonitorContainer
    The comparison session associated with a specific comparison process (defined by its handle).

    Comparison sessions are entities granting access to the comparison model and various high-level operations with it and with the comparison environment. Also, they allow to subscribe to model events.

    Comparison sessions are managed by the comparison manager. It creates a session when a comparison process is started for the specified handle, and discards it either when the merge process based on that session was successfully finished, or a client asks to stop the session's comparison process with discarding.

    See Also:
    IComparisonManager

    • Method Detail

      • getHandle

        ComparisonProcessHandle getHandle()
        Returns the handle of the comparison process this session is associated with.
        Returns:
        the handle, never null

      • getSettings

        IComparisonProcessSettings getSettings()
        Returns the settings that were specified when the session was started.
        Returns:
        the session settings

      • isGlobalScope

        boolean isGlobalScope()
        Checks whether the scope of comparison of the session is global, that is, its settings do not specify any scope object on any side.
        Returns:
        true if the session comparison scope is global, and false otherwise

      • getStatus

        ComparisonProcessStatus getStatus()
        Returns the status of the comparison process.
        Returns:
        the status, never null

      • getDataSource

        IComparisonDataSource getDataSource​(ComparisonSide side)
        Returns the comparison data source by its side.
        Parameters:
        side - the side of the data source, not null
        Returns:
        the data source, may be null when trying to get the common ancestor of a two-way comparison

      • getNode

        ComparisonNode getNode​(long nodeId)
        Returns a result node by the specified id.
        Parameters:
        nodeId - the node id
        Returns:
        the node or null if no node exists with such id in the model

      • getNode

        ComparisonNode getNode​(ComparisonContext comparisonContext,
                       long nodeId)
        Returns a result node by the specified id.
        Parameters:
        comparisonContext - the comparison context, not null
        nodeId - the node id
        Returns:
        the node or null if no node exists with such id in the model

      • getTopNode

        TopComparisonNode getTopNode​(String symlink,
                             ComparisonSide side)
        Returns a top node by the specified symbolic link.
        Parameters:
        symlink - the symbolic link, not null
        side - the side to search at, can not be null
        Returns:
        the top node or null if didn't find it

      • getTopNodeOf

        TopComparisonNode getTopNodeOf​(long nodeId)
        Returns a top-level parent node of the node with the specified id.
        Parameters:
        nodeId - the node id to find top parent for
        Returns:
        the top node or null if no such node found

      • getTopNodeOf

        TopComparisonNode getTopNodeOf​(ComparisonNode node)
        Returns a top-level parent node of the given node.
        Parameters:
        node - the node to find top parent for
        Returns:
        the top node or null if no such node found

      • isInScope

        boolean isInScope​(ComparisonNode node)
        Checks whether the specified node lies within the scope of comparison of this session.
        Parameters:
        node - the node to check, cannot be null
        Returns:
        true if the node is within scope, and false otherwise

      • isInScope

        boolean isInScope​(String symlink,
                  ComparisonSide side)
        Checks whether the specified symbolic link satisfies the scope of comparison on the specified side, that is, is leading to, included into, or coming from the scope of comparison.
        Parameters:
        symlink - the symbolic link to check
        side - the side to which symbolic link relates to, not null
        Returns:
        true if the symbolic link is within scope, false otherwise

      • getRootNode

        RootComparisonNode getRootNode()
        Returns the root of the comparison result tree.
        Returns:
        the root of the comparison result tree.

      • getMatchingStrategy

        MatchingStrategy getMatchingStrategy​(ComparisonSide firstSide,
                                     ComparisonSide secondSide)
        Returns the matching strategy used between the specified sides.

        The method is symmetrical, i. e. getMatchingStrategy(a, b) == getMatchingStrategy(b, a).

        Parameters:
        firstSide - the first side of the comparison, not null
        secondSide - the second side of the comparison, not null
        Returns:
        the matching strategy, never null

      • getDirectCorrespondence

        String getDirectCorrespondence​(String source,
                               ComparisonSide sourceSide,
                               ComparisonSide targetSide)
        Returns the symbolic link corresponding to the given source symbolic link in the direction defined by the specified comparison sides.

        The method will always return null if the source is excluded from the comparison in the specified direction.

        The method is symmetric in the sense that if A2 == getDirectCorrespondence(A1, side1, side2), then A1 == getDirectCorrespondence(A2, side2, side1).

        Parameters:
        source - the string with the source symbolic link, not null
        sourceSide - the source side, not null
        targetSide - the target side, not null
        Returns:
        the string with the target symbolic link or null if no direct correspondence is set

      • isExcluded

        boolean isExcluded​(String source,
                   ComparisonSide sourceSide,
                   ComparisonSide targetSide)
        Checks if the specified symbolic link is explicitly excluded from matching in the specified direction.
        Parameters:
        source - the source symbolic link, not null
        sourceSide - the source side, not null
        targetSide - the target side, not null
        Returns:
        true if the link is excluded from matching, and false otherwise

      • isThreeWay

        boolean isThreeWay()
        Checks whether the comparison session is three-way.
        Returns:
        true if the comparison session is three-way, and false if it is two-way

      • areExplicitCorrespondencesSet

        boolean areExplicitCorrespondencesSet​(ComparisonSide sourceSide,
                                      ComparisonSide targetSide)
        An optimization flag indicating whether explicit correspondence settings are set for the specified direction.
        Parameters:
        sourceSide - the source side of the direction
        targetSide - the target side of the direction
        Returns:
        true if explicit correspondence are set, and false otherwise

      • addChild

        void addChild​(ComparisonNode parentNode,
              ComparisonNode childNode,
              IComparedObjects<?> comparedObjects)
        Adds the specified child node to the specified parent node. If a triple of compared objects is given, it is stored in cache for future fast access by getComparedObjects(ComparisonNode, ComparisonContext) method.
        Parameters:
        parentNode - the parent node, cannot be null
        childNode - the child node to be added, cannot be null
        comparedObjects - the objects being compared by the child node to put in cache, can be null

      • setMustBeMerged

        boolean setMustBeMerged​(long nodeId,
                        boolean mustBeMerged,
                        boolean force)
        Sets the "Merge" flag value to the specified node and to all its children. The flag can be set only when comparison process has been finished.
        Parameters:
        nodeId - the node id
        mustBeMerged - the value to set
        force - true if we want to force change even if merge rule forbids this
        Returns:
        true if the flag set successfully, false otherwise

      • setMergeRule

        boolean setMergeRule​(long nodeId,
                     MergeRule rule,
                     ComparisonContext comparisonContext)
        Sets the given merge rule to the specified node. The rule can be set only when comparison process has been finished.
        Parameters:
        nodeId - the node id
        rule - the merge rule to set, cannot be null
        comparisonContext - current comparison operation context, cannot be null
        Returns:
        true if the rule set successfully, false otherwise

      • setOrderSide

        boolean setOrderSide​(long nodeId,
                     ComparisonSide orderSide,
                     ComparisonContext comparisonContext)
        Sets the order side to be used for children ordering for the specified node. The node must support ordering of its children. The method should be called only when comparison process has been finished.
        Parameters:
        nodeId - the node id
        orderSide - the order side to set, can be either MAIN or OTHER, cannot be null
        comparisonContext - current comparison operation context, cannot be null
        Returns:
        true if the side set successfully, false otherwise

      • setCustomMergeSettings

        void setCustomMergeSettings​(long nodeId,
                            CustomMergeSettings settings,
                            ComparisonContext comparisonContext)
        Sets node's custom merge settings.
        Parameters:
        nodeId - the node id
        settings - the custom merge settings to set, cannot be null
        comparisonContext - current comparison operation context, cannot be null

      • removeComparisonTreeListener

        void removeComparisonTreeListener​(IComparisonSession.IComparisonTreeListener listener)
        Removes a comparison result listener.
        Parameters:
        listener - the result listener, not null

      • getTopNodeStatus

        ComparisonNodeStatus getTopNodeStatus​(long nodeId)
        Returns the comparison status of the specified top-level node.
        Parameters:
        nodeId - the node identifier to get status for, must specify the top-level node
        Returns:
        the node comparison status, never null

      • removeChild

        void removeChild​(ComparisonNode parentNode,
                 ComparisonNode childNode)
        Removes the specified child from the specified parent node.
        Parameters:
        parentNode - the parent node from which to remove the child, not null
        childNode - the child node to remove from the parent node, not null

      • removeChildren

        void removeChildren​(ComparisonNode node)
        Recursively removes all children of the specified node.
        Parameters:
        node - the node for which to remove all its children, not null

      • setCorrespondence

        boolean setCorrespondence​(String mainSymlink,
                          String otherSymlink,
                          String ancestorSymlink)
        Sets correspondence between two symbolic links and common ancestor (optional). The correspondence can be set only when there is no active comparison process. The call of this method causes an automatic start of a new comparison process.
        Parameters:
        mainSymlink - the main symbolic link, may be null
        otherSymlink - the other symbolic link, may be null
        ancestorSymlink - the ancestor symbolic link (optional), may be null
        Returns:
        true if the correspondence set successfully, false otherwise

      • adoptExternalProperty

        boolean adoptExternalProperty​(ExternalPropertyComparisonData extPropData)
        Adopts the given external property if possible. If adopting is possible, the method fills the provided comparison data container by data to be used for adoption.
        Parameters:
        extPropData - the data of the external property to be adopted, cannot be null
        Returns:
        true if adopting is possible, false otherwise

      • prioritize

        void prioritize​(List<Long> nodeIds)
        Asks the session to prioritize the comparison of the specified list of nodes.
        Parameters:
        nodeIds - the ids of the nodes to prioritize their comparison, not null

      • clearCaches

        void clearCaches​(ComparisonNode node)
        Clears compared object cache for the specified node.
        Parameters:
        node - the node to clear the compared object cache for

      • getComparedObjects

        IComparedObjects<?> getComparedObjects​(ComparisonNode node,
                                       ComparisonContext comparisonContext)
        Returns a triple of compared objects for the specified node. Note: it may work slower than #getComparedObjects(ComparisonNode, ComparedEmfObjects) because it has to obtain the top parents triple first. Use that method if the top parents triple is already known.
        Parameters:
        node - the node to get the triple of compared objects for, cannot be null
        comparisonContext - the comparison context, not null
        Returns:
        the compared objects triple, never null

      • getComparedObjects

        IComparedObjects<?> getComparedObjects​(ComparisonNode node,
                                       AbstractComparedEmfObjects<?> topParents,
                                       ComparisonContext comparisonContext)
        Returns a triple of compared objects for the specified node. Uses triple of top parents if they are given to speed up objects obtaining.
        Parameters:
        node - the node to get the triple of compared objects for, cannot be null
        parentTriple - the triple of top parents or null if they are not known
        comparisonContext - the comparison context, not null
        Returns:
        the compared objects triple, never null

      • getSymlinkTranslator

        ISymlinkTranslator getSymlinkTranslator()
        Returns the symbolic link translator serving this session.
        Returns:
        the symbolic link translator

      • getResourceStore

        IResourceStore getResourceStore()
        Returns the resource store accessible within the session.
        Returns:
        the resource store

      • getComparisonProcessStore

        IComparisonProcessStore getComparisonProcessStore()
        Returns the comparison process store of this session.
        Returns:
        the comparison process store

      • getId

        int getId()
        Gets the id of this comparison session.
        Returns:
        the comparison session id

      • getProjectName

        String getProjectName​(ComparisonSide side)
        Returns the given side project name.
        Parameters:
        side - the comparison side, can not be null
        Returns:
        the given side project name, may be null

      • setIntegrationContext

        void setIntegrationContext​(IntegrationContext integrationContext)
        Sets the integration settings context for the comparison session
        Parameters:
        integrationContext - The integration settings context. Could be null

      • getIntegrationContext

        IntegrationContext getIntegrationContext()
        Gets the integration settings context being associated with the comparison session
        Returns:
        The associated integration settings context, if any. null otherwise

      • getEClassById

        org.eclipse.emf.ecore.EClass getEClassById​(int id)
        Gets EClass by its identifier returned by getEClassId(org.eclipse.emf.ecore.EClass) method.
        Parameters:
        id - the identifier to get EClass by.
        Returns:
        the EClass identified by the specified id or null if doesn't exist

      • getEClassId

        int getEClassId​(org.eclipse.emf.ecore.EClass eClass)
        Gets identifier assigned to the specified EClass.
        Parameters:
        eClass - the EClass to get identifier for, cannot be null
        Returns:
        the identifier assigned to the EClass

      • getMatchedObjectsEClass

        org.eclipse.emf.ecore.EClass getMatchedObjectsEClass​(long nodeId)
        Returns EClass of model objects the node relates to.
        Parameters:
        nodeId - the nodeId to return EClass for
        Returns:
        the EClass or null if the node doesn't relate to any model object

      • getMatchedObjectsEClass

        org.eclipse.emf.ecore.EClass getMatchedObjectsEClass​(ComparisonNode node)
        Returns EClass of model objects the node relates to.
        Parameters:
        node - the node to return feature for, may be null
        Returns:
        the EClass or null if the node is null or doesn't relate to any model object

      • getRelatedFeature

        org.eclipse.emf.ecore.EStructuralFeature getRelatedFeature​(long nodeId)
        Returns EStructuralFeature the node relates to.
        Parameters:
        nodeId - the nodeId to return feature for
        Returns:
        the feature or null if the node doesn't relate to any feature

      • getRelatedFeature

        org.eclipse.emf.ecore.EStructuralFeature getRelatedFeature​(ComparisonNode node)
        Returns EStructuralFeature the node relates to.
        Parameters:
        node - the node to return feature for, may be null
        Returns:
        the feature or null if the node doesn't relate to any feature

      • getParentCollectionFeature

        org.eclipse.emf.ecore.EStructuralFeature getParentCollectionFeature​(ComparisonNode node)
        Returns EStructuralFeature of the collection containing the object related to the given comparison node.
        Parameters:
        node - the node related to the collection element, may be be null
        Returns:
        the parent collection feature or null if the node doesn't relate to any collection element

      • isFeatureExcludedFromComparison

        boolean isFeatureExcludedFromComparison​(org.eclipse.emf.ecore.EStructuralFeature feature,
                                        AbstractComparedEmfObjects<?> comparedContextObjects)
        Tells whether the feature is excluded from the comparison process.
        Parameters:
        feature - the feature to check, cannot be null
        comparedContextObjects - the triple of compared objects, cannot be null
        Returns:
        true if the feature is excluded, false otherwise

      • runComparisonTreeReadonlyTask

        <T> T runComparisonTreeReadonlyTask​(IBmTask<T> task)
        Executes the given read-only BM task for a comparison tree of the specified session.
        Parameters:
        task - the task to execute, cannot be null
        Returns:
        the result returned by IBmTask.execute(IBmTransaction, IProgressMonitor) method

      • hasExtendedComparisonSettings

        boolean hasExtendedComparisonSettings​(String symlink)
        Checks if the provided symlink has an extended comparison settings associated with it. Extended settings are being supplied with external comparison configuration.
        Parameters:
        symlink - The target symlink, can be null
        Returns:
        True if the object pointed with the symlink has an extended comparison settings

      • adoptMainSideFeature

        org.eclipse.emf.ecore.EStructuralFeature adoptMainSideFeature​(org.eclipse.emf.ecore.EStructuralFeature mainSideFeature)
        Converts, if possible, the main side feature into a other supported by the other side object. Returns the given main side feature if no convert was found.
        Parameters:
        mainSideFeature - the main side feature to convert, cannot be null
        Returns:
        the converted feature applicable for other side object or given main side feature if no convert was found, never null

      • getComparedObjectsCorrespondences

        Collection<ObjectsTriple<String>> getComparedObjectsCorrespondences()
        Returns a collection of correspondences between compared objects.
        Returns:
        general list of correspondences in the form of pairs (main symlink, other symlink), never null

      • getNodesWithChangedMergeSettings

        Collection<Long> getNodesWithChangedMergeSettings()
        Returns a comparison tree node with serializable merge settings.
        Returns:
        Collection of node BM identifiers, never null

      • getSerializableNodeMergeSettings

        SerializableMergeSettings getSerializableNodeMergeSettings​(ComparisonNode node)
        Returns container of serializable merge settings of the given node.
        Parameters:
        node - the node to get container for, cannot be null
        Returns:
        the container of serializable merge settings, never null

      • hasPotentialMergeProblems

        boolean hasPotentialMergeProblems​(long nodeId)
        Tells whether the node may break the configuration if it is merged.
        Parameters:
        nodeId - the node Id to check
        Returns:
        true if the node may break the configuration, false otherwise

      • getPotentialMergeProblemsDescriptions

        List<PotentialMergeProblemDescription> getPotentialMergeProblemsDescriptions​(long nodeId,
                                                                             ComparisonContext comparisonContext)
        Returns human-readable descriptions of merge problems of the specified node.
        Parameters:
        node - the node to get merge problems descriptions for, cannot be null
        comparisonContext - the comparison context, cannot be null
        Returns:
        the list of descriptions, never null, can be empty if the node doesn't bring any merge problems

      • getPotentialMergeProblemsSourceNodes

        Collection<Long> getPotentialMergeProblemsSourceNodes()
        Returns collection of nodes that cause potential merge problems.
        Returns:
        the collection of such nodes, can be empty, never null

      • isFailedOnMergeUsingExternalTool

        boolean isFailedOnMergeUsingExternalTool​(long nodeId)
        Tells whether the merge using external tool failed for the specified node.
        Parameters:
        nodeId - the node id to check
        Returns:
        true if the merge using external tool failed, false otherwise