| /******************************************************************************* |
| * Copyright (c) 2012, 2013 Obeo. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * Obeo - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.emf.compare.match; |
| |
| import java.util.List; |
| |
| import org.eclipse.emf.common.util.Monitor; |
| import org.eclipse.emf.compare.Comparison; |
| import org.eclipse.emf.compare.scope.IComparisonScope; |
| |
| /** |
| * This class defines the general contract of a Matching engine. We expect subclasses to have a public, |
| * no-argument default constructor for instantiation. |
| * <p> |
| * We generally expect that a call to {@link #match(IComparisonScope)} will return us every single |
| * {@link org.eclipse.emf.compare.Match matches} that can be determined from the given |
| * {@link IComparisonScope context}. This includes all three of : |
| * <ul> |
| * <li>Elements that are present on all three sides of the comparison scope,</li> |
| * <li>Elements that are present on only two sides,</li> |
| * <li>Elements that are only present on a single side.</li> |
| * </ul> |
| * </p> |
| * <p> |
| * Clients can subclass the {@link DefaultMatchEngine default implementation} when all that is needed is to |
| * change the matching strategy. |
| * </p> |
| * |
| * @author <a href="mailto:laurent.goubet@obeo.fr">Laurent Goubet</a> |
| * @see DefaultMatchEngine |
| */ |
| public interface IMatchEngine { |
| |
| /** |
| * This is the entry point of a Comparison process. It is expected to use the provided scope in order to |
| * determine all objects that need to be matched. |
| * <p> |
| * The returned Comparison should include both matched an unmatched objects. It is not the match engine's |
| * responsibility to determine differences between objects, only to match them together. |
| * </p> |
| * |
| * @param scope |
| * The comparison scope that should be used by this engine to determine the objects to match. |
| * @param monitor |
| * The monitor to report progress or to check for cancellation |
| * @return An initialized {@link Comparison} model with all matches determined. |
| */ |
| Comparison match(IComparisonScope scope, Monitor monitor); |
| |
| /** |
| * Wrapper describing the given match engine. |
| * |
| * @author <a href="mailto:axel.richard@obeo.fr">Axel Richard</a> |
| * @since 3.0 |
| */ |
| interface Factory { |
| |
| /** |
| * Returns the wrapped match engine. |
| * |
| * @return the wrapped match engine. |
| */ |
| IMatchEngine getMatchEngine(); |
| |
| /** |
| * Returns the ranking of this match engine factory. |
| * |
| * @return The ranking. |
| * @since 3.0 |
| */ |
| int getRanking(); |
| |
| /** |
| * Set the ranking of this match engine factory. |
| * |
| * @param parseInt |
| * The ranking. |
| * @since 3.0 |
| */ |
| void setRanking(int parseInt); |
| |
| /** |
| * Check if the match engine factory is a good candidate for comparison. |
| * |
| * @param scope |
| * The scope on which the match engine factory will be applied. |
| * @return True if it is the good candidate, false otherwise. |
| * @since 3.0 |
| */ |
| boolean isMatchEngineFactoryFor(IComparisonScope scope); |
| |
| /** |
| * A registry of {@link IMatchEngine.Factory}. |
| * |
| * @since 3.0 |
| */ |
| interface Registry { |
| |
| /** |
| * Returns the match engine factory, for the given scope, owning the highest ranking. |
| * |
| * @param scope |
| * The given scope. |
| * @return The found match engine factory. |
| */ |
| IMatchEngine.Factory getHighestRankingMatchEngineFactory(IComparisonScope scope); |
| |
| /** |
| * Returns the list of {@link IMatchEngine.Factory} contained in the registry. |
| * |
| * @param scope |
| * The scope on which the match engine factories will be applied. |
| * @return The list of {@link IMatchEngine.Factory} contained in the registry. |
| */ |
| List<IMatchEngine.Factory> getMatchEngineFactories(IComparisonScope scope); |
| |
| /** |
| * Add to the registry the given {@link IMatchEngine.Factory}. |
| * |
| * @param matchEngineFactory |
| * The given {@link IMatchEngine.Factory}. |
| * @return The previous value associated with the class name of the given |
| * {@link IMatchEngine.Factory}, or null if there was no entry in the registry for the |
| * class name. |
| */ |
| IMatchEngine.Factory add(IMatchEngine.Factory matchEngineFactory); |
| |
| /** |
| * Remove from the registry the {@link IMatchEngine.Factory} designated by the given |
| * {@link String} . |
| * |
| * @param className |
| * The given {@link String} representing a {@link IMatchEngine.Factory}. |
| * @return The {@link IMatchEngine.Factory} designated by the given {@link String}. |
| */ |
| IMatchEngine.Factory remove(String className); |
| |
| /** |
| * Clear the registry. |
| */ |
| void clear(); |
| } |
| } |
| } |