<commit_before>package tools.vitruv.framework.correspondence;

import java.util.List;
import java.util.Set;
import java.util.function.Supplier;

import org.eclipse.emf.ecore.EObject;

import tools.vitruv.framework.correspondence.Correspondence;
import tools.vitruv.framework.correspondence.CorrespondenceModel;
import tools.vitruv.framework.tuid.Tuid;
import tools.vitruv.framework.util.datatypes.URIHaving;

/**
 * Contains all correspondences for all model instances that conform to the metamodels of a give
 * mapping. The correspondences do not store any information on metamodels. Only correspondence
 * instances link to the metamodels. Therefore every elementA of a correspondence has to be an
 * instance of a metaclass of the first metamodel of the containing correspondence instance. And
 * every elementB of a correspondence has to be an instance of a metaclass of the second metamodel
 * of the containing correspondence instance.
 *
 * @author kramerm
 *
 */
public interface GenericCorrespondenceModel<T extends Correspondence> extends URIHaving {

    /**
     * Returns whether at least one object corresponds to the given object.
     *
     * @param eObject
     *            the object for which correspondences should be looked up
     * @return true if # of corresponding objects > 0
     */

    public boolean hasCorrespondences(List<EObject> eObject);

    /**
     * Returns whether at least one object corresponds to another object.
     *
     * @return true if # of correspondences > 0
     */
    public boolean hasCorrespondences();

    /**
     * Returns all correspondences for the specified object and an empty set if the object has no
     * correspondences. Should never return {@link null}.
     *
     * @param eObjects
     * @return all correspondences for the specified object and an empty set if the object has no
     *         correspondences.
     */

    public Set<T> getCorrespondences(List<EObject> eObjects);

    /**
     * Returns all correspondences for the object with the specified tuid and an empty set if the
     * object has no correspondences. Should never return {@link null}.
     *
     * @param tuids
     * @return all correspondences for the object with the specified tuid and an empty set if the
     *         object has no correspondences.
     */
    public Set<T> getCorrespondencesForTuids(List<Tuid> tuids);

    public Set<List<EObject>> getCorrespondingEObjects(List<EObject> eObjects);
    
    public Set<List<EObject>> getCorrespondingEObjects(List<EObject> eObjects, String tag);
    
    public Set<List<EObject>> getCorrespondingEObjects(Class<? extends Correspondence> correspondenceType, List<EObject> eObjects, String tag);

    public T claimUniqueCorrespondence(final List<EObject> aEObjects, final List<EObject> bEObjects);

    public Set<T> getCorrespondencesThatInvolveAtLeast(Set<EObject> eObjects);
    
    // renamed from addSameTypeCorrespondence
    public void addCorrespondence(T correspondence);

    /**
     * React to the deletion of an object o by deleting all correspondences that
     *
     * Removes all direct correspondences for the given eObject and all correspondences for children
     * of the given eObject and for children of the eObjects corresponding to the given eObject.
     * Does <b>not</b> remove any model elements (only correspondences).
     *
     * @param eObject
     *            for which all correspondences should be removed
     * @return a set containing all removed correspondences
     */
    public Set<Correspondence> removeCorrespondencesThatInvolveAtLeastAndDependend(Set<EObject> eObjects);

    /**
     * Removes the given correspondence, all correspondences for the eObjects of the given
     * correspondence, and all correspondences for their children on both sides. Does <b>not</b>
     * remove any model elements (only correspondences).
     *
     * @param correspondence
     *            that should be removed
     * @return a set containing all removed correspondences
     */
    public Set<T> removeCorrespondencesAndDependendCorrespondences(T correspondence);

    public List<EObject> resolveEObjectsFromUuids(final List<String> uuids);

    public EObject resolveEObjectFromTuid(final Tuid tuid);
    
    public Tuid calculateTuidFromEObject(final EObject eObject);

    /**
     * Is necessary to make the remove operation possible. TODO: check whether we can remove this
     * from the public API
     *
     * @return
     */
    public Tuid calculateTuidFromEObject(final EObject eObject, EObject virtualRootObject, String prefix);

    /**
     * syntactic sugar for map[{@link #calculateTuidFromEObject(EObject)}]
     *
     * @param eObjects
     * @return
     */
    public List<Tuid> calculateTuidsFromEObjects(final List<EObject> eObjects);

    /**
     * SWAPS eObjects1 and eObjects2 to obtain first as and then bs if necessary!
     */
    public Correspondence createAndAddCorrespondence(List<EObject> eObjects1, List<EObject> eObjects2);

    public Correspondence createAndAddCorrespondence(List<EObject> eObjects1, List<EObject> eObjects2,
            Supplier<Correspondence> correspondenceCreator);

    public Correspondence createAndAddManualCorrespondence(List<EObject> eObjects1, List<EObject> eObjects2);

    Set<T> getAllCorrespondencesWithoutDependencies();

    public List<T> getAllCorrespondences();

    /**
     * Returns a view on the {@link CorrespondenceModel} restricted to the specified kind of
     * {@link Correspondence}. The functions of the view will only act on the given implementation
     * of {@link Correspondence}s.
     *
     * @param correspondenceType
     *            the type of {@link Correspondence}s to be handled by the view
     * @return the restricted view on the {@link CorrespondenceModel}
     * @author <NAME>
     */
    public <U extends Correspondence> GenericCorrespondenceModel<U> getView(Class<U> correspondenceType);

    /**
     * Creates a editable view on the {@link CorrespondenceModel} restricted to the specified
     * kind of {@link Correspondence}. To enable the creation of new Correspondences a Supplier
     * method has to be provided to the writable view.
     *
     * @param correspondenceType
     *            the type of {@link Correspondence}s to be handled by the view
     * @param correspondenceCreator
     * @return the restricted editable view on the {@link CorrespondenceModel}
     */
    public <U extends Correspondence> GenericCorrespondenceModel<U> getEditableView(Class<U> correspondenceType,
            Supplier<U> correspondenceCreator);

}<commit_msg>Add documentation on element retrieval from correspondence model<commit_after>package tools.vitruv.framework.correspondence;

import java.util.List;
import java.util.Set;
import java.util.function.Supplier;

import org.eclipse.emf.ecore.EObject;

import tools.vitruv.framework.correspondence.Correspondence;
import tools.vitruv.framework.correspondence.CorrespondenceModel;
import tools.vitruv.framework.tuid.Tuid;
import tools.vitruv.framework.util.datatypes.URIHaving;

/**
 * Contains all correspondences for all model instances that conform to the metamodels of a give
 * mapping. The correspondences do not store any information on metamodels. Only correspondence
 * instances link to the metamodels. Therefore every elementA of a correspondence has to be an
 * instance of a metaclass of the first metamodel of the containing correspondence instance. And
 * every elementB of a correspondence has to be an instance of a metaclass of the second metamodel
 * of the containing correspondence instance.
 *
 * @author kramerm
 *
 */
public interface GenericCorrespondenceModel<T extends Correspondence> extends URIHaving {

    /**
     * Returns whether at least one object corresponds to the given object.
     *
     * @param eObject
     *            the object for which correspondences should be looked up
     * @return true if # of corresponding objects > 0
     */

    public boolean hasCorrespondences(List<EObject> eObject);

    /**
     * Returns whether at least one object corresponds to another object.
     *
     * @return true if # of correspondences > 0
     */
    public boolean hasCorrespondences();

    /**
     * Returns all correspondences for the specified object and an empty set if the object has no
     * correspondences. Should never return {@link null}.
     *
     * @param eObjects
     * @return all correspondences for the specified object and an empty set if the object has no
     *         correspondences.
     */

    public Set<T> getCorrespondences(List<EObject> eObjects);

    /**
     * Returns all correspondences for the object with the specified tuid and an empty set if the
     * object has no correspondences. Should never return {@link null}.
     *
     * @param tuids
     * @return all correspondences for the object with the specified tuid and an empty set if the
     *         object has no correspondences.
     */
    public Set<T> getCorrespondencesForTuids(List<Tuid> tuids);

    /**
     * Returns all elements corresponding to the given one.
     * 
     * @param eObjects - the objects to get the corresponding ones for
     * @return the elements corresponding to the given ones
     */
    public Set<List<EObject>> getCorrespondingEObjects(List<EObject> eObjects);
    
    /**
     * Returns the elements corresponding to the given one, if the correspondence contains the given tag.
     * 
     * @param eObjects - the objects to get the corresponding ones for
     * @param tag - the tag to filter correspondences for. If the tag is <code>null</code>, all correspondences will be returned
     * @return the elements corresponding to the given ones
     */
    public Set<List<EObject>> getCorrespondingEObjects(List<EObject> eObjects, String tag);
    
    /**
     * Returns the elements corresponding to the given one, if the correspondence is of the given type and contains the given tag.
     * 
     * @param correspondenceType - the type of correspondence to filter
     * @param eObjects - the objects to get the corresponding ones for
     * @param tag - the tag to filter correspondences for. If the tag is <code>null</code>, all correspondences will be returned
     * @return the elements corresponding to the given ones
     */
    public Set<List<EObject>> getCorrespondingEObjects(Class<? extends Correspondence> correspondenceType, List<EObject> eObjects, String tag);

    public T claimUniqueCorrespondence(final List<EObject> aEObjects, final List<EObject> bEObjects);

    public Set<T> getCorrespondencesThatInvolveAtLeast(Set<EObject> eObjects);
    
    // renamed from addSameTypeCorrespondence
    public void addCorrespondence(T correspondence);

    /**
     * React to the deletion of an object o by deleting all correspondences that
     *
     * Removes all direct correspondences for the given eObject and all correspondences for children
     * of the given eObject and for children of the eObjects corresponding to the given eObject.
     * Does <b>not</b> remove any model elements (only correspondences).
     *
     * @param eObject
     *            for which all correspondences should be removed
     * @return a set containing all removed correspondences
     */
    public Set<Correspondence> removeCorrespondencesThatInvolveAtLeastAndDependend(Set<EObject> eObjects);

    /**
     * Removes the given correspondence, all correspondences for the eObjects of the given
     * correspondence, and all correspondences for their children on both sides. Does <b>not</b>
     * remove any model elements (only correspondences).
     *
     * @param correspondence
     *            that should be removed
     * @return a set containing all removed correspondences
     */
    public Set<T> removeCorrespondencesAndDependendCorrespondences(T correspondence);

    public List<EObject> resolveEObjectsFromUuids(final List<String> uuids);

    public EObject resolveEObjectFromTuid(final Tuid tuid);
    
    public Tuid calculateTuidFromEObject(final EObject eObject);

    /**
     * Is necessary to make the remove operation possible. TODO: check whether we can remove this
     * from the public API
     *
     * @return
     */
    public Tuid calculateTuidFromEObject(final EObject eObject, EObject virtualRootObject, String prefix);

    /**
     * syntactic sugar for map[{@link #calculateTuidFromEObject(EObject)}]
     *
     * @param eObjects
     * @return
     */
    public List<Tuid> calculateTuidsFromEObjects(final List<EObject> eObjects);

    /**
     * SWAPS eObjects1 and eObjects2 to obtain first as and then bs if necessary!
     */
    public Correspondence createAndAddCorrespondence(List<EObject> eObjects1, List<EObject> eObjects2);

    public Correspondence createAndAddCorrespondence(List<EObject> eObjects1, List<EObject> eObjects2,
            Supplier<Correspondence> correspondenceCreator);

    public Correspondence createAndAddManualCorrespondence(List<EObject> eObjects1, List<EObject> eObjects2);

    Set<T> getAllCorrespondencesWithoutDependencies();

    public List<T> getAllCorrespondences();

    /**
     * Returns a view on the {@link CorrespondenceModel} restricted to the specified kind of
     * {@link Correspondence}. The functions of the view will only act on the given implementation
     * of {@link Correspondence}s.
     *
     * @param correspondenceType
     *            the type of {@link Correspondence}s to be handled by the view
     * @return the restricted view on the {@link CorrespondenceModel}
     * @author <NAME>
     */
    public <U extends Correspondence> GenericCorrespondenceModel<U> getView(Class<U> correspondenceType);

    /**
     * Creates a editable view on the {@link CorrespondenceModel} restricted to the specified
     * kind of {@link Correspondence}. To enable the creation of new Correspondences a Supplier
     * method has to be provided to the writable view.
     *
     * @param correspondenceType
     *            the type of {@link Correspondence}s to be handled by the view
     * @param correspondenceCreator
     * @return the restricted editable view on the {@link CorrespondenceModel}
     */
    public <U extends Correspondence> GenericCorrespondenceModel<U> getEditableView(Class<U> correspondenceType,
            Supplier<U> correspondenceCreator);

}
{'fraction_non_alphanumeric': 0.06763419206999514, 'fraction_numerical': 0.0013887924449690993, 'mean_word_length': 3.45193199381762, 'pattern_counts': {'":': 0, '<': 103, '<?xml version=': 0, '>': 107, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7596149', 'n_tokens_mistral': 3797, 'n_tokens_neox': 3659, 'n_words': 1409}