org.eclipse.viatra2.core2/src/org/eclipse/viatra2/core/IModelManager.java

/*******************************************************************************
 * Copyright (c) 2004-2008 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.core;

import java.util.Set;
import java.util.concurrent.locks.ReadWriteLock;

import org.eclipse.viatra2.errors.VPMCoreException;

/**
 * Interface for defining the requirements for VPM model management
 * implementations
 * 
 * @author Andras Balogh, Istvan Rath, Andras Schmidt
 * 
 */
public interface IModelManager {

	/**
	 * Initializes the model manager.
	 * 
	 * @param p
	 *            - the collection of runtime properties
	 * @param l
	 *            - the framework logger
	 * @param m
	 *            - the owning modelspace
	 * @throws VPMRuntimeException
	 */
	// public void init(Logger l, Properties p, IModelSpace m) throws
	// VPMRuntimeException;

	/**
	 * Retrieves the root entity of the modelspace.
	 * 
	 * @return root entity
	 */
	public IEntity getRoot();

	/**
	 * Deletes the entity from the modelspace according to a specified
	 * semantics.
	 * 
	 * @param e
	 *            entity to be deleted
	 * @param semantics
	 *            semantics id
	 * @deprecated use delete element instead
	 */
	@Deprecated
	public void deleteEntity(IEntity e, EDeleteSemantics semantics)
			throws VPMCoreException;

	/**
	 * Deletes the element from the modelspace according to a specified
	 * semantics.
	 * 
	 * @param me
	 *            element to be deleted
	 * @param semantics
	 *            semantics id
	 */
	public void deleteElement(IModelElement me, EDeleteSemantics semantics)
			throws VPMCoreException;

	/**
	 * Deletes a relation from the modelspace.
	 * 
	 * @param r
	 *            the relation to be deleted.
	 * @deprecated use deleteElement instead
	 */
	@Deprecated
	public void deleteRelation(IRelation r, EDeleteSemantics semantics)
			throws VPMCoreException;

	/**
	 * Retrives the model element by its fully qualified name
	 * 
	 * @param n
	 *            the fully qualified model element name
	 * @return element if found, else null
	 */
	public IModelElement getElementByName(String n);

	/**
	 * Retrieves an entity by its fully qualified name
	 * 
	 * @param n
	 *            fully qualified name of entity
	 * @return entity if found, else null
	 */
	public IEntity getEntityByName(String n);

	/**
	 * Retrieves a relation by its fully qualified name
	 * 
	 * @param n
	 *            fully qualified name of relation
	 * @return relation if found, else null
	 */
	public IRelation getRelationByName(String n);

	/**
	 * Retrives the model element by its ID
	 * 
	 * @param n
	 *            model element ID
	 * @return element if found, else null
	 */
	public IModelElement getElementByID(String n);

	/**
	 * Retrieves an entity by its ID
	 * 
	 * @param n
	 *            ID of entity
	 * @return entity if found, else null
	 */
	public IEntity getEntityByID(String n);

	/**
	 * Retrieves a relation by its ID
	 * 
	 * @param n
	 *            ID of relation
	 * @return relation if found, else null
	 */
	public IRelation getRelationByID(String n);

	/**
	 * Retrieves all entities currently in the modelspace.
	 * 
	 * @return collection of entities
	 */
	public Set<? extends IEntity> getEntities();

	public Set<? extends IModelElement> getElements();

	/**
	 * Retrieves all relations currently in the modelspace.
	 * 
	 * @return collection of relations
	 */
	public Set<? extends IRelation> getRelations();

	/**
	 * Creates a new entity with a random and unique name, contained in the
	 * modelspace root
	 * 
	 * @return reference to the entity
	 */
	public IEntity newEntity();

	/**
	 * Creates a new entity with a random and unique name in the specified
	 * container
	 * 
	 * @param container
	 *            the container, may not be null
	 * @return reference to the entity
	 */
	public IEntity newEntity(IEntity container) throws VPMCoreException;

	/**
	 * Creates a new entity with the given name in the modelspace root
	 * 
	 * @param name
	 *            the name of the entity, may not be null
	 * @return reference to the entity
	 */
	public IEntity newEntity(String name) throws VPMCoreException;

	/**
	 * Creates a new entity with the given name and container
	 * 
	 * @param name
	 *            the name of the entity, may not be null
	 * @param container
	 *            the container, may not be null
	 * @return reference to the entity
	 */
	public IEntity newEntity(String name, IEntity container)
			throws VPMCoreException;

	/**
	 * Creates a new entity with the given name and value in the modelspace root
	 * 
	 * @param name
	 *            the name of the entity, may not be null
	 * @param value
	 *            the value of the entity, may not be null
	 * @return reference to the entity
	 */
	public IEntity newEntity(String name, String value) throws VPMCoreException;

	/**
	 * Creates a new entity with the given name, value and container
	 * 
	 * @param name
	 *            the name of the entity, may not be null
	 * @param value
	 *            the value of the entity, may not be null
	 * @param container
	 *            the container, may not be null
	 * @return reference to the entity
	 */
	public IEntity newEntity(String name, String value, IEntity container)
			throws VPMCoreException;
	/**
	 * Creates a new entity with the given name, value container and a single type. 
	 * Each of the parameters can be left null.
	 * 
	 * @param name
	 *            the name of the entity
	 * @param value
	 *            the value of the entity
	 * @param container
	 *            the container
	 * @param type
	 *            the single initial type of the entity   
	 * @return reference to the entity
	 * @throws VPMCoreException
	 */
	public IEntity newEntity(String name, String value, IEntity container, IEntity type)
			throws VPMCoreException;
	
	

	/**
	 * Creates a new relation with a random and unique name, between the given
	 * model elements.
	 * 
	 * @param from
	 *            source model element
	 * @param to
	 *            target model element
	 * @return reference to the new relation
	 */
	public IRelation newRelation(IModelElement from, IModelElement to)
			throws VPMCoreException;

	/**
	 * Creates a new relation with a random and unique name, between the given
	 * model elements, with the given multiplicity, isAggregation, Inverse
	 * attributes.
	 * 
	 * @param from
	 *            source model element
	 * @param to
	 *            target model element
	 * @param multiplicity
	 *            a valid EMultiplicityKind enumeration constant
	 * @param isaggregation
	 *            true, if the relation represents an aggregation
	 * @param inverse
	 *            the relation's inverse, or null if it has none
	 * @return reference to the new relation
	 */
	public IRelation newRelation(IModelElement from, IModelElement to,
			EMultiplicityKind multiplicity, boolean isaggregation,
			IRelation inverse) throws VPMCoreException;

	/**
	 * Creates a new relation with the given name, between the given elements.
	 * 
	 * @param name
	 *            name of the relation
	 * @param from
	 *            source entity
	 * @param to
	 *            target entity
	 * @return reference to the new relation
	 */
	public IRelation newRelation(String name, IModelElement from,
			IModelElement to) throws VPMCoreException;

	/**
	 * Creates a new relation with the given name, between the given model
	 * elements, with the given multiplicity, isAggregation, hasInverse
	 * attributes.
	 * 
	 * @param name
	 *            name of the relation
	 * @param from
	 *            source model element
	 * @param to
	 *            target model element
	 * @param multiplicity
	 *            a valid EMultiplicityKind enumeration constant
	 * @param isaggregation
	 *            true, if the relation represents an aggregation
	 * @param inverse
	 *            the relation's inverse, or null if it has none
	 * @return reference to the new relation
	 */
	public IRelation newRelation(String name, IModelElement from,
			IModelElement to, EMultiplicityKind multiplicity,
			boolean isaggregation, IRelation inverse) throws VPMCoreException;

	/**
	 * Creates a new relation with the given name, between the given model elements, with the given single type.
	 * Name and type can be left null.
	 * 
	 * @param name
	 *            name of relation
	 * @param from
	 *            source entity
	 * @param to
	 *            target entity
	 * @param type
	 *            the single initial type of the relation       
	 * @return reference to the new relation
	 * @throws VPMCoreException
	 */
	public IRelation newRelation(String name, IModelElement from,
			IModelElement to, IRelation type) throws VPMCoreException;
	
	
	/**
	 * Creates an instanceOf relation between the two model elements
	 * 
	 * @param type
	 *            the type element
	 * @param inst
	 *            the instance
	 */
	public void newInstanceOf(IModelElement type, IModelElement inst)
			throws VPMCoreException;

	public void newInstanceOfEditor(IModelElement type, IModelElement inst)
			throws VPMCoreException;

	public void newInstanceOfMachine(IModelElement type, IModelElement inst)
			throws VPMCoreException;

	/**
	 * Creates a new supertypeOf relation between the two elements
	 * 
	 * @param sup
	 *            the supertype
	 * @param sub
	 *            the subtype
	 */
	public void newSupertypeOf(IModelElement sup, IModelElement sub)
			throws VPMCoreException;

	public void newSupertypeOfMachine(IModelElement sup, IModelElement sub)
			throws VPMCoreException;

	public void newSupertypeOfEditor(IModelElement sup, IModelElement sub)
			throws VPMCoreException;

	/**
	 * Deletes the instanceOf relation between the two model elements
	 * 
	 * @param type
	 *            the type element
	 * @param inst
	 *            the instance
	 */
	public void deleteInstanceOf(IModelElement type, IModelElement inst)
			throws VPMCoreException;

	public void deleteInstanceOfMachine(IModelElement type, IModelElement inst)
			throws VPMCoreException;

	public void deleteInstanceOfEditor(IModelElement type, IModelElement inst)
			throws VPMCoreException;

	/**
	 * Deletes the supertypeOf relation between the two elements
	 * 
	 * @param sup
	 *            the supertype
	 * @param sub
	 *            the subtype
	 */
	public void deleteSupertypeOf(IModelElement sup, IModelElement sub)
			throws VPMCoreException;

	public void deleteSupertypeOfMachine(IModelElement sup, IModelElement sub)
			throws VPMCoreException;

	public void deleteSupertypeOfEditor(IModelElement sup, IModelElement sub)
			throws VPMCoreException;

	/**
	 * Sets the name of the element
	 * 
	 * @param e
	 *            the element
	 * @param n
	 *            the new name
	 */
	public void setName(IModelElement e, String n) throws VPMCoreException;

	/**
	 * Sets the value of the entity
	 * 
	 * @param e
	 *            the entity
	 * @param v
	 *            the new value
	 */
	public void setValue(IEntity e, String v) throws VPMCoreException;

	/**
	 * Sets the source of the relation
	 * 
	 * @param rel
	 *            the relation
	 * @param from
	 *            the new source model element
	 * @throws VPMCoreException
	 */
	public void setRelationFrom(IRelation rel, IModelElement from)
			throws VPMCoreException;

	/**
	 * Sets the target of the relation
	 * 
	 * @param rel
	 *            the relation
	 * @param to
	 *            the new target model element
	 * @throws VPMCoreException
	 */
	public void setRelationTo(IRelation rel, IModelElement to)
			throws VPMCoreException;

	/**
	 * Sets the multiplicity of the relation
	 * 
	 * @param rel
	 *            the relation
	 * @param multiplicity
	 *            a valid EMultiplicityKind enumeration constant
	 */
	public void setRelationMultiplicity(IRelation rel,
			EMultiplicityKind multiplicity) throws VPMCoreException;

	/**
	 * Sets the isAggregation attribute of the relation
	 * 
	 * @param rel
	 *            the relation
	 * @param isaggregation
	 *            true, if the relation should represent an aggregation
	 */
	public void setRelationIsAggregation(IRelation rel, boolean isaggregation)
			throws VPMCoreException;

	/**
	 * Sets the Inverse attribute of the relation
	 * 
	 * @param rel
	 *            the relation
	 * @param inverse
	 *            the relation's inverse, or null if it has none
	 */
	public void setRelationInverse(IRelation rel, IRelation inverse)
			throws VPMCoreException;

	/**
	 * Removes the element from its current container and moves it to the
	 * specified new container
	 * 
	 * @param e
	 *            the element
	 * @param cont
	 *            new container
	 */
	public void moveEntityTo(IEntity e, IEntity cont) throws VPMCoreException;

	/**
	 * Sets the "view information" string attribute of the model element
	 * 
	 * @param me
	 *            the model element
	 * @param viewInfo
	 *            the new "view information" string
	 * @throws VPMCoreException
	 */
	public void setViewInfo(IModelElement me, String viewInfo)
			throws VPMCoreException;

	/**
	 * Sets the isFinalType flag for a model element.
	 * 
	 * @param me
	 *            the model element
	 * @param isfinaltype
	 *            true, if the element is not to be subtyped
	 * @throws VPMCoreException
	 */
	public void setIsFinalType(IModelElement me, boolean isfinaltype)
			throws VPMCoreException;

	/**
	 * Sets whether the type of this relation's source can be omitted (instances
	 * can have source of any type).
	 */
	public void setIsAnyFrom(IRelation rel, boolean isAnyFrom)
			throws VPMCoreException;

	/**
	 * Sets whether the type of this relation's target can be omitted (instances
	 * can have target of any type).
	 */
	public void setIsAnyTo(IRelation rel, boolean isAnyTo)
			throws VPMCoreException;

	/**
	 * Modify the model to let these model elements in the desired relation.
	 * 
	 * @param relationType
	 *            BELOW, OVER, ENTITY and RELATION has no sense, others can be
	 *            ok parameters
	 * @param src
	 * @param tg
	 * @throws VPMCoreException
	 */
//	public void setRelationshipBetween(EConstraint relationType,
//			IModelElement src, IModelElement tg) throws VPMCoreException;

	public void setProperty(IModelElement me, EModelElementProperty property,
			Object value) throws VPMCoreException;

	/**
	 * Modify the model to let the desired relation no longer exist between the
	 * model elements.
	 * 
	 * @param relationType
	 *            not all relation types can be deleted this way
	 * @param src
	 * @param tg
	 * @throws VPMCoreException
	 */
//	public void deleteRelationshipBetween(EConstraint relationType,
//			IModelElement src, IModelElement tg) throws VPMCoreException;

	/**
	 * Copies a set of model elements (<b>deeply</b>) to a destination container
	 * within the modelspace.
	 * 
	 * @param sourceElements
	 *            the set of model elements to copy
	 * @param sourceRoot
	 *            the root of the source model to copy
	 * @param destinationContainer
	 *            the container of the copied model in the destination model
	 * @param copyOutEdges
	 *            true: copy edges going out of the copied part of model
	 * @return the root modelement of the copied model part
	 * @throws VPMCoreException
	 */
	public IModelElement copyModelElements(Set<IModelElement> sourceElements,
			IModelElement sourceRoot, IModelElement destinationContainer,
			boolean copyOutEdges) throws VPMCoreException;

	/**
	 * Copies a model element (and all of its containment subtree) to a
	 * destination container within the modelspace.
	 * 
	 * @param source
	 *            the model element which will be copied along with all its
	 *            <b>deep</b> contents
	 * @param destinationContainer
	 *            the container of the copied model in the destination model
	 * @param copyOutEdges
	 *            true: copy edges going out of the copied part of model
	 * @return the root modelement of the copied model part
	 * @throws VPMCoreException
	 */
	public IModelElement copyModelElement(IModelElement source,
			IModelElement destinationContainer, boolean copyOutEdges)
			throws VPMCoreException;

	/**
	 * Returns a reentrant read-write lock of the modelspace.
	 * 
	 * @return the lock to the modelspace
	 */
	public ReadWriteLock getLock();
}