com.github.agadar.nationstates

Class NationStates

java.lang.Object

com.github.agadar.nationstates.NationStates

All Implemented Interfaces:

INationStates

public final class NationStates
extends Object
implements INationStates

The starting point for consumers of this Java wrapper for the NationStates API.

Author:

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

Constructor Summary

Constructors

Constructor and Description
NationStates(String userAgent) Instantiates a new service and sets the User Agent.

Method Summary

Modifier and Type	Method and Description
void	doVersionCheck() Performs a simple version check, logging the results in the console.
NationQuery	getNation(String nationName) Starts building a nation query, using the given nation name.
NationDumpQuery	getNationDump(DailyDumpMode mode) Starts building a query that retrieves the daily nation dump.
RegionQuery	getRegion(String regionName) Starts building a region query, using the given region name.
RegionDumpQuery	getRegionDump(DailyDumpMode mode) Starts building a query that retrieves the daily region dump.
VersionQuery	getVersion() Starts building a query that retrieves the version number of the latest live NationStates API.
WorldQuery	getWorld(WorldShard... shards) Starts building a world query, using the selected shards.
WorldAssemblyQuery	getWorldAssembly(Council council) Starts building a World Assembly query, using the selected council type.
void	registerTypes(Class... types) Adds the given classes to the JAXB context so that they can be parsed to from retrieved XML responses and files.
TelegramQuery	sendTelegrams(String clientKey, String telegramId, String secretKey, String... nations) Starts building a query that sends (a) telegram(s).
void	setUserAgent(String userAgent) Sets the User Agent.
VerifyQuery	verifyNation(String nation, String checksum) Starts building a query that verifies a nation.

Methods inherited from class java.lang.Object

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

Constructor Detail

NationStates

public NationStates(String userAgent)

Instantiates a new service and sets the User Agent. NationStates moderators should be able to identify you and your script via your User Agent. As such, try providing at least your nation name, and preferably include your e-mail address, a link to a website you own, or something else that can help them contact you if needed.

Parameters:

userAgent - the User Agent to use for API calls

Method Detail

setUserAgent

public void setUserAgent(String userAgent)

Description copied from interface: INationStates

Sets the User Agent. NationStates moderators should be able to identify you and your script via your User Agent. As such, try providing at least your nation name, and preferably include your e-mail address, a link to a website you own, or something else that can help them contact you if needed.

Specified by:

setUserAgent in interface INationStates

Parameters:

userAgent - the User Agent to use for API calls

doVersionCheck

public void doVersionCheck()

Description copied from interface: INationStates

Performs a simple version check, logging the results in the console.

Specified by:

doVersionCheck in interface INationStates

registerTypes

public final void registerTypes(Class... types)

Description copied from interface: INationStates

Adds the given classes to the JAXB context so that they can be parsed to from retrieved XML responses and files. Classes that inherit any of the classes in the domain-package don't need any xml-annotations. Classes that do no inherit those classes, do need xml-annotations.

Specified by:

registerTypes in interface INationStates

Parameters:

types - the classes to add to the JAXB context

getNation

public NationQuery getNation(String nationName)

Description copied from interface: INationStates

Starts building a nation query, using the given nation name.

Specified by:

getNation in interface INationStates

Parameters:

nationName - name of the nation to query

Returns:

a new nation query

getRegion

public RegionQuery getRegion(String regionName)

Description copied from interface: INationStates

Starts building a region query, using the given region name.

Specified by:

getRegion in interface INationStates

Parameters:

regionName - name of the region to query

Returns:

a new region query

getWorld

public WorldQuery getWorld(WorldShard... shards)

Description copied from interface: INationStates

Starts building a world query, using the selected shards.

Specified by:

getWorld in interface INationStates

Parameters:

shards - the selected shards

Returns:

a new world query

getWorldAssembly

public WorldAssemblyQuery getWorldAssembly(Council council)

Description copied from interface: INationStates

Starts building a World Assembly query, using the selected council type.

Specified by:

getWorldAssembly in interface INationStates

Parameters:

council - the council type to query

Returns:

a new World Assembly query

getVersion

public VersionQuery getVersion()

Description copied from interface: INationStates

Starts building a query that retrieves the version number of the latest live NationStates API.

Specified by:

getVersion in interface INationStates

Returns:

a new version query

verifyNation

public VerifyQuery verifyNation(String nation,
                                String checksum)

Description copied from interface: INationStates

Starts building a query that verifies a nation.

Specified by:

verifyNation in interface INationStates

Parameters:

nation - the nation to verify

checksum - the verification checksum

Returns:

a new verify query

sendTelegrams

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

Description copied from interface: INationStates

Starts building a query that sends (a) telegram(s).

Specified by:

sendTelegrams in interface INationStates

Parameters:

clientKey - the client key

telegramId - the telegram id

secretKey - the telegram's secret key

nations - the nation(s) to send the telegram to

Returns:

a new telegram query

getRegionDump

public RegionDumpQuery getRegionDump(DailyDumpMode mode)

Description copied from interface: INationStates

Starts building a query that retrieves the daily region dump.

Specified by:

getRegionDump in interface INationStates

Parameters:

mode - the daily dump mode to use

Returns:

a new daily region dump query

getNationDump

public NationDumpQuery getNationDump(DailyDumpMode mode)

Description copied from interface: INationStates

Starts building a query that retrieves the daily nation dump. Warning: reading the XML file and parsing it to objects may cause a java.lang.OutOfMemoryError on older machines due to the sheer number of Nation objects being created from parsing the retrieved XML file.

Specified by:

getNationDump in interface INationStates

Parameters:

mode - the daily dump mode to use

Returns:

a new daily nation dump query