com.github.agadar.nsapi.query

Class TelegramQuery

java.lang.Object

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

com.github.agadar.nsapi.query.blueprint.APIQuery<TelegramQuery,Void>

com.github.agadar.nsapi.query.TelegramQuery

public final class TelegramQuery
extends APIQuery<TelegramQuery,Void>

A query to the NationStates API's utility resource, sending a telegram.

Author:

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

Field Summary

Fields

Modifier and Type	Field and Description
protected static DependantRateLimiter	RecruitTGrateLimiter The rate limiter for recruitment telegrams.
protected static DependantRateLimiter	TGrateLimiter The rate limiter for normal telegrams.

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

rateLimiter, resourceValue

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

logger

Constructor Summary

Constructors

Constructor and Description
TelegramQuery(String clientKey, String telegramId, String secretKey, String nation) Constructor.

Method Summary

Modifier and Type	Method and Description
protected String	buildURL() Generates a String URL based on the supplied values.
protected RateLimiter	getRateLimiter() Returns the rate limiter to use in the makeRequest()-function.
TelegramQuery	isRecruitment() Ensures the telegram will be send as if it is a recruitment telegram.
protected String	resourceString() Gives the resource string of this Query, e.g.
protected <T extends Void> T	translateResponse(InputStream response, Class<T> type) Translates the stream response to the object this Query wishes to return via its execute() function.
protected void	validateQueryParameters() Validates the query parameters before executing the query.

Methods inherited from class com.github.agadar.nsapi.query.blueprint.APIQuery

execute

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

closeInputStreamQuietly, execute, makeRequest

Methods inherited from class java.lang.Object

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

Field Detail

TGrateLimiter

protected static final DependantRateLimiter TGrateLimiter

The rate limiter for normal telegrams. The mandated rate limit is 1 telegram per 30 seconds. To make sure we're on the safe side, we reduce this to 1 telegram per 35 seconds.

RecruitTGrateLimiter

protected static final DependantRateLimiter RecruitTGrateLimiter

The rate limiter for recruitment telegrams. The mandated rate limit is 1 telegram per 180 seconds. To make sure we're on the safe side, we reduce this to 1 telegram per 185 seconds.

Constructor Detail

TelegramQuery

public TelegramQuery(String clientKey,
                     String telegramId,
                     String secretKey,
                     String nation)

Constructor.

Parameters:

clientKey - the client key

telegramId - the telegram id

secretKey - the telegram's secret key

nation - the nation to send the telegram to

Method Detail

isRecruitment

public TelegramQuery isRecruitment()

Ensures the telegram will be send as if it is a recruitment telegram. If you're sending a recruitment telegram, then this should be set, or the mandated rate limit might be violated and your telegrams won't be send.

Returns:

this

resourceString

protected String resourceString()

Description copied from class: APIQuery

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

Specified by:

resourceString in class APIQuery<TelegramQuery,Void>

Returns:

the resource string of this Query

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<TelegramQuery,Void>

translateResponse

protected <T extends Void> T translateResponse(InputStream response,
                                               Class<T> type)

Description copied from class: AbstractQuery

Translates the stream response to the object this Query wishes to return via its execute() function. The standard way to translate is via JAXB, which assumes the stream is in a valid XML-format. Child classes might want to override this function if they wish to return primitives or something else.

Overrides:

translateResponse in class AbstractQuery<TelegramQuery,Void>

Type Parameters:

T - type to parse to

Parameters:

response - the response to translate

type - type to parse to

Returns:

the translated response

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 APIQuery<TelegramQuery,Void>

Returns:

the generated String URL

getRateLimiter

protected RateLimiter getRateLimiter()

Description copied from class: APIQuery

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

Overrides:

getRateLimiter in class APIQuery<TelegramQuery,Void>

Returns:

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