1    // ============================================================================
2    //   Copyright 2006, 2007, 2008 Daniel W. Dyer
3    //
4    //   Licensed under the Apache License, Version 2.0 (the "License");
5    //   you may not use this file except in compliance with the License.
6    //   You may obtain a copy of the License at
7    //
8    //       http://www.apache.org/licenses/LICENSE-2.0
9    //
10   //   Unless required by applicable law or agreed to in writing, software
11   //   distributed under the License is distributed on an "AS IS" BASIS,
12   //   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   //   See the License for the specific language governing permissions and
14   //   limitations under the License.
15   // ============================================================================
16   package org.uncommons.watchmaker.examples.travellingsalesman;
17   
18   import java.util.Collection;
19   import java.util.List;
20   
21   /**
22    * Defines methods that must be implemented by classes that provide
23    * solutions to the Travelling Salesman problem.
24    * @author Daniel Dyer
25    */
26   public interface TravellingSalesmanStrategy
27   {
28       /**
29        * @return A description of the strategy.
30        */
31       String getDescription();
32   
33       /**
34        * Calculates the shortest round trip distance that visits each
35        * of the specified cities once and returns to the starting point.
36        * @param cities The destination that must each be visited for the route
37        * to be valid.
38        * @param progressListener A call-back for keeping track of the route-finding
39        * algorithm's progress.
40        * @return The shortest route found for the given list of destinations.
41        */
42       List<String> calculateShortestRoute(Collection<String> cities,
43                                           ProgressListener progressListener);
44   }
45