org.eclipse.viatra2.core2/src/org/eclipse/viatra2/framework/IFramework.java

/*******************************************************************************
 * Copyright (c) 2004-2009 Andras Schmidt, Andras Balogh, 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:
 *    Andras Schmidt, Andras Balogh, Istvan Rath - initial API and implementation
 *******************************************************************************/

package org.eclipse.viatra2.framework;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Collection;
import java.util.Map;
import java.util.Set;

import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.viatra2.codegen.CodeOutputPlugin;
import org.eclipse.viatra2.codegen.CodeOutputPluginFactory;
import org.eclipse.viatra2.core.IModelSpace;
import org.eclipse.viatra2.errors.VPMRuntimeException;
import org.eclipse.viatra2.framework.properties.VPMProperties;
import org.eclipse.viatra2.imports.NativeImporterFactory;
import org.eclipse.viatra2.interpreters.IProgressReport;
import org.eclipse.viatra2.interpreters.ModelInterpreterFactory;
import org.eclipse.viatra2.loaders.LoaderFactory;
import org.eclipse.viatra2.logger.Logger;
import org.eclipse.viatra2.logger.LoggerFactory;
import org.eclipse.viatra2.natives.INativeFunctionManager;
import org.eclipse.viatra2.tags.ITagManager;

/**
 *
 * Summary: Interface of the VPM modeling framework used by the GUI.
 *
 * Description: This interface consists of all the public methods used to
 * manipulate Viatra2 Framework instances, e.g. getters for modelspace, logger,
 * output, runtime properties, framework id, save, load, run, merge, native
 * import.
 *
 * @author Andras Schmidt
 *
 */
public interface IFramework extends IAdaptable{
	/**
	 * query the file from which this framwork was initialized
	 *
	 * @return The file from which this framework was initialized
	 */
	public String getCurrentFilename();

	/**
	 * Set the associated file name.
	 *
	 * @param fName
	 */
	public void setCurrentFileName(String fName);

	/**
	 * Returns the VPM model in this framework.
	 *
	 * @return the VPM model in this framework
	 */
	public IModelSpace getTopmodel();

	/**
	 * Returns the logger interface for this framework. Events to be logged
	 * should be written on this logger.
	 *
	 * @return the logger interface for this framework
	 */
	public Logger getLogger();

	/**
	 * Code output of interpreters should be written onto the interface returned
	 * by this method. The real output is configurable.
	 *
	 * @return the code out interface
	 */
	public CodeOutputPlugin getCodeOutput();

	/**
	 * Add a logger listener to this framework instance.
	 *
	 * @param l
	 */
	public void addLoggerListener(Logger l);

	public Collection<Logger> getAllLoggerListeners();

	public void removeLoggerListener(Logger l);

	public void addCodeOutListener(CodeOutputPlugin l);

	public Collection<CodeOutputPlugin> getAllCodeOutListeners();

	public void removeCodeOutListener(CodeOutputPlugin l);

	public void addFrameworkGlobalListener(IFrameworkGlobalListener l);

	public void removeFrameworkGlobalListener(IFrameworkGlobalListener l);

	public Collection<IFrameworkGlobalListener> getAllGlobalListeners();

	public Collection<CodeOutputPluginFactory> getAvailableCodeOutPlugins();

	public Collection<LoggerFactory> getAvailableLoggers();

	public Collection<ModelInterpreterFactory> getAvailableInterpreters();

	/**
	 * Save the state of model into the given file.
	 *
	 * @param fileName
	 * @throws FrameworkException
	 * @throws IOException
	 */
	public void saveFile(String fileName) throws FrameworkException,
			IOException;

	public void saveFile(OutputStream os, String newFileName)
			throws FrameworkException, IOException;

	/**
	 * Returns an array of parameter names of a Machine instance.

	 * @return names of available parameters
	 * @throws VPMRuntimeException
	 */
	public String[] getEntrypointParameters(Object entrypoint)
			throws FrameworkException;

	/**
	 * Runs the given machine with parameters.
	 *
	 * @param entrypoint
	 *            : the machine or rule object to run
	 * @param params
	 *            mapping from parameter name to parameter value
	 * @param pr
	 *            the progress report callback
	 */
	public void runEntrypoint(Object entrypoint, Map<String, Object> params,
			IProgressReport pr) throws VPMRuntimeException;

	/**
	 * True if the given machine instance is runnable.
	 */
	public boolean isRunnable(Object machine) throws FrameworkException;

	/**
	 * Returns the machines which are currently loaded
	 *
	 * @return the set of machine instances which are currently loaded
	 */
	public Collection<Object> getMachines();

	/**
	 * Queries a machine in the registry by its fully qualified name. Returns
	 * null if the machine cannot be found.
	 *
	 * @param machineFqn
	 *            the fully qualified name of the machine to find
	 * @return the machine object whose fully qualified name matches the query
	 */
	public Object getMachineByFQN(String machineFqn);

	/**
	 * Adds a listener to the machine set. Will be notified when the Machine set
	 * is changed.
	 *
	 * @param l
	 */
	public void addMachineSetListener(IMachineSetChangedListener l);

	/**
	 * Removes a machine set listener.
	 *
	 * @param l
	 */
	public void removeMachineSetListener(IMachineSetChangedListener l);

	/**
	 * Import the given file into the model with the given importer
	 *
	 * @param fileName
	 *            the file to be imported
	 * @param importerName
	 *            impoter id see getNativeImporters
	 * @throws FrameworkException
	 */
	public void nativeImport(String fileName, String importerName)
			throws FrameworkException;

	public void nativeImport(InputStream stream, String importerName)
			throws FrameworkException;

	/**
	 * Loads a machine description from a file.
	 *
	 * @param fileName
	 * @throws FrameworkException
	 */
	public Object loadMachine(String fileName, String loaderName)
			throws FrameworkException;
	
	/**
	 * Loads a machine description from a resource identified by a URI.
	 *
	 * @param URI
	 * @throws FrameworkException
	 */
	public Object loadMachineURI(String URI, String loaderName)
			throws FrameworkException;

	/**
	 * Loads a machine description from a stream.
	 *
	 * @param stream
	 * @param loaderName
	 * @throws FrameworkException
	 */
	public Object loadMachine(InputStream stream, String loaderName)
			throws FrameworkException;

	/**
	 * Adds a machine to the machine set.
	 *
	 * @param fqn
	 *            the fully qualified name of the machine
	 * @param machine
	 * @throws FrameworkException
	 */
	public void addMachine(String fqn, Object machine)
			throws FrameworkException;

	/**
	 * Removes a machine from the machine set.
	 *
	 * @param fqn
	 *            the fully qualified name of the machine to remove
	 * @throws FrameworkException
	 */
	public void removeMachine(String fqn) throws FrameworkException;

	/**
	 * Returns the set of native importer id's which are capable of importing a
	 * file with extension ext.
	 *
	 * @param ext
	 *            the file's extension to import
	 * @return the set of native importer id's which are capable of importing a
	 *         file with extension ext
	 */
	public Set<String> getNativeImportersForExtension(String ext);// throws
																	// FrameworkException
																	// ;

	public Set<String> getLoadersForExtension(String ext);// throws
															// FrameworkException
															// ;

	/**
	 * Import the given IResource instance into the model with the given
	 * importer
	 *
	 * @param resource
	 *            the IResource instance to be imported
	 * @param importerName
	 *            impoter id see getNativeImporters
	 * @throws FrameworkException
	 */
	// public void nativeImport(IResource resource, String importerName) throws
	// FrameworkException;
	/**
	 * Merges a given VPML file with the current modelspace.
	 *
	 * @param fileName
	 *            the VPML file to merge
	 * @throws FrameworkException
	 * @throws IOException
	 */
	public void mergeFile(String fileName) throws FrameworkException,
			IOException;

	/**
	 * Merges a given VPML file in the form of an InputStream with the current
	 * modelspace.
	 *
	 * @param stream
	 *            the InputStream of the VPML file to merge
	 * @throws FrameworkException
	 * @throws IOException
	 */
	public void mergeStream(InputStream stream) throws FrameworkException,
			IOException;

	/**
	 * Returns all native importer classes recognized by the framework. All
	 * importers have a string id
	 *
	 * @return mapping from impoter id to importer class
	 */
	public Map<String, NativeImporterFactory> getNativeImporters();

	/**
	 * Returns all native importer classes recognized by the framework. All
	 * importers have a string id
	 *
	 * @return mapping from impoter id to importer class
	 */
	public Map<String, LoaderFactory> getLoaders();

	/**
	 * get the native function manager. Native function manager is used to find
	 * native functions, which can be used by interpreters.
	 *
	 * @return the native function manager
	 */
	public INativeFunctionManager getNativeFunctionManager();

	/**
	 * Returns this IFramework's unique string ID.
	 *
	 * @return this IFramework's unique string ID
	 */
	public String getId();

	/**
	 * Returns the IFramework's multiproperty container.
	 *
	 * @return the IFramework's multiproperty container.
	 */
	public VPMProperties getProperties();

	/**
	 * Gets the tag manager associated to the Framework.
	 */
	public ITagManager getTagManager();

	/**
	 * Returns the VTCLParserManager
	 */
	public Object getVTCLParserManager();

	/**
	 * Registers a framework service with (unique) name "serviceName"
	 * Services are stored in a map where the "serviceName" identifies the service
	 * provider class as defined in the extenders of the "frameworkservice" extension point.
	 * @param serviceName: unique name of the service (defined by extenders of the frameworkservice extension point)
	 * @throws FrameworkException
	 */
	public void registerFrameworkService(String serviceName) throws FrameworkException;

	/**
	 * Unregisters a service with a unique "serviceName" from the map of
	 * service providers
	 * @param serviceName: unique name of the service to be unregistered
	 */
	public void unregisterFrameworkService(String serviceName);

}