com.github.agadar.nationstates.query

Class APIQuery<Q extends APIQuery,R>

java.lang.Object

com.github.agadar.nationstates.query.AbstractQuery<Q,R>

com.github.agadar.nationstates.query.APIQuery<Q,R>

Type Parameters:

Q - the child class that extends this abstract class

R - the type the child class' execute()-function returns

Direct Known Subclasses:

ShardQuery, TelegramQuery, VerifyQuery, VersionQuery

public abstract class APIQuery<Q extends APIQuery,R>
extends AbstractQuery<Q,R>

Top parent class for all Queries to the NationStates API.

Author:

Agadar (https://github.com/Agadar/)

Field Summary

Fields

Modifier and Type	Field and Description
protected IRateLimiter	generalRateLimiter The general rate limiter for all API calls.
protected String	resourceValue The resource value, e.g.

Fields inherited from class com.github.agadar.nationstates.query.AbstractQuery

userAgent

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	APIQuery(IXmlConverter xmlConverter, IRateLimiter generalRateLimiter, IRateLimiter scrapingRateLimiter, String baseUrl, String userAgent, int apiVersion, String resourceValue) Constructor.

Method Summary

Modifier and Type	Method and Description
protected String	buildURL() Generates a String URL based on the supplied values.
<T> T	execute(Class<T> type) Executes this query, returning any result.
protected IRateLimiter	getRateLimiter() Returns the rate limiter to use in the makeRequest()-function.
protected abstract String	resourceString() Gives the resource string of this Query, e.g.
Q	slowMode() Makes the Query execute in slow mode, reducing the rate limit from 6 requests per 4 seconds to only 1 request per second.
protected void	validateQueryParameters() Validates the query parameters before executing the query.

Methods inherited from class com.github.agadar.nationstates.query.AbstractQuery

closeInputStreamQuietly, execute, makeRequest, translateResponse

Methods inherited from class java.lang.Object

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

Field Detail

generalRateLimiter

protected final IRateLimiter generalRateLimiter

The general rate limiter for all API calls.

resourceValue

protected final String resourceValue

The resource value, e.g. the nation's or region's name. Set by the constructor.

Constructor Detail

APIQuery

protected APIQuery(IXmlConverter xmlConverter,
                   IRateLimiter generalRateLimiter,
                   IRateLimiter scrapingRateLimiter,
                   String baseUrl,
                   String userAgent,
                   int apiVersion,
                   String resourceValue)

Constructor. Sets the resource value, e.g. the nation's or region's name.

Parameters:

xmlConverter - The converter for translating XML from the API to objects.

resourceValue - The resource value (e.g. 'nation', 'region'...)

generalRateLimiter - The default rate limiter

baseUrl - The URL to the API to consume

userAgent - The User Agent to communicate with

apiVersion - The version of the API to expect to consume

scrapingRateLimiter - Rate limiter used when 'scraping'

Method Detail

slowMode

public Q slowMode()

Makes the Query execute in slow mode, reducing the rate limit from 6 requests per 4 seconds to only 1 request per second. This is suggested by the official documentations when scraping i.e. when requesting a LOT of data that cannot be retrieved from the daily dumps.

Returns:

this

getRateLimiter

protected IRateLimiter getRateLimiter()

Returns the rate limiter to use in the makeRequest()-function. Child classes can override this to supply their own rate limiter if needed.

Returns:

the rate limiter to use in the makeRequest()-function

execute

public <T> T execute(Class<T> type)

Description copied from class: AbstractQuery

Executes this query, returning any result. Child classes may want to override this if they want to use rate limiters and such.

Overrides:

execute in class AbstractQuery<Q extends APIQuery,R>

Type Parameters:

T - the type to return

Parameters:

type - the type to return

Returns:

the result, of the given type

validateQueryParameters

protected void validateQueryParameters()

Description copied from class: AbstractQuery

Validates the query parameters before executing the query. If the query parameters are invalid, an exception is thrown. Child classes will want to override this class (making sure to still call super.validateQueryParameters()) if they have additional parameters to validate.

Overrides:

validateQueryParameters in class AbstractQuery<Q extends APIQuery,R>

buildURL

protected String buildURL()

Description copied from class: AbstractQuery

Generates a String URL based on the supplied values. Subclasses might want to override this method to build the String URL further to accommodate for additional shards/modes/options/etc.

Overrides:

buildURL in class AbstractQuery<Q extends APIQuery,R>

Returns:

the generated String URL

resourceString

protected abstract String resourceString()

Gives the resource string of this Query, e.g. 'nation', 'region', etc.

Returns:

the resource string of this Query