me.tobiadeyinka.itunessearch.search

Class MediaSearch

java.lang.Object

me.tobiadeyinka.itunessearch.search.MediaSearch

public class MediaSearch
extends Object

API endpoint for non-specific media types. See Searching the iTunes Store for more details about the parameters. Created by Tobi Adeyinka on 2017. 10. 15..

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	allowExplicit allow/exclude explicit content in search results.
protected int	apiVersion The version of the iTunes api to use (1/2).
protected com.neovisionaries.i18n.CountryCode	countryCode ISO 3166-1 alpha-2 country code for the iTunes store to search.
protected int	limit The maximum number of item's to return.
protected ItunesMedia	media The media type to search for.
protected ReturnLanguage	returnLanguage The language to return the result in (only english/japanese).
protected String	searchTerm The term to search for.
protected URL	searchUrl URL used to search the iTunes store, generated using all the variables of the instance

Constructor Summary

Constructors

Constructor and Description
MediaSearch()

Method Summary

Modifier and Type	Method and Description
T	allowExplicit(boolean allowExplicit) allow/remove explicit content in search results.
MediaSearch	andReturn(MediaSearchReturnType returnType) Sets the return type of the results
protected String	constructUrlString()
org.json.JSONObject	execute() execute the search
boolean	explicitAllowed()
int	getApiVersion()
MediaAttribute	getAttribute()
com.neovisionaries.i18n.CountryCode	getCountryCode()
int	getLimit()
ItunesMedia	getMedia()
ReturnLanguage	getReturnLanguage()
MediaSearchReturnType	getReturnType()
String	getSearchTerm()
URL	getSearchUrl()
MediaSearch	inAttribute(MediaAttribute attribute) Sets the media attribute the search term is compared with.
T	inCountry(com.neovisionaries.i18n.CountryCode countryCode) Sets the iTunes store to search.
protected void	runPreExecutionChecks() check the validity of all required data before executing the search
T	with(String searchTerm) Sets the term to search for.
T	withApiVersion(ItunesApiVersion apiVersion) Set the version of the iTunes api to use (1/2).
T	withLimit(int limit) Sets the maximum number of item's to return.
T	withReturnLanguage(ReturnLanguage returnLanguage) Sets the language results are return in.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

searchTerm

protected String searchTerm

The term to search for.

media

protected final ItunesMedia media

The media type to search for.

limit

protected int limit

The maximum number of item's to return. Default is 50.

apiVersion

protected int apiVersion

The version of the iTunes api to use (1/2). Default is 2.

allowExplicit

protected boolean allowExplicit

allow/exclude explicit content in search results. Explicit content is allowed by default.

countryCode

protected com.neovisionaries.i18n.CountryCode countryCode

ISO 3166-1 alpha-2 country code for the iTunes store to search. Default is US.

returnLanguage

protected ReturnLanguage returnLanguage

The language to return the result in (only english/japanese). Default is english.

searchUrl

protected URL searchUrl

URL used to search the iTunes store, generated using all the variables of the instance

Constructor Detail

MediaSearch

public MediaSearch()

Method Detail

inAttribute

public MediaSearch inAttribute(MediaAttribute attribute)

Sets the media attribute the search term is compared with. Default is all attributes.

Parameters:

attribute - the music attribute the searchTerm is compared with.

Returns:

the current instance of MediaSearch

andReturn

public MediaSearch andReturn(MediaSearchReturnType returnType)

Sets the return type of the results

Parameters:

returnType - the type of results you want returned

Returns:

the current instance of MediaSearch

constructUrlString

protected String constructUrlString()

getAttribute

public MediaAttribute getAttribute()

Returns:

the attribute to search in

getReturnType

public MediaSearchReturnType getReturnType()

Returns:

the type of data to return

with

public T with(String searchTerm)

Sets the term to search for. Required.

Parameters:

searchTerm - the term to search for

Returns:

the current search instance

withLimit

public T withLimit(int limit)

Sets the maximum number of item's to return. Default is 50.

Parameters:

limit - the maximum number of item's to return.

Returns:

the current search instance

withApiVersion

public T withApiVersion(ItunesApiVersion apiVersion)

Set the version of the iTunes api to use (1/2). Default is 2.

Parameters:

apiVersion - the version of the iTunes api to use.

Returns:

the current search instance

allowExplicit

public T allowExplicit(boolean allowExplicit)

allow/remove explicit content in search results. Explicit content is allowed by default.

Parameters:

allowExplicit - allow explicit content or not.

Returns:

the current search instance

withReturnLanguage

public T withReturnLanguage(ReturnLanguage returnLanguage)

Sets the language results are return in. Default is english.

Parameters:

returnLanguage - The language result should be return in.

Returns:

the current search instance

inCountry

public T inCountry(com.neovisionaries.i18n.CountryCode countryCode)

Sets the iTunes store to search.

Parameters:

countryCode - ISO 3166-1 alpha-2 country code for the iTunes store to search. Default is US.

Returns:

the current instance of MediaSearch

runPreExecutionChecks

protected void runPreExecutionChecks()

check the validity of all required data before executing the search

Throws:

MissingRequiredParameterException - if the search term is not set.

InvalidParameterException - if any of the set parameters are invalid.

execute

public org.json.JSONObject execute()

execute the search

Returns:

A JSONObject object containing the results.

Throws:

MissingRequiredParameterException - if the search term is not set.

InvalidParameterException - if any of the set parameters are invalid.

SearchURLConstructionFailure - if there is an error during url construction.

NetworkCommunicationException - if any issues occur while communicating with the iTunes api.

getSearchTerm

public String getSearchTerm()

Returns:

the term being searched for

getMedia

public ItunesMedia getMedia()

Returns:

the set media type being searched for

getLimit

public int getLimit()

Returns:

the maximum number of results

getApiVersion

public int getApiVersion()

Returns:

the api version to use

explicitAllowed

public boolean explicitAllowed()

Returns:

the explicit data setting

getCountryCode

public com.neovisionaries.i18n.CountryCode getCountryCode()

Returns:

the iTunes store being searched

getReturnLanguage

public ReturnLanguage getReturnLanguage()

Returns:

the language the result should be returned in

getSearchUrl

public URL getSearchUrl()

Returns:

the url used to search the iTunes store.