001package de.deepamehta.core;
002
003import de.deepamehta.core.model.AssociationModel;
004import de.deepamehta.core.model.RoleModel;
005import de.deepamehta.core.model.TopicRoleModel;
006
007import java.util.List;
008
009
010
011/**
012 * ### FIXDOC: Specification of an association -- A n-ary connection between topics and other associations.
013 *
014 * @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
015 */
016public interface Association extends DeepaMehtaObject {
017
018    Role getRole1();
019
020    Role getRole2();
021
022    // ---
023
024    DeepaMehtaObject getPlayer1();
025
026    DeepaMehtaObject getPlayer2();
027
028    // --- Convenience Methods ---
029
030    /**
031     * @return  this association's role that matches the given role type.
032     *          If no role matches, null is returned.
033     *          If both roles are matching an exception is thrown.
034     */
035    Role getRole(String roleTypeUri);
036
037    boolean hasSameRoleTypeUris();
038
039    /**
040     * Checks if the given players match this association.
041     * The given role type URIs must be different.
042     * The player position ("1" vs. "2") is not relevant.
043     *
044     * @return  true if the given players match this association.
045     *
046     * @throws  IllegalArgumentException    if both given role type URIs are identical.
047     */
048    boolean matches(String roleTypeUri1, long playerId1, String roleTypeUri2, long playerId2);
049
050    long getOtherPlayerId(long id);
051
052    // ---
053
054    /**
055     * ### TODO: make it work for assoc players as well or drop it
056     *
057     * @teturn  this association's topic which plays the given role.
058     *          If there is no such topic, null is returned.
059     *          <p>
060     *          If there are 2 such topics an exception is thrown.
061     */
062    Topic getTopic(String roleTypeUri);
063
064    /**
065     * ### TODO: make it work for assoc players as well or drop it
066     *
067     * @teturn  this association's topic which has the given type.
068     *          If there is no such topic, null is returned.
069     *          <p>
070     *          If there are 2 such topics an exception is thrown.
071     */
072    Topic getTopicByType(String topicTypeUri);
073
074    // ---
075
076    /**
077     * ### TODO: rethink this method
078     *
079     * Returns this association's role which refers to the same object as the given role model.
080     * The role returned is found by comparing topic IDs, topic URIs, or association IDs.
081     * The role types are <i>not</i> compared.
082     * <p>
083     * If the object refered by the given role model is not a player in this association an exception is thrown.
084     */
085    Role getRole(RoleModel roleModel);
086
087    /**
088     * ### TODO: drop it
089     */
090    boolean isPlayer(TopicRoleModel roleModel);
091
092    // ---
093
094    void update(AssociationModel model);
095
096    // ---
097
098    Association loadChildTopics();
099    Association loadChildTopics(String assocDefUri);
100
101    // ---
102
103    AssociationModel getModel();
104}