com.google.gdata.client.youtube

Class YouTubeQuery

java.lang.Object

com.google.gdata.client.Query

com.google.gdata.client.youtube.YouTubeQuery

public class YouTubeQuery
extends Query

A helper class that helps building queries for the YouTube feeds. Not all feeds implement all parameters defined on this class. See the documentation to get the list of parameters each feed supports.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	YouTubeQuery.OrderBy Standard values for the orderby parameter.
static class	YouTubeQuery.SafeSearch Standard values for the safeSearch parameter.
static class	YouTubeQuery.Time Standard values for the time parameter.
static class	YouTubeQuery.Uploader Standard values for the uploader parameter.

Nested classes/interfaces inherited from class com.google.gdata.client.Query

Query.CategoryFilter, Query.CustomParameter, Query.ResultFormat

Field Summary

Fields inherited from class com.google.gdata.client.Query

UNDEFINED

Constructor Summary

Constructors

Constructor and Description
YouTubeQuery(URL feedUrl) Constructs a new YouTubeQuery object that targets a feed.

Method Summary

Methods

Modifier and Type	Method and Description
String	getCountryRestriction() Retrieves the country restriction set on the current query, if any.
Set<Integer>	getFormats() Gets the value of the format parameter.
boolean	getIncludeRacy() Deprecated. Please use getSafeSearch() instead.
String	getIpRestriction() Retrieves the IP restriction set on the current query, if any.
String	getLanguageRestrict() Gets the value of the lr parameter.
GeoRssWhere	getLocation() Returns the value of the location parameter.
String	getLocationRadius() Sets the value of the location-radius parameter.
YouTubeQuery.OrderBy	getOrderby() Gets the value of the orderby parameter.
String	getOrderByRelevanceForLanguage() Gets the language for which relevance ordering is optimized.
YouTubeQuery.SafeSearch	getSafeSearch() Gets the value of the safeSearch parameter.
YouTubeQuery.Time	getTime() Gets the value of the time parameter.
YouTubeQuery.Uploader	getUploader() Gets the value of the uploader parameter.
String	getVideoQuery() Deprecated. Please use Query.getFullTextQuery() instead.
boolean	hasRestrictLocation() Returns true if the query only wants results that have latitude and longitude information.
void	setCountryRestriction(String countryCode) Sets the restriction parameter to a country code.
void	setFormats(int... formats) Sets the value of the format parameter.
void	setFormats(Set<Integer> formats) Sets the value of the format parameter.
void	setIncludeRacy(Boolean includeRacy) Deprecated. Please use #setSafeSearch(String) instead.
void	setIpRestriction(String ip) Sets the restriction parameter to an IP v4 address.
void	setLanguageRestrict(String languageCode) Sets the value of the lr parameter.
void	setLocation(GeoRssWhere where) Sets the value of the location parameter.
void	setLocationRadius(String locationRadius) Sets the value of the location-radius parameter.
void	setOrderBy(YouTubeQuery.OrderBy orderBy) Sets the value of the orderby parameter.
void	setOrderByRelevanceForLanguage(String languageCode) Sets order by relevance with results optimized for a specific language.
void	setRestrictLocation(boolean isRestrictLocation) Set/unset the location restrict.
void	setSafeSearch(YouTubeQuery.SafeSearch safeSearch) Sets the value of the safeSearch parameter.
void	setTime(YouTubeQuery.Time time) Sets the value of the time parameter.
void	setUploader(YouTubeQuery.Uploader uploader) Sets the value of the uploader parameter.
void	setVideoQuery(String query) Deprecated. Please use Query#setFullTextQuery() instead.

Methods inherited from class com.google.gdata.client.Query

addCategoryFilter, addCustomParameter, appendQueryParameter, getAuthor, getCategoryFilters, getCustomParameters, getCustomParameters, getFeedUrl, getFields, getFullTextQuery, getIntegerCustomParameter, getMaxResults, getPublishedMax, getPublishedMin, getQueryUri, getResultFormat, getStartIndex, getStringCustomParameter, getUpdatedMax, getUpdatedMin, getUrl, isStrict, isValidState, setAuthor, setFields, setFullTextQuery, setIntegerCustomParameter, setMaxResults, setPublishedMax, setPublishedMin, setResultFormat, setStartIndex, setStrict, setStringCustomParameter, setUpdatedMax, setUpdatedMin

Methods inherited from class java.lang.Object

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

Constructor Detail

YouTubeQuery

public YouTubeQuery(URL feedUrl)

Constructs a new YouTubeQuery object that targets a feed. The initial state of the query contains no parameters, meaning all entries in the feed would be returned if the query was executed immediately after construction.

Parameters:

feedUrl - the URL of the feed against which queries will be executed.

Method Detail

getVideoQuery

@Deprecated
public String getVideoQuery()

Deprecated. Please use Query.getFullTextQuery() instead.

Gets the value of the vq parameter.

Returns:

current query string

setVideoQuery

@Deprecated
public void setVideoQuery(String query)

Deprecated. Please use Query#setFullTextQuery() instead.

Sets the value of the vq parameter. The vq parameter is exactly equivalent to the q parameter.

Parameters:

query - query string, null to remove the parameter

getTime

public YouTubeQuery.Time getTime()

Gets the value of the time parameter.

Returns:

value of the time parameter

Throws:

IllegalStateException - if a time value was found in the query that cannot be transformed into YouTubeQuery.Time

setTime

public void setTime(YouTubeQuery.Time time)

Sets the value of the time parameter.

Parameters:

time - time value, null to remove the parameter

getFormats

public Set<Integer> getFormats()

Gets the value of the format parameter.

Returns:

all defined formats, might be empty but not null

Throws:

NumberFormatException - if the current value is invalid.

setFormats

public void setFormats(int... formats)

Sets the value of the format parameter. See the documentation for a description of the different formats that are be available.

Parameters:

formats - integer id of all the formats you are interested in. Videos will be returned if and only if they have downloadable content for at least one of these formats. No formats removes the parameter.

setFormats

public void setFormats(Set<Integer> formats)

Sets the value of the format parameter. See the documentation for a description of the different formats that are be available.

Parameters:

formats - integer id of all the formats you are interested in. Videos will be returned if and only if they have downloadable content for at least one of these formats. null or an empty set removes the parameter

setLanguageRestrict

public void setLanguageRestrict(String languageCode)

Sets the value of the lr parameter. This parameters restricts the videos that are returned to videos with its title, description and tags mostly in the specified language. It might be different from the language of the video itself.

Parameters:

languageCode - ISO 639-1 2-letter language code. zh-Hans for simplified chinese, zh-Hant for traditional chinese.

getLanguageRestrict

public String getLanguageRestrict()

Gets the value of the lr parameter.

Returns:

value of the lr parameter; a language code

getOrderby

public YouTubeQuery.OrderBy getOrderby()

Gets the value of the orderby parameter.

Returns:

value of the orderby parameter.

Throws:

IllegalStateException - if a time value was found in the query that cannot be transformed into YouTubeQuery.OrderBy

setOrderBy

public void setOrderBy(YouTubeQuery.OrderBy orderBy)

Sets the value of the orderby parameter.

Parameters:

orderBy - value of the orderby parameter, null to remove the parameter

setOrderByRelevanceForLanguage

public void setOrderByRelevanceForLanguage(String languageCode)

Sets order by relevance with results optimized for a specific language.

Parameters:

languageCode - null or ISO 639-1 2-letter language code. zh-Hans for simplified chinese, zh-Hant for traditional chinese.

getOrderByRelevanceForLanguage

public String getOrderByRelevanceForLanguage()

Gets the language for which relevance ordering is optimized.

Returns:

a language code as specified to setOrderByRelevanceForLanguage(java.lang.String) or null

Throws:

IllegalStateException - if ordering is not set to relevance

getSafeSearch

public YouTubeQuery.SafeSearch getSafeSearch()

Gets the value of the safeSearch parameter.

Returns:

value of the safeSearch parameter.

Throws:

IllegalStateException - if a value was found in the query that cannot be transformed into YouTubeQuery.SafeSearch

setSafeSearch

public void setSafeSearch(YouTubeQuery.SafeSearch safeSearch)

Sets the value of the safeSearch parameter.

Parameters:

safeSearch - value of safeSearch parameter, null to remove the parameter

getIncludeRacy

@Deprecated
public boolean getIncludeRacy()

Deprecated. Please use getSafeSearch() instead.

Gets the value of the racy parameter.

Returns:

true if the racy=include parameter is present

setIncludeRacy

@Deprecated
public void setIncludeRacy(Boolean includeRacy)

Deprecated. Please use #setSafeSearch(String) instead.

Sets the value of the racy parameter.

Parameters:

includeRacy - true to include racy content, false to exclude it, null to remove the parameter

setLocation

public void setLocation(GeoRssWhere where)

Sets the value of the location parameter.

Parameters:

where - A GeoRssWhere element describing the center of where to search.

getLocation

public GeoRssWhere getLocation()

Returns the value of the location parameter.

Returns:

A GeoRssWhere element describing the center of where to search.

setLocationRadius

public void setLocationRadius(String locationRadius)

Sets the value of the location-radius parameter. Format is "100km". Valid units of measurement are "ft", "mi", "m", and "km".

Parameters:

locationRadius - The requested search radius.

Throws:

InvalidArgumentException - if the given string is not a properly formatted location radius.

getLocationRadius

public String getLocationRadius()

Sets the value of the location-radius parameter. Format is "100km". Valid units of measurement are "ft", "mi", "m", and "km".

Returns:

The current search radius.

setRestrictLocation

public void setRestrictLocation(boolean isRestrictLocation)

Set/unset the location restrict.

Parameters:

isRestrictLocation - true if only videos that have latitude and longitude information are to be returned, false otherwise.

hasRestrictLocation

public boolean hasRestrictLocation()

Returns true if the query only wants results that have latitude and longitude information.

Returns:

true if the query is restricted by location, false otherwise.

getCountryRestriction

public String getCountryRestriction()

Retrieves the country restriction set on the current query, if any.

Returns:

the current country restriction as a two letter ISO 3166 country code, or null if no country restriction is set.

See Also:

getIpRestriction()

setCountryRestriction

public void setCountryRestriction(String countryCode)

Sets the restriction parameter to a country code.

This parameter restricts the returned results to content available for clients in the specified country.

Only one of the setCountryRestriction(String) or setIpRestriction(String) should be used, using both will only take into consideration the last used.

Parameters:

countryCode - a two letter ISO-3166 country code, may be null to mean no restriction at all.

Throws:

IllegalArgumentException - if the given country code is not a well formated two letter country code.

getIpRestriction

public String getIpRestriction()

Retrieves the IP restriction set on the current query, if any.

Returns:

the current IP v4 restriction or null if no IP restriction is set.

See Also:

getCountryRestriction()

setIpRestriction

public void setIpRestriction(String ip)

Sets the restriction parameter to an IP v4 address.

This parameter restricts the returned results to content available for clients in the country that the provided IP address belongs to.

Only one of the setCountryRestriction(String) or setIpRestriction(String) should be used, using both will only take into consideration the last used.

Parameters:

ip - a v4 IP address and may be null to mean no restriction at all.

Throws:

IllegalArgumentException - if the given address is not a well formated IP v4 address.

getUploader

public YouTubeQuery.Uploader getUploader()

Gets the value of the uploader parameter.

Returns:

value of the uploader parameter.

Throws:

IllegalStateException - if a value was found in the query that cannot be transformed into YouTubeQuery.Uploader

setUploader

public void setUploader(YouTubeQuery.Uploader uploader)

Sets the value of the uploader parameter.

Parameters:

uploader - value of the uploader parameter, null to remove the parameter