/**
* Performs the web-service call. If the <code>session</code> parameter is <code>non-null</code>
* then an authenticated call is made. If it's <code>null</code> then an unauthenticated call is
* made.<br>
* The <code>apiKey</code> parameter is always required, even when a valid session is passed to
* this method.
*
* @param method The method to call
* @param apiKey A Last.fm API key
* @param params Parameters
* @param session A Session instance or <code>null</code>
* @return the result of the operation
*/
private Result call(String method, String apiKey, Map<String, String> params) {
params =
new HashMap<String, String>(params); // create new Map in case params is an immutable Map
InputStream inputStream = null;
// try to load from cache
String cacheEntryName = Cache.createCacheEntryName(method, params);
if (cache != null) {
inputStream = getStreamFromCache(cacheEntryName);
}
// no entry in cache, load from web
if (inputStream == null) {
// fill parameter map with apiKey and session info
params.put(PARAM_API_KEY, apiKey);
try {
HttpURLConnection urlConnection = openPostConnection(method, params);
inputStream = getInputStreamFromConnection(urlConnection);
if (inputStream == null) {
this.lastResult =
Result.createHttpErrorResult(
urlConnection.getResponseCode(), urlConnection.getResponseMessage());
return lastResult;
} else {
if (cache != null) {
long expires = urlConnection.getHeaderFieldDate("Expires", -1);
if (expires == -1) {
expires = cache.findExpirationDate(method, params);
}
if (expires != -1) {
cache.store(
cacheEntryName, inputStream, expires); // if data wasn't cached store new result
inputStream = cache.load(cacheEntryName);
if (inputStream == null) throw new CallException("Caching/Reloading failed");
}
}
}
} catch (IOException e) {
throw new CallException(e);
}
}
try {
Result result = createResultFromInputStream(inputStream);
if (!result.isSuccessful()) {
Log.w(TAG, String.format("API call failed with result: %s%n", result));
if (cache != null) {
cache.remove(cacheEntryName);
}
}
this.lastResult = result;
return result;
} catch (IOException e) {
throw new CallException(e);
} catch (SAXException e) {
throw new CallException(e);
}
}
/**
* Creates a Last.fm playlist.
*
* @param title A title for the playlist
* @param description A description for the playlist
* @param session A Session instance
* @return the result of the operation
*/
public static Playlist create(String title, String description, Session session) {
Result result =
Caller.getInstance()
.call("playlist.create", session, "title", title, "description", description);
if (!result.isSuccessful()) return null;
return ResponseBuilder.buildItem(
result.getContentElement().getChild("playlist"), Playlist.class);
}
/**
* Gets a list of a user's playlists on Last.fm. Note that this method only fetches metadata
* regarding the user's playlists. If you want to retrieve the list of tracks in a playlist use
* {@link Playlist#fetch(String, String) Playlist.fetch()}.
*
* @param user The last.fm username to fetch the playlists of.
* @param apiKey A Last.fm API key.
* @return a list of Playlists
*/
public static Collection<Playlist> getPlaylists(String user, String apiKey) {
Result result = Caller.getInstance().call("user.getPlaylists", apiKey, "user", user);
if (!result.isSuccessful()) return Collections.emptyList();
Collection<Playlist> playlists = new ArrayList<Playlist>();
for (DomElement element : result.getContentElement().getChildren("playlist")) {
playlists.add(Playlist.playlistFromElement(element));
}
return playlists;
}
/**
* Get a list of valid countries and {@link de.umass.lastfm.Geo.Metro}s for use in the other
* webservices.
*
* @param country Optionally restrict the results to those Metros from a particular country, as
* defined by the ISO 3166-1 country names standard
* @param apiKey A Last.fm API key
* @return a List of {@link de.umass.lastfm.Geo.Metro}s
*/
public static Collection<Metro> getMetros(String country, String apiKey) {
Map<String, String> params = new HashMap<String, String>();
MapUtilities.nullSafePut(params, "country", country);
Result result = Caller.getInstance().call("geo.getMetros", apiKey, params);
if (!result.isSuccessful()) return Collections.emptyList();
Collection<DomElement> children = result.getContentElement().getChildren("metro");
Collection<Metro> metros = new ArrayList<Metro>(children.size());
for (DomElement child : children) {
metros.add(new Metro(child.getChildText("name"), child.getChildText("country")));
}
return metros;
}
private Result createResultFromInputStream(InputStream inputStream)
throws SAXException, IOException {
Document document =
newDocumentBuilder().parse(new InputSource(new InputStreamReader(inputStream, "UTF-8")));
Element root = document.getDocumentElement(); // lfm element
String statusString = root.getAttribute("status");
Status status = "ok".equals(statusString) ? Status.OK : Status.FAILED;
if (status == Status.FAILED) {
Element errorElement = (Element) root.getElementsByTagName("error").item(0);
int errorCode = Integer.parseInt(errorElement.getAttribute("code"));
String message = errorElement.getTextContent();
return Result.createRestErrorResult(errorCode, message);
} else {
return Result.createOkResult(document);
}
}
static Result createRestErrorResult(int errorCode, String errorMessage) {
Result r = new Result(errorMessage);
r.errorCode = errorCode;
return r;
}
static Result createHttpErrorResult(int httpErrorCode, String errorMessage) {
Result r = new Result(errorMessage);
r.httpErrorCode = httpErrorCode;
return r;
}