001/* 002 * Copyright (c) 2012, the Last.fm Java Project and Committers 003 * All rights reserved. 004 * 005 * Redistribution and use of this software in source and binary forms, with or without modification, are 006 * permitted provided that the following conditions are met: 007 * 008 * - Redistributions of source code must retain the above 009 * copyright notice, this list of conditions and the 010 * following disclaimer. 011 * 012 * - Redistributions in binary form must reproduce the above 013 * copyright notice, this list of conditions and the 014 * following disclaimer in the documentation and/or other 015 * materials provided with the distribution. 016 * 017 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED 018 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 019 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 020 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 021 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 022 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 023 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 024 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 025 */ 026 027package de.umass.lastfm; 028 029import java.util.Collection; 030import java.util.Collections; 031import java.util.HashMap; 032import java.util.Map; 033 034import de.umass.util.MapUtilities; 035import de.umass.xml.DomElement; 036 037/** 038 * Venue information bean. 039 * 040 * @author Janni Kovacs 041 */ 042public class Venue extends ImageHolder { 043 044 static final ItemFactory<Venue> FACTORY = new VenueFactory(); 045 046 private String name; 047 private String url, website; 048 private String city, country, street, postal, phonenumber; 049 050 private float latitude, longitude; 051 private String timezone; 052 private String id; 053 054 private Venue() { 055 } 056 057 public String getId() { 058 return id; 059 } 060 061 /** 062 * Returns a last.fm URL to this venue, e.g.: https://www.last.fm/venue/<id>-<venue name> 063 * 064 * @return last.fm url 065 * @see #getWebsite() 066 */ 067 public String getUrl() { 068 return url; 069 } 070 071 /** 072 * Returns an URL to the actual venue's website. 073 * 074 * @return website url 075 */ 076 public String getWebsite() { 077 return website; 078 } 079 080 public String getCity() { 081 return city; 082 } 083 084 public String getCountry() { 085 return country; 086 } 087 088 public float getLatitude() { 089 return latitude; 090 } 091 092 public float getLongitude() { 093 return longitude; 094 } 095 096 public String getName() { 097 return name; 098 } 099 100 public String getPostal() { 101 return postal; 102 } 103 104 public String getStreet() { 105 return street; 106 } 107 108 public String getTimezone() { 109 return timezone; 110 } 111 112 public String getPhonenumber() { 113 return phonenumber; 114 } 115 116 /** 117 * Search for a venue by venue name. 118 * 119 * @param venue The venue name you would like to search for 120 * @param apiKey A Last.fm API key 121 * @return a list of venues 122 */ 123 public static Collection<Venue> search(String venue, String apiKey) { 124 return search(venue, null, apiKey); 125 } 126 127 /** 128 * Search for a venue by venue name. 129 * 130 * @param venue The venue name you would like to search for 131 * @param country Filter your results by country. Expressed as an ISO 3166-2 code 132 * @param apiKey A Last.fm API key 133 * @return a list of venues 134 */ 135 public static Collection<Venue> search(String venue, String country, String apiKey) { 136 Map<String, String> params = new HashMap<String, String>(); 137 params.put("venue", venue); 138 MapUtilities.nullSafePut(params, "country", country); 139 Result result = Caller.getInstance().call("venue.search", apiKey, params); 140 if (!result.isSuccessful()) 141 return Collections.emptyList(); 142 DomElement child = result.getContentElement().getChild("venuematches"); 143 return ResponseBuilder.buildCollection(child, Venue.class); 144 } 145 146 /** 147 * Get a list of upcoming events at this venue. 148 * 149 * @param venueId The venue id to fetch the events for 150 * @param apiKey A Last.fm API key 151 * @return a list of events 152 * @see #getPastEvents 153 */ 154 public static Collection<Event> getEvents(String venueId, String apiKey) { 155 return getEvents(venueId, false, apiKey); 156 } 157 158 /** 159 * Get a list of upcoming events at this venue. 160 * 161 * @param venueId The venue id to fetch the events for 162 * @param festivalsOnly Whether only festivals should be returned, or all events 163 * @param apiKey A Last.fm API key 164 * @return a list of events 165 * @see #getPastEvents 166 */ 167 public static Collection<Event> getEvents(String venueId, boolean festivalsOnly, String apiKey) { 168 Result result = Caller.getInstance().call("venue.getEvents", apiKey, "venue", venueId, "festivalsonly", festivalsOnly ? "1" : "0" ); 169 return ResponseBuilder.buildCollection(result, Event.class); 170 } 171 172 /** 173 * Get a paginated list of all the events held at this venue in the past. 174 * 175 * @param venueId The id for the venue you would like to fetch event listings for 176 * @param apiKey A Last.fm API key 177 * @return a paginated list of events 178 */ 179 public static PaginatedResult<Event> getPastEvents(String venueId, String apiKey) { 180 return getPastEvents(venueId, false, -1, -1, apiKey); 181 } 182 183 /** 184 * Get a paginated list of all the events held at this venue in the past. 185 * 186 * @param venueId The id for the venue you would like to fetch event listings for 187 * @param festivalsOnly Whether only festivals should be returned, or all events. 188 * @param page The page of results to return 189 * @param limit The number of results to fetch per page. 190 * @param apiKey A Last.fm API key 191 * @return a paginated list of events 192 */ 193 public static PaginatedResult<Event> getPastEvents(String venueId, boolean festivalsOnly, int page, int limit, String apiKey) { 194 Map<String, String> params = new HashMap<String, String>(); 195 params.put("venue", venueId); 196 params.put("festivalsonly", festivalsOnly ? "1" : "0"); 197 MapUtilities.nullSafePut(params, "page", page); 198 MapUtilities.nullSafePut(params, "limit", limit); 199 Result result = Caller.getInstance().call("venue.getPastEvents", apiKey, params); 200 return ResponseBuilder.buildPaginatedResult(result, Event.class); 201 } 202 203 private static class VenueFactory implements ItemFactory<Venue> { 204 public Venue createItemFromElement(DomElement element) { 205 Venue venue = new Venue(); 206 venue.id = element.getChildText("id"); 207 venue.name = element.getChildText("name"); 208 venue.url = element.getChildText("url"); 209 venue.phonenumber = element.getChildText("phonenumber"); 210 venue.website = element.getChildText("website"); 211 ImageHolder.loadImages(venue, element); 212 DomElement l = element.getChild("location"); 213 venue.city = l.getChildText("city"); 214 venue.country = l.getChildText("country"); 215 venue.street = l.getChildText("street"); 216 venue.postal = l.getChildText("postalcode"); 217 venue.timezone = l.getChildText("timezone"); 218 DomElement p = l.getChild("geo:point"); 219 if (p.getChildText("geo:lat").length() != 0) { // some venues don't have geo information applied 220 venue.latitude = Float.parseFloat(p.getChildText("geo:lat")); 221 venue.longitude = Float.parseFloat(p.getChildText("geo:long")); 222 } 223 return venue; 224 } 225 } 226}