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

Interface IComparisonSession

All Superinterfaces:
IProgressMonitorContainer
All Known Implementing Classes:
ComparisonSession
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:

  • Method Details

    • 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

    • isInInputScope

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

    • isInInputScope

      boolean isInInputScope(String symlink, ComparisonSide side)
      Checks whether the specified symbolic link satisfies the input comparison scope (before the scope was extended) on the specified side.
      Parameters:
      symlink - the symbolic link to check, cannot be null
      side - the side to which symbolic link relates to, cannot null
      Returns:
      true if the symbolic link is within the input 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

    • addComparisonTreeListener

      void addComparisonTreeListener(IComparisonSession.IComparisonTreeListener listener)
      Adds a comparison result listener.
      Parameters:
      listener - the result listener, not 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

    • 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