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(s).

Author:

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

Field Summary

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... nations) Constructor.

Method Summary

Modifier and Type	Method and Description
TelegramQuery	addListeners(TelegramSentListener... newListeners) Registers new telegram event listeners.
protected String	buildURL() Generates a String URL based on the supplied values.
long	estimatedDuration() The estimated time it will take to send all of this query's telegrams, in milliseconds.
<T extends Void> T	execute(Class<T> type) Executes this query, returning any result.
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

slowMode

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

Constructor Detail

TelegramQuery

public TelegramQuery(String clientKey,
                     String telegramId,
                     String secretKey,
                     String... nations)

Constructor.

Parameters:

clientKey - the client key

telegramId - the telegram id

secretKey - the telegram's secret key

nations - the nation(s) 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

addListeners

public TelegramQuery addListeners(TelegramSentListener... newListeners)

Registers new telegram event listeners.

Parameters:

newListeners - the listeners to register

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 APIQuery<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

estimatedDuration

public long estimatedDuration()

The estimated time it will take to send all of this query's telegrams, in milliseconds. Assumes no interference from other TelegramQueries being executed simultaneously.

Returns:

the estimated time in milliseconds

execute

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

Type Parameters:

T - the type to return

Parameters:

type - the type to return

Returns:

the result, of the given type

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