PageRenderTime 64ms CodeModel.GetById 23ms RepoModel.GetById 0ms app.codeStats 0ms

/foobnix-parent-utils/foobnix-lastfm/src/main/java/de/umass/lastfm/Geo.java

https://github.com/foobnix/foobnix-android
Java | 285 lines | 140 code | 36 blank | 109 comment | 6 complexity | 730a424910c6b4a0419f300cd3fdd8ce MD5 | raw file
    

  1. /*

    2. 

  2.  * Copyright (c) 2011, the Last.fm Java Project and Committers

    3. 

  3.  * All rights reserved.

    4. 

  4.  *

    5. 

  5.  * Redistribution and use of this software in source and binary forms, with or without modification, are

    6. 

  6.  * permitted provided that the following conditions are met:

    7. 

  7.  *

    8. 

  8.  * - Redistributions of source code must retain the above

    9. 

  9.  *   copyright notice, this list of conditions and the

    10. 

  10.  *   following disclaimer.

    11. 

  11.  *

    12. 

  12.  * - Redistributions in binary form must reproduce the above

    13. 

  13.  *   copyright notice, this list of conditions and the

    14. 

  14.  *   following disclaimer in the documentation and/or other

    15. 

  15.  *   materials provided with the distribution.

    16. 

  16.  *

    17. 

  17.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED

    18. 

  18.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

    19. 

  19.  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR

    20. 

  20.  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

    21. 

  21.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

    22. 

  22.  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR

    23. 

  23.  * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF

    24. 

  24.  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    25. 

  25.  */

    26. 

  26. 

    27. 

  27. package de.umass.lastfm;

    28. 

  28. 

    29. 

  29. import java.util.*;

    30. 

  30. 

    31. 

  31. import de.umass.util.MapUtilities;

    32. 

  32. import de.umass.util.StringUtilities;

    33. 

  33. import de.umass.xml.DomElement;

    34. 

  34. 

    35. 

  35. /**

    36. 

  36.  * Provides nothing more than a namespace for the API methods starting with geo.

    37. 

  37.  *

    38. 

  38.  * @author Janni Kovacs

    39. 

  39.  */

    40. 

  40. public class Geo {

    41. 

  41. 

    42. 

  42. 	/**

    43. 

  43. 	 * This inner class represents a Metro, which is composed of its name and the name of its country.

    44. 

  44. 	 *

    45. 

  45. 	 * @see Geo#getMetros(String, String)

    46. 

  46. 	 */

    47. 

  47. 	public static class Metro {

    48. 

  48. 		private String name;

    49. 

  49. 		private String country;

    50. 

  50. 

    51. 

  51. 		public Metro(String name, String country) {

    52. 

  52. 			this.name = name;

    53. 

  53. 			this.country = country;

    54. 

  54. 		}

    55. 

  55. 

    56. 

  56. 		public String getName() {

    57. 

  57. 			return name;

    58. 

  58. 		}

    59. 

  59. 

    60. 

  60. 		public String getCountry() {

    61. 

  61. 			return country;

    62. 

  62. 		}

    63. 

  63. 	}

    64. 

  64. 

    65. 

  65. 	private Geo() {

    66. 

  66. 	}

    67. 

  67. 

    68. 

  68. 	/**

    69. 

  69. 	 * Get all events in a specific location by country or city name.<br/> This method returns <em>all</em> events by subsequently calling

    70. 

  70. 	 * {@link #getEvents(String, String, int, String)} and concatenating the single results into one list.<br/> Pay attention if you use this

    71. 

  71. 	 * method as it may produce a lot of network traffic and therefore may consume a long time.

    72. 

  72. 	 *

    73. 

  73. 	 * @param location Specifies a location to retrieve events for

    74. 

  74. 	 * @param distance Find events within a specified distance

    75. 

  75. 	 * @param apiKey A Last.fm API key.

    76. 

  76. 	 * @return a list containing all events

    77. 

  77. 	 */

    78. 

  78. 	public static Collection<Event> getAllEvents(String location, String distance, String apiKey) {

    79. 

  79. 		Collection<Event> events = null;

    80. 

  80. 		int page = 1, total;

    81. 

  81. 		do {

    82. 

  82. 			PaginatedResult<Event> result = getEvents(location, distance, page, apiKey);

    83. 

  83. 			total = result.getTotalPages();

    84. 

  84. 			Collection<Event> pageResults = result.getPageResults();

    85. 

  85. 			if (events == null) {

    86. 

  86. 				// events is initialized here to initialize it with the right size and avoid array copying later on

    87. 

  87. 				events = new ArrayList<Event>(total * pageResults.size());

    88. 

  88. 			}

    89. 

  89. 			for (Event artist : pageResults) {

    90. 

  90. 				events.add(artist);

    91. 

  91. 			}

    92. 

  92. 			page++;

    93. 

  93. 		} while (page <= total);

    94. 

  94. 		return events;

    95. 

  95. 	}

    96. 

  96. 

    97. 

  97. 	/**

    98. 

  98. 	 * Get all events in a specific location by country or city name.<br/> This method only returns the first page of a possibly paginated

    99. 

  99. 	 * result. To retrieve all pages get the total number of pages via {@link de.umass.lastfm.PaginatedResult#getTotalPages()} and subsequently

    100. 

  100. 	 * call {@link #getEvents(String, String, int, String)} with the successive page numbers.

    101. 

  101. 	 *

    102. 

  102. 	 * @param location Specifies a location to retrieve events for

    103. 

  103. 	 * @param distance Find events within a specified distance

    104. 

  104. 	 * @param apiKey A Last.fm API key.

    105. 

  105. 	 * @return a {@link PaginatedResult} containing a list of events

    106. 

  106. 	 */

    107. 

  107. 	public static PaginatedResult<Event> getEvents(String location, String distance, String apiKey) {

    108. 

  108. 		return getEvents(location, distance, 1, apiKey);

    109. 

  109. 	}

    110. 

  110. 

    111. 

  111. 	/**

    112. 

  112. 	 * Get all events in a specific location by country or city name.<br/> This method only returns the specified page of a paginated result.

    113. 

  113. 	 *

    114. 

  114. 	 * @param location Specifies a location to retrieve events for

    115. 

  115. 	 * @param distance Find events within a specified distance

    116. 

  116. 	 * @param page A page number for pagination

    117. 

  117. 	 * @param apiKey A Last.fm API key.

    118. 

  118. 	 * @return a {@link PaginatedResult} containing a list of events

    119. 

  119. 	 */

    120. 

  120. 	public static PaginatedResult<Event> getEvents(String location, String distance, int page, String apiKey) {

    121. 

  121. 		Map<String, String> params = new HashMap<String, String>();

    122. 

  122. 		params.put("page", String.valueOf(page));

    123. 

  123. 		MapUtilities.nullSafePut(params, "location", location);

    124. 

  124. 		MapUtilities.nullSafePut(params, "distance", distance);

    125. 

  125. 		Result result = Caller.getInstance().call("geo.getEvents", apiKey, params);

    126. 

  126. 		return ResponseBuilder.buildPaginatedResult(result, Event.class);

    127. 

  127. 	}

    128. 

  128. 

    129. 

  129. 	/**

    130. 

  130. 	 * Get all events in a specific location by country or city name.<br/> This method only returns the specified page of a paginated result.

    131. 

  131. 	 *

    132. 

  132. 	 * @param latitude Latitude

    133. 

  133. 	 * @param longitude Longitude

    134. 

  134. 	 * @param page A page number for pagination

    135. 

  135. 	 * @param apiKey A Last.fm API key.

    136. 

  136. 	 * @return a {@link PaginatedResult} containing a list of events

    137. 

  137. 	 */

    138. 

  138. 	public static PaginatedResult<Event> getEvents(double latitude, double longitude, int page, String apiKey) {

    139. 

  139. 		Map<String, String> params = new HashMap<String, String>();

    140. 

  140. 		params.put("page", String.valueOf(page));

    141. 

  141. 		params.put("lat", String.valueOf(latitude));

    142. 

  142. 		params.put("long", String.valueOf(longitude));

    143. 

  143. 		Result result = Caller.getInstance().call("geo.getEvents", apiKey, params);

    144. 

  144. 		return ResponseBuilder.buildPaginatedResult(result, Event.class);

    145. 

  145. 	}

    146. 

  146. 

    147. 

  147. 	/**

    148. 

  148. 	 * Get the most popular artists on Last.fm by country

    149. 

  149. 	 *

    150. 

  150. 	 * @param country A country name, as defined by the ISO 3166-1 country names standard

    151. 

  151. 	 * @param apiKey A Last.fm API key.

    152. 

  152. 	 * @return list of Artists

    153. 

  153. 	 */

    154. 

  154. 	public static Collection<Artist> getTopArtists(String country, String apiKey) {

    155. 

  155. 		Result result = Caller.getInstance().call("geo.getTopArtists", apiKey, "country", country);

    156. 

  156. 		return ResponseBuilder.buildCollection(result, Artist.class);

    157. 

  157. 	}

    158. 

  158. 

    159. 

  159. 	/**

    160. 

  160. 	 * Get the most popular tracks on Last.fm by country

    161. 

  161. 	 *

    162. 

  162. 	 * @param country A country name, as defined by the ISO 3166-1 country names standard

    163. 

  163. 	 * @param apiKey A Last.fm API key.

    164. 

  164. 	 * @return a list of Tracks

    165. 

  165. 	 */

    166. 

  166. 	public static Collection<Track> getTopTracks(String country, String apiKey) {

    167. 

  167. 		Result result = Caller.getInstance().call("geo.getTopTracks", apiKey, "country", country);

    168. 

  168. 		return ResponseBuilder.buildCollection(result, Track.class);

    169. 

  169. 	}

    170. 

  170. 

    171. 

  171. 	/**

    172. 

  172. 	 * Get a list of valid countries and {@link Metro}s for use in the other webservices.

    173. 

  173. 	 *

    174. 

  174. 	 * @param apiKey A Last.fm API key

    175. 

  175. 	 * @return a List of {@link Metro}s

    176. 

  176. 	 */

    177. 

  177. 	public static Collection<Metro> getMetros(String apiKey) {

    178. 

  178. 		return getMetros(null, apiKey);

    179. 

  179. 	}

    180. 

  180. 

    181. 

  181. 	/**

    182. 

  182. 	 * Get a list of valid countries and {@link Metro}s for use in the other webservices.

    183. 

  183. 	 *

    184. 

  184. 	 * @param country Optionally restrict the results to those Metros from a particular country, as defined by the ISO 3166-1 country names

    185. 

  185. 	 * standard

    186. 

  186. 	 * @param apiKey A Last.fm API key

    187. 

  187. 	 * @return a List of {@link Metro}s

    188. 

  188. 	 */

    189. 

  189. 	public static Collection<Metro> getMetros(String country, String apiKey) {

    190. 

  190. 		Map<String, String> params = new HashMap<String, String>();

    191. 

  191. 		MapUtilities.nullSafePut(params, "country", country);

    192. 

  192. 		Result result = Caller.getInstance().call("geo.getMetros", apiKey, params);

    193. 

  193. 		if (!result.isSuccessful())

    194. 

  194. 			return Collections.emptyList();

    195. 

  195. 		Collection<DomElement> children = result.getContentElement().getChildren("metro");

    196. 

  196. 		Collection<Metro> metros = new ArrayList<Metro>(children.size());

    197. 

  197. 		for (DomElement child : children) {

    198. 

  198. 			metros.add(new Metro(child.getChildText("name"), child.getChildText("country")));

    199. 

  199. 		}

    200. 

  200. 		return metros;

    201. 

  201. 	}

    202. 

  202. 

    203. 

  203. 	/**

    204. 

  204. 	 * Get a list of available chart periods for this metro, expressed as date ranges which can be sent to the chart services.

    205. 

  205. 	 *

    206. 

  206. 	 * @param metro The name of the metro, or <code>null</code>

    207. 

  207. 	 * @param apiKey A Last.fm API key

    208. 

  208. 	 * @return a list of available charts as a Map

    209. 

  209. 	 */

    210. 

  210. 	public static LinkedHashMap<String, String> getMetroWeeklyChartList(String metro, String apiKey) {

    211. 

  211. 		return Chart.getWeeklyChartList("geo.getMetroWeeklyChartList", "metro", metro, apiKey);

    212. 

  212. 	}

    213. 

  213. 

    214. 

  214. 	public static Chart<Artist> getMetroArtistChart(String country, String metro, String apiKey) {

    215. 

  215. 		return getMetroArtistChart(country, metro, null, null, apiKey);

    216. 

  216. 	}

    217. 

  217. 

    218. 

  218. 	public static Chart<Artist> getMetroArtistChart(Metro metro, String start, String end, String apiKey) {

    219. 

  219. 		return getMetroArtistChart(metro.getCountry(), metro.getName(), start, end, apiKey);

    220. 

  220. 	}

    221. 

  221. 

    222. 

  222. 	public static Chart<Artist> getMetroArtistChart(String country, String metro, String start, String end, String apiKey) {

    223. 

  223. 		return Chart.getChart("geo.getMetroArtistChart", "artist", StringUtilities.map("country", country, "metro", metro), start, end, -1, apiKey);

    224. 

  224. 	}

    225. 

  225. 

    226. 

  226. 	public static Chart<Track> getMetroTrackChart(String country, String metro, String apiKey) {

    227. 

  227. 		return getMetroTrackChart(country, metro, null, null, apiKey);

    228. 

  228. 	}

    229. 

  229. 

    230. 

  230. 	public static Chart<Track> getMetroTrackChart(Metro metro, String start, String end, String apiKey) {

    231. 

  231. 		return getMetroTrackChart(metro.getCountry(), metro.getName(), start, end, apiKey);

    232. 

  232. 	}

    233. 

  233. 

    234. 

  234. 	public static Chart<Track> getMetroTrackChart(String country, String metro, String start, String end, String apiKey) {

    235. 

  235. 		return Chart.getChart("geo.getMetroTrackChart", "track", StringUtilities.map("country", country, "metro", metro), start, end, -1, apiKey);

    236. 

  236. 	}

    237. 

  237. 

    238. 

  238. 	public static Chart<Artist> getMetroHypeArtistChart(String country, String metro, String apiKey) {

    239. 

  239. 		return getMetroHypeArtistChart(country, metro, null, null, apiKey);

    240. 

  240. 	}

    241. 

  241. 

    242. 

  242. 	public static Chart<Artist> getMetroHypeArtistChart(Metro metro, String start, String end, String apiKey) {

    243. 

  243. 		return getMetroHypeArtistChart(metro.getCountry(), metro.getName(), start, end, apiKey);

    244. 

  244. 	}

    245. 

  245. 

    246. 

  246. 	public static Chart<Artist> getMetroHypeArtistChart(String country, String metro, String start, String end, String apiKey) {

    247. 

  247. 		return Chart.getChart("geo.getMetroHypeArtistChart", "artist", StringUtilities.map("country", country, "metro", metro), start, end, -1, apiKey);

    248. 

  248. 	}

    249. 

  249. 

    250. 

  250. 	public static Chart<Track> getMetroHypeTrackChart(String country, String metro, String apiKey) {

    251. 

  251. 		return getMetroHypeTrackChart(country, metro, null, null, apiKey);

    252. 

  252. 	}

    253. 

  253. 

    254. 

  254. 	public static Chart<Track> getMetroHypeTrackChart(Metro metro, String start, String end, String apiKey) {

    255. 

  255. 		return getMetroHypeTrackChart(metro.getCountry(), metro.getName(), start, end, apiKey);

    256. 

  256. 	}

    257. 

  257. 

    258. 

  258. 	public static Chart<Track> getMetroHypeTrackChart(String country, String metro, String start, String end, String apiKey) {

    259. 

  259. 		return Chart.getChart("geo.getMetroHypeTrackChart", "track", StringUtilities.map("country", country, "metro", metro), start, end, -1, apiKey);

    260. 

  260. 	}

    261. 

  261. 

    262. 

  262. 	public static Chart<Artist> getMetroUniqueArtistChart(String country, String metro, String apiKey) {

    263. 

  263. 		return getMetroUniqueArtistChart(country, metro, null, null, apiKey);

    264. 

  264. 	}

    265. 

  265. 

    266. 

  266. 	public static Chart<Artist> getMetroUniqueArtistChart(Metro metro, String start, String end, String apiKey) {

    267. 

  267. 		return getMetroUniqueArtistChart(metro.getCountry(), metro.getName(), start, end, apiKey);

    268. 

  268. 	}

    269. 

  269. 

    270. 

  270. 	public static Chart<Artist> getMetroUniqueArtistChart(String country, String metro, String start, String end, String apiKey) {

    271. 

  271. 		return Chart.getChart("geo.getMetroUniqueArtistChart", "artist", StringUtilities.map("country", country, "metro", metro), start, end, -1, apiKey);

    272. 

  272. 	}

    273. 

  273. 

    274. 

  274. 	public static Chart<Track> getMetroUniqueTrackChart(String country, String metro, String apiKey) {

    275. 

  275. 		return getMetroUniqueTrackChart(country, metro, null, null, apiKey);

    276. 

  276. 	}

    277. 

  277. 

    278. 

  278. 	public static Chart<Track> getMetroUniqueTrackChart(Metro metro, String start, String end, String apiKey) {

    279. 

  279. 		return getMetroUniqueTrackChart(metro.getCountry(), metro.getName(), start, end, apiKey);

    280. 

  280. 	}

    281. 

  281. 

    282. 

  282. 	public static Chart<Track> getMetroUniqueTrackChart(String country, String metro, String start, String end, String apiKey) {

    283. 

  283. 		return Chart.getChart("geo.getMetroUniqueTrackChart", "track", StringUtilities.map("country", country, "metro", metro), start, end, -1, apiKey);

    284. 

  284. 	}

    285. 

  285. }
    286.