org.eclipse.viatra2.gtasm.patternmatcher/src/org/eclipse/viatra2/gtasm/patternmatcher/patterns/IPatternMatcher.java

/*******************************************************************************
 * Copyright (c) 2004-2008 Peter Pasztor, Akos Horvath, Gergely Varro, Istvan Rath and Daniel Varro
 * 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:
 *    Peter Pasztor, Akos Horvath, Gergely Varro, Istvan Rath - initial API and implementation
 *******************************************************************************/

package org.eclipse.viatra2.gtasm.patternmatcher.patterns;

import java.util.Collection;

import org.eclipse.viatra2.gtasm.interpreter.exception.ViatraTransformationException;
import org.eclipse.viatra2.gtasm.patternmatcher.IMatching;
import org.eclipse.viatra2.gtasm.patternmatcher.PatternCallSignature;


/*
 * TODO The interpreted engine uses the following mappings: VariableType =>
 * PatternVariable ValueType => AnyModelElement
 */

/**
 * The runtime representation of a pattern, which can execute pattern matching
 * in interpreted mode. This interface is used by the ASM interpreter for
 * performing pattern matching.
 * 
 * @author Gergely Varro
 */
public interface IPatternMatcher {
	/**
	 * Returns <code>true</code> if this pattern matcher is able to find a
	 * matching for the pattern it represents by taking into account all the
	 * initial mapping and pattern scope restrictions.
	 * 
	 * @param inputMapping
	 *            the array of model elements that constitute the input mapping.
	 *            The position of a binding for a given pattern variable is
	 *            defined by the position of the same pattern variable in the
	 *            pattern declaration.
	 * @return <code>true</code> if this pattern matcher is able to find a
	 *         matching for the pattern it represents.
	 * @throws ViatraTransformationException 
	 */
	public boolean match(Object[] inputMapping)
			throws ViatraTransformationException;

	/*
	 * TODO If any of the variables is called in forall mode an exception is
	 * thrown.
	 */
	/**
	 * Returns a matching being found by this pattern matcher by using the
	 * invocation mode specified by the pattern call signature during the
	 * execution and by taking into account all the initial mapping and pattern
	 * scope restrictions.
	 * 
	 * @param inputMapping
	 *            the array of model elements that constitute the input mapping.
	 *            The position of a binding for a given pattern variable is
	 *            defined by the position of the same pattern variable in the
	 *            pattern declaration.
	 * @param signature
	 *            the array of variable signatures. The order of signatures
	 *            should be the same as the order of pattern variables in the
	 *            pattern declaration from which this pattern matcher has been
	 *            derived.
	 * @return the matching that has been found by this pattern matcher.
	 * @throws ViatraTransformationException 
	 */
	public IMatching match(Object[] inputMapping,
			PatternCallSignature[] signature) throws ViatraTransformationException;
	/*
	 * TODO If any of the variables is called in forall mode an exception is
	 * thrown.
	 */
	/**
	 * Returns a matching being found by this pattern matcher by using the
	 * invocation mode specified by the pattern call signature during the
	 * execution and by taking into account all the initial mapping and pattern
	 * scope restrictions.
	 * 
	 * In case of multiple pattern matchings, true pseudorandom choice is mandatory.
	 * 
	 * @param inputMapping
	 *            the array of model elements that constitute the input mapping.
	 *            The position of a binding for a given pattern variable is
	 *            defined by the position of the same pattern variable in the
	 *            pattern declaration.
	 * @param signature
	 *            the array of variable signatures. The order of signatures
	 *            should be the same as the order of pattern variables in the
	 *            pattern declaration from which this pattern matcher has been
	 *            derived.
	 * @return the matching that has been found by this pattern matcher.
	 * @throws ViatraTransformationException 
	 */
	public IMatching matchRandomly(Object[] inputMapping,
			PatternCallSignature[] signature) throws ViatraTransformationException;
	
	/**
	 * Returns the collection of matchings being found by this pattern matcher
	 * by using the invocation mode specified by the pattern call signature
	 * during the execution and by taking into account all the initial mapping
	 * and pattern scope restrictions.
	 * 
	 * @param inputMapping
	 *            the array of model elements that constitute the input mapping.
	 *            The position of a binding for a given pattern variable is
	 *            defined by the position of the same pattern variable in the
	 *            pattern declaration from which this pattern matcher has been
	 *            derived.
	 * @param signature
	 *            the array of variable signatures. The order of signatures
	 *            should be the same as the order of pattern variables in the
	 *            pattern declaration from which this pattern matcher has been
	 *            derived.
	 * @param quantificationOrder
	 * @return the collection of matchings that have been found by this pattern
	 *         matcher.
	 * @throws ViatraTransformationException 
	 */
	public Collection<IMatching> matchAll(Object[] inputMapping,
			PatternCallSignature[] signature, Integer[] quantificationOrder)
			throws ViatraTransformationException;
}