com.github.agadar.nationstates.query

Class AbstractQuery<Q extends AbstractQuery,R>

java.lang.Object

com.github.agadar.nationstates.query.AbstractQuery<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:

APIQuery, DailyDumpQuery

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

Top parent class for all Queries to NationStates in general.

Author:

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

Field Summary

Fields

Modifier and Type	Field and Description
protected String	userAgent User agent by which this library or its consumer is recognized.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractQuery(IXmlConverter xmlConverter, String baseUrl, String userAgent) Constructor, setting the returnType.

Method Summary

Modifier and Type	Method and Description
protected String	buildURL() Generates a String URL based on the supplied values.
protected static void	closeInputStreamQuietly(InputStream stream) Closes the given InputStream.
R	execute() Executes this query, returning any result.
<T> T	execute(Class<T> type) Executes this query, returning any result.
protected <T> T	makeRequest(String urlStr, Class<T> type) Makes a GET request to the NationStates API.
protected <T> 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 java.lang.Object

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

Field Detail

userAgent

protected final String userAgent

User agent by which this library or its consumer is recognized.

Constructor Detail

AbstractQuery

protected AbstractQuery(IXmlConverter xmlConverter,
                        String baseUrl,
                        String userAgent)

Constructor, setting the returnType.

Parameters:

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

baseUrl - Base URL to NationStates.

userAgent - User agent by which this library or its consumer is recognized.

Method Detail

validateQueryParameters

protected void validateQueryParameters()

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.

buildURL

protected String buildURL()

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.

Returns:

the generated String URL

execute

public final R execute()

Executes this query, returning any result.

Returns:

the result

execute

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

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

Type Parameters:

T - the type to return

Parameters:

type - the type to return

Returns:

the result, of the given type

makeRequest

protected final <T> T makeRequest(String urlStr,
                                  Class<T> type)

Makes a GET request to the NationStates API. Throws exceptions if the call failed. If the requested nation/region/etc. simply wasn't found, it returns null.

Type Parameters:

T - type to parse to

Parameters:

urlStr - the url to make the request to

type - type to parse to

Returns:

the retrieved data, or null if the resource wasn't found

translateResponse

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

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.

Type Parameters:

T - type to parse to

Parameters:

response - the response to translate

type - type to parse to

Returns:

the translated response

closeInputStreamQuietly

protected static final void closeInputStreamQuietly(InputStream stream)

Closes the given InputStream. If an exception occurs, the exception is not thrown or returned. Use this if you don't particularly care about catching exceptions thrown by closing InputStreams.

Parameters:

stream - the InputStream to close