001package systems.dmx.core;
002
003import systems.dmx.core.model.AssociationModel;
004import systems.dmx.core.model.RoleModel;
005import systems.dmx.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 DMXObject {
017
018    Role getRole1();
019
020    Role getRole2();
021
022    // ---
023
024    DMXObject getPlayer1();
025
026    DMXObject 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     * @return  this association's player which plays the given role.
056     *          If there is no such player, null is returned.
057     *          <p>
058     *          If there are 2 such players an exception is thrown.
059     */
060    RelatedObject getPlayer(String roleTypeUri);
061
062    /**
063     * ### TODO: make it work for assoc players as well or drop it
064     *
065     * @return  this association's topic which has the given type.
066     *          If there is no such topic, null is returned.
067     *          <p>
068     *          If there are 2 such topics an exception is thrown.
069     */
070    Topic getTopicByType(String topicTypeUri);
071
072    // ---
073
074    /**
075     * ### TODO: rethink this method
076     *
077     * Returns this association's role which refers to the same object as the given role model.
078     * The role returned is found by comparing topic IDs, topic URIs, or association IDs.
079     * The role types are <i>not</i> compared.
080     * <p>
081     * If the object refered by the given role model is not a player in this association an exception is thrown.
082     */
083    Role getRole(RoleModel roleModel);
084
085    /**
086     * ### TODO: drop it
087     */
088    boolean isPlayer(TopicRoleModel roleModel);
089
090    // ---
091
092    void update(AssociationModel model);
093
094    // ---
095
096    @Override
097    Association loadChildTopics();
098
099    @Override
100    Association loadChildTopics(String assocDefUri);
101
102    // ---
103
104    @Override
105    AssociationModel getModel();
106}