com.github.agadar.nsapi

Class NSAPI

java.lang.Object

com.github.agadar.nsapi.NSAPI

public final class NSAPI
extends Object

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

Author:

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

Field Summary

Fields

Modifier and Type	Field and Description
static int	API_VERSION The NationStates API version this wrapper uses.

Constructor Summary

Constructors

Constructor and Description
NSAPI()

Method Summary

Modifier and Type	Method and Description
static String	getUserAgent() Getter for the User Agent.
static NationQuery	nation(String nationName) Starts building a nation query, using the given nation name.
static NationDumpQuery	nationdump(DailyDumpMode mode) Starts building a query that retrieves the daily nation dump.
static ByteArrayOutputStream	objectToXml(Object obj) Deprecated.
static RegionQuery	region(String regionName) Starts building a region query, using the given region name.
static RegionDumpQuery	regiondump(DailyDumpMode mode) Starts building a query that retrieves the daily region dump.
static void	registerJaxbTypes(Class... types) Deprecated.
static void	setUserAgent(String userAgent) Sets the User Agent.
static TelegramQuery	telegram(String clientKey, String telegramId, String secretKey, String... nations) Starts building a query that sends (a) telegram(s).
static VerifyQuery	verify(String nation, String checksum) Starts building a query that verifies a nation.
static VersionQuery	version() Starts building a query that retrieves the version number of the latest live NationStates API.
static WAQuery	wa(Council council) Starts building a World Assembly query, using the selected council type.
static WorldQuery	world(WorldShard... shards) Starts building a world query, using the selected shards.
static <T> T	xmlToObject(InputStream xml, Class<T> toType) Deprecated.

Methods inherited from class java.lang.Object

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

Field Detail

API_VERSION

public static final int API_VERSION

The NationStates API version this wrapper uses.

See Also:

Constant Field Values

Constructor Detail

NSAPI

public NSAPI()

Method Detail

registerJaxbTypes

@Deprecated
public static final void registerJaxbTypes(Class... types)

Deprecated.

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. Deprecated. Use XmlConverter.registerTypes(...) instead.

Parameters:

types - the classes to add to the JAXB context

xmlToObject

@Deprecated
public static final <T> T xmlToObject(InputStream xml,
                                                   Class<T> toType)

Deprecated.

Uses JAXB to parse the supplied XML stream to an instance of the specified type. Deprecated. Use XmlConverter.xmlToObject(...) instead.

Type Parameters:

T - the type to parse to

Parameters:

xml - the XML stream

toType - the type to parse to

Returns:

instance of the specified type

objectToXml

@Deprecated
public static final ByteArrayOutputStream objectToXml(Object obj)

Deprecated.

Uses JAXB to parse an object to an output stream. Deprecated. Use XmlConverter.objectToXml instead.

Parameters:

obj - object to parse to output stream

Returns:

an output stream

setUserAgent

public static void setUserAgent(String userAgent)

Sets the User Agent. If this is the first time the User Agent is set, then a version check is automatically done as well. 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

getUserAgent

public static String getUserAgent()

Getter for the User Agent.

Returns:

the User Agent

nation

public static NationQuery nation(String nationName)

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

Parameters:

nationName - name of the nation to query

Returns:

a new nation query

region

public static RegionQuery region(String regionName)

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

Parameters:

regionName - name of the region to query

Returns:

a new region query

world

public static WorldQuery world(WorldShard... shards)

Starts building a world query, using the selected shards.

Parameters:

shards - the selected shards

Returns:

a new world query

wa

public static WAQuery wa(Council council)

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

Parameters:

council - the council type to query

Returns:

a new World Assembly query

version

public static VersionQuery version()

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

Returns:

a new version query

verify

public static VerifyQuery verify(String nation,
                                 String checksum)

Starts building a query that verifies a nation.

Parameters:

nation - the nation to verify

checksum - the verification checksum

Returns:

a new verify query

telegram

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

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

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

regiondump

public static RegionDumpQuery regiondump(DailyDumpMode mode)

Starts building a query that retrieves the daily region dump.

Parameters:

mode - the daily dump mode to use

Returns:

a new daily region dump query

nationdump

public static NationDumpQuery nationdump(DailyDumpMode mode)

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.

Parameters:

mode - the daily dump mode to use

Returns:

a new daily nation dump query