Google Data APIs Client Library (1.41.1)



com.google.gdata.client.youtube
Class YouTubeQuery

java.lang.Object
  extended by com.google.gdata.client.Query
      extended by 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
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
YouTubeQuery(java.net.URL feedUrl)
          Constructs a new YouTubeQuery object that targets a feed.
 
Method Summary
 java.lang.String getCountryRestriction()
          Retrieves the country restriction set on the current query, if any.
 java.util.Set<java.lang.Integer> getFormats()
          Gets the value of the format parameter.
 boolean getIncludeRacy()
          Deprecated. Please use getSafeSearch() instead.
 java.lang.String getIpRestriction()
          Retrieves the IP restriction set on the current query, if any.
 java.lang.String getLanguageRestrict()
          Gets the value of the lr parameter.
 GeoRssWhere getLocation()
          Returns the value of the location parameter.
 java.lang.String getLocationRadius()
          Sets the value of the location-radius parameter.
 YouTubeQuery.OrderBy getOrderby()
          Gets the value of the orderby parameter.
 java.lang.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.
 java.lang.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(java.lang.String countryCode)
          Sets the restriction parameter to a country code.
 void setFormats(int... formats)
          Sets the value of the format parameter.
 void setFormats(java.util.Set<java.lang.Integer> formats)
          Sets the value of the format parameter.
 void setIncludeRacy(java.lang.Boolean includeRacy)
          Deprecated. Please use #setSafeSearch(String) instead.
 void setIpRestriction(java.lang.String ip)
          Sets the restriction parameter to an IP v4 address.
 void setLanguageRestrict(java.lang.String languageCode)
          Sets the value of the lr parameter.
 void setLocation(GeoRssWhere where)
          Sets the value of the location parameter.
 void setLocationRadius(java.lang.String locationRadius)
          Sets the value of the location-radius parameter.
 void setOrderBy(YouTubeQuery.OrderBy orderBy)
          Sets the value of the orderby parameter.
 void setOrderByRelevanceForLanguage(java.lang.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(java.lang.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(java.net.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 java.lang.String getVideoQuery()
Deprecated. Please use Query.getFullTextQuery() instead.

Gets the value of the vq parameter.

Returns:
current query string

setVideoQuery

@Deprecated
public void setVideoQuery(java.lang.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:
java.lang.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 java.util.Set<java.lang.Integer> getFormats()
Gets the value of the format parameter.

Returns:
all defined formats, might be empty but not null
Throws:
java.lang.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(java.util.Set<java.lang.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(java.lang.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 java.lang.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:
java.lang.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(java.lang.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 java.lang.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:
java.lang.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:
java.lang.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(java.lang.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(java.lang.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 java.lang.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 java.lang.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(java.lang.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:
java.lang.IllegalArgumentException - if the given country code is not a well formated two letter country code.

getIpRestriction

public java.lang.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(java.lang.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:
java.lang.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:
java.lang.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