com.github.agadar.nsapi.query.blueprint

Class APIQuery<Q extends APIQuery,R>

java.lang.Object

com.github.agadar.nsapi.query.blueprint.AbstractQuery<Q,R>

com.github.agadar.nsapi.query.blueprint.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 static RateLimiter	rateLimiter The general rate limiter for all API calls.
protected String	resourceValue The resource value, e.g.

Fields inherited from class com.github.agadar.nsapi.query.blueprint.AbstractQuery

logger

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	APIQuery(String resourceValue) Constructor.

Method Summary

Modifier and Type	Method and Description
protected String	buildURL() Generates a String URL based on the supplied values.
<T extends R> T	execute(Class<T> type) Executes this query, returning any result.
protected RateLimiter	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.nsapi.query.blueprint.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

rateLimiter

protected static final RateLimiter rateLimiter

The general rate limiter for all API calls. The mandated rate limit is 50 requests per 30 seconds. To make sure we're on the safe side, we reduce this to 45 requests per 30 seconds. To get a spread-like pattern instead of a burst-like pattern, we make this into 6 requests per 4 seconds.

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(String resourceValue)

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

Parameters:

resourceValue - the resource value

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 RateLimiter 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 extends R> 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