001    package de.deepamehta.core;
002    
003    import de.deepamehta.core.model.AssociationModel;
004    import de.deepamehta.core.model.RoleModel;
005    import de.deepamehta.core.model.TopicRoleModel;
006    import de.deepamehta.core.service.ClientState;
007    import de.deepamehta.core.service.Directives;
008    
009    import java.util.List;
010    
011    
012    
013    /**
014     * ### FIXDOC: Specification of an association -- A n-ary connection between topics and other associations.
015     *
016     * @author <a href="mailto:jri@deepamehta.de">Jörg Richter</a>
017     */
018    public interface Association extends DeepaMehtaObject {
019    
020    
021    
022        // === Model ===
023    
024        Role getRole1();
025    
026        Role getRole2();
027    
028        // ---
029    
030        /**
031         * @teturn  this association's topic which plays the given role.
032         *          If there is no such topic, null is returned.
033         *          <p>
034         *          If there are 2 such topics an exception is thrown.
035         */
036        Topic getTopic(String roleTypeUri);
037    
038        /**
039         * @teturn  this association's topics which play the given role.
040         *          The resulting set can have 0, 1, or 2 elements.
041         */
042        List<Topic> getTopics(String roleTypeUri);
043    
044        // ---
045    
046        /**
047         * Returns this association's role which refers to the same object as the given role model.
048         * The role returned is found by comparing topic IDs, topic URIs, or association IDs.
049         * The role types are <i>not</i> compared.
050         * <p>
051         * If the object refered by the given role model is not a player in this association an exception is thrown.
052         */
053        Role getRole(RoleModel roleModel);
054    
055        boolean isPlayer(TopicRoleModel roleModel);
056    
057        // ---
058    
059        AssociationModel getModel();
060    
061    
062    
063        // === Updating ===
064    
065        void update(AssociationModel model, ClientState clientState, Directives directives);
066    
067    
068    
069        // === Traversal ===
070    
071        // ### TODO: move to DeepaMehtaObject
072        // ### TODO: add "othersAssocTypeUri" argument
073        RelatedAssociation getRelatedAssociation(String assocTypeUri, String myRoleTypeUri, String othersRoleTypeUri);
074    }