NATION

PASSWORD

[API] Java Wrapper for the NS API (updated Dec 22nd, '18)

Bug reports, general help, ideas for improvements, and questions about how things are meant to work.
User avatar
Agadar
Powerbroker
 
Posts: 7756
Founded: Dec 06, 2009
Psychotic Dictatorship

[API] Java Wrapper for the NS API (updated Dec 22nd, '18)

Postby Agadar » Mon Jul 11, 2016 4:26 pm

[ Agadar's Java Wrapper for the NationStates API ]

This Java library provides programmers with an easy way to communicate with the NationStates API. It supports the following basic functionalities:

  • Retrieving information about Nations, Regions, the World Assembly, and the World;
  • Downloading and reading daily data dumps;
  • Sending telegrams;
  • Verifying users.
On top of the basic functionalities, this wrapper also ensures the mandated rate limits are not violated, and gives warnings when the wrapper itself is outdated, so that you don't have to worry about any of those things.

[ Basics ]

Instantiating a NationStates object and setting a User Agent is the first thing you'll have to do, ensuring NationStates admins can identify your script:

Code: Select all
NationStates nationStates = new DefaultNationStatesImpl("Example Nation's Script (example@example.com)");

That's all you need to do to be able to use the wrapper! Now we can, say, retrieve the national animal name of a nation:

Code: Select all
Nation nation = nationStates.getNation("agadar").shards(NationShard.ANIMAL).execute();

This gives us a Nation object holding the animal name. That's all there is to it! All queries are build and executed in a similar fashion.

[ Custom return types ]

The 'Nation' class and other such domain classes have little to no methods: they exist solely to hold the information you request from the NationStates API. If you want to add methods, then you can inherit the domain classes or create entirely seperate ones and tell the wrapper to use your custom domain classes instead.

For example, imagine we create a class 'CustomNation' that inherits 'Nation' but which holds some handy methods not natively present in the 'Nation' class. We then first register our custom class so that it is recognized:

Code: Select all
nationStates.registerTypes(CustomNation.class);

Now whenever we want a Nation-query to return our custom type, we can use the overloaded execute()-function, like so:

Code: Select all
CustomNation nation = nationStates.getNation("agadar").shards(NationShard.ANIMAL).execute(CustomNation.class);

And voilà: we now have an instance of our custom class, holding the retrieved animal name.

[ Links ]

Releases
Source code
NationStates API documentation
More applications
Last edited by Agadar on Sat Dec 22, 2018 9:09 am, edited 11 times in total.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7756
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Wed Jul 13, 2016 7:22 pm

Just released version 1.1.0. Might be a few hours until it shows up over at mvnrepository.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7756
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Mon Sep 05, 2016 12:40 pm

Version 1.2.0 now available. See the 'Releases' link in the OP.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7756
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Sat Feb 04, 2017 10:03 am

Released version 2.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7756
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Mon Dec 25, 2017 6:34 pm

Released version 3.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7756
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Sun Mar 04, 2018 8:56 am

Released version 4.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7756
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Sat Dec 22, 2018 9:11 am

Released version 5.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!


Advertisement

Remove ads

Return to Technical

Who is online

Users browsing this forum: No registered users

Advertisement

Remove ads