RandomOrgAPIExample

What is this repo or project?

Example program for using the random.org java api by iarks to generate random integers within a given range. Note that the library code is still under development and as such this example may be subject to change. To check out the library source code, click here

What do I do with this?

This library makes it easy to integrate random.org's 'true randomness' into java projects by getting rid of underlaying http requests and making things as simple as making a method call. Use this library to generate random integer numbers using random.org's true random numbers generators.

How do I use this?

Pre-requisites to setup this library

1. To get started all you need is an API key. To get your API key click here.
   The key should be sent to your email address and is of the format 00000000-0000-0000-0000-000000000000
   
2. Next you need the jar file itself. Click here to obtain that.

You can now proceed to use the library in your projects

1. Add the downloaded jar file to your project. This process may differ depending on the IDE being used.
   For example, this is the way to do it in Intellij. To know how to do it for your IDE ask Google.
   
   
2. Once the library is set up for use import the required classes by typing in the following codes into your project:

import com.github.iarks.RandomOrgAPI.InvalidMethodCallException;
import com.github.iarks.RandomOrgAPI.InvalidResponseException;
import com.github.iarks.RandomOrgAPI.RandomNumber;

(Check out the example for more details)

Documentation and usage:

(Check out the example project for a better understanding of this section)

• Initialise a RandomNumber object and pass in your API key as follows. In place of "YOUR API KEY HERE" type in the API key obtained earlier.

RandomNumber rn = new RandomNumber("YOUR API KEY HERE");

• void generate(int n, int max, int min, boolean replacement, String id)
  The generate() method calls the underlaying API on the RandomNumber object and generates n random numbers.
  Example code snippet to call the generate() method on the rn object created in step 1

rn.generate(5, 10, 2, false, "method");

Paramethers	Datatype	Meaning
n	integer	How many random integers you need. Must be within the [1,1e4] range.
min	integer	The lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range.
max	integer	The upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range.
replacement	Boolean	Specifies whether the random numbers should be picked with replacement. Passing true will cause the numbers to be picked with replacement, i.e., the resulting set of numbers may contain duplicate values (like a series of dice rolls). If you want the set of numbers picked to be unique (like raffle tickets drawn from a container), set this value to false.
id	String	An identifier, which will be returned in the response. Can be anything. Does not influence output.

• int[] getElementAsArray()
  Returns an integer array containing the generated random numbers. Always call this method after calling generate() method, otherwise it will throw an InvalidMethodCallException, because the numbers have not been generated as yet.
  Use the following code snippet to obtain the array of generated numbers.

int arrayOfRandoms[] = rn.getElementAsArray();

• int getElementAt(int index)
  Accepts an integer index and returns the generated random number at that index. Use this method to individually adress the generated numbers. Always call this method after calling generate(), otherwise it will throw an InvalidMethodCallException, because the numbers have not been generated as yet. Example code snippet:

int firstRandomNumber = rn.getElementAt(0);

• int getBitsLeft()
  By default random.org only allows upto 250,000 bits per API key daily. This function returns an integer containing the (estimated) number of remaining true random bits available to the client. Example code snippet,

int bitsLeft = rn.getBitsLeft();

• int getBitsUsed()
  By default random.org only allows upto 250,000 bits per API key daily. This function returns an integer containing the number of true random bits used to complete the current request. Example code snippet

int bitsUsed = rn.getBitsUsed();

• int getRequestsLeft()
  By default random.org only allows upto 1000 API calls per key daily. This function returns an integer containing the (estimated) number of remaining API requests available to the client after the current request. Example code snippet,

int requestsLeft = rn.getRequestsLeft();