Installing the plugin

In the root of your grails project, use the command line to install the plugin with:

$ grails install-plugin itunes-services

iTunes Service Plugin

Description

A plugin for the Grails Framework that facilitates the integration with iTunes Search Services and Feeds. The plugin draws on the Rome libraries to parse and handle feed data, and then converts results into instances of an Album domain class. It also provides advanced Search API functionality, marshalling these into various Domain Classes.

The net result: Wire a service into your controller, call a method, and receive back a list of Domain objects that may be persisted or rendered directly in your GSP.

Feeds and Web Services

The initial release focused only on retrieving and processing RSS Feeds that iTunes exposes. Subsequent releases include Artist and Album searches to mention a few. The plugin will also expand beyond the realm of Music, and will include Apps, Podcasts, TV Programs, Films and Music Videos. Please let me know what else you would like from the plugin!

Using the Feeds API

class FeedsDemoController {
    def itunesFeedsService
    ...
    //inside the action closure
    def command = new FeedsCommand()
    List newReleases = itunesFeedsService.getNewAlbumReleases(command)
    List justAddedAlbums = itunesFeedsService.getJustAddedAlbums(command)
    List featuredAlbums = itunesFeedsService.getFeaturedAlbums(command)
    List topAlbums = itunesFeedsService.getTopAlbums(command)
    //from release 0.1.1 you can omit the command object on all service calls for default values
    List defaultNewReleases = itunesFeedsService.getNewAlbumReleases()
    ...
}

Please refer to the source code for more details about structuring your searches, and the fields available in the domain instances returned.

Using the Search API

class SearchDemoController {
    def itunesSearchService
    ...
    //in the action closure
    List artistByName = itunesSearchService.searchArtistsbyName('xxxx')
    List albumsByName = itunesSearchService.searchAlbumsByName('xxxx')
    List albumsByArtist = itunesSearchService.searchAlbumsByArtist('xxxx')
    List tracksByName = itunesSearchService.searchTracksByName('xxxx')
    List tracksByArtist = itunesSearchService.searchTracksByArtist('xxxx')
    ...
}

Please refer to the source code for more details about structuring your searches, and the fields available in the domain instances returned.

SearchProfiles

The iTunes Search Service also provides a search() method that takes an ItunesSearchCommand object. This ItunesSearchCommand is constructed with a SearchProfile enum instance and a search term. This give a convenient method of performing preconfigured complex searches.

The SearchProfile enum:

enum SearchProfile {
    ALBUMS('Albums', Media.MUSIC, Entity.ALBUM, Attribute.ALBUM_TERM),
    MUSIC_ARTISTS('Artists', Media.MUSIC, Entity.MUSIC_ARTIST, Attribute.ARTIST_TERM),
    MUSIC_TRACKS('Tracks', Media.MUSIC, Entity.MUSIC_TRACK, Attribute.MUSIC_TRACK_TERM),
    ALBUMS_BY_ARTIST('Albums by Artist', Media.MUSIC, Entity.ALBUM, Attribute.ARTIST_TERM),
    TRACKS_BY_ARTIST('Tracks by Artist', Media.MUSIC, Entity.MUSIC_TRACK, Attribute.ARTIST_TERM)
    String name
    Media media
    Entity entity
    Attribute attribute
    public SearchProfile(String name, Media media, Entity entity, Attribute attribute){
        this.name = name
        this.media = media
        this.entity = entity
        this.attribute = attribute
    }
}

This gives you many handy permutations of the Media, Entity and Attribute enums. Alternativeley you could instantiate an ItunesSearchCommand using instances of these low level enums (Media, Entity and Attribute) in order to construct your own queries.

To understand the iTunes search API, please refer to the following docs: http://www.apple.com/itunes/affiliates/resources/documentation/itunes-store-web-service-search-api.html

Once again, please refer to the source code for more details of this implementation.

Bugs and Enhancements

Find bugs or want enhancements? Please come over to http://jira.grails.org/browse/GPITUNES and report any bugs or usability issues. New feature requests are also always welcome!

Source Code

Source code is available at: http://github.com/marcoVermeulen/grails-itunes-services-plugin

Demo

Fetch the plugin source from GitHub, step into the plugin directory and run the app:

git clone git@github.com:marcoVermeulen/grails-itunes-services-plugin.git
cd grails-itunes-services-plugin
grails run-app

Wait for the application to start up and point your browser at http://localhost:8080/itunes-service/feedsDemo and http://localhost:8080/itunes-service/searchDemo