001    /**
002     * planningtool - A Planning Tool with Critiquing Support.
003     * 
004     * Copyright (C) 2006 olale
005    
006     * This program is free software; you can redistribute it and/or
007     * modify it under the terms of the GNU General Public License
008     * as published by the Free Software Foundation; either version 2
009     * of the License, or (at your option) any later version.
010    
011     * This program is distributed in the hope that it will be useful,
012     * but WITHOUT ANY WARRANTY; without even the implied warranty of
013     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014     * GNU General Public License for more details.
015    
016     * You should have received a copy of the GNU General Public License
017     * along with this program; if not, write to the Free Software
018     * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019    
020     * Contact information: 
021     * E-mail: olale@ida.liu.se
022     *         olale@lysator.liu.se
023     */
024    package se.liu.ida.critiquer.resources;
025    
026    import java.io.Serializable;
027    import java.util.HashMap;
028    
029    import se.liu.ida.critiquer.activities.Activity;
030    
031    /**
032     * <p>
033     * Interface for functions defined by agents that calculate how long a mission
034     * takes to complete. What do we mean by this?
035     * </p>
036     * 
037     * <p>
038     * For the missions that agents can participate in, there should be some notion
039     * of what capacity they have with respect to handling the mission. This does
040     * not, however, have to imply that each agent can solve a mission on their own.
041     * </p>
042     * 
043     * <p>
044     * There are only a few cases here as I see it, all under the condition that the
045     * agent can actually contribute to an activity:
046     * </p>
047     * <ol>
048     * <li>The agent may be able to do a given part of the job that in turn takes a
049     * given amount of time (transporting itself to a rendez-vous point during
050     * dispatch).</li>
051     * 
052     * <li>The agent may do a given amount of work per time unit and, if enough
053     * time is given, solve the mission on its own.</li>
054     * 
055     * </ol>
056     * 
057     * <p>
058     * Both these contributions can be accomodated using a single method that
059     * <code>performs</code> some task and, if appropriate, modifies properties of
060     * the activity to reflect the work done. The return value is then the time it
061     * took the unit to perform its task. The activity may then calculate how long
062     * it will take to complete based on the agents participating by using either
063     * the side effects they cause or
064     * </p>
065     * 
066     * <p>
067     * "Given" amounts are calculated or specified by the agent. The human planner
068     * should specify which agents to use and the job here is only to perform the
069     * specified activity.
070     * </p>
071     * 
072     */
073    public interface AgentContributionCalculator<T extends Activity> extends Serializable {
074    
075            /**
076             * 
077             * Perform some work by modifying appropriate attributes in the activity to
078             * indicate what is being done.
079             * 
080             * Return the time it took to perform the work.
081             * 
082             * If we consider the case where this operation would mean that we transport
083             * people from location A to location B, this would mean that each
084             * subsequent call to <code>perform</code> would transport as many people as would fit
085             * into the vehicle and drive to location B. The next call would then imply
086             * going back to location A, fetch another batch of people there and go
087             * back to B.
088             * 
089             */
090            public long perform(T activity, HashMap<String,Integer> attributes);
091    
092    }