JarCastingOpenLastFM
Simple Java library for non-auth methods of Last.fm API.
OpenLastFM provides all available Last.fm API methods that don't require user authorization. Can be useful for grabbing some data from the service. E.g. artist info, album alias correction, popular tracks around and etc.
- Contains Java object wrappers for any API response
- Supports paginated result response (search or lists with many objects)
- Convenient request builders
- Can check methods for required parameters before calling
- Supports consistent queries
Full list of methods is available in Last.fm API Documentation
Installing
Maven
In your pom.xml inside the <dependencies> tag
<dependencies>
...
<dependency>
<groupId>ru.blizzed</groupId>
<artifactId>openlastfm</artifactId>
<version>1.0.3</version>
</dependency>
</dependencies>
Gradle
In your build.gradle file inside the dependencies section
- Gradle 3.0 and above
dependencies {
...
implementation 'ru.blizzed:openlastfm:1.0.3'
}
- Below 3.0
dependencies {
...
compile 'ru.blizzed:openlastfm:1.0.3'
}
Usage
Initialization
First of all you need to initialize library by calling one of available initialize methods.
- You don't care about
langparam (default is EN)
OpenLastFMContext.initialize("your-last-fm-api-key");
- You need a custom language
OpenLastFMContext.initialize("your-last-fm-api-key", Locale.YOUR_LOCALE);
You can configure each request with lang param to support multilanguage
Building and executing requests
For example, you need to call a method from the artist section, then needed class, that contains all available methods, is ApiArtist. This class (and others such classes) provides you completed methods with expected result calling type.
ApiMethod<ArtistInfo> artistInfoMethod = ApiArtist.getInfo();
Now you need to pass params into the method and generate a request. In OpenLastFM all requests are ApiRequest's. You can get it by calling withParams method of gotten ApiMethod with needed set of params. All params are instance of Param and have expected input data type. Static class LastFMParams contains completed instances of all parameters so you should use it.
ApiRequest<ArtistInfo> request = artistInfoMethod.withParams(LastFMParams.ARTIST.of("Dimmu Borgir"));
or the same but with a set of params
ApiRequest<ArtistInfo> request = artistInfoMethod.withParams(
LastFMParams.ARTIST.of("Dimmu Borgir"),
LastFMParams.LANG.of(Locale.GERMAN)
);
Yeah! We've got an ApiRequest and now we are a step away from the learning of Dimmu Borgir! All we need to do is just execute this request. Let's do this now!
- With callback
ApiRequestListener
request.execute(new ApiRequest.ApiRequestListener<ArtistInfo>() {
@Override
public void onComplete(ApiResponse<ArtistInfo> response) {
ArtistInfo artistInfo = response.getContent();
System.out.println(artistInfo.getBio().getContent());
@Override
public void onApiError(ApiResponse<Error> error) {
/* This method triggers you when API has been called but response contains an error */
// Handle Api Error
@Override
public void onFailure(ApiRequestException exception) {
/* This method triggers you when call to API cannot be established E.g. no internet connection */
// Handle Failure
}
});
Tip: you can override not all callback methods
- With exceptions handling
try {
ApiResponse<ArtistInfo> response = request.execute();
ArtistInfo artist = response.getContent();
System.out.println(artist.getBio().getContent());
} catch (ApiRequestException | ApiResponseException e) {
// Handle error
}
Wow! We learned that Dimmu Borgir is amazing norwegian Symphonic Black Metal band and now we want to get and listen to their tracks from the best album! But what if you want to get only 5 tracks now, and others you are going to estimate tomorrow when your roommate will go away and you will got a wonderful opportunity for a powerful headbanging? Hmm.. Let's take a look!
Paginated responses
Here we are building our initial request as usual and if we need the next page just call getNextPageRequest
ApiRequest<PageResult<Track>> request = ApiArtist.getTopTracks().withParams(
LastFMParams.ARTIST.of("Dimmu Borgir"),
LastFMParams.PERIOD.of(Period.THREE_MONTHS),
LastFMParams.LIMIT.of(5) // 5 tracks per page
);
PageResult<Track> trackPage = request.execute().getContent();
trackPage.getItems().forEach(System.out::println);
PageResult<Track> nextPage = trackPage.getNextPageRequest(request).execute().getContent();
Request cancelling
Something went wrong and your roommate is coming back so you need to cancel request for the next portion of headbanging tracks immediately:
request.cancel();
Errors
You can use errors.LastFMErrors class that contains all Last.FM API errors with descriptions.
Customization
Custom param
You can create your own Param with certain content type
Param<SomeType> param = new Param("paramName");
Custom method
ApiMethod<SomeType> albumApiMethod = new ApiMethod.Builder<SomeType>("sectionName", "method")
.addParamsDescriptions(
new ApiParamDescription(LastFMParams.ARTIST, true, LastFMParams.MBID),
new ApiParamDescription(LastFMParams.MBID, false),
new ApiParamDescription(LastFMParams.AUTOCORRECT, false)
)
.buildWithResultModelParser(new ModelParser<SomeType>("rootTag") {
@Override
public SomeType parse(JsonObject root) {
return new Gson().parse(root, new SomeType.class);
}
});
ApiParamDescription is just helper-wrapper class, which second parameter in constructor is flag that shows param is required for API. Third parameter is not required, but used for special situations when one of params is required but can be replaced by another. See examples in Last.fm API documentation. Params descriptions are not required but desirable.
ModelParser is an interface which implementation should parse an expected response object using Google Gson. You can use completed implementations such as models.ObjectModelParser, models.SkipRootModelParser, models.PaginatedResultModelParser, and etc.
License
Copyright (c) 2017 BlizzedRu (Ivan Vlasov)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.