From 19718ac60393de321310d74fb7386024fb078612 Mon Sep 17 00:00:00 2001 From: = <=> Date: Thu, 14 Jan 2021 15:45:49 +0000 Subject: [PATCH 1/5] Release 2 Update This library now supports Release 2 of the RANDOM.ORG JSON-RPC API. Updates: - New methods (generateIntegerSequences, generateSignedIntegerSequences, createIntegerSequenceCache and getResult) - New optional parameter JsonObject 'userData' can now be used with signed methods returning random values - Parameter 'base' can now be used on integer and integer sequences methods (Basic and Signed API). NOTE: basic methods 'generateIntegers' and 'generateIntegerSequences' return String values when the 'base' parameter is used, even when it is decimal (base = 10). For int values, simply use the method without 'base' parameter. The same applies to 'createIntegerCache' abd 'createIntegerSequenceCache'. Signed methods 'generateSignedIntegers' and 'generateSignedIntegerSequences' return int values for decimal base, String values otherwise. - Updated test cases to cover new methods and use JUnit ErrorCollector - getUsage() is called in the RandomOrgClient constructor to update remaining requests and bits - Minor bug fix to improve threading for serialized clients - Added error codes (RandomOrg Errors: 305, 306 and 307) --- README.rst | 8 +- .../src/org/random/api/RandomOrgCache.java | 167 +- .../src/org/random/api/RandomOrgClient.java | 4201 ++++++++++++----- .../RandomOrgBadHTTPResponseException.java | 16 +- .../RandomOrgInsufficientBitsError.java | 29 +- .../RandomOrgInsufficientRequestsError.java | 22 +- .../api/exception/RandomOrgJSONRPCError.java | 20 +- .../RandomOrgKeyNotRunningError.java | 18 +- .../exception/RandomOrgRANDOMORGError.java | 20 +- .../RandomOrgSendTimeoutException.java | 16 +- .../random/test/RandomOrgClientBasicTest.java | 1498 +++--- .../random/test/RandomOrgRandomBasicTest.java | 6 +- .../src/org/random/util/RandomOrgRandom.java | 445 +- 13 files changed, 4410 insertions(+), 2056 deletions(-) diff --git a/README.rst b/README.rst index facb047..e866ed1 100644 --- a/README.rst +++ b/README.rst @@ -1,14 +1,14 @@ JSON-RPC-Java =============== -RANDOM.ORG JSON-RPC API (Release 1) implementation. +RANDOM.ORG JSON-RPC API (Release 2) implementation. -This is a Java implementation of the RANDOM.ORG JSON-RPC API (R1). It provides either serialized or unserialized access to both the signed and unsigned methods of the API through the RandomOrgClient class. It also provides a convenience class through the RandomOrgClient class, the RandomOrgCache, for precaching requests. In the context of this module, a serialized client is one for which the sequence of requests matches the sequence of responses. +This is a Java implementation of the RANDOM.ORG JSON-RPC API (R2). It provides either serialized or unserialized access to both the signed and unsigned methods of the API through the RandomOrgClient class. It also provides a convenience class through the RandomOrgClient class, the RandomOrgCache, for precaching requests. In the context of this module, a serialized client is one for which the sequence of requests matches the sequence of responses. Installation ------------ -Requires the `gson `_ lib and `Commons Codec `_ lib for normal operation, and the `junit `_ lib to run tests. +Requires the `gson `_ lib and `Commons Codec `_ lib for normal operation, and the `junit `_ lib and `hamcrest `_ lib to run tests. Usage ----- @@ -86,7 +86,7 @@ This library now also includes a RANDOM.ORG implementation of the `java.util.Ran Documentation ------------- -For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/1/ +For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/2 Tests ----- diff --git a/RandomJSONRPC/src/org/random/api/RandomOrgCache.java b/RandomJSONRPC/src/org/random/api/RandomOrgCache.java index 9fd3b4e..d2458de 100644 --- a/RandomJSONRPC/src/org/random/api/RandomOrgCache.java +++ b/RandomJSONRPC/src/org/random/api/RandomOrgCache.java @@ -10,19 +10,20 @@ import com.google.gson.JsonObject; -/** Precache class for frequently used requests. - ** - ** ** WARNING ** - ** Instances of this class should only be obtained using a RandomOrgClient's - ** createCache() methods. - ** - ** This class strives to keep a Queue of response results populated for instant - ** access via its public get() method. Work is done by a background Thread, which - ** issues the appropriate request at suitable intervals. - ** - ** @param return array type, e.g., int[] - ** - **/ +/** + * Precache class for frequently used requests. + * + * ** WARNING ** + * Instances of this class should only be obtained using a RandomOrgClient's + * createCache() methods. + * + * This class strives to keep a Queue of response results populated for instant + * access via its public get() method. Work is done by a background Thread, which + * issues the appropriate request at suitable intervals. + * + * @param return array type, e.g., int[] + * + */ public class RandomOrgCache { private JsonObjectInputCallable requestFunction; @@ -48,19 +49,20 @@ public class RandomOrgCache { private static final Logger LOGGER = Logger.getLogger(RandomOrgClient.class.getPackage().getName()); - /** Initialize class and start Queue population Thread running as a daemon. - ** - ** ** WARNING ** - ** Should only be called by RandomOrgClient's createCache() methods. - ** - ** @param requestFunction function used to send supplied request to server. - ** @param processFunction function to process result of requestFunction into expected output. - ** @param request request to send to server via requestFunction. - ** @param cacheSize number of request responses to try maintain. - ** @param bulkRequestNumber if request is set to be issued in bulk, number of result sets in a bulk request, else 0. - ** @param requestNumber if request is set to be issued in bulk, number of results in a single request, else 0. - ** @param singleRequestSize in bits for adjusting bulk requests if bits are in short supply on the server. - **/ + /** + * Initialize class and start Queue population Thread running as a daemon. + * + * ** WARNING ** + * Should only be called by RandomOrgClient's createCache() methods. + * + * @param requestFunction function used to send supplied request to server. + * @param processFunction function to process result of requestFunction into expected output. + * @param request request to send to server via requestFunction. + * @param cacheSize number of request responses to try maintain. + * @param bulkRequestNumber if request is set to be issued in bulk, number of result sets in a bulk request, else 0. + * @param requestNumber if request is set to be issued in bulk, number of results in a single request, else 0. + * @param singleRequestSize in bits for adjusting bulk requests if bits are in short supply on the server. + */ protected RandomOrgCache(JsonObjectInputCallable requestFunction, JsonObjectInputCallable processFunction, JsonObject request, int cacheSize, int bulkRequestNumber, int requestNumber, int singleRequestSize) { @@ -86,14 +88,15 @@ public void run() { t.start(); } - /** Keep issuing requests to server until Queue is full. When Queue is full if requests - ** are being issued in bulk, wait until Queue has enough space to accommodate all of a - ** bulk request before issuing a new request, otherwise issue a new request every time - ** an item in the Queue has been consumed. - ** - ** Note that requests to the server are blocking, i.e., only one request will be issued by - ** the cache at any given time. - **/ + /** + * Keep issuing requests to server until Queue is full. When Queue is full if requests + * are being issued in bulk, wait until Queue has enough space to accommodate all of a + * bulk request before issuing a new request, otherwise issue a new request every time + * an item in the Queue has been consumed. + * + * Note that requests to the server are blocking, i.e., only one request will be issued by + * the cache at any given time. + */ @SuppressWarnings("unchecked") protected void populateQueue() { while (true) { @@ -219,27 +222,29 @@ public void resume() { } } - /** Return true if cache is currently not re-populating itself. - **

- ** Values currently cached may still be retrieved with get(), - ** but no new values are being fetched from the server. - **

- ** This state can be changed with stop() and resume(). - ** - ** @see #stop() - ** @see #resume() - ** - ** @return true if cache is currently not re-populating itself. - **/ + /** + * Return {@code true} if cache is currently not re-populating itself. + *

+ * Values currently cached may still be retrieved with {@code get()}, + * but no new values are being fetched from the server. + *

+ * This state can be changed with {@code stop()} and {@code resume()}. + * + * @see #stop() + * @see #resume() + * + * @return {@code true} if cache is currently not re-populating itself. + */ public boolean isPaused() { return this.paused; } - /** Get next response. - ** - ** @return next appropriate response for the request this RandomOrgCache represents - ** or if Queue is empty throws a NoSuchElementException. - **/ + /** + * Get next response. + * + * @return next appropriate response for the request this RandomOrgCache represents + * or if Queue is empty throws a NoSuchElementException. + */ public T get() { synchronized (this.lock) { T result = this.queue.remove(); @@ -248,19 +253,20 @@ public T get() { } } - /** Get next response or wait until the next value is available. - **

- ** This method will block until a value is available. - **

- ** Note: if the cache is paused or no more randomness is available from the server this call can result in a dead lock. - ** - ** @see #isPaused() - ** - ** @return next appropriate response for the request this RandomOrgCache represents - ** - ** @throws InterruptedException if any thread interrupted the current thread before or - ** while the current thread was waiting for a notification. The interrupted status of - ** the current thread is cleared when this exception is thrown. + /** + * Get next response or wait until the next value is available. + *

+ * This method will block until a value is available. + *

+ * Note: if the cache is paused or no more randomness is available from the server this call can result in a dead lock. + * + * @see #isPaused() + * + * @return next appropriate response for the request this RandomOrgCache represents + * + * @throws InterruptedException if any thread interrupted the current thread before or + * while the current thread was waiting for a notification. The interrupted status of + * the current thread is cleared when this exception is thrown. */ public T getOrWait() throws InterruptedException { @@ -275,29 +281,32 @@ public T getOrWait() throws InterruptedException { return result; } - /** Get number of results of type {@link #T} remaining in the cache. - **

- ** This essentially returns how often get() may be called without a cache refill, - ** or getOrWait() may be called without blocking. - ** - ** @return current number of cached results - **/ + /** + * Get number of results of type {@link #T} remaining in the cache. + *

+ * This essentially returns how often {@code get()} may be called without a cache refill, + * or {@code getOrWait()} may be called without blocking. + * + * @return current number of cached results + */ public int getCachedValues() { return this.queue.size(); } - /** Get number of bits used by this cache. - ** - ** @return number of used bits - **/ + /** + * Get number of bits used by this cache. + * + * @return number of used bits + */ public long getUsedBits() { return this.usedBits; } - /** Get number of requests used by this cache. - ** - ** @return number of used requests - **/ + /** + * Get number of requests used by this cache. + * + * @return number of used requests + */ public long getUsedRequests() { return this.usedRequests; } diff --git a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java index 7f448a4..29f2490 100644 --- a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java +++ b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java @@ -6,6 +6,7 @@ import java.io.InputStreamReader; import java.net.MalformedURLException; import java.net.URL; +import java.util.Arrays; import java.util.Calendar; import java.util.GregorianCalendar; import java.util.HashMap; @@ -25,40 +26,41 @@ import org.random.api.exception.RandomOrgRANDOMORGError; import org.random.api.exception.RandomOrgSendTimeoutException; +import com.google.gson.Gson; import com.google.gson.JsonArray; import com.google.gson.JsonObject; import com.google.gson.JsonParser; -/** RandomOrgClient main class through which API functions are accessed. - ** - ** This class provides either serialized or unserialized (determined on class creation) - ** access to both the signed and unsigned methods of the RANDOM.ORG API. These are - ** threadsafe and implemented as blocking remote procedure calls. - ** - ** If requests are to be issued serially a background Thread will maintain a Queue of - ** requests to process in sequence. - ** - ** The class also provides access to creation of a convenience class, RandomOrgCache, - ** for precaching API responses when the request is known in advance. - ** - ** This class will only allow the creation of one instance per API key. If an instance - ** of this class already exists for a given key, that instance will be returned instead - ** of a new instance. - ** - ** This class obeys most of the guidelines set forth in https://api.random.org/guidelines - ** All requests respect the server's advisoryDelay returned in any responses, or use - ** DEFAULT_DELAY if no advisoryDelay is returned. If the supplied API key is paused, i.e., - ** has exceeded its daily bit/request allowance, this implementation will back off until - ** midnight UTC. - ** - ** @see https://api.random.org/ - ** @see http://code.google.com/p/google-gson/ - ** @author Anders Haahr - **/ +/** + * RandomOrgClient main class through which API functions are accessed. + * + * This class provides either serialized or unserialized (determined on class creation) access + * to both the signed and unsigned methods of the RANDOM.ORG API. These are threadsafe and + * implemented as blocking remote procedure calls. + * + * If requests are to be issued serially a background Thread will maintain a Queue of requests + * to process in sequence. + * + * The class also provides access to creation of a convenience class, RandomOrgCache, for precaching + * API responses when the request is known in advance. + * + * This class will only allow the creation of one instance per API key. If an instance of this class + * already exists for a given key, that instance will be returned instead of a new instance. + * + * This class obeys most of the guidelines set forth in https://api.random.org/json-rpc/2 + * All requests respect the server's advisoryDelay returned in any responses, or use DEFAULT_DELAY + * if no advisoryDelay is returned. If the supplied API key is paused, i.e., has exceeded its daily + * bit/request allowance, this implementation will back off until midnight UTC. + * + * @see https://api.random.org/ + * @see http://code.google.com/p/google-gson/ + * @author Anders Haahr + */ public class RandomOrgClient { - // Basic RANDOM.ORG API functions https://api.random.org/json-rpc/1/ + // Basic RANDOM.ORG API functions https://api.random.org/json-rpc/2 private static final String INTEGER_METHOD = "generateIntegers"; + private static final String INTEGER_SEQUENCE_METHOD = "generateIntegerSequences"; private static final String DECIMAL_FRACTION_METHOD = "generateDecimalFractions"; private static final String GAUSSIAN_METHOD = "generateGaussians"; private static final String STRING_METHOD = "generateStrings"; @@ -66,13 +68,15 @@ public class RandomOrgClient { private static final String BLOB_METHOD = "generateBlobs"; private static final String GET_USAGE_METHOD = "getUsage"; - // Signed RANDOM.ORG API functions https://api.random.org/json-rpc/1/signing + // Signed RANDOM.ORG API functions https://api.random.org/json-rpc/2/signed private static final String SIGNED_INTEGER_METHOD = "generateSignedIntegers"; + private static final String SIGNED_INTEGER_SEQUENCE_METHOD = "generateSignedIntegerSequences"; private static final String SIGNED_DECIMAL_FRACTION_METHOD = "generateSignedDecimalFractions"; private static final String SIGNED_GAUSSIAN_METHOD = "generateSignedGaussians"; private static final String SIGNED_STRING_METHOD = "generateSignedStrings"; private static final String SIGNED_UUID_METHOD = "generateSignedUUIDs"; private static final String SIGNED_BLOB_METHOD = "generateSignedBlobs"; + private static final String GET_RESULT_METHOD = "getResult"; private static final String VERIFY_SIGNATURE_METHOD = "verifySignature"; // Blob format literals @@ -85,15 +89,23 @@ public class RandomOrgClient { // On request fetch fresh allowance state if current state data is older than this value (1 hour) private static final int ALLOWANCE_STATE_REFRESH_SECONDS = 3600*1000; - // default data sizes in bits + // Default data sizes in bits private static final int UUID_SIZE = 122; + // Default parameter values + public static final boolean DEFAULT_REPLACEMENT = true; + public static final int DEFAULT_INT_BASE = 10; + public static final JsonObject DEFAULT_USER_DATA = null; + public static final int DEFAULT_CACHE_SIZE = 20; + public static final int DEFAULT_CACHE_SIZE_SMALL = 10; //UUID and BLOB caches + // Maintain a dictionary of API keys and their instances. private static HashMap keyIndexedInstances = new HashMap(); private static HashSet randomOrgErrors = new HashSet(); static { - int[] ints = {100, 101, 200, 201, 202, 203, 204, 300, 301, 302, 303, 304, 400, 401, 402, 403, 500, 32000}; + int[] ints = {100, 101, 200, 201, 202, 203, 204, 300, 301, 302, 303, 304, 305, 306, 307, + 400, 401, 402, 403, 404, 405, 500, 32000}; for (int i : ints) { RandomOrgClient.randomOrgErrors.add(i); } @@ -106,12 +118,12 @@ public class RandomOrgClient { private int httpTimeout; private boolean serialized; - // maintain info to obey server advisory delay + // Maintain info to obey server advisory delay private Object advisoryDelayLock = new Object(); private int advisoryDelay = 0; private long lastResponseReceivedTime = 0; - // maintain usage statistics from server + // Maintain usage statistics from server private int requestsLeft = -1; private int bitsLeft = -1; @@ -121,33 +133,42 @@ public class RandomOrgClient { private String backoffError; private LinkedList> serializedQueue; + + // Gson instance for handling certain Json operations + private Gson gson = new Gson(); - /** Ensure only one instance of RandomOrgClient exists per API key. Create a new instance if the - ** supplied key isn't already known, otherwise return the previously instantiated one. - ** New instance will have a blockingTimeout of 24*60*60*1000 milliseconds, i.e., 1 day, a httpTimeout of - ** 120*1000 milliseconds, and will issue serialized requests. - ** - ** @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys - ** - ** @return new instance if instance doesn't already exist for this key, else existing instance. - **/ + /** + * Ensure only one instance of RandomOrgClient exists per API key. Create a new instance + * if the supplied key isn't already known, otherwise return the previously instantiated one. + * + * New instance will have a blockingTimeout of 24*60*60*1000 milliseconds, i.e., 1 day, + * a httpTimeout of 120*1000 milliseconds, and will issue serialized requests. + * + * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys + * + * @return new instance if instance doesn't already exist for this key, else existing instance. + */ public static RandomOrgClient getRandomOrgClient(String apiKey) { return RandomOrgClient.getRandomOrgClient(apiKey, 24*60*60*1000, 120*1000, true); } - /** Ensure only one instance of RandomOrgClient exists per API key. Create a new instance if the - ** supplied key isn't already known, otherwise return the previously instantiated one. - ** - ** @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys - ** @param blockingTimeout maximum time in milliseconds to wait before being allowed to send a request. - ** Note this is a hint not a guarantee. Be advised advisory delay from server must always be obeyed. - ** Supply a value of -1 to allow blocking forever. (default 24*60*60*1000, i.e., 1 day). - ** @param httpTimeout maximum time in milliseconds to wait for the server response to a request. (default 120*1000). - ** @param serialized determines whether or not requests from this instance will be added to a Queue and - ** issued serially or sent when received, obeying any advisory delay (default true). - ** - ** @return new instance if instance doesn't already exist for this key, else existing instance. - **/ + /** + * Ensure only one instance of RandomOrgClient exists per API key. Create a new instance + * if the supplied key isn't already known, otherwise return the previously instantiated one. + * + * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys + * @param blockingTimeout maximum time in milliseconds to wait before being allowed to send + * a request. Note this is a hint not a guarantee. Be advised advisory delay from server + * must always be obeyed. Supply a value of -1 to allow blocking forever + * (default 24*60*60*1000, i.e., 1 day). + * @param httpTimeout maximum time in milliseconds to wait for the server response to a + * request (default 120*1000). + * @param serialized determines whether or not requests from this instance will be added to + * a Queue and issued serially or sent when received, obeying any advisory delay + * (default true). + * + * @return new instance if instance doesn't already exist for this key, else existing instance. + */ public static RandomOrgClient getRandomOrgClient(String apiKey, long blockingTimeout, int httpTimeout, boolean serialized) { RandomOrgClient instance = RandomOrgClient.keyIndexedInstances.get(apiKey); @@ -159,18 +180,22 @@ public static RandomOrgClient getRandomOrgClient(String apiKey, long blockingTim return instance; } - /** Constructor. Initialize class and start serialized request sending Thread running as a daemon if applicable. - ** - ** @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys - ** @param blockingTimeout maximum time in milliseconds to wait before being allowed to send a request. - ** Note this is a hint not a guarantee. Be advised advisory delay from server must always be obeyed. - ** Supply a value of -1 to allow blocking forever. (default 24*60*60*1000, i.e., 1 day). - ** @param httpTimeout maximum time in milliseconds to wait for the server response to a request. (default 120*1000). - ** @param serialized determines whether or not requests from this instance will be added to a Queue and - ** issued serially or sent when received, obeying any advisory delay (default true). - **/ - private RandomOrgClient(String apiKey, long blockingTimeout, int httpTimeout, boolean serialized) { - + /** + * Constructor. Initialize class and start serialized request sending Thread running as + * a daemon if applicable. + * + * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys + * @param blockingTimeout maximum time in milliseconds to wait before being allowed to + * send a request. Note this is a hint not a guarantee. Be advised advisory delay + * from server must always be obeyed. Supply a value of -1 to allow blocking forever + * (default 24*60*60*1000, i.e., 1 day). + * @param httpTimeout maximum time in milliseconds to wait for the server response to a + * request. (default 120*1000). + * @param serialized determines whether or not requests from this instance will be added to + * a Queue and issued serially or sent when received, obeying any advisory delay + * (default true). + */ + private RandomOrgClient(String apiKey, long blockingTimeout, int httpTimeout, boolean serialized) { if (serialized) { // set up the serialized request Queue and Thread this.serializedQueue = new LinkedList>(); @@ -190,148 +215,493 @@ public void run() { this.apiKey = apiKey; this.blockingTimeout = blockingTimeout; this.httpTimeout = httpTimeout; + + try { + this.getUsage(); + } catch (Exception e) { + LOGGER.log(Level.INFO, e.getMessage()); + } + } + + // Basic methods for generating randomness, see: https://api.random.org/json-rpc/2/basic + + /** + * Request and return an array of true random integers within a user-defined range from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegers + * + * @param n the number of random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * + * @return int[] of random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[] generateIntegers(int n, int min, int max) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateIntegers(n, min, max, DEFAULT_REPLACEMENT); + } + + /** + * Request and return an array of true random integers within a user-defined range from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegers + * + * @param n the number of random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * + * @return int[] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[] generateIntegers(int n, int min, int max, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractInts(this.integerMethod(n, min, max, replacement, DEFAULT_INT_BASE)); + } + + /** + * Request and return an array of true random integers within a user-defined range from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegers + * + * @param n the number of random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). For base 10, if you would prefer an int[] to be returned instead + * of a String[], please use the {@link #generateIntegers(int n, int min, int max, + * boolean replacement) generateIntegers} method without the base parameter. + * + * @return String[] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[] generateIntegers(int n, int min, int max, boolean replacement, int base) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractStrings(this.integerMethod(n, min, max, replacement, base)); + } + + /** + * Request and return uniform sequences of true random integers within user-defined ranges + * from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * + * @return int[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[][] generateIntegerSequences(int n, int length, int min, int max) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateIntegerSequences(n, length, min, max, DEFAULT_REPLACEMENT); + } + + /** + * Request and return uniform sequences of true random integers within user-defined ranges + * from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * + * @return int[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractIntSequences(this.integerSequencesMethod(n, length, min, max, replacement, DEFAULT_INT_BASE, DEFAULT_USER_DATA, false)); + } + + /** + * Request and return uniform sequences of true random integers within user-defined ranges + * from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). For base 10, if you would prefer an int[][] to be returned + * instead of a String[][] please use the {@link #generateIntegerSequences(int n, int length, + * int min, int max, boolean replacement) generateIntegerSequences} method without + * the base parameter. + * + * @return String[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement, int base) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractIntSequencesString(this.integerSequencesMethod(n, length, + min, max, replacement, base, DEFAULT_USER_DATA, false)); } - // Basic methods for generating randomness, see: https://api.random.org/json-rpc/1/basic - - /** Request and return an array of true random integers within a user-defined range from the server. - ** See: https://api.random.org/json-rpc/1/basic#generateIntegers - ** - ** @param n how many random integers you need. Must be within the [1,1e4] range. - ** @param min the lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param max the upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** - ** @return array of random integers. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public int[] generateIntegers(int n, int min, int max) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - return generateIntegers(n, min, max, true); - } - - /** Request and return an array of true random integers within a user-defined range from the server. - ** See: https://api.random.org/json-rpc/1/basic#generateIntegers - ** - ** @param n how many random integers you need. Must be within the [1,1e4] range. - ** @param min the lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param max the upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param replacement specifies whether the random numbers should be picked with replacement. - ** If True the resulting numbers may contain duplicate values, otherwise the numbers will all be unique (default True). - ** - ** @return array of random integers. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public int[] generateIntegers(int n, int min, int max, boolean replacement) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * + * @return int[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + boolean[] replacement = new boolean[n]; + Arrays.fill(replacement, DEFAULT_REPLACEMENT); + + return this.generateIntegerSequences(n, length, min, max, replacement); + } + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param replacement an array with n Boolean values, each specifying whether the sequence + * identified by its index will be created with or without replacement. If true, the + * resulting numbers may contain duplicate values, otherwise the numbers will all be + * unique within each sequence (default true). + * + * @return int[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + int[] base = new int[n]; + Arrays.fill(base, DEFAULT_INT_BASE); + + return this.extractIntSequences(this.integerSequencesMethod(n, length, + min, max, replacement, base, DEFAULT_USER_DATA, false)); + } + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. + * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param replacement an array with n Boolean values, each specifying whether the sequence + * identified by its index will be created with or without replacement. If true, the + * resulting numbers may contain duplicate values, otherwise the numbers will all be + * unique within each sequence (default true). + * @param base an array with n integer values, each specifying the base that will be used to + * display the sequence identified by its index. Values allowed are 2, 8, 10 and 16 + * (default 10). For base 10, if you require an int[][] instead of a String[][], please + * use the {@link #generateIntegerSequences(int n, int[] length, int[] min, int[] max, + * boolean[] replacement) generateIntegerSequences} method without the base parameter. + * + * @return String[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractIntSequencesString(this.integerSequencesMethod(n, length, + min, max, replacement, base, DEFAULT_USER_DATA, false)); + } - JsonObject request = new JsonObject(); + /** + * Request and return a list (size n) of true random decimal fractions, from a uniform + * distribution across the [0,1] interval with a user-defined number of decimal places + * from the server. + * See: https://api.random.org/json-rpc/2/basic#generateDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * + * @return double[] of true random decimal fractions. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public double[] generateDecimalFractions(int n, int decimalPlaces) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateDecimalFractions(n, decimalPlaces, DEFAULT_REPLACEMENT); + } - request.addProperty("n", n); - request.addProperty("min", min); - request.addProperty("max", max); - request.addProperty("replacement", replacement); - - request = this.generateKeyedRequest(request, INTEGER_METHOD); - - JsonObject response = this.sendRequest(request); - - return this.extractInts(response); - } - - /** Request and return a list (size n) of true random decimal fractions, from a uniform distribution across - ** the [0,1] interval with a user-defined number of decimal places from the server. - ** See: https://api.random.org/json-rpc/1/basic#generateDecimalFractions - ** - ** @param n how many random decimal fractions you need. Must be within the [1,1e4] range. - ** @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. - ** - ** @return array of random doubles. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public double[] generateDecimalFractions(int n, int decimalPlaces) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - return this.generateDecimalFractions(n, decimalPlaces, true); - } - - /** Request and return a list (size n) of true random decimal fractions, from a uniform distribution across - ** the [0,1] interval with a user-defined number of decimal places from the server. - ** See: https://api.random.org/json-rpc/1/basic#generateDecimalFractions - ** - ** @param n how many random decimal fractions you need. Must be within the [1,1e4] range. - ** @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. - ** @param replacement specifies whether the random numbers should be picked with replacement. - ** If True the resulting numbers may contain duplicate values, otherwise the numbers will all be unique (default True). - ** - ** @return array of random doubles. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public double[] generateDecimalFractions(int n, int decimalPlaces, boolean replacement) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request and return a list (size n) of true random decimal fractions, from a uniform + * distribution across the [0,1] interval with a user-defined number of decimal places + * from the server. + * See: https://api.random.org/json-rpc/2/basic#generateDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * + * @return double[] of true random decimal fractions. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public double[] generateDecimalFractions(int n, int decimalPlaces, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -345,37 +715,44 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla return this.extractDoubles(response); } - /** Request and return a list (size n) of true random numbers from a Gaussian distribution (also known as a - ** normal distribution). The form uses a Box-Muller Transform to generate the Gaussian distribution from - ** uniformly distributed numbers. See: https://api.random.org/json-rpc/1/basic#generateGaussians - ** - ** @param n how many random numbers you need. Must be within the [1,1e4] range. - ** @param mean the distribution's mean. Must be within the [-1e6,1e6] range. - ** @param standardDeviation the distribution's standard deviation. Must be within the [-1e6,1e6] range. - ** @param significantDigits the number of significant digits to use. Must be within the [2,20] range. - ** - ** @return array of true random doubles from a Gaussian distribution. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public double[] generateGaussians(int n, double mean, double standardDeviation, int significantDigits) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request and return a list (size n) of true random numbers from a Gaussian distribution + * (also known as a normal distribution). The form uses a Box-Muller Transform to generate + * the Gaussian distribution from uniformly distributed numbers. + * See: https://api.random.org/json-rpc/2/basic#generateGaussians + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * + * @return double[] of true random doubles from a Gaussian distribution. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public double[] generateGaussians(int n, double mean, double standardDeviation, int significantDigits) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -390,70 +767,82 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, return this.extractDoubles(response); } - /** Request and return a list (size n) of true random unicode strings from the server. - ** See: https://api.random.org/json-rpc/1/basic#generateStrings - ** - ** @param n how many random strings you need. Must be within the [1,1e4] range. - ** @param length the length of each string. Must be within the [1,20] range. All strings will be of the same length. - ** @param characters a string that contains the set of characters that are allowed to occur in the random strings. - ** The maximum number of characters is 80. - ** - ** @return array of random Strings. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public String[] generateStrings(int n, int length, String characters) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - return this.generateStrings(n, length, characters, true); - } - - /** Request and return a list (size n) of true random unicode strings from the server. - ** See: https://api.random.org/json-rpc/1/basic#generateStrings - ** - ** @param n how many random strings you need. Must be within the [1,1e4] range. - ** @param length the length of each string. Must be within the [1,20] range. All strings will be of the same length. - ** @param characters a string that contains the set of characters that are allowed to occur in the random strings. - ** The maximum number of characters is 80. - ** @param replacement specifies whether the random strings should be picked with replacement. If True the resulting - ** list of strings may contain duplicates, otherwise the strings will all be unique (default True). - ** - ** @return array of random Strings. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public String[] generateStrings(int n, int length, String characters, boolean replacement) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request and return a list (size n) of true random unicode strings from the server. + * See: https://api.random.org/json-rpc/2/basic#generateStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to occur + * in the random strings. The maximum number of characters is 80. + * + * @return String[] of true random Strings. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[] generateStrings(int n, int length, String characters) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateStrings(n, length, characters, DEFAULT_REPLACEMENT); + } + + /** + * Request and return a list (size n) of true random unicode strings from the server. + * See: https://api.random.org/json-rpc/2/basic#generateStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to occur + * in the random strings. The maximum number of characters is 80. + * @param replacement specifies whether the random strings should be picked with replacement. + * If True the resulting list of strings may contain duplicates, otherwise the strings + * will all be unique (default true). + * + * @return String[] of true random Strings. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[] generateStrings(int n, int length, String characters, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -468,33 +857,38 @@ public String[] generateStrings(int n, int length, String characters, boolean re return this.extractStrings(response); } - /** Request and return a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) in accordance - ** with section 4.4 of RFC 4122, from the server. See: https://api.random.org/json-rpc/1/basic#generateUUIDs - ** - ** @param n how many random UUIDs you need. Must be within the [1,1e3] range. - ** - ** @return array of random UUIDs. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public UUID[] generateUUIDs(int n) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request and return a list (size n) of version 4 true random Universally Unique IDentifiers + * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. + * See: https://api.random.org/json-rpc/2/basic#generateUUIDs + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * + * @return UUID[] of true random UUIDs. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public UUID[] generateUUIDs(int n) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -506,67 +900,79 @@ public UUID[] generateUUIDs(int n) throws RandomOrgSendTimeoutException, return this.extractUUIDs(response); } - /** Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings - ** containing true random data from the server. See: https://api.random.org/json-rpc/1/basic#generateBlobs - ** - ** @param n how many random blobs you need. Must be within the [1,100] range. - ** @param size the size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8. - ** - ** @return array of random blobs as Strings. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public String[] generateBlobs(int n, int size) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - - return this.generateBlobs(n, size, RandomOrgClient.BLOB_FORMAT_BASE64); - } - - /** Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings - ** containing true random data from the server. See: https://api.random.org/json-rpc/1/basic#generateBlobs - ** - ** @param n how many random blobs you need. Must be within the [1,100] range. - ** @param size the size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8. - ** @param format specifies the format in which the blobs will be returned. Values allowed are - ** BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). - ** - ** @return array of random blobs as Strings. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public String[] generateBlobs(int n, int size, String format) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings + * containing true random data from the server. + * See: https://api.random.org/json-rpc/2/basic#generateBlobs + * + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range + * and must be divisible by 8. + * + * @return String[] of true random blobs as Strings. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[] generateBlobs(int n, int size) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateBlobs(n, size, BLOB_FORMAT_BASE64); + } + + /** + * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings + * containing true random data from the server. + * See: https://api.random.org/json-rpc/2/basic#generateBlobs + * + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range + * and must be divisible by 8. + * @param format specifies the format in which the blobs will be returned. Values allowed + * are BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). + * + * @return String[] of true random blobs as Strings. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[] generateBlobs(int n, int size, String format) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -580,159 +986,521 @@ public String[] generateBlobs(int n, int size, String format) throws RandomOrgSe return this.extractStrings(response); } - // Signed methods for generating randomness, see: https://api.random.org/json-rpc/1/signing - - /** Request a list (size n) of true random integers within a user-defined range from the server. Returns a - ** dictionary object with the parsed integer list mapped to 'data', the original response mapped to 'random', - ** and the response's signature mapped to 'signature'. See: https://api.random.org/json-rpc/1/signing#generateSignedIntegers - ** - ** @param n how many random integers you need. Must be within the [1,1e4] range. - ** @param min the lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param max the upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random int[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedIntegers(int n, int min, int max) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - return generateSignedIntegers(n, min, max, true); - } - - /** Request a list (size n) of true random integers within a user-defined range from the server. Returns a - ** dictionary object with the parsed integer list mapped to 'data', the original response mapped to 'random', - ** and the response's signature mapped to 'signature'. See: https://api.random.org/json-rpc/1/signing#generateSignedIntegers - ** - ** @param n how many random integers you need. Must be within the [1,1e4] range. - ** @param min the lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param max the upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param replacement specifies whether the random numbers should be picked with replacement. - ** If True the resulting numbers may contain duplicate values, otherwise the numbers will all be unique (default True). - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random int[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + // Signed methods for generating randomness, see: https://api.random.org/json-rpc/2/signed + + /** + * Request a list (size n) of true random integers within a user-defined range from the server. + * Returns a dictionary object with the parsed integer list mapped to 'data', the original + * response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedIntegers + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegers(int n, int min, int max) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedIntegers(n, min, max, DEFAULT_REPLACEMENT); + } + + /** + * Request a list (size n) of true random integers within a user-defined range from the server. + * Returns a dictionary object with the parsed integer list mapped to 'data', the original + * response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedIntegers + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedIntegers(n, min, max, replacement, DEFAULT_INT_BASE, DEFAULT_USER_DATA); + } + + /** + * Request a list (size n) of true random integers within a user-defined range from the server. + * Returns a dictionary object with the parsed integer list mapped to 'data', the original + * response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedIntegers + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, + * 8, 10 and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[] if decimal (base 10) + * or random String[] if non-decimal (any other base value) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement, int base, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("min", min); request.addProperty("max", max); request.addProperty("replacement", replacement); + request.addProperty("base", base); + request.add("userData", userData); request = this.generateKeyedRequest(request, SIGNED_INTEGER_METHOD); JsonObject response = this.sendRequest(request); HashMap result = new HashMap(); - result.put("data", this.extractInts(response)); + if (base == 10) { + result.put("data", this.extractInts(response)); + } else { + result.put("data", this.extractStrings(response)); + } + return this.extractSignedResponse(response, result); + } + + /** + * Request and return uniform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int length, int min, int max) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedIntegerSequences(n, length, min, max, DEFAULT_REPLACEMENT, + DEFAULT_INT_BASE, DEFAULT_USER_DATA); + } + + /** + * Request and return uniform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, + * 10 and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] if decimal (base 10) + * or random String[][] if non-decimal (any other base value) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject response = this.integerSequencesMethod(n, length, min, max, + replacement, base, userData, true); + + HashMap result = new HashMap(); + if (base == 10) { + result.put("data", this.extractIntSequences(response)); + } else { + result.put("data", this.extractIntSequencesString(response)); + } return this.extractSignedResponse(response, result); } - - /** Request a list (size n) of true random decimal fractions, from a uniform distribution across the [0,1] interval - ** with a user-defined number of decimal places from the server. Returns a dictionary object with the parsed decimal - ** fraction list mapped to 'data', the original response mapped to 'random', and the response's signature mapped to - ** 'signature'. See: https://api.random.org/json-rpc/1/signing#generateSignedDecimalFractions - ** - ** @param n how many random decimal fractions you need. Must be within the [1,1e4] range. - ** @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random double[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedDecimalFractions(int n, int decimalPlaces) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - - return this.generateSignedDecimalFractions(n, decimalPlaces, true); - } - - /** Request a list (size n) of true random decimal fractions, from a uniform distribution across the [0,1] interval - ** with a user-defined number of decimal places from the server. Returns a dictionary object with the parsed decimal - ** fraction list mapped to 'data', the original response mapped to 'random', and the response's signature mapped to - ** 'signature'. See: https://api.random.org/json-rpc/1/signing#generateSignedDecimalFractions - ** - ** @param n how many random decimal fractions you need. Must be within the [1,1e4] range. - ** @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. - ** @param replacement specifies whether the random numbers should be picked with replacement. - ** If True the resulting numbers may contain duplicate values, otherwise the numbers will all be unique (default True). - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random double[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences" + * https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + boolean[] replacement = new boolean[n]; + Arrays.fill(replacement, DEFAULT_REPLACEMENT); + int[] base = new int[n]; + Arrays.fill(base, DEFAULT_INT_BASE); + + return this.generateSignedIntegerSequences(n, length, min, max, replacement, + base, DEFAULT_USER_DATA); + } + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the + * sequence identified by its index. Each value in the array must + * be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of + * the sequence identified by its index. Each value in the array must + * be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of + * the sequence identified by its index. Each value in the array must + * be within the [-1e9,1e9] range. + * @param replacement an array with n Boolean values, each specifying whether + * the sequence identified by its index will be created with or without + * replacement. If true, the resulting numbers may contain + * duplicate values, otherwise the numbers will all be unique within + * each sequence (default true). + * @param base an array with n integer values, each specifying the base + * that will be used to display the sequence identified by its index. + * Values allowed are 2, 8, 10 and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] if decimal (all base values are 10) + * or random String[][] if non-decimal (any other mix of base values) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + int[] defaultBase = new int[n]; + Arrays.fill(defaultBase, DEFAULT_INT_BASE); + + JsonObject response = this.integerSequencesMethod(n, length, min, max, + replacement, base, userData, true); + HashMap result = new HashMap(); + if (Arrays.equals(base, defaultBase)) { + result.put("data", this.extractIntSequences(response)); + } else { + result.put("data", this.extractIntSequencesString(response)); + } + + return this.extractSignedResponse(response, result); + } + + /** + * Request a list (size n) of true random decimal fractions, from a uniform distribution + * across the [0,1] interval with a user-defined number of decimal places from the server. + * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the + * original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedDecimalFractions(n, decimalPlaces, DEFAULT_REPLACEMENT); + } + + /** + * Request a list (size n) of true random decimal fractions, from a uniform distribution + * across the [0,1] interval with a user-defined number of decimal places from the server. + * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the + * original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedDecimalFractions(n, decimalPlaces, replacement, DEFAULT_USER_DATA); + } + + /** + * Request a list (size n) of true random decimal fractions, from a uniform distribution + * across the [0,1] interval with a user-defined number of decimal places from the server. + * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the + * original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("decimalPlaces", decimalPlaces); request.addProperty("replacement", replacement); + request.add("userData", userData); request = this.generateKeyedRequest(request, SIGNED_DECIMAL_FRACTION_METHOD); @@ -744,44 +1512,101 @@ public HashMap generateSignedDecimalFractions(int n, int decimal return this.extractSignedResponse(response, result); } - /** Request a list (size n) of true random numbers from a Gaussian distribution (also known as a normal distribution). - ** The form uses a Box-Muller Transform to generate the Gaussian distribution from uniformly distributed numbers. - ** Returns a dictionary object with the parsed random number list mapped to 'data', the original response mapped to 'random', - ** and the response's signature mapped to 'signature'. See: https://api.random.org/json-rpc/1/signing#generateSignedGaussians - ** - ** @param n how many random numbers you need. Must be within the [1,1e4] range. - ** @param mean the distribution's mean. Must be within the [-1e6,1e6] range. - ** @param standardDeviation the distribution's standard deviation. Must be within the [-1e6,1e6] range. - ** @param significantDigits the number of significant digits to use. Must be within the [2,20] range. - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random double[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request a list (size n) of true random numbers from a Gaussian distribution (also known + * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian + * distribution from uniformly distributed numbers. Returns a dictionary object with the + * parsed random number list mapped to 'data', the original response mapped to 'random', + * and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedGaussians + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedGaussians(n, mean, standardDeviation, + significantDigits, DEFAULT_USER_DATA); + } + + /** + * Request a list (size n) of true random numbers from a Gaussian distribution (also known + * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian + * distribution from uniformly distributed numbers. Returns a dictionary object with the + * parsed random number list mapped to 'data', the original response mapped to 'random', + * and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedGaussians + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("mean", mean); request.addProperty("standardDeviation", standardDeviation); request.addProperty("significantDigits", significantDigits); + request.add("userData", userData); request = this.generateKeyedRequest(request, SIGNED_GAUSSIAN_METHOD); @@ -793,78 +1618,142 @@ public HashMap generateSignedGaussians(int n, double mean, doubl return this.extractSignedResponse(response, result); } - /** Request a list (size n) of true random strings from the server. Returns a dictionary object with the parsed random - ** string list mapped to 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - ** See: https://api.random.org/json-rpc/1/signing#generateSignedStrings - ** - ** @param n how many random strings you need. Must be within the [1,1e4] range. - ** @param length the length of each string. Must be within the [1,20] range. All strings will be of the same length. - ** @param characters a string that contains the set of characters that are allowed to occur in the random strings. - ** The maximum number of characters is 80. - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random String[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedStrings(int n, int length, String characters) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - return this.generateSignedStrings(n, length, characters, true); - } - - /** Request a list (size n) of true random strings from the server. Returns a dictionary object with the parsed random - ** string list mapped to 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - ** See: https://api.random.org/json-rpc/1/signing#generateSignedStrings - ** - ** @param n how many random strings you need. Must be within the [1,1e4] range. - ** @param length the length of each string. Must be within the [1,20] range. All strings will be of the same length. - ** @param characters a string that contains the set of characters that are allowed to occur in the random strings. - ** The maximum number of characters is 80. - ** @param replacement specifies whether the random strings should be picked with replacement. If True the resulting - ** list of strings may contain duplicates, otherwise the strings will all be unique (default True). - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random String[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request a list (size n) of true random strings from the server. Returns a dictionary + * object with the parsed random string list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to + * occur in the random strings. The maximum number of characters is 80. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedStrings(int n, int length, String characters) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedStrings(n, length, characters, DEFAULT_REPLACEMENT); + } + + /** + * Request a list (size n) of true random strings from the server. Returns a dictionary + * object with the parsed random string list mapped to 'data',the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to + * occur in the random strings. The maximum number of characters is 80. + * @param replacement specifies whether the random strings should be picked with replacement. + * If true, the resulting list of strings may contain duplicates, otherwise the strings + * will all be unique (default true). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedStrings(n, length, characters, replacement, + DEFAULT_USER_DATA); + } + + /** + * Request a list (size n) of true random strings from the server. Returns a dictionary + * object with the parsed random string list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to + * occur in the random strings. The maximum number of characters is 80. + * @param replacement specifies whether the random strings should be picked with replacement. + * If true, the resulting list of strings may contain duplicates, otherwise the strings + * will all be unique (default true). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("length", length); request.addProperty("characters", characters); request.addProperty("replacement", replacement); + request.add("userData", userData); request = this.generateKeyedRequest(request, SIGNED_STRING_METHOD); @@ -876,38 +1765,85 @@ public HashMap generateSignedStrings(int n, int length, String c return this.extractSignedResponse(response, result); } - /** Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) in accordance with - ** section 4.4 of RFC 4122, from the server. Returns a dictionary object with the parsed random UUID list mapped - ** to 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - ** See: https://api.random.org/json-rpc/1/signing#generateSignedUUIDs - ** - ** @param n how many random UUIDs you need. Must be within the [1,1e3] range. - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random UUID[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedUUIDs(int n) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) + * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary + * object with the parsed random UUID list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedUUIDs + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random UUID[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedUUIDs(int n) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedUUIDs(n, DEFAULT_USER_DATA); + } + + /** + * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) + * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary + * object with the parsed random UUID list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedUUIDs + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random UUID[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedUUIDs(int n, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); + request.add("userData", userData); request = this.generateKeyedRequest(request, SIGNED_UUID_METHOD); @@ -919,74 +1855,135 @@ public HashMap generateSignedUUIDs(int n) throws RandomOrgSendTi return this.extractSignedResponse(response, result); } - /** Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data from the server. Returns a - ** dictionary object with the parsed random BLOB list mapped to 'data', the original response mapped to 'random', - ** and the response's signature mapped to 'signature'. See: https://api.random.org/json-rpc/1/signing#generateSignedBlobs - ** - ** @param n how many random blobs you need. Must be within the [1,100] range. - ** @param size the size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8. - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random String[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedBlobs(int n, int size) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - - return this.generateSignedBlobs(n, size, RandomOrgClient.BLOB_FORMAT_BASE64); - } - - /** Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data from the server. Returns a - ** dictionary object with the parsed random BLOB list mapped to 'data', the original response mapped to 'random', - ** and the response's signature mapped to 'signature'. See: https://api.random.org/json-rpc/1/signing#generateSignedBlobs - ** - ** @param n how many random blobs you need. Must be within the [1,100] range. - ** @param size the size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8. - ** @param format specifies the format in which the blobs will be returned. Values allowed are - ** BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). - ** - ** @return HashMap with "random": random JsonObject, "signature": signature String, "data": random String[] - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public HashMap generateSignedBlobs(int n, int size, String format) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - + /** + * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data + * from the server. Returns a dictionary object with the parsed random BLOB list mapped + * to 'data', the original response mapped to 'random', and the response's signature + * mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedBlobs + * + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] + * range and must be divisible by 8. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedBlobs(int n, int size) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedBlobs(n, size, BLOB_FORMAT_BASE64); + } + + /** + * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data + * from the server. Returns a dictionary object with the parsed random BLOB list mapped + * to 'data', the original response mapped to 'random', and the response's signature + * mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedBlobs + * + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] + * range and must be divisible by 8. + * @param format specifies the format in which the blobs will be returned. Values allowed + * are BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedBlobs(int n, int size, String format) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedBlobs(n, size, format, DEFAULT_USER_DATA); + } + + /** + * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data + * from the server. Returns a dictionary object with the parsed random BLOB list mapped + * to 'data', the original response mapped to 'random', and the response's signature + * mapped to 'signature'. + * See: https://api.random.org/json-rpc/2/signed#generateSignedBlobs + * + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] + * range and must be divisible by 8. + * @param format specifies the format in which the blobs will be returned. Values allowed + * are BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedBlobs(int n, int size, String format, JsonObject userData) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("size", size); request.addProperty("format", format); + request.add("userData", userData); request = this.generateKeyedRequest(request, SIGNED_BLOB_METHOD); @@ -997,38 +1994,95 @@ public HashMap generateSignedBlobs(int n, int size, String forma return this.extractSignedResponse(response, result); } - - // Signature verification for signed methods, see: https://api.random.org/json-rpc/1/signing - - /** Verify the signature of a response previously received from one of the methods in the Signed API with the - ** server. This is used to examine the authenticity of numbers. Return True on verification success. - ** See: https://api.random.org/json-rpc/1/signing#verifySignature - ** - ** @param random the random field from a response returned by RANDOM.ORG through one of the Signed API methods. - ** @param signature the signature field from the same response that the random field originates from. - ** - ** @return verification success. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - public boolean verifySignature(JsonObject random, String signature) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { + + // Retrieve a signed result generated within the last 24h, + // see https://api.random.org/json-rpc/2/signed#getResult + + /** + * Retrieve signed random values generated within the last 24h, using a serial number. + * If the historical response was found, a response with the result property containing + * the same values that were returned by the method that was used to generate the values. + * See: https://api.random.org/json-rpc/2/signed#getResult + * + * @param serialNumber an integer containing the serial number associated with the response + * you wish to retrieve. + * + * @return HashMap with "random": random JsonObject, "signature": signature String + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap getResult(int serialNumber) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject request = new JsonObject(); + + request.addProperty("serialNumber", serialNumber); + + request = this.generateKeyedRequest(request, GET_RESULT_METHOD); + JsonObject response = this.sendRequest(request); + + HashMap result = new HashMap(); + + return this.extractSignedResponse(response, result); + } + + // Signature verification for signed methods, see: https://api.random.org/json-rpc/2/signed + + /** + * Verify the signature of a response previously received from one of the methods in + * the Signed API with the server. This is used to examine the authenticity of numbers. + * Return True on verification success. + * See: https://api.random.org/json-rpc/2/signed#verifySignature + * + * @param random the random field from a response returned by RANDOM.ORG through one of + * the Signed API methods. + * @param signature the signature field from the same response that the random field + * originates from. + * + * @return verification success. + * + *@throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public boolean verifySignature(JsonObject random, String signature) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.add("random", random); @@ -1043,31 +2097,41 @@ public boolean verifySignature(JsonObject random, String signature) throws Rando // Methods used to create a cache for any given randomness request. - /** Get a RandomOrgCache to obtain random integers. The RandomOrgCache can be polled for new results conforming to - ** the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random integers you need. Must be within the [1,1e4] range. - ** @param min the lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param max the upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** - ** @return RandomOrgCache - **/ + /** + * Get a RandomOrgCache to obtain random integers. The RandomOrgCache can be polled for + * new results conforming to the output format of the input request. RandomOrgCache type + * is same as expected return value. + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createIntegerCache(int n, int min, int max) { - return this.createIntegerCache(n, min, max, true, 20); - } - - /** Get a RandomOrgCache to obtain random integers. The RandomOrgCache can be polled for new results conforming to - ** the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random integers you need. Must be within the [1,1e4] range. - ** @param min the lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param max the upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. - ** @param replacement specifies whether the random numbers should be picked with replacement. - ** If True the resulting numbers may contain duplicate values, otherwise the numbers will all be unique (default True). - ** @param cacheSize number of result-sets for the cache to try to maintain at any given time (default 20, minimum 2). - ** - ** @return RandomOrgCache - **/ + return this.createIntegerCache(n, min, max, DEFAULT_REPLACEMENT, DEFAULT_CACHE_SIZE); + } + + /** + * Get a RandomOrgCache to obtain random integers. The RandomOrgCache can be polled for + * new results conforming to the output format of the input request. RandomOrgCache type + * is same as expected return value. + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param cacheSize number of result-sets for the cache to try to maintain at any given time + * (default 20, minimum 2). + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createIntegerCache(int n, int min, int max, boolean replacement, int cacheSize) { if (cacheSize < 2) { cacheSize = 2; @@ -1101,7 +2165,15 @@ public RandomOrgCache createIntegerCache(int n, int min, int max, boolean return new RandomOrgCache( new JsonObjectInputCallable() { @Override - public JsonObject call() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, RandomOrgInsufficientBitsError, RandomOrgBadHTTPResponseException, RandomOrgRANDOMORGError, RandomOrgJSONRPCError, MalformedURLException, IOException { + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { return RandomOrgClient.this.sendRequest(this.input); } }, new JsonObjectInputCallable() { @@ -1112,30 +2184,495 @@ public int[] call() { }, request, cacheSize, bulkN, n, maxRequestSize); } + + /** + * Get a RandomOrgCache to obtain random integers. The RandomOrgCache can be polled for + * new results conforming to the output format of the input request. RandomOrgCache type + * is same as expected return value. + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). For base 10, if you would prefer a {@code RandomOrgCache} + * to be returned instead of a {@code RandomOrgCache}, please use the {@link + * #createIntegerCache(int n, int min, int max, boolean replacement, int cacheSize) + * createIntegerCache} method without the base parameter. + * @param cacheSize number of result-sets for the cache to try to maintain at any given time + * (default 20, minimum 2). + * + * @return {@code RandomOrgCache} + */ + public RandomOrgCache createIntegerCache(int n, int min, int max, boolean replacement, int base, int cacheSize) { + if (cacheSize < 2) { + cacheSize = 2; + } + + JsonObject request = new JsonObject(); + + request.addProperty("min", min); + request.addProperty("max", max); + request.addProperty("replacement", replacement); + request.addProperty("base", base); + + int bulkN = 0; + + // If possible, make requests more efficient by bulk-ordering from the server. + // initially set at cache_size/2, but cache will auto-shrink bulk request size + // if requests can't be fulfilled. + if (replacement) { + bulkN = cacheSize/2; + request.addProperty("n", bulkN*n); + + // not possible to make the request more efficient + } else { + request.addProperty("n", n); + } + + // get the request object for use in all requests from this cache + request = this.generateKeyedRequest(request, INTEGER_METHOD); + + // max single request size, in bits, for adjusting bulk requests later + int maxRequestSize = (int) Math.ceil(Math.log(max - min + 1)/Math.log(2) * n); + + return new RandomOrgCache( + new JsonObjectInputCallable() { + @Override + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return RandomOrgClient.this.sendRequest(this.input); + } + }, new JsonObjectInputCallable() { + @Override + public String[] call() { + return RandomOrgClient.this.extractStrings(this.input); + } + }, + request, cacheSize, bulkN, n, maxRequestSize); + } + + /** + * Get a RandomOrgCache to obtain random integer sequences. The RandomOrgCache can be polled + * for new results conforming to the output format of the input request. RandomOrgCache + * type is same as expected return value. + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param length the length of each array of random integers requested. Must be within + * the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * + * @return {@code RandomOrgCache} + */ + public RandomOrgCache createIntegerSequenceCache(int n, int length, int min, int max) { + return this.createIntegerSequenceCache(n, length, min, max, DEFAULT_REPLACEMENT, DEFAULT_CACHE_SIZE_SMALL); + } + + /** + * Get a RandomOrgCache to obtain random integer sequences. The RandomOrgCache can be polled + * for new results conforming to the output format of the input request. RandomOrgCache + * type is same as expected return value. + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param length the length of each array of random integers requested. Must be within + * the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default True). + * @param cacheSize number of result-sets for the cache to try to maintain at any given + * time (default 10, minimum 2). + * + * @return {@code RandomOrgCache} + */ + public RandomOrgCache createIntegerSequenceCache(int n, int length, int min, int max, boolean replacement, int cacheSize) { + if (cacheSize < 2) { + cacheSize = 2; + } + + JsonObject request = new JsonObject(); + + request.addProperty("length", length); + request.addProperty("min", min); + request.addProperty("max", max); + request.addProperty("replacement", replacement); + + int bulkN = 0; + + // If possible, make requests more efficient by bulk-ordering from the server. + // initially set at cache_size/2, but cache will auto-shrink bulk request size + // if requests can't be fulfilled. + if (replacement) { + bulkN = cacheSize/2; + request.addProperty("n", bulkN*n); + + // not possible to make the request more efficient + } else { + request.addProperty("n", n); + } + + // get the request object for use in all requests from this cache + request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); + + // max single request size, in bits, for adjusting bulk requests later + int maxRequestSize = (int) Math.ceil(Math.log(max - min + 1)/Math.log(2) * n); + + return new RandomOrgCache( + new JsonObjectInputCallable() { + @Override + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return RandomOrgClient.this.sendRequest(this.input); + } + }, new JsonObjectInputCallable() { + @Override + public int[][] call() { + return RandomOrgClient.this.extractIntSequences(this.input); + } + }, + request, cacheSize, bulkN, n, maxRequestSize); + } + + /** + * Get a RandomOrgCache to obtain random integer sequences. The RandomOrgCache can be polled + * for new results conforming to the output format of the input request. RandomOrgCache + * type is same as expected return value. + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param length the length of each array of random integers requested. Must be within + * the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default True). + * @param base the base that will be used to display the numbers. Values allowed are 2, + * 8, 10 and 16 (default 10). For base 10, if you would prefer a {@code + * RandomOrgCache} to be returned instead of a {@code RandomOrgCache}, + * please use the {@link #createIntegerSequenceCache(int n, int length, int min, + * int max, boolean replacement, int cacheSize) createIntegerSequenceCache} method + * without the base parameter. + * @param cacheSize number of result-sets for the cache to try to maintain at any given + * time (default 10, minimum 2). + * + * @return {@code RandomOrgCache} + */ + public RandomOrgCache createIntegerSequenceCache(int n, int length, int min, int max, boolean replacement, int base, int cacheSize) { + if (cacheSize < 2) { + cacheSize = 2; + } + + JsonObject request = new JsonObject(); + + request.addProperty("length", length); + request.addProperty("min", min); + request.addProperty("max", max); + request.addProperty("replacement", replacement); + request.addProperty("base", base); + + int bulkN = 0; - /** Get a RandomOrgCache to obtain random decimal fractions. The RandomOrgCache can be polled for new results - ** conforming to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random decimal fractions you need. Must be within the [1,1e4] range. - ** @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. - ** - ** @return RandomOrgCache - **/ + // If possible, make requests more efficient by bulk-ordering from the server. + // initially set at cache_size/2, but cache will auto-shrink bulk request size if requests can't be fulfilled. + if (replacement) { + bulkN = cacheSize/2; + request.addProperty("n", bulkN*n); + + // not possible to make the request more efficient + } else { + request.addProperty("n", n); + } + + // get the request object for use in all requests from this cache + request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); + + // max single request size, in bits, for adjusting bulk requests later + int maxRequestSize = (int) Math.ceil(Math.log(max - min + 1)/Math.log(2) * n); + + return new RandomOrgCache( + new JsonObjectInputCallable() { + @Override + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return RandomOrgClient.this.sendRequest(this.input); + } + }, new JsonObjectInputCallable() { + @Override + public String[][] call() { + return RandomOrgClient.this.extractIntSequencesString(this.input); + } + }, + request, cacheSize, bulkN, n, maxRequestSize); + } + + /** + * Get a RandomOrgCache to obtain random integer sequences. The RandomOrgCache can be + * polled for new results conforming to the output format of the input request. RandomOrgCache + * type is same as expected return value. + * + * @param n how many random integers you need. Must be within the + * [1,1e4] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * + * @return {@code RandomOrgCache} + */ + public RandomOrgCache createIntegerSequenceCache(int n, int[] length, int[] min, int[] max) { + boolean[] replacement = new boolean[n]; + Arrays.fill(replacement, DEFAULT_REPLACEMENT); + return createIntegerSequenceCache(n, length, min, max, replacement, DEFAULT_CACHE_SIZE_SMALL); + } + + /** + * Get a RandomOrgCache to obtain random integer sequences. The RandomOrgCache can be polled + * for new results conforming to the output format of the input request. RandomOrgCache + * type is same as expected return value. + * + * @param n how many random integers you need. Must be within the + * [1,1e4] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param replacement an array with n boolean values, each specifying whether the sequence + * identified by its index will be created with or without replacement. If true, the + * resulting numbers may contain duplicate values, otherwise the numbers will all be + * unique within each sequence (default boolean[n] with all values set to true). + * @param cacheSize number of result-sets for the cache to try to maintain + * at any given time (default 10, minimum 2). + * + * @return {@code RandomOrgCache} + */ + public RandomOrgCache createIntegerSequenceCache(int n, int[] length, int[] min, int[] max, boolean[] replacement, int cacheSize) { + if (cacheSize < 2) { + cacheSize = 2; + } + + boolean[] defaultReplacement = new boolean[replacement.length]; + Arrays.fill(defaultReplacement, true); + + JsonObject request = new JsonObject(); + + int bulkN = 0; + + // If possible, make requests more efficient by bulk-ordering from the server. + // initially set at cache_size/2, but cache will auto-shrink bulk request size + // if requests can't be fulfilled. + if (Arrays.equals(replacement, defaultReplacement)) { + bulkN = cacheSize/2; + + request.addProperty("n", bulkN*n); + + length = adjust(length, bulkN*n); + min = adjust(min, bulkN*n); + max = adjust(max, bulkN*n); + replacement = adjust(replacement, bulkN*n); + + // not possible to make the request more efficient + } else { + request.addProperty("n", n); + } + + request.add("length", gson.toJsonTree(length)); + request.add("min", gson.toJsonTree(min)); + request.add("max", gson.toJsonTree(max)); + request.add("replacement", gson.toJsonTree(replacement)); + + // get the request object for use in all requests from this cache + request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); + + // max single request size, in bits, for adjusting bulk requests later + + + int maxRequestSize = (int) Math.ceil(Math.log(max(max) - min(min) + 1)/Math.log(2) * n * max(length)); + + return new RandomOrgCache( + new JsonObjectInputCallable() { + @Override + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return RandomOrgClient.this.sendRequest(this.input); + } + }, new JsonObjectInputCallable() { + @Override + public int[][] call() { + return RandomOrgClient.this.extractIntSequences(this.input); + } + }, + request, cacheSize, bulkN, n, maxRequestSize); + } + + /** + * Get a RandomOrgCache to obtain random integer sequences. The RandomOrgCache can be polled + * for new results conforming to the output format of the input request. RandomOrgCache + * type is same as expected return value. + * + * @param n how many random integers you need. Must be within the + * [1,1e4] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param replacement an array with n boolean values, each specifying whether the sequence + * identified by its index will be created with or without replacement. If true, the + * resulting numbers may contain duplicate values, otherwise the numbers will all be + * unique within each sequence (default boolean[n] with all values set to true). + * @param base an array with n integer values, each specifying the base that will be used to + * display the sequence identified by its index. Values allowed are 2, 8, 10 and 16 + * (default 10). For base 10, if you require an {@code RandomOrgCache} instead of + * a {@code RandomOrgCache}, please use the {@link #createIntegerSequenceCache( + * int n, int[] length, int[] min, int[] max, boolean[] replacement, int cacheSize) + * createIntegerSequenceCache} method without the base parameter. + * @param cacheSize number of result-sets for the cache to try to maintain + * at any given time (default 10, minimum 2). + * + * @return {@code RandomOrgCache} + */ + public RandomOrgCache createIntegerSequenceCache(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, int cacheSize) { + if (cacheSize < 2) { + cacheSize = 2; + } + + boolean[] defaultReplacement = new boolean[replacement.length]; + Arrays.fill(defaultReplacement, true); + + JsonObject request = new JsonObject(); + + int bulkN = 0; + + // If possible, make requests more efficient by bulk-ordering from the server. + // initially set at cache_size/2, but cache will auto-shrink bulk request size + // if requests can't be fulfilled. + if (Arrays.equals(replacement, defaultReplacement)) { + bulkN = cacheSize/2; + + request.addProperty("n", bulkN*n); + + length = adjust(length, bulkN*n); + min = adjust(min, bulkN*n); + max = adjust(max, bulkN*n); + replacement = adjust(replacement, bulkN*n); + base = adjust(base, bulkN*n); + + // not possible to make the request more efficient + } else { + request.addProperty("n", n); + } + + request.add("length", gson.toJsonTree(length)); + request.add("min", gson.toJsonTree(min)); + request.add("max", gson.toJsonTree(max)); + request.add("replacement", gson.toJsonTree(replacement)); + request.add("base", gson.toJsonTree(base)); + + // get the request object for use in all requests from this cache + request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); + + // max single request size, in bits, for adjusting bulk requests later + + + int maxRequestSize = (int) Math.ceil(Math.log(max(max) - min(min) + 1)/Math.log(2) * n * max(length)); + + return new RandomOrgCache( + new JsonObjectInputCallable() { + @Override + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return RandomOrgClient.this.sendRequest(this.input); + } + }, new JsonObjectInputCallable() { + @Override + public String[][] call() { + return RandomOrgClient.this.extractIntSequencesString(this.input); + } + }, + request, cacheSize, bulkN, n, maxRequestSize); + } + + /** + * Get a RandomOrgCache to obtain random decimal fractions. The RandomOrgCache can be polled + * for new results conforming to the output format of the input request. RandomOrgCache type + * is same as expected return value. + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createDecimalFractionCache(int n, int decimalPlaces) { - return this.createDecimalFractionCache(n, decimalPlaces, true, 20); - } - - /** Get a RandomOrgCache to obtain random decimal fractions. The RandomOrgCache can be polled for new results - ** conforming to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random decimal fractions you need. Must be within the [1,1e4] range. - ** @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. - ** @param replacement specifies whether the random numbers should be picked with replacement. - ** If True the resulting numbers may contain duplicate values, otherwise the numbers will all be unique (default True). - ** @param cacheSize number of result-sets for the cache to try to maintain at any given time (default 20, minimum 2). - ** - ** @return RandomOrgCache - **/ + return this.createDecimalFractionCache(n, decimalPlaces, DEFAULT_REPLACEMENT, DEFAULT_CACHE_SIZE); + } + + /** + * Get a RandomOrgCache to obtain random decimal fractions. The RandomOrgCache can be polled + * for new results conforming to the output format of the input request. RandomOrgCache type + * is same as expected return value. + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param cacheSize number of result-sets for the cache to try to maintain at any given time + * (default 20, minimum 2). + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createDecimalFractionCache(int n, int decimalPlaces, boolean replacement, int cacheSize) { if (cacheSize < 2) { cacheSize = 2; @@ -1149,7 +2686,8 @@ public RandomOrgCache createDecimalFractionCache(int n, int decimalPla int bulkN = 0; // If possible, make requests more efficient by bulk-ordering from the server. - // initially set at cache_size/2, but cache will auto-shrink bulk request size if requests can't be fulfilled. + // initially set at cache_size/2, but cache will auto-shrink bulk request size + // if requests can't be fulfilled. if (replacement) { bulkN = cacheSize/2; request.addProperty("n", bulkN*n); @@ -1168,7 +2706,15 @@ public RandomOrgCache createDecimalFractionCache(int n, int decimalPla return new RandomOrgCache( new JsonObjectInputCallable() { @Override - public JsonObject call() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, RandomOrgInsufficientBitsError, RandomOrgBadHTTPResponseException, RandomOrgRANDOMORGError, RandomOrgJSONRPCError, MalformedURLException, IOException { + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { return RandomOrgClient.this.sendRequest(this.input); } }, new JsonObjectInputCallable() { @@ -1180,31 +2726,40 @@ public double[] call() { request, cacheSize, bulkN, n, maxRequestSize); } - /** Get a RandomOrgCache to obtain random numbers. The RandomOrgCache can be polled for new results - ** conforming to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random numbers you need. Must be within the [1,1e4] range. - ** @param mean the distribution's mean. Must be within the [-1e6,1e6] range. - ** @param standardDeviation the distribution's standard deviation. Must be within the [-1e6,1e6] range. - ** @param significantDigits the number of significant digits to use. Must be within the [2,20] range. - ** - ** @return RandomOrgCache - **/ + /** + * Get a RandomOrgCache to obtain random numbers. The RandomOrgCache can be polled for new + * results conforming to the output format of the input request. RandomOrgCache type is same + * as expected return value. + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createGaussianCache(int n, double mean, double standardDeviation, int significantDigits) { - return this.createGaussianCache(n, mean, standardDeviation, significantDigits, 20); - } - - /** Get a RandomOrgCache to obtain random numbers. The RandomOrgCache can be polled for new results - ** conforming to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random numbers you need. Must be within the [1,1e4] range. - ** @param mean the distribution's mean. Must be within the [-1e6,1e6] range. - ** @param standardDeviation the distribution's standard deviation. Must be within the [-1e6,1e6] range. - ** @param significantDigits the number of significant digits to use. Must be within the [2,20] range. - ** @param cacheSize number of result-sets for the cache to try to maintain at any given time (default 20, minimum 2). - ** - ** @return RandomOrgCache - **/ + return this.createGaussianCache(n, mean, standardDeviation, significantDigits, DEFAULT_CACHE_SIZE); + } + + /** + * Get a RandomOrgCache to obtain random numbers. The RandomOrgCache can be polled for new + * results conforming to the output format of the input request. RandomOrgCache type is + * same as expected return value. + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * @param cacheSize number of result-sets for the cache to try to maintain at any given time + * (default 20, minimum 2). + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createGaussianCache(int n, double mean, double standardDeviation, int significantDigits, int cacheSize) { if (cacheSize < 2) { cacheSize = 2; @@ -1219,7 +2774,8 @@ public RandomOrgCache createGaussianCache(int n, double mean, double s int bulkN = 0; // make requests more efficient by bulk-ordering from the server. - // initially set at cache_size/2, but cache will auto-shrink bulk request size if requests can't be fulfilled. + // initially set at cache_size/2, but cache will auto-shrink bulk request size if + // requests can't be fulfilled. bulkN = cacheSize/2; request.addProperty("n", bulkN*n); @@ -1232,7 +2788,15 @@ public RandomOrgCache createGaussianCache(int n, double mean, double s return new RandomOrgCache( new JsonObjectInputCallable() { @Override - public JsonObject call() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, RandomOrgInsufficientBitsError, RandomOrgBadHTTPResponseException, RandomOrgRANDOMORGError, RandomOrgJSONRPCError, MalformedURLException, IOException { + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { return RandomOrgClient.this.sendRequest(this.input); } }, new JsonObjectInputCallable() { @@ -1244,33 +2808,41 @@ public double[] call() { request, cacheSize, bulkN, n, maxRequestSize); } - /** Get a RandomOrgCache to obtain random strings. The RandomOrgCache can be polled for new results - ** conforming to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random strings you need. Must be within the [1,1e4] range. - ** @param length the length of each string. Must be within the [1,20] range. All strings will be of the same length. - ** @param characters a string that contains the set of characters that are allowed to occur in the random strings. - ** The maximum number of characters is 80. - ** - ** @return RandomOrgCache - **/ + /** + * Get a RandomOrgCache to obtain random strings. The RandomOrgCache can be polled for new + * results conforming to the output format of the input request. RandomOrgCache type is + * same as expected return value. + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings will + * be of the same length. + * @param characters a string that contains the set of characters that are allowed to occur + * in the random strings. The maximum number of characters is 80. + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createStringCache(int n, int length, String characters) { - return this.createStringCache(n, length, characters, true, 20); - } - - /** Get a RandomOrgCache to obtain random strings. The RandomOrgCache can be polled for new results - ** conforming to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random strings you need. Must be within the [1,1e4] range. - ** @param length the length of each string. Must be within the [1,20] range. All strings will be of the same length. - ** @param characters a string that contains the set of characters that are allowed to occur in the random strings. - ** The maximum number of characters is 80. - ** @param replacement specifies whether the random strings should be picked with replacement. If True the resulting - ** list of strings may contain duplicates, otherwise the strings will all be unique (default True). - ** @param cacheSize number of result-sets for the cache to try to maintain at any given time (default 20, minimum 2). - ** - ** @return RandomOrgCache - **/ + return this.createStringCache(n, length, characters, DEFAULT_REPLACEMENT, DEFAULT_CACHE_SIZE); + } + + /** + * Get a RandomOrgCache to obtain random strings. The RandomOrgCache can be polled for new + * results conforming to the output format of the input request. RandomOrgCache type is + * same as expected return value. + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to occur + * in the random strings. The maximum number of characters is 80. + * @param replacement specifies whether the random strings should be picked with replacement. + * If true, the resulting list of strings may contain duplicates, otherwise the strings + * will all be unique (default true). + * @param cacheSize number of result-sets for the cache to try to maintain at any given time + * (default 20, minimum 2). + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createStringCache(int n, int length, String characters, boolean replacement, int cacheSize) { if (cacheSize < 2) { cacheSize = 2; @@ -1285,7 +2857,8 @@ public RandomOrgCache createStringCache(int n, int length, String char int bulkN = 0; // If possible, make requests more efficient by bulk-ordering from the server. - // initially set at cache_size/2, but cache will auto-shrink bulk request size if requests can't be fulfilled. + // initially set at cache_size/2, but cache will auto-shrink bulk request size + // if requests can't be fulfilled. if (replacement) { bulkN = cacheSize/2; request.addProperty("n", bulkN*n); @@ -1304,7 +2877,15 @@ public RandomOrgCache createStringCache(int n, int length, String char return new RandomOrgCache( new JsonObjectInputCallable() { @Override - public JsonObject call() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, RandomOrgInsufficientBitsError, RandomOrgBadHTTPResponseException, RandomOrgRANDOMORGError, RandomOrgJSONRPCError, MalformedURLException, IOException { + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { return RandomOrgClient.this.sendRequest(this.input); } }, new JsonObjectInputCallable() { @@ -1316,25 +2897,30 @@ public String[] call() { request, cacheSize, bulkN, n, maxRequestSize); } - /** Get a RandomOrgCache to obtain UUIDs. The RandomOrgCache can be polled for new results conforming to the - ** output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random UUIDs you need. Must be within the [1,1e3] range. - ** - ** @return RandomOrgCache - **/ + /** + * Get a RandomOrgCache to obtain UUIDs. The RandomOrgCache can be polled for new results + * conforming to the output format of the input request. RandomOrgCache type is same as + * expected return value. + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createUUIDCache(int n) { - return this.createUUIDCache(n, 10); + return this.createUUIDCache(n, DEFAULT_CACHE_SIZE_SMALL); } - /** Get a RandomOrgCache to obtain UUIDs. The RandomOrgCache can be polled for new results conforming to the - ** output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random UUIDs you need. Must be within the [1,1e3] range. - ** @param cacheSize number of result-sets for the cache to try to maintain at any given time (default 10, minimum 2). - ** - ** @return RandomOrgCache - **/ + /** + * Get a RandomOrgCache to obtain UUIDs. The RandomOrgCache can be polled for new results + * conforming to the output format of the input request. RandomOrgCache type is same as + * expected return value. + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * @param cacheSize number of result-sets for the cache to try to maintain at any given time + * (default 10, minimum 2). + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createUUIDCache(int n, int cacheSize) { if (cacheSize < 2) { cacheSize = 2; @@ -1345,7 +2931,8 @@ public RandomOrgCache createUUIDCache(int n, int cacheSize) { int bulkN = 0; // make requests more efficient by bulk-ordering from the server. - // initially set at cache_size/2, but cache will auto-shrink bulk request size if requests can't be fulfilled. + // initially set at cache_size/2, but cache will auto-shrink bulk request size if + // requests can't be fulfilled. bulkN = cacheSize/2; request.addProperty("n", bulkN*n); @@ -1358,7 +2945,15 @@ public RandomOrgCache createUUIDCache(int n, int cacheSize) { return new RandomOrgCache( new JsonObjectInputCallable() { @Override - public JsonObject call() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, RandomOrgInsufficientBitsError, RandomOrgBadHTTPResponseException, RandomOrgRANDOMORGError, RandomOrgJSONRPCError, MalformedURLException, IOException { + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { return RandomOrgClient.this.sendRequest(this.input); } }, new JsonObjectInputCallable() { @@ -1370,29 +2965,36 @@ public UUID[] call() { request, cacheSize, bulkN, n, maxRequestSize); } - /** Get a RandomOrgCache to obtain random blobs. The RandomOrgCache can be polled for new results conforming - ** to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random blobs you need. Must be within the [1,100] range. - ** @param size the size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8. - ** - ** @return RandomOrgCache - **/ + /** + * Get a RandomOrgCache to obtain random blobs. The RandomOrgCache can be polled for new + * results conforming to the output format of the input request. RandomOrgCache type is + * same as expected return value. + * + * @param n how many random blobs you need. Must be within the [1,20] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range + * and must be divisible by 8. + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createBlobCache(int n, int size) { - return this.createBlobCache(n, size, RandomOrgClient.BLOB_FORMAT_BASE64, 10); - } - - /** Get a RandomOrgCache to obtain random blobs. The RandomOrgCache can be polled for new results conforming - ** to the output format of the input request. RandomOrgCache type is same as expected return value. - ** - ** @param n how many random blobs you need. Must be within the [1,100] range. - ** @param size the size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8. - ** @param format specifies the format in which the blobs will be returned. Values allowed are - ** BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). - ** @param cacheSize number of result-sets for the cache to try to maintain at any given time (default 10, minimum 2). - ** - ** @return RandomOrgCache - **/ + return this.createBlobCache(n, size, BLOB_FORMAT_BASE64, DEFAULT_CACHE_SIZE_SMALL); + } + + /** + * Get a RandomOrgCache to obtain random blobs. The RandomOrgCache can be polled for new + * results conforming to the output format of the input request. RandomOrgCache type is + * same as expected return value. + * + * @param n how many random blobs you need. {@code n*(cacheSize/2)} must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range + * and must be divisible by 8. + * @param format specifies the format in which the blobs will be returned. Values allowed are + * BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). + * @param cacheSize number of result-sets for the cache to try to maintain at any given time + * (default 10, minimum 2). + * + * @return {@code RandomOrgCache} + */ public RandomOrgCache createBlobCache(int n, int size, String format, int cacheSize) { if (cacheSize < 2) { cacheSize = 2; @@ -1406,7 +3008,8 @@ public RandomOrgCache createBlobCache(int n, int size, String format, int bulkN = 0; // make requests more efficient by bulk-ordering from the server. - // initially set at cache_size/2, but cache will auto-shrink bulk request size if requests can't be fulfilled. + // initially set at cache_size/2, but cache will auto-shrink bulk request size + // if requests can't be fulfilled. bulkN = cacheSize/2; request.addProperty("n", bulkN*n); @@ -1419,7 +3022,15 @@ public RandomOrgCache createBlobCache(int n, int size, String format, return new RandomOrgCache( new JsonObjectInputCallable() { @Override - public JsonObject call() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, RandomOrgInsufficientBitsError, RandomOrgBadHTTPResponseException, RandomOrgRANDOMORGError, RandomOrgJSONRPCError, MalformedURLException, IOException { + public JsonObject call() throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { return RandomOrgClient.this.sendRequest(this.input); } }, new JsonObjectInputCallable() { @@ -1433,22 +3044,26 @@ public String[] call() { // Methods for accessing server usage statistics. - /** Return the (estimated) number of remaining API requests available to the client. If cached - ** usage info is older than ALLOWANCE_STATE_REFRESH_SECONDS fresh info is obtained from server. - ** If fresh info has to be obtained the following exceptions can be raised. - ** - ** @return number of requests remaining. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ + /** + * Return the (estimated) number of remaining API requests available to the client. If + * cached usage info is older than ALLOWANCE_STATE_REFRESH_SECONDS fresh info is obtained + * from server. If fresh info has to be obtained the following exceptions can be raised. + * + * @return number of requests remaining. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ public int getRequestsLeft() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1464,22 +3079,26 @@ public int getRequestsLeft() throws RandomOrgSendTimeoutException, return this.requestsLeft; } - /** Return the (estimated) number of remaining true random bits available to the client. If cached - ** usage info is older than ALLOWANCE_STATE_REFRESH_SECONDS fresh info is obtained from server. - ** If fresh info has to be obtained the following exceptions can be raised. - ** - ** @return number of bits remaining. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ + /** + * Return the (estimated) number of remaining true random bits available to the client. + * If cached usage info is older than ALLOWANCE_STATE_REFRESH_SECONDS fresh info is obtained + * from server. If fresh info has to be obtained the following exceptions can be raised. + * + * @return number of bits remaining. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ public int getBitsLeft() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1489,26 +3108,31 @@ public int getBitsLeft() throws RandomOrgSendTimeoutException, RandomOrgJSONRPCError, MalformedURLException, IOException { + if (this.bitsLeft < 0 || System.currentTimeMillis() > (this.lastResponseReceivedTime + RandomOrgClient.ALLOWANCE_STATE_REFRESH_SECONDS)) { this.getUsage(); } return this.bitsLeft; } - + // Server communications & helper functions. - /** Issue a getUsage request to update bits and requests left. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ + /** + * Issue a getUsage request to update bits and requests left. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ private void getUsage() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1517,8 +3141,7 @@ private void getUsage() throws RandomOrgSendTimeoutException, RandomOrgRANDOMORGError, RandomOrgJSONRPCError, MalformedURLException, - IOException { - + IOException { JsonObject request = new JsonObject(); request = this.generateKeyedRequest(request, GET_USAGE_METHOD); @@ -1526,15 +3149,15 @@ private void getUsage() throws RandomOrgSendTimeoutException, this.sendRequest(request); } - /** Add generic request parameters and API key to custom request. - ** - ** @param params custom parameters to generate request around. - ** @param method to send request to. - ** - ** @return fleshed out JSON request. - **/ - private JsonObject generateKeyedRequest(JsonObject params, String method) { - + /** + * Add generic request parameters and API key to custom request. + * + * @param params custom parameters to generate request around. + * @param method to send request to. + * + * @return fleshed out JSON request. + */ + private JsonObject generateKeyedRequest(JsonObject params, String method) { params.addProperty("apiKey", this.apiKey); JsonObject request = new JsonObject(); @@ -1547,15 +3170,15 @@ private JsonObject generateKeyedRequest(JsonObject params, String method) { return request; } - /** Add generic request parameters to custom request. - ** - ** @param params custom parameters to generate request around. - ** @param method to send request to. - ** - ** @return fleshed out JSON request. - **/ + /** + * Add generic request parameters to custom request. + * + * @param params custom parameters to generate request around. + * @param method to send request to. + * + * @return fleshed out JSON request. + */ private JsonObject generateRequest(JsonObject params, String method) { - JsonObject request = new JsonObject(); request.addProperty("jsonrpc", "2.0"); @@ -1566,14 +3189,14 @@ private JsonObject generateRequest(JsonObject params, String method) { return request; } - /** Extracts int[] from JSON response. - ** - ** @param response JSON from which to extract data. - ** - ** @return extracted int[]. - **/ - protected int[] extractInts(JsonObject response) { - + /** + * Extracts int[] from JSON response. + * + * @param response JSON from which to extract data. + * + * @return extracted int[]. + */ + protected int[] extractInts(JsonObject response) { JsonArray data = this.extractResponse(response); int[] randoms = new int[data.size()]; @@ -1584,14 +3207,50 @@ protected int[] extractInts(JsonObject response) { return randoms; } - /** Extracts double[] from JSON response. - ** - ** @param response JSON from which to extract data. - ** - ** @return extracted double[]. - **/ - protected double[] extractDoubles(JsonObject response) { + /** + * Extracts int[][] from JSON response. + * + * @param response JSON from which to extract data. + * + * @return extracted int[][]. + */ + protected int[][] extractIntSequences(JsonObject response) { + JsonArray data = this.extractResponse(response); + int[][] randoms = new int[data.size()][]; + + for (int i = 0; i < randoms.length; i++) { + randoms[i] = gson.fromJson(data.get(i), int[].class); + } + + return randoms; + } + + /** + * Extracts String[][] from JSON response. + * + * @param response JSON from which to extract data. + * + * @return extracted String[][]. + */ + protected String[][] extractIntSequencesString(JsonObject response) { + JsonArray data = this.extractResponse(response); + String[][] randoms = new String[data.size()][]; + for (int i = 0; i < randoms.length; i++) { + randoms[i] = gson.fromJson(data.get(i), String[].class); + } + + return randoms; + } + + /** + * Extracts double[] from JSON response. + * + * @param response JSON from which to extract data. + * + * @return extracted double[]. + */ + protected double[] extractDoubles(JsonObject response) { JsonArray data = this.extractResponse(response); double[] randoms = new double[data.size()]; @@ -1602,14 +3261,14 @@ protected double[] extractDoubles(JsonObject response) { return randoms; } - /** Extracts String[] from JSON response. - ** - ** @param response JSON from which to extract data. - ** - ** @return extracted String[]. - **/ - protected String[] extractStrings(JsonObject response) { - + /** + * Extracts String[] from JSON response. + * + * @param response JSON from which to extract data. + * + * @return extracted String[]. + */ + protected String[] extractStrings(JsonObject response) { JsonArray data = this.extractResponse(response); String[] randoms = new String[data.size()]; @@ -1620,14 +3279,14 @@ protected String[] extractStrings(JsonObject response) { return randoms; } - /** Extracts UUID[] from JSON response. - ** - ** @param response JSON from which to extract data. - ** - ** @return extracted UUID[]. - **/ - protected UUID[] extractUUIDs(JsonObject response) { - + /** + * Extracts UUID[] from JSON response. + * + * @param response JSON from which to extract data. + * + * @return extracted UUID[]. + */ + protected UUID[] extractUUIDs(JsonObject response) { JsonArray data = this.extractResponse(response); UUID[] randoms = new UUID[data.size()]; @@ -1638,23 +3297,25 @@ protected UUID[] extractUUIDs(JsonObject response) { return randoms; } - /** Gets random data as separate from response JSON. - ** - ** @param response JSON from which to extract data. - ** - ** @return JsonArray of random data. - **/ + /** + * Gets random data as separate from response JSON. + * + * @param response JSON from which to extract data. + * + * @return JsonArray of random data. + */ private JsonArray extractResponse(JsonObject response) { return response.get("result").getAsJsonObject().get("random").getAsJsonObject().get("data").getAsJsonArray(); } - /** Gets signing data from response JSON and add to result HashMap. - ** - ** @param response JSON from which to extract data. - ** @param result to add signing data to. - ** - ** @return the passed in result HasMap. - **/ + /** + * Gets signing data from response JSON and add to result HashMap. + * + * @param response JSON from which to extract data. + * @param result to add signing data to. + * + * @return the passed in result HashMap. + */ private HashMap extractSignedResponse(JsonObject response, HashMap result) { result.put("random", response.get("result").getAsJsonObject().get("random").getAsJsonObject()); result.put("signature", response.get("result").getAsJsonObject().get("signature").getAsString()); @@ -1662,33 +3323,37 @@ private HashMap extractSignedResponse(JsonObject response, HashM return result; } - /** Gets verification response as separate from response JSON. - ** - ** @param response JSON from which to extract verification response. - ** - ** @return verification success. - **/ + /** + * Gets verification response as separate from response JSON. + * + * @param response JSON from which to extract verification response. + * + * @return verification success. + */ private boolean extractVerificationResponse(JsonObject response) { - return response.get("result").getAsJsonObject().get("authenticity").getAsBoolean(); } - /** Send request as determined by serialized boolean. - ** - ** @param request JSON to send. - ** - ** @return JsonObject response. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ + /** + * Send request as determined by serialized boolean. + * + * @param request JSON to send. + * + * @return JsonObject response. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ protected JsonObject sendRequest(JsonObject request) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1702,31 +3367,37 @@ protected JsonObject sendRequest(JsonObject request) throws RandomOrgSendTimeout return this.serialized ? this.sendSerializedRequest(request) : this.sendUnserializedRequest(request); } - /** Immediate call to server. Networking is run on a separate thread as Android platform disallows networking on the main thread. - ** - ** @param request JSON to send. - ** - ** @return JsonObject response. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - private JsonObject sendUnserializedRequest(JsonObject request) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { + /** + * Immediate call to server. Networking is run on a separate thread as Android platform + * disallows networking on the main thread. + * + * @param request JSON to send. + * + * @return JsonObject response. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + private JsonObject sendUnserializedRequest(JsonObject request) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { // Send request immediately. UnserializedRunnable r = new UnserializedRunnable(request); @@ -1737,7 +3408,8 @@ private JsonObject sendUnserializedRequest(JsonObject request) throws RandomOrgS try { Thread.sleep(50); } catch (InterruptedException e) { - LOGGER.log(Level.INFO, "Client interrupted while waiting for server to return a response."); + LOGGER.log(Level.INFO, "Client interrupted while waiting for server to " + + "return a response."); } } @@ -1750,7 +3422,7 @@ private JsonObject sendUnserializedRequest(JsonObject request) throws RandomOrgS return (JsonObject) r.getData().get("response"); } - /** Runnable for unserialized network calls. **/ + /** Runnable for unserialized network calls. */ private class UnserializedRunnable implements Runnable { private JsonObject request; @@ -1762,7 +3434,7 @@ public UnserializedRunnable(JsonObject request) { this.request = request; } - /* @see java.lang.Runnable#run() */ + /** @see java.lang.Runnable#run() */ @Override public void run() { this.data = RandomOrgClient.this.sendRequestCore(this.request); @@ -1774,34 +3446,38 @@ public HashMap getData() { } } - /** Add request to queue to be executed by networking thread one-by-one. - ** Method blocks until this request receives a response or times out. - ** - ** @param request JSON to send. - ** - ** @return JsonObject response. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ - private JsonObject sendSerializedRequest(JsonObject request) throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { - - // Add request to the queue with it's own lock. + /** + * Add request to queue to be executed by networking thread one-by-one. Method blocks until + * this request receives a response or times out. + * + * @param request JSON to send. + * + * @return JsonObject response. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + private JsonObject sendSerializedRequest(JsonObject request) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + // Creating request to add to the queue with it's own lock. Object requestLock = new Object(); HashMap data = new HashMap(); @@ -1810,13 +3486,15 @@ private JsonObject sendSerializedRequest(JsonObject request) throws RandomOrgSen data.put("response", null); data.put("exception", null); - synchronized (this.serializedQueue) { - this.serializedQueue.offer(data); - this.serializedQueue.notify(); - } - // Wait on the lock for the specified blocking timeout. synchronized (requestLock) { + + // Adding request to the queue + synchronized (this.serializedQueue) { + this.serializedQueue.offer(data); + this.serializedQueue.notify(); + } + try { if (this.blockingTimeout == -1) { requestLock.wait(); @@ -1824,16 +3502,19 @@ private JsonObject sendSerializedRequest(JsonObject request) throws RandomOrgSen requestLock.wait(this.blockingTimeout); } } catch (InterruptedException e) { - LOGGER.log(Level.INFO, "Client interrupted while waiting for request to be sent."); + LOGGER.log(Level.INFO, "Client interrupted while waiting for request to " + + "be sent."); } - // Lock has now either been notified or timed out. Examine data to determine which and react accordingly. + // Lock has now either been notified or timed out. Examine data to determine + // which and react accordingly. // Request wasn't sent in time, cancel and raise exception. if (data.get("response") == null && data.get("exception") == null) { data.put("request", null); - throw new RandomOrgSendTimeoutException("The maximum allowed blocking time of " + this.blockingTimeout - + "millis has been exceeded while waiting for a synchronous request to send."); + throw new RandomOrgSendTimeoutException("The maximum allowed blocking time of " + + this.blockingTimeout + "millis has been exceeded while waiting " + + "for a synchronous request to send."); } // Exception on sending request. @@ -1847,20 +3528,19 @@ private JsonObject sendSerializedRequest(JsonObject request) throws RandomOrgSen } /** Thread to synchronously send requests in queue. */ - protected void threadedRequestSending() { - + protected void threadedRequestSending() { // Thread to execute queued requests. while (true) { HashMap request; - synchronized (this.serializedQueue) { // Block and wait for a request. if (this.serializedQueue.isEmpty()) { try { this.serializedQueue.wait(); } catch (InterruptedException e) { - LOGGER.log(Level.INFO, "Client thread interrupted while waiting for a request to send."); + LOGGER.log(Level.INFO, "Client thread interrupted while waiting " + + "for a request to send."); } } @@ -1891,20 +3571,24 @@ protected void threadedRequestSending() { } } - /** Throw specific Exception types. - ** - ** @param e exception to throw. - ** - ** @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request can be sent. - ** @throws RandomOrgKeyNotRunningError API key has been stopped. - ** @throws RandomOrgInsufficientRequestsError API key's server requests allowance has been exceeded. - ** @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - ** @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. - ** @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws IOException @see java.io.IOException - **/ + /** + * Throw specific Exception types. + * + * @param e exception to throw. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ private void throwException(Exception e) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1936,28 +3620,30 @@ private void throwException(Exception e) throws RandomOrgSendTimeoutException, } } - /** Core send request function. - ** - ** @param request JSON to send. - ** - ** @return info on request success/response in a HashMap with one or other of the following entries: - ** "exception" : Exception - exception thrown, possible exception types: - ** RandomOrgSendTimeoutException - ** RandomOrgKeyNotRunningError - ** RandomOrgInsufficientRequestsError - ** RandomOrgInsufficientBitsError - ** RandomOrgBadHTTPResponseException - ** RandomOrgRANDOMORGError - ** RandomOrgJSONRPCError - ** MalformedURLException - ** IOException - ** "response" : JsonObject - response - **/ + /** + * Core send request function. + * + * @param request JSON to send. + * + * @return info on request success/response in a HashMap with one or other of the following entries: + * "exception" : Exception - exception thrown, possible exception types: + * RandomOrgSendTimeoutException + * RandomOrgKeyNotRunningError + * RandomOrgInsufficientRequestsError + * RandomOrgInsufficientBitsError + * RandomOrgBadHTTPResponseException + * RandomOrgRANDOMORGError + * RandomOrgJSONRPCError + * MalformedURLException + * IOException + * "response" : JsonObject - response + */ protected HashMap sendRequestCore(JsonObject request) { HashMap ret = new HashMap(); - // If a back-off is set, no more requests can be issued until the required back-off time is up. + // If a back-off is set, no more requests can be issued until the required + // back-off time is up. if (this.backoff != -1) { // Time not yet up, throw exception. @@ -1978,17 +3664,20 @@ protected HashMap sendRequestCore(JsonObject request) { wait = this.advisoryDelay - (System.currentTimeMillis() - this.lastResponseReceivedTime); } - // Wait the specified delay if necessary and if wait time is not longer than the set blocking timeout. + // Wait the specified delay if necessary and if wait time is not longer than the + // set blocking timeout. if (wait > 0) { if (this.blockingTimeout != -1 && wait > this.blockingTimeout) { - ret.put("exception", new RandomOrgSendTimeoutException("The server advisory delay of " + wait + - "millis is greater than the defined maximum allowed blocking time of " + this.blockingTimeout + "millis.")); + ret.put("exception", new RandomOrgSendTimeoutException("The server advisory delay of " + + wait + "millis is greater than the defined maximum allowed " + + "blocking time of " + this.blockingTimeout + "millis.")); return ret; } try { Thread.sleep(wait); } catch (InterruptedException e) { - LOGGER.log(Level.INFO, "Client interrupted while waiting for server mandated blocking time."); + LOGGER.log(Level.INFO, "Client interrupted while waiting for server " + + "mandated blocking time."); } } @@ -2018,7 +3707,7 @@ protected HashMap sendRequestCore(JsonObject request) { String message = error.get("message").getAsString(); // RandomOrgAllowanceExceededError, API key not running, backoff until midnight UTC, - // from RANDOM.ORG Errors: https://api.random.org/json-rpc/1/error-codes + // from RANDOM.ORG Errors: https://api.random.org/json-rpc/2/error-codes if (code == 402) { Calendar date = new GregorianCalendar(); @@ -2033,21 +3722,27 @@ protected HashMap sendRequestCore(JsonObject request) { ret.put("exception", new RandomOrgInsufficientRequestsError(this.backoffError)); return ret; } else if (code == 401) { - ret.put("exception", new RandomOrgKeyNotRunningError("Error " + code + ": " + message)); + ret.put("exception", new RandomOrgKeyNotRunningError("Error " + code + + ": " + message)); return ret; } else if (code == 403) { - ret.put("exception", new RandomOrgInsufficientBitsError("Error " + code + ": " + message, this.bitsLeft)); + ret.put("exception", new RandomOrgInsufficientBitsError("Error " + code + + ": " + message, this.bitsLeft)); return ret; - // RandomOrgRANDOMORGError from RANDOM.ORG Errors: https://api.random.org/json-rpc/1/error-codes + // RandomOrgRANDOMORGError from RANDOM.ORG Errors: + // https://api.random.org/json-rpc/2/error-codes } else if (RandomOrgClient.randomOrgErrors.contains(code)) { - ret.put("exception", new RandomOrgRANDOMORGError("Error " + code + ": " + message)); + ret.put("exception", new RandomOrgRANDOMORGError("Error " + code + + ": " + message)); return ret; - // RandomOrgJSONRPCError from JSON-RPC Errors: https://api.random.org/json-rpc/1/error-codes + // RandomOrgJSONRPCError from JSON-RPC Errors: + // https://api.random.org/json-rpc/2/error-codes } else { - ret.put("exception", new RandomOrgJSONRPCError("Error " + code + ": " + message)); + ret.put("exception", new RandomOrgJSONRPCError("Error " + code + + ": " + message)); return ret; } } @@ -2076,19 +3771,22 @@ protected HashMap sendRequestCore(JsonObject request) { return ret; } - /** POST JSON to server and return JSON response. - ** - ** @param json request to post. - ** - ** @return JSON response. - ** - ** @throws IOException @see java.io.IOException - ** @throws MalformedURLException in the unlikely event something goes wrong with URL creation. @see java.net.MalformedURLException - ** @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. - **/ - private JsonObject post(JsonObject json) throws IOException, MalformedURLException, RandomOrgBadHTTPResponseException { - - HttpsURLConnection con = (HttpsURLConnection) new URL("https://api.random.org/json-rpc/1/invoke").openConnection(); + /** + * POST JSON to server and return JSON response. + * + * @param json request to post. + * + * @return JSON response. + * + * @throws IOException @see java.io.IOException + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + */ + private JsonObject post(JsonObject json) throws IOException, + MalformedURLException, + RandomOrgBadHTTPResponseException { + HttpsURLConnection con = (HttpsURLConnection) new URL("https://api.random.org/json-rpc/2/invoke").openConnection(); con.setConnectTimeout(this.httpTimeout); // headers @@ -2118,9 +3816,228 @@ private JsonObject post(JsonObject json) throws IOException, MalformedURLExcepti return new JsonParser().parse(response.toString()).getAsJsonObject(); + // Alternative to avoid the deprecation warnings when using Gson 2.8.6+: + // return JsonParser.parseString(response.toString()).getAsJsonObject(); + // ...or throw error } else { - throw new RandomOrgBadHTTPResponseException("Error " + responseCode + ": " + con.getResponseMessage()); + throw new RandomOrgBadHTTPResponseException("Error " + responseCode + ": " + + con.getResponseMessage()); + } + } + + /** Helper function for generateIntegers + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). + * + * @return JsonObject returned from the request + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + private JsonObject integerMethod(int n, int min, int max, boolean replacement, int base) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject request = new JsonObject(); + + request.addProperty("n", n); + request.addProperty("min", min); + request.addProperty("max", max); + request.addProperty("replacement", replacement); + request.addProperty("base", base); + + request = this.generateKeyedRequest(request, INTEGER_METHOD); + + return this.sendRequest(request); + } + + /** + * Helper function for generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * @param signed boolean representing whether the request uses Basic API (false) or signed + * API (true). + * + * @return JsonObject returned from the request + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + private JsonObject integerSequencesMethod(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData, boolean signed) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject request = new JsonObject(); + + request.addProperty("n", n); + request.addProperty("length", length); + request.addProperty("min", min); + request.addProperty("max", max); + request.addProperty("replacement", replacement); + request.addProperty("base", base); + + if (signed) { + request.add("userData", userData); + request = this.generateKeyedRequest(request, SIGNED_INTEGER_SEQUENCE_METHOD); + } else { + request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); + } + + return this.sendRequest(request); + } + + /** + * Helper function for generateIntegerSequences with array ([]) parameters + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * @param signed boolean representing whether the request uses Basic API (false) or signed + * API (true). + * + * @return JsonObject returned from the request + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + private JsonObject integerSequencesMethod(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData, boolean signed) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject request = new JsonObject(); + + request.addProperty("n", n); + request.add("length", gson.toJsonTree(length).getAsJsonArray()); + request.add("min", gson.toJsonTree(min).getAsJsonArray()); + request.add("max", gson.toJsonTree(max).getAsJsonArray()); + request.add("replacement", gson.toJsonTree(replacement).getAsJsonArray()); + request.add("base", gson.toJsonTree(base).getAsJsonArray()); + + if (signed) { + request.add("userData", userData); + request = this.generateKeyedRequest(request, SIGNED_INTEGER_SEQUENCE_METHOD); + } else { + request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); + } + + return this.sendRequest(request); + } + + /** Helper function for createIntegerSequenceCache with array ([]) parameters */ + private int min(int[] a) { + int[] min2 = Arrays.copyOf(a, a.length); + Arrays.sort(min2); + return min2[0]; + } + + /** Helper function for createIntegerSequenceCache with array ([]) parameters */ + private int max(int[] a) { + int[] max2 = Arrays.copyOf(a, a.length); + Arrays.sort(max2); + return max2[max2.length-1]; + } + + /** Helper function for createIntegerSequenceCache with array ([]) parameters */ + private int[] adjust(int[] a, int n) { + int[] adjusted = new int[n]; + for(int i = 1, k = 0; i <= n / a.length; i++) { + for (int j = 0; j < a.length; j++) { + adjusted[k++] = a[j]; + } + } + return adjusted; + } + + /** Helper function for createIntegerSequenceCache with array ([]) parameters */ + private boolean[] adjust(boolean[] a, int n) { + boolean[] adjusted = new boolean[n]; + for(int i = 1, k = 0; i <= n / a.length; i++) { + for (int j = 0; j < a.length; j++) { + adjusted[k++] = a[j]; + } } + return adjusted; } } \ No newline at end of file diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgBadHTTPResponseException.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgBadHTTPResponseException.java index a254bef..8abdafe 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgBadHTTPResponseException.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgBadHTTPResponseException.java @@ -1,14 +1,16 @@ package org.random.api.exception; -/** Exception raised by the RandomOrgClient class when the connection - ** doesn't return a HTTP 200 OK response. - **/ +/** + * Exception raised by the RandomOrgClient class when the connection + * doesn't return a HTTP 200 OK response. + */ public class RandomOrgBadHTTPResponseException extends RuntimeException { - /** Constructs a new exception with the specified detail message. - ** - ** @param message @see java.lang.Exception#Exception(java.lang.String) - **/ + /** + * Constructs a new exception with the specified detail message. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + */ public RandomOrgBadHTTPResponseException(String message) { super(message); } diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientBitsError.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientBitsError.java index bbd9a2f..faf453a 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientBitsError.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientBitsError.java @@ -1,29 +1,30 @@ package org.random.api.exception; -/** Exception raised by the RandomOrgClient class when its API key's - ** request has exceeded its remaining server bits allowance. If the - ** client is currently issuing large requests it may be possible to - ** succeed with smaller requests. Use the client's getBitsLeft() call - ** or the getBits() in this class to help determine if an alternative - ** request size is appropriate. - **/ +/** + * Exception raised by the RandomOrgClient class when its API key's + * request has exceeded its remaining server bits allowance. If the + * client is currently issuing large requests it may be possible to + * succeed with smaller requests. Use the client's getBitsLeft() call + * or the getBits() in this class to help determine if an alternative + * request size is appropriate. + */ public class RandomOrgInsufficientBitsError extends RuntimeException { private int bits = -1; - /** Constructs a new exception with the specified detail message. - ** - ** @param message @see java.lang.Exception#Exception(java.lang.String) - ** @param bits remaining just before error thrown - **/ + /** + * Constructs a new exception with the specified detail message. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + * @param bits remaining just before error thrown + */ public RandomOrgInsufficientBitsError(String message, int bits) { super(message); this.bits = bits; } - /** @return bits remaining just before error. - **/ + /** @return bits remaining just before error. */ public int getBits() { return this.bits; } diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientRequestsError.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientRequestsError.java index 6b5adfc..77d3001 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientRequestsError.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgInsufficientRequestsError.java @@ -1,17 +1,19 @@ package org.random.api.exception; -/** Exception raised by the RandomOrgClient class when its API key's - ** server requests allowance has been exceeded. This indicates that a - ** back-off until midnight UTC is in effect, before which no requests - ** will be sent by the client as no meaningful server responses will - ** be returned. - **/ +/** + * Exception raised by the RandomOrgClient class when its API key's + * server requests allowance has been exceeded. This indicates that a + * back-off until midnight UTC is in effect, before which no requests + * will be sent by the client as no meaningful server responses will + * be returned. + */ public class RandomOrgInsufficientRequestsError extends RuntimeException { - /** Constructs a new exception with the specified detail message. - ** - ** @param message @see java.lang.Exception#Exception(java.lang.String) - **/ + /** + * Constructs a new exception with the specified detail message. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + */ public RandomOrgInsufficientRequestsError(String message) { super(message); } diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java index 79147b6..176276f 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java @@ -1,16 +1,18 @@ package org.random.api.exception; -/** Exception raised by the RandomOrgClient class when the server - ** returns a JSON-RPC Error. - ** - ** @see https://api.random.org/json-rpc/1/error-codes - **/ +/** + * Exception raised by the RandomOrgClient class when the server + * returns a JSON-RPC Error. + * + * @see https://api.random.org/json-rpc/2/error-codes + */ public class RandomOrgJSONRPCError extends RuntimeException { - /** Constructs a new exception with the specified detail message. - ** - ** @param message @see java.lang.Exception#Exception(java.lang.String) - **/ + /** + * Constructs a new exception with the specified detail message. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + */ public RandomOrgJSONRPCError(String message) { super(message); } diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgKeyNotRunningError.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgKeyNotRunningError.java index 181a015..6c1d648 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgKeyNotRunningError.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgKeyNotRunningError.java @@ -1,15 +1,17 @@ package org.random.api.exception; -/** Exception raised by the RandomOrgClient class when its API key - ** has been stopped. Requests will not complete while API key is - ** in the stopped state. - **/ +/** + * Exception raised by the RandomOrgClient class when its API key + * has been stopped. Requests will not complete while API key is + * in the stopped state. + */ public class RandomOrgKeyNotRunningError extends RuntimeException { - /** Constructs a new exception with the specified detail message. - ** - ** @param message @see java.lang.Exception#Exception(java.lang.String) - **/ + /** + * Constructs a new exception with the specified detail message. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + */ public RandomOrgKeyNotRunningError(String message) { super(message); } diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java index 0d2c5eb..f464b2e 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java @@ -1,16 +1,18 @@ package org.random.api.exception; -/** Exception raised by the RandomOrgClient class when the server - ** returns a RANDOM.ORG Error. - ** - ** @see https://api.random.org/json-rpc/1/error-codes - **/ +/** + * Exception raised by the RandomOrgClient class when the server + * returns a RANDOM.ORG Error. + * + * @see https://api.random.org/json-rpc/2/error-codes + */ public class RandomOrgRANDOMORGError extends RuntimeException { - /** Constructs a new exception with the specified detail message. - ** - ** @param message @see java.lang.Exception#Exception(java.lang.String) - **/ + /** + * Constructs a new exception with the specified detail message. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + */ public RandomOrgRANDOMORGError(String message) { super(message); } diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgSendTimeoutException.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgSendTimeoutException.java index cfd78b8..03e7b4b 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgSendTimeoutException.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgSendTimeoutException.java @@ -1,14 +1,16 @@ package org.random.api.exception; -/** Exception raised by the RandomOrgClient class when its set - ** blocking timeout is exceeded before the request can be sent. - **/ +/** + * Exception raised by the RandomOrgClient class when its set + * blocking timeout is exceeded before the request can be sent. + */ public class RandomOrgSendTimeoutException extends RuntimeException { - /** Constructs a new exception with the specified detail message. - ** - ** @param message @see java.lang.Exception#Exception(java.lang.String) - **/ + /** + * Constructs a new exception with the specified detail message. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + */ public RandomOrgSendTimeoutException(String message) { super(message); } diff --git a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java index 33027de..291d101 100644 --- a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java +++ b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java @@ -1,78 +1,93 @@ package org.random.test; -import static org.junit.Assert.assertNotNull; -import static org.junit.Assert.assertTrue; - +import java.util.Arrays; import java.util.HashMap; import java.util.NoSuchElementException; import java.util.UUID; -import org.junit.Assert; import org.junit.BeforeClass; +import org.junit.Rule; import org.junit.Test; +import org.junit.rules.ErrorCollector; import org.random.api.RandomOrgCache; import org.random.api.RandomOrgClient; import org.random.api.exception.RandomOrgRANDOMORGError; +import com.google.gson.Gson; import com.google.gson.JsonObject; -/** A set of tests for RandomOrgClient.java - ** @author Anders Haahr - **/ +import static org.hamcrest.Matchers.*; + +/** + * A set of tests for RandomOrgClient.java + */ public class RandomOrgClientBasicTest { - private static RandomOrgClient roc, roc2; + @Rule + public ErrorCollector collector = new ErrorCollector(); + + private static RandomOrgClient[] rocs = new RandomOrgClient[2]; private static final String API_KEY_1 = "YOUR_API_KEY_HERE"; private static final String API_KEY_2 = "YOUR_API_KEY_HERE"; private static final int BIT_QUOTA = 1000000; + private static final int[] LENGTH = {3, 4, 5, 6}; + private static final int[] MIN = {0, 10, 20, 30}; + private static final int[] MAX = {40, 50, 60, 70}; + private static final boolean[] REPLACEMENT = {false, true, false, true}; + private static final int[] BASE = {2, 8, 10, 16}; + + private static JsonObject userData = new JsonObject(); + @BeforeClass public static void testSetup() { - roc = RandomOrgClient.getRandomOrgClient(API_KEY_1, 3000, 120000, false); - roc2 = RandomOrgClient.getRandomOrgClient(API_KEY_2); + rocs[0] = RandomOrgClient.getRandomOrgClient(API_KEY_1, 5000, 120000, false); + rocs[1] = RandomOrgClient.getRandomOrgClient(API_KEY_2); + + userData.addProperty("Test", "Text"); + userData.addProperty("Test2", "Text2"); } @Test public void testInfo() { - try { - assertTrue(roc.getBitsLeft() >= 0); - assertTrue(roc.getRequestsLeft() >= 0); - - assertTrue(roc2.getBitsLeft() >= 0); - assertTrue(roc2.getRequestsLeft() >= 0); - - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(client(i), roc.getBitsLeft(), greaterThanOrEqualTo(0)); + collector.checkThat(client(i), roc.getRequestsLeft(), greaterThanOrEqualTo(0)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } + @Test public void testAPIKeyDuplication() { RandomOrgClient dupe = RandomOrgClient.getRandomOrgClient(API_KEY_1); - assertTrue(!roc.equals(roc2)); - assertTrue(roc.equals(dupe)); + collector.checkThat("RandomOrgClient roc1 should not be the same as " + + "RandomOrgClient roc2", rocs[0].equals(rocs[1]), equalTo(false)); + collector.checkThat("RandomOrgClient roc1 and RandomOrgClient dupe " + + "should be the same", rocs[0].equals(dupe), equalTo(true)); } + @Test - public void testPositiveGetBitsLeft_1(){ - try { - int bitsLeft = roc.getBitsLeft(); - assertTrue(0 <= bitsLeft && bitsLeft <= BIT_QUOTA); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - } - - @Test - public void testPositiveGetBitsLeft_2(){ - try { - int bitsLeft = roc2.getBitsLeft(); - assertTrue(0 <= bitsLeft && bitsLeft <= BIT_QUOTA); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGetBitsLeft(){ + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + int bitsLeft = roc.getBitsLeft(); + collector.checkThat(client(i), bitsLeft, greaterThanOrEqualTo(0)); + collector.checkThat(client(i) + i, bitsLeft, lessThanOrEqualTo(BIT_QUOTA)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @@ -80,81 +95,81 @@ public void testPositiveGetBitsLeft_2(){ @Test public void testNegativeErrorMessage202(){ - try{ - roc.generateIntegers(100000, 0, 10); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); - } - try{ - roc2.generateIntegers(100000, 0, 10); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + roc.generateIntegers(100000, 0, 10); + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; } } - + @Test public void testNegativeErrorMessage203(){ - try{ - roc.generateIntegers(10, 0, 1000000001); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + roc.generateIntegerSequences(3, LENGTH, MIN, MAX); + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; } - try{ - roc2.generateIntegers(10, 0, 1000000001); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); + } + + @Test + public void testNegativeErrorMessage204(){ + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + roc.generateIntegerSequences(4, new int[] {1}, MIN, MAX); + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; } } @Test public void testNegativeErrorMessage300(){ - try{ - roc.generateIntegers(10, 10, 0); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); - } - try{ - roc2.generateIntegers(10, 10, 0); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + roc.generateIntegers(10, 10, 0); + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; } } - + @Test public void testNegativeErrorMessage301(){ - try{ - roc.generateIntegers(20, 0, 10, false); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); - } - try{ - roc2.generateIntegers(20, 0, 10, false); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); - } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); - } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + roc.generateIntegers(20, 0, 10, false); + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; } } @@ -163,11 +178,11 @@ public void testNegativeErrorMessage400(){ try{ RandomOrgClient rpc2 = RandomOrgClient.getRandomOrgClient("ffffffff-ffff-ffff-ffff-ffffffffffff"); rpc2.generateIntegers(1, 0, 1); - Assert.fail("should have thrown RandomOrgRANDOMORGError"); + collector.addError(new Error(errorMessage())); } catch(RandomOrgRANDOMORGError e) { System.out.println(e.getMessage()); } catch (Exception e) { - Assert.fail("should have thrown RandomOrgRANDOMORGError, instead threw " + e.getClass().getName()); + collector.addError(new Error(errorMessage(e))); } } @@ -175,541 +190,851 @@ public void testNegativeErrorMessage400(){ @Test public void testPositiveGenerateInteger_1(){ - try { - assertNotNull(roc.generateIntegers(10, 0, 10)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - assertNotNull(roc2.generateIntegers(10, 0, 10)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + // Testing generateIntgers(int n, in min, int max) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegers(10, 0, 10), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } - + @Test public void testPositiveGenerateInteger_2(){ - try { - assertNotNull(roc.generateIntegers(10, 0, 10, false)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + // Testing generateIntgers(int n, in min, int max, boolean replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegers(10, 0, 10, false), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } - try { - assertNotNull(roc2.generateIntegers(10, 0, 10, false)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + } + + @Test + public void testPositiveGenerateInteger_3(){ + // Testing generateIntgers(int n, in min, int max, boolean replacement, int base) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegers(10, 0, 10, false, 16), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_1(){ + // Testing generateIntegerSequences(int n, int length, int min, int max) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegerSequences(3, 5, 0, 10), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_2(){ + // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegerSequences(3, 5, 0, 10, false), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_3(){ + // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement, int base) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegerSequences(3, 5, 0, 10, false, 16), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_4(){ + // Testing generateIntegerSequences(int n, int[] length, int[] min, int[] max) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegerSequences(4, LENGTH, MIN, MAX), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_5(){ + // Testing generateIntegerSequences(int n, int[] length, int[] min, + // int[] max, boolean[] replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_6(){ + // Testing generateIntegerSequences(int n, int[] length, int[] min, + // int[] max, boolean[] replacement, int[] base) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, BASE), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test public void testPositiveGenerateDecimalFractions_1(){ - try { - assertNotNull(roc.generateDecimalFractions(10, 5)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - assertNotNull(roc2.generateDecimalFractions(10, 5)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + // Testing generateDecimalFractions(int n, int decimalPlaces) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateDecimalFractions(10, 5), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i ++; } } @Test public void testPositiveGenerateDecimalFractions_2(){ - try { - assertNotNull(roc.generateDecimalFractions(10, 5, false)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + // Testing generateDecimalFractions(int n, int decimalPlaces, boolean replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateDecimalFractions(10, 5, false), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } - try { - assertNotNull(roc2.generateDecimalFractions(10, 5, false)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + } + + @Test + public void testPositiveGenerateGaussians(){ + // Testing generateGaussians(int n, double mean, double standardDeviation, + // double significantDigits) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateGaussians(10, 3.41d, 2.1d, 4), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test - public void testPositiveGenerateGaussians(){ - try { - assertNotNull(roc.generateGaussians(10, 3.41d, 2.1d, 4)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateStrings_1(){ + // Testing generateStrings(int n, int length, String characters) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateStrings(10, 5, "abcd"), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } - try { - assertNotNull(roc2.generateGaussians(10, 3.41d, 2.1d, 4)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + } + + @Test + public void testPositiveGenerateStrings_2(){ + // Testing generateStrings(int n, int length, String characters, + // boolean replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateStrings(10, 5, "abcd", false), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateUUIDs(){ + // Testing generateUUIDs(int n) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateUUIDs(10), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test - public void testPositiveGenerateStrings_1(){ - try { - assertNotNull(roc.generateStrings(10, 5, "abcd")); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateBlobs_1(){ + // Testing generateBlobs(int n, int size) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateBlobs(10, 16), notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } - try { - assertNotNull(roc2.generateStrings(10, 5, "abcd")); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + } + + @Test + public void testPositiveGenerateBlobs_2(){ + // Testing generateBlobs(int n, int size, String format) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + collector.checkThat(roc.generateBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX), + notNullValue()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } + // Test Functions (Signed) + @Test - public void testPositiveGenerateStrings_2(){ - try { - assertNotNull(roc.generateStrings(10, 5, "abcd", false)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedInteger_1() { + // Testing generateSignedStrings(int n, int min, int max) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegers(10, 0, 10); + + signedValueTester(roc, i, o, int[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } - try { - assertNotNull(roc2.generateStrings(10, 5, "abcd", false)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + } + + @Test + public void testPositiveGenerateSignedInteger_2(){ + // Testing generateSignedStrings(int n, int min, int max, boolean replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegers(10, 0, 10, false); + + signedValueTester(roc, i, o, int[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedInteger_3(){ + // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, + // int base, JsonObject userData) -- decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 10, userData); + + signedValueTester(roc, i, o, int[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedInteger_4(){ + // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, + // int base, JsonObject userData) -- non-decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 16, userData); + + signedValueTester(roc, i, o, String[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_1(){ + // Testing generateSignedIntegerSequences(int n, int length, int min, int max) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10); + + signedValueTester(roc, i, o, int[][].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_2(){ + // Testing generateSignedIntegerSequences(int n, int length, int min, int max, + // boolean replacement, int base, JsonObject userData) + // -- decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 10, userData); + + signedValueTester(roc, i, o, int[][].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_3(){ + // Testing generateSignedIntegerSequences(int n, int length, int min, int max, + // boolean replacement, int base, JsonObject userData) + // -- non-decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 16, userData); + + signedValueTester(roc, i, o, String[][].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_4(){ + // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX); + + signedValueTester(roc, i, o, int[][].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_5(){ + // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, JsonObject userData) + // -- decimal + int[] decimalBase = {10, 10, 10, 10}; + int i = 1; + + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, decimalBase, userData); + + signedValueTester(roc, i, o, int[][].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_6(){ + // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, JsonObject userData) + // -- non-decimal + int i = 1; + + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, BASE, userData); + + signedValueTester(roc, i, o, String[][].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedDecimalFractions_1(){ + // Testing generateSignedDecimalFractions(int n, int decimalPlaces) + int i = 1; + + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedDecimalFractions(10, 5); + + signedValueTester(roc, i, o, double[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test - public void testPositiveGenerateUUIDs(){ - try { - assertNotNull(roc.generateUUIDs(10)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedDecimalFractions_2(){ + // Testing generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedDecimalFractions(10, 5, false); + + signedValueTester(roc, i, o, double[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } - try { - assertNotNull(roc2.generateUUIDs(10)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + } + + @Test + public void testPositiveGenerateSignedDecimalFractions_3(){ + // Testing generateSignedDecimalFractions(int n, int decimalPlaces, + // boolean replacement, JsonObject userData) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedDecimalFractions(10, 5, false, userData); + + signedValueTester(roc, i, o, double[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test - public void testPositiveGenerateBlobs_1(){ - try { - assertNotNull(roc.generateBlobs(10, 16)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedGaussians_1(){ + // Testing generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4); + + signedValueTester(roc, i, o, double[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } - try { - assertNotNull(roc2.generateBlobs(10, 16)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + } + + @Test + public void testPositiveGenerateSignedGaussians_2(){ + // Testing generateSignedGaussians(int n, double mean, double standardDeviation, + // int significantDigits, JsonObject userData) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4, userData); + + signedValueTester(roc, i, o, double[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedStrings_1(){ + // Testing generateSignedStrings(int n, int length, String characters) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedStrings(10, 5, "abcd"); + + signedValueTester(roc, i, o, String[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedStrings_2(){ + // Testing generateSignedStrings(int n, int length, String characters, boolean replacement) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedStrings(10, 5, "abcd", false); + + signedValueTester(roc, i, o, String[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + public void testPositiveGenerateSignedStrings_3(){ + // Testing generateSignedStrings(int n, int length, String characters, + // boolean replacement, JsonObject userData) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedStrings(10, 5, "abcd", false, userData); + + signedValueTester(roc, i, o, String[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test - public void testPositiveGenerateBlobs_2(){ - try { - assertNotNull(roc.generateBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - assertNotNull(roc2.generateBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX)); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedUUIDs_1(){ + // Testing generateSignedUUIDs(int n) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedUUIDs(10); + + signedValueTester(roc, i, o, UUID[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } - - // Test Functions (Signed) @Test - public void testPositiveGenerateSignedInteger_1(){ - try { - HashMap o = roc.generateSignedIntegers(10, 0, 10); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(int[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - HashMap o = roc2.generateSignedIntegers(10, 0, 10); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(int[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedUUIDs_2(){ + // Testing generateSignedUUIDs(int n, JsonObject userData) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedUUIDs(10, userData); + + signedValueTester(roc, i, o, UUID[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test - public void testPositiveGenerateSignedInteger_2(){ - try { - HashMap o = roc.generateSignedIntegers(10, 0, 10, false); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(int[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - HashMap o = roc2.generateSignedIntegers(10, 0, 10, false); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(int[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedBlobs_1(){ + // Testing generateSignedBlobs(int n, int size) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedBlobs(10, 16); + + signedValueTester(roc, i, o, String[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } @Test - public void testPositiveGenerateSignedDecimalFractions_1(){ - try { - HashMap o = roc.generateSignedDecimalFractions(10, 5); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(double[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - HashMap o = roc2.generateSignedDecimalFractions(10, 5); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(double[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedBlobs_2(){ + // Testing generateSignedBlobs(int n, int size, String format) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX); + + signedValueTester(roc, i, o, String[].class); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } - + @Test - public void testPositiveGenerateSignedDecimalFractions_2(){ - try { - HashMap o = roc.generateSignedDecimalFractions(10, 5, false); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(double[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - HashMap o = roc2.generateSignedDecimalFractions(10, 5, false); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(double[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testPositiveGenerateSignedBlobs_3(){ + // Testing generateSignedBlobs(int n, int size, String format, JsonObject userData) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, userData); + + signedValueTester(roc, i, o, String[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } - + + // Test additional functions + @Test - public void testPositiveGenerateSignedGaussians(){ - try { - HashMap o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(double[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } - try { - HashMap o = roc2.generateSignedGaussians(10, 3.41d, 2.1d, 4); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(double[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + public void testGetResult(){ + // Testing getResult(int serialNumber) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegers(10, 0, 10); + HashMap o2 = roc.getResult(((JsonObject)o.get("random")).get("serialNumber").getAsInt()); + + JsonObject data = ((JsonObject)o2.get("random")).getAsJsonObject(); + int[] response = new Gson().fromJson(data.get("data"), int[].class); + + collector.checkThat(Arrays.equals((int[])o.get("data"), response), equalTo(true)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; } } + // Test Functions (Cache) + @Test - public void testPositiveGenerateSignedStrings_1(){ + public void testIntegerCache_1(){ + // Testing createIntegerCache(int n, int min, int max) + RandomOrgCache c = rocs[0].createIntegerCache(5, 0, 10); + c.stop(); + try { - HashMap o = roc.generateSignedStrings(10, 5, "abcd"); - - assertNotNull(o); + c.get(); + collector.addError(new Error("should have thrown NoSuchElementException")); + } catch (NoSuchElementException e) {} - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); + collector.checkThat(c.isPaused(), equalTo(true)); + c.resume(); - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); + int[] got = null; - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + // Testing RandomOrgCache function get() + while (got == null) { + try { + got = c.get(); + } catch (NoSuchElementException e) { + try { + Thread.sleep(50); + } catch (InterruptedException e1) { + collector.addError(new Error("shouldn't have been interrupted!")); + } + } } - try { - HashMap o = roc2.generateSignedStrings(10, 5, "abcd"); - assertNotNull(o); + collector.checkThat(got, notNullValue()); - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); + got = null; - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); + // Testing RandomOrgCache info functions + collector.checkThat(c.getCachedValues(), greaterThan(0)); + collector.checkThat((int)c.getUsedBits(), greaterThan(0)); + collector.checkThat((int)c.getUsedRequests(), greaterThan(0)); - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + // Testing RandomOrgCache function getOrWait() + while (got == null) { + try { + got = c.getOrWait(); + } catch (NoSuchElementException e) { + try { + Thread.sleep(50); + } catch (InterruptedException e1) { + collector.addError(new Error("shouldn't have been interrupted!")); + } + } catch (Exception e) { + collector.addError(new Error("should have returned a value")); + } } } - + @Test - public void testPositiveGenerateSignedStrings_2(){ + public void testIntegerCache_2(){ + // Testing createIntegerCache(int n, int min, int max, boolean replacement, + // int base, int cacheSize) + RandomOrgCache c = rocs[0].createIntegerCache(5, 50, 100, false, 16, 5); + c.stop(); + try { - HashMap o = roc.generateSignedStrings(10, 5, "abcd", false); - - assertNotNull(o); + c.get(); + collector.addError(new Error("should have thrown NoSuchElementException")); + } catch (NoSuchElementException e) {} - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); + collector.checkThat(c.isPaused(), equalTo(true)); + c.resume(); - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); + String[] got = null; - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + // Testing RandomOrgCache function get() + while (got == null) { + try { + got = c.get(); + } catch (NoSuchElementException e) { + try { + Thread.sleep(50); + } catch (InterruptedException e1) { + collector.addError(new Error("shouldn't have been interrupted!")); + } + } } - try { - HashMap o = roc2.generateSignedStrings(10, 5, "abcd", false); - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } + collector.checkThat(got, notNullValue()); } - + @Test - public void testPositiveGenerateSignedUUIDs(){ + public void testIntegerSequenceCache_1(){ + // Testing createIntegerSequenceCache(int n, int length int min, int max) + RandomOrgCache c = rocs[0].createIntegerSequenceCache(2, 5, 0, 10); + c.stop(); + try { - HashMap o = roc.generateSignedUUIDs(10); - - assertNotNull(o); + c.get(); + collector.addError(new Error("should have thrown NoSuchElementException")); + } catch (NoSuchElementException e) {} - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); + c.resume(); - assertTrue(o.get("data").getClass().equals(UUID[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); + int[][] got = null; - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + while (got == null) { + try { + got = c.get(); + } catch (NoSuchElementException e) { + try { + Thread.sleep(50); + } catch (InterruptedException e1) { + collector.addError(new Error("shouldn't have been interrupted!")); + } + } } - try { - HashMap o = roc2.generateSignedUUIDs(10); - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(UUID[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } + collector.checkThat(got, notNullValue()); } - + @Test - public void testPositiveGenerateSignedBlobs_1(){ + public void testIntegerSequenceCache_2(){ + // Testing createIntegerSequenceCache(int n, int length int min, int max, + // boolean replacement, int base, int cacheSize) + RandomOrgCache c = rocs[0].createIntegerSequenceCache(2, 5, 0, 10, false, 16, 3); + c.stop(); + try { - HashMap o = roc.generateSignedBlobs(10, 16); - - assertNotNull(o); + c.get(); + collector.addError(new Error("should have thrown NoSuchElementException")); + } catch (NoSuchElementException e) {} - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); + c.resume(); - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); + String[][] got = null; - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + while (got == null) { + try { + got = c.get(); + } catch (NoSuchElementException e) { + try { + Thread.sleep(50); + } catch (InterruptedException e1) { + collector.addError(new Error("shouldn't have been interrupted!")); + } + } } - try { - HashMap o = roc2.generateSignedBlobs(10, 16); - - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } + collector.checkThat(got, notNullValue()); } @Test - public void testPositiveGenerateSignedBlobs_2(){ + public void testIntegerSequenceCache_3(){ + // Testing createIntegerSequenceCache(int n, int[] length, int[] min, int[] max) + RandomOrgCache c = rocs[0].createIntegerSequenceCache(4, LENGTH, MIN, MAX); + c.stop(); + try { - HashMap o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX); - - assertNotNull(o); + c.get(); + collector.addError(new Error("should have thrown NoSuchElementException")); + } catch (NoSuchElementException e) {} - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); + c.resume(); - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); + int[][] got = null; - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + while (got == null) { + try { + got = c.get(); + } catch (NoSuchElementException e) { + try { + Thread.sleep(50); + } catch (InterruptedException e1) { + collector.addError(new Error("shouldn't have been interrupted!")); + } + } } - try { - HashMap o = roc2.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX); - assertNotNull(o); - - assertTrue(o.containsKey("data")); - assertTrue(o.containsKey("random")); - assertTrue(o.containsKey("signature")); - - assertTrue(o.get("data").getClass().equals(String[].class)); - assertTrue(o.get("random").getClass().equals(JsonObject.class)); - assertTrue(o.get("signature").getClass().equals(String.class)); - - assertTrue(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature"))); - } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); - } + collector.checkThat(got, notNullValue()); } - - // Test Functions (Cache) @Test - public void testIntegerCache(){ - RandomOrgCache c = roc.createIntegerCache(5, 0, 10); + public void testIntegerSequenceCache_4(){ + // Testing createIntegerSequenceCache(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, int cacheSize) + boolean[] replacement = {true, true, true, true}; + RandomOrgCache c = rocs[0].createIntegerSequenceCache(4, LENGTH, MIN, MAX, replacement, BASE, 10); c.stop(); try { c.get(); - Assert.fail("should have thrown NoSuchElementException"); + collector.addError(new Error("should have thrown NoSuchElementException")); } catch (NoSuchElementException e) {} c.resume(); - int[] got = null; + String[][] got = null; while (got == null) { try { @@ -718,22 +1043,27 @@ public void testIntegerCache(){ try { Thread.sleep(50); } catch (InterruptedException e1) { - Assert.fail("shouldn't have been interrupted!"); + collector.addError(new Error("shouldn't have been interrupted!")); } } } - assertNotNull(got); + for (int i = 0; i < got.length; i++) { + collector.checkThat(got[i].length == LENGTH[i], equalTo(true)); + } + + collector.checkThat(got, notNullValue()); } - + @Test public void testDecimalFractionCache(){ - RandomOrgCache c = roc2.createDecimalFractionCache(1, 5); + // Testing createDecimalFractionCache(int n, int decimalPlaces) + RandomOrgCache c = rocs[1].createDecimalFractionCache(1, 5); c.stop(); try { c.get(); - Assert.fail("should have thrown NoSuchElementException"); + collector.addError(new Error("should have thrown NoSuchElementException")); } catch (NoSuchElementException e) {} c.resume(); @@ -747,22 +1077,24 @@ public void testDecimalFractionCache(){ try { Thread.sleep(50); } catch (InterruptedException e1) { - Assert.fail("shouldn't have been interrupted!"); + collector.addError(new Error("shouldn't have been interrupted!")); } } } - assertNotNull(got); + collector.checkThat(got, notNullValue()); } @Test public void testGaussianCache(){ - RandomOrgCache c = roc.createGaussianCache(10, 3.41d, 2.1d, 4); + // Testing createGaussianCache(int n, double mean, double standardDeviation, + // int significantDigits) + RandomOrgCache c = rocs[0].createGaussianCache(10, 3.41d, 2.1d, 4); c.stop(); try { c.get(); - Assert.fail("should have thrown NoSuchElementException"); + collector.addError(new Error("should have thrown NoSuchElementException")); } catch (NoSuchElementException e) {} c.resume(); @@ -776,22 +1108,23 @@ public void testGaussianCache(){ try { Thread.sleep(50); } catch (InterruptedException e1) { - Assert.fail("shouldn't have been interrupted!"); + collector.addError(new Error("shouldn't have been interrupted!")); } } } - assertNotNull(got); + collector.checkThat(got, notNullValue()); } @Test public void testStringCache(){ - RandomOrgCache c = roc2.createStringCache(5, 5, "abcds"); + // Testing createStringCache(int n, int length, String characters) + RandomOrgCache c = rocs[1].createStringCache(5, 5, "abcds"); c.stop(); try { c.get(); - Assert.fail("should have thrown NoSuchElementException"); + collector.addError(new Error("should have thrown NoSuchElementException")); } catch (NoSuchElementException e) {} c.resume(); @@ -805,22 +1138,23 @@ public void testStringCache(){ try { Thread.sleep(50); } catch (InterruptedException e1) { - Assert.fail("shouldn't have been interrupted!"); + collector.addError(new Error("shouldn't have been interrupted!")); } } } - assertNotNull(got); + collector.checkThat(got, notNullValue()); } @Test public void testUUIDCache(){ - RandomOrgCache c = roc.createUUIDCache(5); + // Testing createUUIDCache(int n) + RandomOrgCache c = rocs[0].createUUIDCache(5); c.stop(); try { c.get(); - Assert.fail("should have thrown NoSuchElementException"); + collector.addError(new Error("should have thrown NoSuchElementException")); } catch (NoSuchElementException e) {} c.resume(); @@ -834,22 +1168,23 @@ public void testUUIDCache(){ try { Thread.sleep(50); } catch (InterruptedException e1) { - Assert.fail("shouldn't have been interrupted!"); + collector.addError(new Error("shouldn't have been interrupted!")); } } } - assertNotNull(got); + collector.checkThat(got, notNullValue()); } @Test public void testBlobCache(){ - RandomOrgCache c = roc2.createBlobCache(5, 8); + // Testing createBlobCache(int n, int size) + RandomOrgCache c = rocs[1].createBlobCache(5, 8); c.stop(); try { c.get(); - Assert.fail("should have thrown NoSuchElementException"); + collector.addError(new Error("should have thrown NoSuchElementException")); } catch (NoSuchElementException e) {} c.resume(); @@ -863,11 +1198,100 @@ public void testBlobCache(){ try { Thread.sleep(50); } catch (InterruptedException e1) { - Assert.fail("shouldn't have been interrupted!"); + collector.addError(new Error("shouldn't have been interrupted!")); } } } - assertNotNull(got); + collector.checkThat(got, notNullValue()); + } + + // Error message and helper functions + + private String client(int i) { + return "RandomOrgClient roc" + i + " "; + } + + private String errorMessage() { + return errorMessage(-1); + } + + private String errorMessage(int i) { + return errorMessage(i, null); + } + + private String errorMessage(Exception e) { + return errorMessage(-1, e); + } + + private String errorMessage(int i, Exception e) { + return errorMessage(i, e, false); + } + + private String errorMessage(int i, Exception e, boolean networking) { + if (networking) { + return client(i) + " - Networking error: " + e.getClass().getName() + + ":" + e.getMessage(); + } else { + String s = ""; + if (i > -1) { + s += client(i); + } + s += "should have thrown RandomOrgRANDOMORGError"; + if (e != null) { + s += ", instead threw " + e.getClass().getName(); + } + return s; + } + } + + /** + * Helper function for testing methods returning signed values + * + * @param roc RandomOrgClient instance being used + * @param i index of RandomOrgClient instance in rocs + * @param o HashMap returned from call to a RandomOrgClient method + * returning signed values + * @param cls Class of the data expected to be returned from the call to the + * RandomOrgClient method + * + */ + private void signedValueTester(RandomOrgClient roc, int i, HashMap o, Class cls) { + signedValueTester(roc, i, o, cls, false); + } + + /** + * Helper function for testing methods returning signed values + * + * @param roc RandomOrgClient instance being used + * @param i index of RandomOrgClient instance in rocs + * @param o HashMap returned from call to a RandomOrgClient method + * returning signed values + * @param cls Class of the data expected to be returned from the call to the + * RandomOrgClient method + * @param hasUserData boolean stating whether the request included userData (true) or not (false) + * + */ + private void signedValueTester(RandomOrgClient roc, int i, HashMap o, Class cls, boolean hasUserData) { + collector.checkThat(o, notNullValue()); + + collector.checkThat(o.containsKey("data"), equalTo(true)); + collector.checkThat(o.containsKey("random"), equalTo(true)); + collector.checkThat(o.containsKey("signature"), equalTo(true)); + + collector.checkThat(o.get("data").getClass(), equalTo(cls)); + collector.checkThat(o.get("random").getClass(), equalTo(JsonObject.class)); + collector.checkThat(o.get("signature").getClass(), equalTo(String.class)); + + if (hasUserData) { + collector.checkThat(((JsonObject) o.get("random")).get("userData"), equalTo(userData)); + } + + try { + collector.checkThat(roc.verifySignature((JsonObject)o.get("random"), + (String)o.get("signature")), equalTo(true)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } } } diff --git a/RandomJSONRPC/src/org/random/test/RandomOrgRandomBasicTest.java b/RandomJSONRPC/src/org/random/test/RandomOrgRandomBasicTest.java index fe393f1..78d5b1d 100644 --- a/RandomJSONRPC/src/org/random/test/RandomOrgRandomBasicTest.java +++ b/RandomJSONRPC/src/org/random/test/RandomOrgRandomBasicTest.java @@ -8,8 +8,7 @@ import org.junit.Test; import org.random.util.RandomOrgRandom; -/** A set of tests for RandomOrgRandom.java - **/ +/** A set of tests for RandomOrgRandom.java */ public class RandomOrgRandomBasicTest { private static RandomOrgRandom random; @@ -29,7 +28,8 @@ public void testIntegerRange(){ assertTrue(i >= 0); assertTrue(i < 10); } catch (Exception e) { - Assert.fail("Networking error: " + e.getClass().getName() + ":" + e.getMessage()); + Assert.fail("Networking error: " + e.getClass().getName() + + ":" + e.getMessage()); } } } diff --git a/RandomJSONRPC/src/org/random/util/RandomOrgRandom.java b/RandomJSONRPC/src/org/random/util/RandomOrgRandom.java index 38c20bb..552f1b1 100644 --- a/RandomJSONRPC/src/org/random/util/RandomOrgRandom.java +++ b/RandomJSONRPC/src/org/random/util/RandomOrgRandom.java @@ -20,31 +20,30 @@ import org.random.api.exception.RandomOrgRANDOMORGError; import org.random.api.exception.RandomOrgSendTimeoutException; -/** A partial implementation of {@link Random} using RANDOM.ORG for true RNG. - **

- ** This implements a true random number generator based on the RANDOM.ORG service. - ** For more information see https://api.random.org/. - **

- ** This class offers cached number retrieving from the random.org server over the official API. - ** The cached numbers can be accessed bit wise by the typical public methods of the random class. - ** If more bits are requested than currently cached the methods will block until more data is - ** retrieved from the server. - **

- ** To use this class a official API key from https://api.random.org/api-keys is required. - **

- ** By default this caches a maximum of 512 bits in two blobs of 256 bits each. - ** To optimize the cache for your needs you can setup the cache size (number of blobs) and - ** cache bits (number of bits per blob) on creation of an instance. - ** - ** @see https://random.org/ - ** @see https://api.random.org/ - ** - ** @author Adam Wagenhaeuser - **/ +/** + * A partial implementation of {@link Random} using RANDOM.ORG for true RNG. + *

+ * This implements a true random number generator based on the RANDOM.ORG service. + * For more information see https://api.random.org/. + *

+ * This class offers cached number retrieving from the random.org server over the official API. + * The cached numbers can be accessed bit wise by the typical public methods of the random class. + * If more bits are requested than currently cached the methods will block until more data is + * retrieved from the server. + *

+ * To use this class a official API key from https://api.random.org/api-keys is required. + *

+ * By default this caches a maximum of 512 bits in two blobs of 256 bits each. + * To optimize the cache for your needs you can setup the cache size (number of blobs) and + * cache bits (number of bits per blob) on creation of an instance. + * + * @see https://random.org/ + * @see https://api.random.org/ + * + * @author Adam Wagenhaeuser + */ public class RandomOrgRandom extends Random { - /** - **/ private static final long serialVersionUID = 4785372106424073371L; /** integer bit masks */ @@ -84,21 +83,19 @@ public class RandomOrgRandom extends Random { 0xFFFFFFFF, }; - /** Default cache size is 256. - **/ + /** Default cache size is 256. */ private static final int DEFAULT_CACHE_BITS = 256; - /** Default cache number is 2. - **/ + /** Default cache number is 2. */ private static final int DEFAULT_CACHE_SIZE = 2; - /** Cache bits - number of bits to cache per blob. - ** - ** Must be within the [1,1048576] range and must be divisible by 8. - ** This will be automatically enforced (rounded up unless too large). - ** - ** Default is 256. - **/ + /* Cache bits - number of bits to cache per blob. + * + * Must be within the [1,1048576] range and must be divisible by 8. + * This will be automatically enforced (rounded up unless too large). + * + * Default is 256. + */ private int cacheBits; /** Cache size - number of blobs to cache. @@ -108,25 +105,27 @@ public class RandomOrgRandom extends Random { **/ private int cacheSize; - /** The local RANDOM.ORG blob cache. - **

- ** This stores up to {@link #cacheSize}*{@link #cacheBits} values. - **/ + /** + * The local RANDOM.ORG blob cache. + *

+ * This stores up to {@link #cacheSize}*{@link #cacheBits} values. + */ private RandomOrgCache cache; - /** The current blob from which random numbers are being pulled. - ** Once blob is in use it is removed from the blob cache. - **/ + /** + * The current blob from which random numbers are being pulled. + * Once blob is in use it is removed from the blob cache. + */ private byte[] currentBlob; - /** Next index into the currently active blob. - **/ + /** Next index into the currently active blob. */ private int currentBlobIndex; - /** The RANDOM.ORG client used for the cache. - ** - ** @see #cache - **/ + /** + * The RANDOM.ORG client used for the cache. + * + * @see #cache + */ private RandomOrgClient client; /** Left to right bit buffer for getting less than 8 bits. @@ -143,41 +142,43 @@ public class RandomOrgRandom extends Random { private static final Logger LOGGER = Logger.getLogger(RandomOrgClient.class.getPackage().getName()); - /** Create a new RandomOrgRandom instance for the given API key. - **

- ** This RandomOrgRandom needs an official API key for the RANDOM.ORG API. - ** See https://api.random.org/api-keys for more details. - **

- ** The RANDOM.ORG library guarantees only one client is running per API key at any - ** given time, so it's safe to create multiple RandomOrgRandom classes - ** with the same API key if needed. - ** - ** @param apiKey a RANDOM.ORG API key - **/ + /** + * Constructor. Create a new RandomOrgRandom instance for the given API key. + *

+ * This RandomOrgRandom needs an official API key + * for the RANDOM.ORG API. + *

+ * The RANDOM.ORG library guarantees only one client is running per API key at any + * given time, so it's safe to create multiple RandomOrgRandom classes + * with the same API key if needed. + * + * @param apiKey a RANDOM.ORG API key + */ public RandomOrgRandom(String apiKey) { this(apiKey, DEFAULT_CACHE_SIZE, DEFAULT_CACHE_BITS); } - /** Create a new RandomOrgRandom instance for the given API key and cache size. - **

- ** This RandomOrgRandom needs an official API key for the RANDOM.ORG API. - ** See https://api.random.org/api-keys for more details. - **

- ** The cacheSize specifies the number of blobs maintained by a background thread. - ** If you set the value too high it may consume much of your daily allowance on the server. - ** It the value is too low your application may block frequently. The default value is 2. - **

- ** The cacheBits parameter specifies the number of bits per blob in the cache. - ** If you set the value too high it may consume much of your daily allowance on the server. - ** It the value is too low your application will block frequently. The default value is 256. - **

- ** The RANDOM.ORG library guarantees only one client is running per API key at any - ** given time, so it's safe to create multiple RandomOrgRandom classes - ** with the same API key if needed. - ** - ** @param apiKey a RANDOM.ORG API key - ** @param cacheSize the desired cache size - **/ + /** + * Constructor. Create a new RandomOrgRandom instance for the given API key and cache size. + *

+ * This RandomOrgRandom needs an official API key + * for the RANDOM.ORG API. + *

+ * The RANDOM.ORG library guarantees only one client is running per API key at any + * given time, so it's safe to create multiple RandomOrgRandom classes + * with the same API key if needed. + * + * @param apiKey a RANDOM.ORG API key + * @param cacheSize number of blobs to cache. If you set the value too high it may consume + * much of your daily allowance on the server. It the value is too low your application + * may block frequently. Cache size minimum is 2, which will be automatically enforced + * (default 2). + * @param cacheBits number of bits to cache per blob. If you set the value too high it may + * consume much of your daily allowance on the server. It the value is too low your + * application will block frequently. Must be within the [1,1048576] range and must be + * divisible by 8. This will be automatically enforced (rounded up unless too large; + * default 256). + */ public RandomOrgRandom(String apiKey, int cacheSize, int cacheBits) { this.cacheSize = cacheSize; @@ -192,39 +193,41 @@ public RandomOrgRandom(String apiKey, int cacheSize, int cacheBits) { this.cache = this.client.createBlobCache(1, cacheBits, RandomOrgClient.BLOB_FORMAT_BASE64, cacheSize); } - /** Create a new RandomOrgRandom using the given client. - **

- ** This RandomOrgRandom needs a RANDOM.ORG client instance for the random.org API. - **

- ** The RANDOM.ORG library guarantees only one client is running per API key at any - ** given time, so it's safe to create multiple RandomOrgRandom classes - ** with the same API key if needed. - ** - ** @param client the RANDOM.ORG client to use - **/ + /** + * Constructor. Create a new RandomOrgRandom using the given client. + *

+ * This RandomOrgRandom needs a RANDOM.ORG client instance for the random.org API. + *

+ * The RANDOM.ORG library guarantees only one client is running per API key at any + * given time, so it's safe to create multiple RandomOrgRandom classes + * with the same API key if needed. + * + * @param client the RANDOM.ORG client to use + */ public RandomOrgRandom(RandomOrgClient client) { this(client, DEFAULT_CACHE_SIZE, DEFAULT_CACHE_BITS); } - /** Create a new RandomOrgRandom using the given client and cache size. - **

- ** This RandomOrgRandom needs a RANDOM.ORG client instance for the random.org API. - **

- ** The cacheSize specifies the number of blobs maintained by a background thread. - ** If you set the value too high it may consume much of your daily allowance on the server. - ** It the value is too low your application may block frequently. The default value is 2. - **

- ** The cacheBits parameter specifies the number of bits per blob in the cache. - ** If you set the value too high it may consume much of your daily allowance on the server. - ** It the value is too low your application will block frequently. The default value is 256. - **

- ** The RANDOM.ORG library guarantees only one client is running per API key at any - ** given time, so it's safe to create multiple RandomOrgRandom classes - ** with the same API key if needed. - ** - ** @param client the RANDOM.ORG client to use - ** @param cacheSize the desired cache size - **/ + /** + * Constructor. Create a new RandomOrgRandom using the given client and cache size. + *

+ * This RandomOrgRandom needs a RANDOM.ORG client instance for the random.org API. + *

+ * The RANDOM.ORG library guarantees only one client is running per API key at any + * given time, so it's safe to create multiple RandomOrgRandom classes + * with the same API key if needed. + * + * @param client the RANDOM.ORG client to use + * @param cacheSize number of blobs to cache. If you set the value too high it may consume + * much of your daily allowance on the server. It the value is too low your application + * may block frequently. Cache size minimum is 2, which will be automatically enforced + * (default 2). + * @param cacheBits number of bits to cache per blob. If you set the value too high it may + * consume much of your daily allowance on the server. It the value is too low your + * application will block frequently. Must be within the [1,1048576] range and must be + * divisible by 8. This will be automatically enforced (rounded up unless too large; + * default 256). + */ public RandomOrgRandom(RandomOrgClient client, int cacheSize, int cacheBits) { this.client = client; this.cacheSize = cacheSize; @@ -236,29 +239,30 @@ public RandomOrgRandom(RandomOrgClient client, int cacheSize, int cacheBits) { this.cache = this.client.createBlobCache(1, cacheBits, RandomOrgClient.BLOB_FORMAT_BASE64, cacheSize); } - /** Gets the remaining quota for the used key. - **

- ** This method gets the bit count still retrievable from the - ** server. If this value is negative no more bits can be retrieved. - **

- ** Note that this method will access a buffered value if that value is not too - ** old, so the returned value can be different from the value on the server. - **

- ** Note that this value does not contain the local cached bits, so the current - ** local available bit count can be larger than the return of this method. - ** - ** @return the remaining bit quota - ** - ** @throws RandomOrgSendTimeoutException @see {@link RandomOrgClient#getBitsLeft()} - ** @throws RandomOrgKeyNotRunningError @see {@link RandomOrgClient#getBitsLeft()} - ** @throws RandomOrgInsufficientRequestsError @see {@link RandomOrgClient#getBitsLeft()} - ** @throws RandomOrgInsufficientBitsError @see {@link RandomOrgClient#getBitsLeft()} - ** @throws RandomOrgBadHTTPResponseException @see {@link RandomOrgClient#getBitsLeft()} - ** @throws RandomOrgRANDOMORGError @see {@link RandomOrgClient#getBitsLeft()} - ** @throws RandomOrgJSONRPCError @see {@link RandomOrgClient#getBitsLeft()} - ** @throws MalformedURLException @see {@link RandomOrgClient#getBitsLeft()} - ** @throws IOException @see {@link RandomOrgClient#getBitsLeft()} - **/ + /** + * Gets the remaining quota for the used key. + *

+ * This method gets the bit count still retrievable from the + * server. If this value is negative no more bits can be retrieved. + *

+ * Note that this method will access a buffered value if that value is not too + * old, so the returned value can be different from the value on the server. + *

+ * Note that this value does not contain the local cached bits, so the current + * local available bit count can be larger than the return of this method. + * + * @return the remaining bit quota + * + * @throws RandomOrgSendTimeoutException @see {@link RandomOrgClient#getBitsLeft()} + * @throws RandomOrgKeyNotRunningError @see {@link RandomOrgClient#getBitsLeft()} + * @throws RandomOrgInsufficientRequestsError @see {@link RandomOrgClient#getBitsLeft()} + * @throws RandomOrgInsufficientBitsError @see {@link RandomOrgClient#getBitsLeft()} + * @throws RandomOrgBadHTTPResponseException @see {@link RandomOrgClient#getBitsLeft()} + * @throws RandomOrgRANDOMORGError @see {@link RandomOrgClient#getBitsLeft()} + * @throws RandomOrgJSONRPCError @see {@link RandomOrgClient#getBitsLeft()} + * @throws MalformedURLException @see {@link RandomOrgClient#getBitsLeft()} + * @throws IOException @see {@link RandomOrgClient#getBitsLeft()} + */ public long getRemainingQuota() throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -271,35 +275,37 @@ public long getRemainingQuota() throws RandomOrgSendTimeoutException, return this.client.getBitsLeft(); } - /** Returns the size of the local cache. - **

- ** This size can be specified in the constructor. - ** - ** @return the size of the cache. - **/ + /** + * Returns the size of the local cache. + *

+ * This size can be specified in the constructor. + * + * @return the size of the cache. + */ public int getCachSize() { return this.cacheSize; } - /** Returns the size of each blob in the cache in bits. - **

- ** This size can be specified in the constructor. - ** - ** @return the number of bits per blob in the cache. - **/ + /** + * Returns the size of each blob in the cache in bits. + *

+ * This size can be specified in the constructor. + * + * @return the number of bits per blob in the cache. + */ public int getCachBits() { return this.cacheBits; } - /** Blocking implementation of {@link java.util.Random#nextInt(int)} using RANDOM.ORG's RNG service. - ** - ** @see java.util.Random#nextInt(int) - ** - ** @throws NoSuchElementException if a number couldn't be retrieved. - **/ + /** + * Blocking implementation of {@link java.util.Random#nextInt(int)} using RANDOM.ORG's RNG service. + * + * @see java.util.Random#nextInt(int) + * + * @throws NoSuchElementException if a number couldn't be retrieved. + */ @Override - public int nextInt(int n) { - + public int nextInt(int n) { if (n <= 0) { throw new IllegalArgumentException("n must be positive"); } @@ -334,15 +340,15 @@ public int nextInt(int n) { return r; } - /** Blocking implementation of {@link java.util.Random#next(int)} using RANDOM.ORG's RNG service. - ** - ** @see java.util.Random#next(int) - ** - ** @throws NoSuchElementException if a number couldn't be retrieved. - **/ + /** + * Blocking implementation of {@link java.util.Random#next(int)} using RANDOM.ORG's RNG service. + * + * @see java.util.Random#next(int) + * + * @throws NoSuchElementException if a number couldn't be retrieved. + */ @Override - public synchronized int next(int bits) { - + public synchronized int next(int bits) { // how many full bytes to read int sz = bits / 8; @@ -386,30 +392,31 @@ public synchronized int next(int bits) { return num; } - /** Gets the given count of random bits. - **

- ** Note: for standard retrieval of bits use the next(int) method. - **

- ** numBits must be in the range of 1 to 7 inclusive. - **

- ** This method will return numBits bits as an 8 bit byte value. - ** The random bits are stored in the least significant bits and the most significant bits are filled with zeros. - ** All random numbers are in the range of 0 to 2^numBits - 1 inclusive. - ** 

-	 ** Example getting 4 bits:
-	 ** 
-	 ** int ranBits = getSubBits(4) & 0x0F
-	 **
- ** - ** @param numBits number of bits to fetch - ** - ** @return a byte containing the requested number of random bits - ** - ** @see #next(int) - ** - ** @throws IllegalArgumentException if the number of bits requested is not between 1 and 7 inclusive - ** @throws NoSuchElementException if a number couldn't be retrieved. - **/ + /** + * Gets the given count of random bits. + *

+ * Note: for standard retrieval of bits use the next(int) method. + *

+ * numBits must be in the range of 1 to 7 inclusive. + *

+ * This method will return numBits bits as an 8 bit byte value. + * The random bits are stored in the least significant bits and the most significant bits are filled with zeros. + * All random numbers are in the range of 0 to 2^numBits - 1 inclusive. + * 

+	 * Example getting 4 bits:
+	 * 
+	 * int ranBits = getSubBits(4) & 0x0F
+	 *
+ * + * @param numBits number of bits to fetch + * + * @return a byte containing the requested number of random bits + * + * @see #next(int) + * + * @throws IllegalArgumentException if the number of bits requested is not between 1 and 7 inclusive + * @throws NoSuchElementException if a number couldn't be retrieved. + */ protected synchronized byte getSubBits(int numBits) { if (numBits < 1 || 7 < numBits) { @@ -447,12 +454,12 @@ protected synchronized byte getSubBits(int numBits) { return b; } - /** Gets the next blob from the cache. - ** - ** @throws NoSuchElementException if a blob couldn't be retrieved. - **/ - private synchronized void moveToNextBlob() throws NoSuchElementException { - + /** + * Gets the next blob from the cache. + * + * @throws NoSuchElementException if a blob couldn't be retrieved. + */ + private synchronized void moveToNextBlob() throws NoSuchElementException { String blob = null; try { @@ -467,29 +474,11 @@ private synchronized void moveToNextBlob() throws NoSuchElementException { if (getRemainingQuota() <= 0) { throw e; } - } catch (RandomOrgKeyNotRunningError e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); + } catch (Exception e1) { + LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + + e1.getClass().getName() + ": " + e1.getMessage()); throw e; - } catch (RandomOrgInsufficientRequestsError e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - throw e; - } catch (RandomOrgInsufficientBitsError e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - throw e; - } catch (MalformedURLException e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - throw e; - } catch (RandomOrgSendTimeoutException e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - } catch (RandomOrgBadHTTPResponseException e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - } catch (RandomOrgRANDOMORGError e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - } catch (RandomOrgJSONRPCError e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - } catch (IOException e1) { - LOGGER.log(Level.INFO, "RandomOrgRandom moveToNextBlob Exception: " + e1.getClass().getName() + ": " + e1.getMessage()); - } + } } if (blob == null) { @@ -508,20 +497,22 @@ private synchronized void moveToNextBlob() throws NoSuchElementException { } } - /** Return true if n is a power of 2. - ** - ** @param n to evaluate - ** @return true if n is a power of 2 - **/ + /** + * Return true if n is a power of 2. + * + * @param n to evaluate + * @return true if n is a power of 2 + */ private boolean isPow2(int n) { return n == 0 ? false : (n & (n - 1)) == 0; } - /** Return next power of 2 greater than n. - ** - ** @param n to evaluate - ** @return next power of 2 greater than n. - **/ + /** + * Return next power of 2 greater than n. + * + * @param n to evaluate + * @return next power of 2 greater than n. + */ private int nextPow2(int n) { int v = n; v--; @@ -534,13 +525,13 @@ private int nextPow2(int n) { return v; } - /** Log2 of n. - ** - ** @param n to evaluate - should be a power of 2. - ** @return Log2 of n - **/ - private int log2(int n) { - + /** + * Log2 of n. + * + * @param n to evaluate - should be a power of 2. + * @return Log2 of n + */ + private int log2(int n) { int log = 0; if ((n & 0xffff0000) != 0 ) { From 1ebffae62770f345c29430e1be8a3b46c86a25a3 Mon Sep 17 00:00:00 2001 From: = <=> Date: Fri, 29 Jan 2021 10:18:19 +0000 Subject: [PATCH 2/5] Release 3 Update This library now supports Release 3 of the RANDOM.ORG JSON-RPC API. Updates: - New methods (createTickets, listTickets and getTicket) - Method overloading for all signed value-returning methods to contain the optional 'ticketId' parameter - Added RandomOrg error codes 420, 421, 422 and 423 - Added tests for all new methods, error codes 420, 421 and 422 and signed methods with 'ticketId' parameter --- README.rst | 6 +- .../src/org/random/api/RandomOrgClient.java | 862 ++++++++++++++++-- .../random/test/RandomOrgClientBasicTest.java | 435 ++++++++- 3 files changed, 1179 insertions(+), 124 deletions(-) diff --git a/README.rst b/README.rst index e866ed1..20dd923 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,9 @@ JSON-RPC-Java =============== -RANDOM.ORG JSON-RPC API (Release 2) implementation. +RANDOM.ORG JSON-RPC API (Release 3) implementation. -This is a Java implementation of the RANDOM.ORG JSON-RPC API (R2). It provides either serialized or unserialized access to both the signed and unsigned methods of the API through the RandomOrgClient class. It also provides a convenience class through the RandomOrgClient class, the RandomOrgCache, for precaching requests. In the context of this module, a serialized client is one for which the sequence of requests matches the sequence of responses. +This is a Java implementation of the RANDOM.ORG JSON-RPC API (R3). It provides either serialized or unserialized access to both the signed and unsigned methods of the API through the RandomOrgClient class. It also provides a convenience class through the RandomOrgClient class, the RandomOrgCache, for precaching requests. In the context of this module, a serialized client is one for which the sequence of requests matches the sequence of responses. Installation ------------ @@ -86,7 +86,7 @@ This library now also includes a RANDOM.ORG implementation of the `java.util.Ran Documentation ------------- -For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/2 +For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/3 Tests ----- diff --git a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java index 29f2490..93577ed 100644 --- a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java +++ b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java @@ -47,7 +47,7 @@ * This class will only allow the creation of one instance per API key. If an instance of this class * already exists for a given key, that instance will be returned instead of a new instance. * - * This class obeys most of the guidelines set forth in https://api.random.org/json-rpc/2 + * This class obeys most of the guidelines set forth in https://api.random.org/json-rpc/3 * All requests respect the server's advisoryDelay returned in any responses, or use DEFAULT_DELAY * if no advisoryDelay is returned. If the supplied API key is paused, i.e., has exceeded its daily * bit/request allowance, this implementation will back off until midnight UTC. @@ -58,7 +58,7 @@ */ public class RandomOrgClient { - // Basic RANDOM.ORG API functions https://api.random.org/json-rpc/2 + // Basic RANDOM.ORG API functions https://api.random.org/json-rpc/3/basic private static final String INTEGER_METHOD = "generateIntegers"; private static final String INTEGER_SEQUENCE_METHOD = "generateIntegerSequences"; private static final String DECIMAL_FRACTION_METHOD = "generateDecimalFractions"; @@ -68,7 +68,7 @@ public class RandomOrgClient { private static final String BLOB_METHOD = "generateBlobs"; private static final String GET_USAGE_METHOD = "getUsage"; - // Signed RANDOM.ORG API functions https://api.random.org/json-rpc/2/signed + // Signed RANDOM.ORG API functions https://api.random.org/json-rpc/3/signed private static final String SIGNED_INTEGER_METHOD = "generateSignedIntegers"; private static final String SIGNED_INTEGER_SEQUENCE_METHOD = "generateSignedIntegerSequences"; private static final String SIGNED_DECIMAL_FRACTION_METHOD = "generateSignedDecimalFractions"; @@ -77,6 +77,9 @@ public class RandomOrgClient { private static final String SIGNED_UUID_METHOD = "generateSignedUUIDs"; private static final String SIGNED_BLOB_METHOD = "generateSignedBlobs"; private static final String GET_RESULT_METHOD = "getResult"; + private static final String CREATE_TICKET_METHOD = "createTickets"; + private static final String LIST_TICKET_METHOD = "listTickets"; + private static final String GET_TICKET_METHOD = "getTicket"; private static final String VERIFY_SIGNATURE_METHOD = "verifySignature"; // Blob format literals @@ -96,6 +99,7 @@ public class RandomOrgClient { public static final boolean DEFAULT_REPLACEMENT = true; public static final int DEFAULT_INT_BASE = 10; public static final JsonObject DEFAULT_USER_DATA = null; + public static final String DEFAULT_TICKET_ID = null; public static final int DEFAULT_CACHE_SIZE = 20; public static final int DEFAULT_CACHE_SIZE_SMALL = 10; //UUID and BLOB caches @@ -105,7 +109,7 @@ public class RandomOrgClient { private static HashSet randomOrgErrors = new HashSet(); static { int[] ints = {100, 101, 200, 201, 202, 203, 204, 300, 301, 302, 303, 304, 305, 306, 307, - 400, 401, 402, 403, 404, 405, 500, 32000}; + 400, 401, 402, 403, 404, 405, 420, 421, 422, 423, 500, 32000}; for (int i : ints) { RandomOrgClient.randomOrgErrors.add(i); } @@ -223,11 +227,11 @@ public void run() { } } - // Basic methods for generating randomness, see: https://api.random.org/json-rpc/2/basic + // Basic methods for generating randomness, see: https://api.random.org/json-rpc/3/basic /** * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegers + * See: https://api.random.org/json-rpc/3/basic#generateIntegers * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -235,7 +239,7 @@ public void run() { * @param max the upper boundary for the range from which the random numbers will be picked. * Must be within the [-1e9,1e9] range. * - * @return int[] of random integers. + * @return int[] of true random integers. * * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request * can be sent. @@ -265,7 +269,7 @@ public int[] generateIntegers(int n, int min, int max) /** * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegers + * See: https://api.random.org/json-rpc/3/basic#generateIntegers * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -306,7 +310,7 @@ public int[] generateIntegers(int n, int min, int max, boolean replacement) /** * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegers + * See: https://api.random.org/json-rpc/3/basic#generateIntegers * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -352,7 +356,7 @@ public String[] generateIntegers(int n, int min, int max, boolean replacement, i /** * Request and return uniform sequences of true random integers within user-defined ranges * from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -393,7 +397,7 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max) /** * Request and return uniform sequences of true random integers within user-defined ranges * from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -431,13 +435,14 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max, boo RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.extractIntSequences(this.integerSequencesMethod(n, length, min, max, replacement, DEFAULT_INT_BASE, DEFAULT_USER_DATA, false)); + return this.extractIntSequences(this.integerSequencesMethod(n, length, min, max, replacement, + DEFAULT_INT_BASE, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); } /** * Request and return uniform sequences of true random integers within user-defined ranges * from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -481,13 +486,13 @@ public String[][] generateIntegerSequences(int n, int length, int min, int max, MalformedURLException, IOException { return this.extractIntSequencesString(this.integerSequencesMethod(n, length, - min, max, replacement, base, DEFAULT_USER_DATA, false)); + min, max, replacement, base, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); } /** * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -531,7 +536,7 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma /** * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -573,14 +578,14 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma int[] base = new int[n]; Arrays.fill(base, DEFAULT_INT_BASE); - return this.extractIntSequences(this.integerSequencesMethod(n, length, - min, max, replacement, base, DEFAULT_USER_DATA, false)); + return this.extractIntSequences(this.integerSequencesMethod(n, length, min, max, replacement, + base, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); } /** * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. - * See: https://api.random.org/json-rpc/2/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -624,15 +629,15 @@ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.extractIntSequencesString(this.integerSequencesMethod(n, length, - min, max, replacement, base, DEFAULT_USER_DATA, false)); + return this.extractIntSequencesString(this.integerSequencesMethod(n, length, min, max, + replacement, base, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); } /** * Request and return a list (size n) of true random decimal fractions, from a uniform * distribution across the [0,1] interval with a user-defined number of decimal places * from the server. - * See: https://api.random.org/json-rpc/2/basic#generateDecimalFractions + * See: https://api.random.org/json-rpc/3/basic#generateDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -669,7 +674,7 @@ public double[] generateDecimalFractions(int n, int decimalPlaces) * Request and return a list (size n) of true random decimal fractions, from a uniform * distribution across the [0,1] interval with a user-defined number of decimal places * from the server. - * See: https://api.random.org/json-rpc/2/basic#generateDecimalFractions + * See: https://api.random.org/json-rpc/3/basic#generateDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -719,7 +724,7 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla * Request and return a list (size n) of true random numbers from a Gaussian distribution * (also known as a normal distribution). The form uses a Box-Muller Transform to generate * the Gaussian distribution from uniformly distributed numbers. - * See: https://api.random.org/json-rpc/2/basic#generateGaussians + * See: https://api.random.org/json-rpc/3/basic#generateGaussians * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -769,7 +774,7 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, /** * Request and return a list (size n) of true random unicode strings from the server. - * See: https://api.random.org/json-rpc/2/basic#generateStrings + * See: https://api.random.org/json-rpc/3/basic#generateStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -807,7 +812,7 @@ public String[] generateStrings(int n, int length, String characters) /** * Request and return a list (size n) of true random unicode strings from the server. - * See: https://api.random.org/json-rpc/2/basic#generateStrings + * See: https://api.random.org/json-rpc/3/basic#generateStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -815,7 +820,7 @@ public String[] generateStrings(int n, int length, String characters) * @param characters a string that contains the set of characters that are allowed to occur * in the random strings. The maximum number of characters is 80. * @param replacement specifies whether the random strings should be picked with replacement. - * If True the resulting list of strings may contain duplicates, otherwise the strings + * If true, the resulting list of strings may contain duplicates, otherwise the strings * will all be unique (default true). * * @return String[] of true random Strings. @@ -860,7 +865,7 @@ public String[] generateStrings(int n, int length, String characters, boolean re /** * Request and return a list (size n) of version 4 true random Universally Unique IDentifiers * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. - * See: https://api.random.org/json-rpc/2/basic#generateUUIDs + * See: https://api.random.org/json-rpc/3/basic#generateUUIDs * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @@ -903,7 +908,7 @@ public UUID[] generateUUIDs(int n) /** * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings * containing true random data from the server. - * See: https://api.random.org/json-rpc/2/basic#generateBlobs + * See: https://api.random.org/json-rpc/3/basic#generateBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range @@ -940,7 +945,7 @@ public String[] generateBlobs(int n, int size) /** * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings * containing true random data from the server. - * See: https://api.random.org/json-rpc/2/basic#generateBlobs + * See: https://api.random.org/json-rpc/3/basic#generateBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range @@ -986,13 +991,13 @@ public String[] generateBlobs(int n, int size, String format) return this.extractStrings(response); } - // Signed methods for generating randomness, see: https://api.random.org/json-rpc/2/signed + // Signed methods for generating randomness, see: https://api.random.org/json-rpc/3/signed /** * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedIntegers + * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1034,7 +1039,7 @@ public HashMap generateSignedIntegers(int n, int min, int max) * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedIntegers + * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1079,7 +1084,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedIntegers + * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1122,6 +1127,60 @@ public HashMap generateSignedIntegers(int n, int min, int max, b RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedIntegers(n, min, max, replacement, base, userData, DEFAULT_TICKET_ID); + } + + /** + * Request a list (size n) of true random integers within a user-defined range from the server. + * Returns a dictionary object with the parsed integer list mapped to 'data', the original + * response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, + * 8, 10 and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[] if decimal (base 10) + * or random String[] if non-decimal (any other base value) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement, int base, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -1130,6 +1189,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b request.addProperty("replacement", replacement); request.addProperty("base", base); request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_INTEGER_METHOD); @@ -1148,7 +1208,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * Request and return uniform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1193,7 +1253,7 @@ public HashMap generateSignedIntegerSequences(int n, int length, * Request and return uniform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1238,8 +1298,64 @@ public HashMap generateSignedIntegerSequences(int n, int length, RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedIntegerSequences(n, length, min, max, replacement, base, userData, DEFAULT_TICKET_ID); + } + + /** + * Request and return uniform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, + * 10 and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] if decimal (base 10) + * or random String[][] if non-decimal (any other base value) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject response = this.integerSequencesMethod(n, length, min, max, - replacement, base, userData, true); + replacement, base, userData, ticketId, true); HashMap result = new HashMap(); if (base == 10) { @@ -1255,8 +1371,7 @@ public HashMap generateSignedIntegerSequences(int n, int length, * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences" - * https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1306,7 +1421,7 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the @@ -1357,11 +1472,74 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedIntegerSequences(n, length, min, max, replacement, base, userData, + DEFAULT_TICKET_ID); + } + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the + * sequence identified by its index. Each value in the array must + * be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of + * the sequence identified by its index. Each value in the array must + * be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of + * the sequence identified by its index. Each value in the array must + * be within the [-1e9,1e9] range. + * @param replacement an array with n Boolean values, each specifying whether + * the sequence identified by its index will be created with or without + * replacement. If true, the resulting numbers may contain + * duplicate values, otherwise the numbers will all be unique within + * each sequence (default true). + * @param base an array with n integer values, each specifying the base + * that will be used to display the sequence identified by its index. + * Values allowed are 2, 8, 10 and 16 (default 10). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] if decimal (all base values are 10) + * or random String[][] if non-decimal (any other mix of base values) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { int[] defaultBase = new int[n]; Arrays.fill(defaultBase, DEFAULT_INT_BASE); JsonObject response = this.integerSequencesMethod(n, length, min, max, - replacement, base, userData, true); + replacement, base, userData, ticketId, true); HashMap result = new HashMap(); if (Arrays.equals(base, defaultBase)) { @@ -1378,7 +1556,7 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedDecimalFractions + * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -1417,7 +1595,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedDecimalFractions + * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -1459,7 +1637,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedDecimalFractions + * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -1495,12 +1673,61 @@ public HashMap generateSignedDecimalFractions(int n, int decimal RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedDecimalFractions(n, decimalPlaces, replacement, userData, DEFAULT_TICKET_ID); + } + + /** + * Request a list (size n) of true random decimal fractions, from a uniform distribution + * across the [0,1] interval with a user-defined number of decimal places from the server. + * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the + * original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("decimalPlaces", decimalPlaces); request.addProperty("replacement", replacement); request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_DECIMAL_FRACTION_METHOD); @@ -1518,7 +1745,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedGaussians + * See: https://api.random.org/json-rpc/3/signed#generateSignedGaussians * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -1563,7 +1790,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedGaussians + * See: https://api.random.org/json-rpc/3/signed#generateSignedGaussians * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -1600,6 +1827,57 @@ public HashMap generateSignedGaussians(int n, double mean, doubl RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedGaussians(n, mean, standardDeviation, significantDigits, userData, + DEFAULT_TICKET_ID); + } + + /** + * Request a list (size n) of true random numbers from a Gaussian distribution (also known + * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian + * distribution from uniformly distributed numbers. Returns a dictionary object with the + * parsed random number list mapped to 'data', the original response mapped to 'random', + * and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateSignedGaussians + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -1607,6 +1885,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl request.addProperty("standardDeviation", standardDeviation); request.addProperty("significantDigits", significantDigits); request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_GAUSSIAN_METHOD); @@ -1622,7 +1901,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedStrings + * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1663,7 +1942,7 @@ public HashMap generateSignedStrings(int n, int length, String c * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data',the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedStrings + * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1708,7 +1987,7 @@ public HashMap generateSignedStrings(int n, int length, String c * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedStrings + * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1738,15 +2017,65 @@ public HashMap generateSignedStrings(int n, int length, String c * @throws IOException @see java.io.IOException */ public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject userData) - throws RandomOrgSendTimeoutException, - RandomOrgKeyNotRunningError, - RandomOrgInsufficientRequestsError, - RandomOrgInsufficientBitsError, - RandomOrgBadHTTPResponseException, - RandomOrgRANDOMORGError, - RandomOrgJSONRPCError, - MalformedURLException, - IOException { + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedStrings(n, length, characters, replacement, userData, DEFAULT_TICKET_ID); + } + + /** + * Request a list (size n) of true random strings from the server. Returns a dictionary + * object with the parsed random string list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to + * occur in the random strings. The maximum number of characters is 80. + * @param replacement specifies whether the random strings should be picked with replacement. + * If true, the resulting list of strings may contain duplicates, otherwise the strings + * will all be unique (default true). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); @@ -1754,6 +2083,7 @@ public HashMap generateSignedStrings(int n, int length, String c request.addProperty("characters", characters); request.addProperty("replacement", replacement); request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_STRING_METHOD); @@ -1770,7 +2100,7 @@ public HashMap generateSignedStrings(int n, int length, String c * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedUUIDs + * See: https://api.random.org/json-rpc/3/signed#generateSignedUUIDs * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @@ -1808,7 +2138,7 @@ public HashMap generateSignedUUIDs(int n) * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedUUIDs + * See: https://api.random.org/json-rpc/3/signed#generateSignedUUIDs * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @param userData JsonObject that will be included in unmodified form. Its maximum size @@ -1840,10 +2170,55 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData) RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedUUIDs(n, userData, DEFAULT_TICKET_ID); + } + + /** + * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) + * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary + * object with the parsed random UUID list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateSignedUUIDs + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random UUID[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedUUIDs(int n, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_UUID_METHOD); @@ -1860,7 +2235,7 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData) * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature * mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedBlobs + * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -1900,7 +2275,7 @@ public HashMap generateSignedBlobs(int n, int size) * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature * mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedBlobs + * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -1942,7 +2317,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature * mapped to 'signature'. - * See: https://api.random.org/json-rpc/2/signed#generateSignedBlobs + * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -1978,12 +2353,61 @@ public HashMap generateSignedBlobs(int n, int size, String forma RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedBlobs(n, size, format, userData, DEFAULT_TICKET_ID); + } + + /** + * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data + * from the server. Returns a dictionary object with the parsed random BLOB list mapped + * to 'data', the original response mapped to 'random', and the response's signature + * mapped to 'signature'. + * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs + * + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] + * range and must be divisible by 8. + * @param format specifies the format in which the blobs will be returned. Values allowed + * are BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedBlobs(int n, int size, String format, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("size", size); request.addProperty("format", format); request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_BLOB_METHOD); @@ -1996,13 +2420,13 @@ public HashMap generateSignedBlobs(int n, int size, String forma } // Retrieve a signed result generated within the last 24h, - // see https://api.random.org/json-rpc/2/signed#getResult + // see https://api.random.org/json-rpc/3/signed#getResult /** * Retrieve signed random values generated within the last 24h, using a serial number. * If the historical response was found, a response with the result property containing * the same values that were returned by the method that was used to generate the values. - * See: https://api.random.org/json-rpc/2/signed#getResult + * See: https://api.random.org/json-rpc/3/signed#getResult * * @param serialNumber an integer containing the serial number associated with the response * you wish to retrieve. @@ -2044,14 +2468,235 @@ public HashMap getResult(int serialNumber) return this.extractSignedResponse(response, result); } + + // Ticket methods + + /** + * Create n tickets to be used in signed value-generating methods. + * See: https://api.random.org/json-rpc/3/signed#createTickets + * + * @param n The number of tickets requested. This must be a number in the [1, 50] range. + * @param showResult A boolean value that determines how much information calls to {@link + * #getTicket(String ticketId) getTicket} will return. If {@code showResult} is {@code false}, + * {@code getTicket} will return only the basic ticket information. If {@code showResult} is + * {@code true}, the full random and signature objects from the response that was used to satisfy + * the ticket is returned. + * + * @return JsonObject[] of ticket objects + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public JsonObject[] createTickets(int n, boolean showResult) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + + JsonObject request = new JsonObject(); + + request.addProperty("n", n); + request.addProperty("showResult", showResult); + + request = this.generateKeyedRequest(request, CREATE_TICKET_METHOD); + + JsonObject response = this.sendRequest(request); + + return this.extractTickets(response); + } + + /** + * Obtain information about tickets linked with your API key. The maximum number of tickets + * that can be returned by this method is 2000. + * See: https://api.random.org/json-rpc/3/signed#listTickets + * + * @param ticketType A string describing the type of tickets you want to obtain information + * about. Possible values are {@code singleton, head} and {@code tail}. + *
    + *
  • {@code singleton} returns tickets that have no previous or next tickets. + *
  • {@code head} returns tickets hat do not have a previous ticket but that + * do have a next ticket. + *
  • {@code tail} returns tickets that have a previous ticket but do not have + * a next ticket. + *
+ * + * @return JsonObject[] of tickets of the type requested + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public JsonObject[] listTickets(String ticketType) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + + JsonObject request = new JsonObject(); + + request.addProperty("ticketType", ticketType); + + request = this.generateKeyedRequest(request, LIST_TICKET_METHOD); + + JsonObject response = this.sendRequest(request); + + return this.extractTickets(response); + } + + /** + * Obtain information about a single ticket using the {@code ticketId} associated with it. + * If the ticket has {@code showResult} set to true and has been used, this method will return the + * values generated. + * See:https://api.random.org/json-rpc/3/signed#getTicket + * + * @param ticketId A string containing a ticket identifier returned by a prior call to the + * {@link #createTickets(int n, boolean showResult) createTicket} method. + * + * @return HashMap with the following data: + *

If the ticket was created with {@code showResult true} and has been used in a + * signed value-generating method: + *

    + *
  • "random": random JsonObject as returned from the server + *
  • "signature": signature String + *
  • "data": an array of random values of the type corresponding to the method that + * the ticket was used on + *
+ * If the ticket was created with {@code showResult false} or has not yet been used: + *
    + *
  • "result": JsonObject returned from the server + *
+ * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap getTicket(String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + + JsonObject request = new JsonObject(); + + request.addProperty("ticketId", ticketId); + + request = this.generateRequest(request, GET_TICKET_METHOD); + + JsonObject response = this.sendRequest(request); + + HashMap result = new HashMap(); + + response = response.get("result").getAsJsonObject(); + + if (response.has("result") && !response.get("result").isJsonNull()) { + String method = response.get("result").getAsJsonObject() + .get("random").getAsJsonObject() + .get("method").getAsString(); + + if (method.equals(SIGNED_INTEGER_METHOD)) { + if (response.get("result").getAsJsonObject() + .get("random").getAsJsonObject() + .get("base").getAsInt() == 10) { + // decimal base + result.put("data", this.extractInts(response)); + } else { + // non-decimal base + result.put("data", this.extractStrings(response)); + } + } else if (method.equals(SIGNED_INTEGER_SEQUENCE_METHOD)) { + boolean decimal = false; + JsonObject random = response.get("result").getAsJsonObject() + .get("random").getAsJsonObject(); + + if (random.get("base").isJsonArray()) { + // Integer sequence method with array parameters + int[] defaultBase = new int[random.get("n").getAsInt()]; + Arrays.fill(defaultBase, DEFAULT_INT_BASE); + + if (Arrays.equals(defaultBase, gson.fromJson(random.get("base"), int[].class))) { + // Decimal base for all sequences requested + decimal = true; + } + } else if (random.get("base").getAsInt() == 10) { + // Integer sequence method with single value parameters and decimal base + decimal = true; + } + + if (decimal) { + result.put("data", this.extractIntSequences(response)); + } else { + result.put("data", this.extractIntSequencesString(response)); + } + } else if (method.equals(SIGNED_DECIMAL_FRACTION_METHOD) + || method.equals(SIGNED_GAUSSIAN_METHOD)) { + result.put("data", this.extractDoubles(response)); + } else if (method.equals(SIGNED_STRING_METHOD) + || method.equals(SIGNED_BLOB_METHOD)) { + result.put("data", this.extractStrings(response)); + } else if (method.equals(SIGNED_UUID_METHOD)) { + result.put("data", this.extractUUIDs(response)); + } + return this.extractSignedResponse(response, result); + } else { + /* + * Returns the information for a ticket with showResult == false OR + * a ticket with showResult == true, but which has not yet been used + */ + result.put("result", response); + return result; + } + } - // Signature verification for signed methods, see: https://api.random.org/json-rpc/2/signed + // Signature verification for signed methods, see: https://api.random.org/json-rpc/3/signed /** * Verify the signature of a response previously received from one of the methods in * the Signed API with the server. This is used to examine the authenticity of numbers. * Return True on verification success. - * See: https://api.random.org/json-rpc/2/signed#verifySignature + * See: https://api.random.org/json-rpc/3/signed#verifySignature * * @param random the random field from a response returned by RANDOM.ORG through one of * the Signed API methods. @@ -3108,15 +3753,14 @@ public int getBitsLeft() throws RandomOrgSendTimeoutException, RandomOrgJSONRPCError, MalformedURLException, IOException { - if (this.bitsLeft < 0 || System.currentTimeMillis() > (this.lastResponseReceivedTime + RandomOrgClient.ALLOWANCE_STATE_REFRESH_SECONDS)) { this.getUsage(); } return this.bitsLeft; } - - // Server communications & helper functions. + // Server communications & helper functions. + /** * Issue a getUsage request to update bits and requests left. * @@ -3297,6 +3941,22 @@ protected UUID[] extractUUIDs(JsonObject response) { return randoms; } + /** + * Gets list of ticket objects from response JSON. + * + * @param response JSON from which to extract list of ticket objects. + * + * @return JsonObject[] of tickets. + */ + protected JsonObject[] extractTickets(JsonObject response) { + JsonArray t = (JsonArray) response.get("result"); + JsonObject[] tickets = new JsonObject[t.size()]; + for (int i = 0; i < tickets.length; i++) { + tickets[i] = t.get(i).getAsJsonObject(); + } + return tickets; + } + /** * Gets random data as separate from response JSON. * @@ -3707,7 +4367,7 @@ protected HashMap sendRequestCore(JsonObject request) { String message = error.get("message").getAsString(); // RandomOrgAllowanceExceededError, API key not running, backoff until midnight UTC, - // from RANDOM.ORG Errors: https://api.random.org/json-rpc/2/error-codes + // from RANDOM.ORG Errors: https://api.random.org/json-rpc/3/error-codes if (code == 402) { Calendar date = new GregorianCalendar(); @@ -3732,14 +4392,14 @@ protected HashMap sendRequestCore(JsonObject request) { return ret; // RandomOrgRANDOMORGError from RANDOM.ORG Errors: - // https://api.random.org/json-rpc/2/error-codes + // https://api.random.org/json-rpc/3/error-codes } else if (RandomOrgClient.randomOrgErrors.contains(code)) { ret.put("exception", new RandomOrgRANDOMORGError("Error " + code + ": " + message)); return ret; // RandomOrgJSONRPCError from JSON-RPC Errors: - // https://api.random.org/json-rpc/2/error-codes + // https://api.random.org/json-rpc/3/error-codes } else { ret.put("exception", new RandomOrgJSONRPCError("Error " + code + ": " + message)); @@ -3747,24 +4407,34 @@ protected HashMap sendRequestCore(JsonObject request) { } } - JsonObject result = response.get("result").getAsJsonObject(); + String method = request.get("method").getAsString(); - // Update usage statistics - if (result.has("requestsLeft")) { - this.requestsLeft = result.get("requestsLeft").getAsInt(); - this.bitsLeft = result.get("bitsLeft").getAsInt(); - } - - // Set new server advisory delay - synchronized (this.advisoryDelayLock) { - if (result.has("advisoryDelay")) { - this.advisoryDelay = result.get("advisoryDelay").getAsInt(); - } else { - // Use default if none from server. + if (method.equals("listTickets") || method.equals("createTickets") || method.equals("getTicket")) { + // Set default server advisory delay + synchronized (this.advisoryDelayLock) { this.advisoryDelay = RandomOrgClient.DEFAULT_DELAY; + this.lastResponseReceivedTime = System.currentTimeMillis(); } + } else { + JsonObject result = response.get("result").getAsJsonObject(); - this.lastResponseReceivedTime = System.currentTimeMillis(); + // Update usage statistics + if (result.has("requestsLeft")) { + this.requestsLeft = result.get("requestsLeft").getAsInt(); + this.bitsLeft = result.get("bitsLeft").getAsInt(); + } + + // Set new server advisory delay + synchronized (this.advisoryDelayLock) { + if (result.has("advisoryDelay")) { + this.advisoryDelay = result.get("advisoryDelay").getAsInt(); + } else { + // Use default if none from server. + this.advisoryDelay = RandomOrgClient.DEFAULT_DELAY; + } + + this.lastResponseReceivedTime = System.currentTimeMillis(); + } } ret.put("response", response); @@ -3786,7 +4456,7 @@ protected HashMap sendRequestCore(JsonObject request) { private JsonObject post(JsonObject json) throws IOException, MalformedURLException, RandomOrgBadHTTPResponseException { - HttpsURLConnection con = (HttpsURLConnection) new URL("https://api.random.org/json-rpc/2/invoke").openConnection(); + HttpsURLConnection con = (HttpsURLConnection) new URL("https://api.random.org/json-rpc/3/invoke").openConnection(); con.setConnectTimeout(this.httpTimeout); // headers @@ -3814,7 +4484,7 @@ private JsonObject post(JsonObject json) throws IOException, } in.close(); - return new JsonParser().parse(response.toString()).getAsJsonObject(); + return JsonParser.parseString(response.toString()).getAsJsonObject(); // Alternative to avoid the deprecation warnings when using Gson 2.8.6+: // return JsonParser.parseString(response.toString()).getAsJsonObject(); @@ -3894,6 +4564,10 @@ private JsonObject integerMethod(int n, int min, int max, boolean replacement, i * and 16 (default 10). * @param userData JsonObject that will be included in unmodified form. Its maximum size in * encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). * @param signed boolean representing whether the request uses Basic API (false) or signed * API (true). * @@ -3912,7 +4586,7 @@ private JsonObject integerMethod(int n, int min, int max, boolean replacement, i * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - private JsonObject integerSequencesMethod(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData, boolean signed) + private JsonObject integerSequencesMethod(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData, String ticketId, boolean signed) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -3933,6 +4607,7 @@ private JsonObject integerSequencesMethod(int n, int length, int min, int max, b if (signed) { request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_INTEGER_SEQUENCE_METHOD); } else { request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); @@ -3958,6 +4633,10 @@ private JsonObject integerSequencesMethod(int n, int length, int min, int max, b * and 16 (default 10). * @param userData JsonObject that will be included in unmodified form. Its maximum size in * encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). * @param signed boolean representing whether the request uses Basic API (false) or signed * API (true). * @@ -3976,7 +4655,7 @@ private JsonObject integerSequencesMethod(int n, int length, int min, int max, b * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - private JsonObject integerSequencesMethod(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData, boolean signed) + private JsonObject integerSequencesMethod(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData, String ticketId, boolean signed) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -3997,6 +4676,7 @@ private JsonObject integerSequencesMethod(int n, int[] length, int[] min, int[] if (signed) { request.add("userData", userData); + request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_INTEGER_SEQUENCE_METHOD); } else { request = this.generateKeyedRequest(request, INTEGER_SEQUENCE_METHOD); diff --git a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java index 291d101..364011f 100644 --- a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java +++ b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java @@ -1,6 +1,5 @@ package org.random.test; -import java.util.Arrays; import java.util.HashMap; import java.util.NoSuchElementException; import java.util.UUID; @@ -186,6 +185,58 @@ public void testNegativeErrorMessage400(){ } } + @Test + public void testNegativeErrorMessage420(){ + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + roc.generateSignedIntegers(5, 0, 10, false, 10, null, "ffffffffffffffff"); + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; + } + } + + @Test + public void testNegativeErrorMessage421(){ + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + roc.generateSignedIntegers(5, 0, 10, false, 10, null, "d5b8f6d03f99a134"); + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; + } + } + + @Test + public void testNegativeErrorMessage422(){ + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + + roc.generateSignedIntegers(5, 0, 10, false, 10, null, ticketId); + roc.generateSignedIntegers(5, 0, 10, false, 10, null, ticketId); + + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + System.out.println(e.getMessage()); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; + } + } + // Test Functions @Test @@ -441,7 +492,7 @@ public void testPositiveGenerateSignedInteger_1() { try { HashMap o = roc.generateSignedIntegers(10, 0, 10); - signedValueTester(roc, i, o, int[].class); + this.signedValueTester(roc, i, o, int[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -457,7 +508,7 @@ public void testPositiveGenerateSignedInteger_2(){ try { HashMap o = roc.generateSignedIntegers(10, 0, 10, false); - signedValueTester(roc, i, o, int[].class); + this.signedValueTester(roc, i, o, int[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -474,7 +525,7 @@ public void testPositiveGenerateSignedInteger_3(){ try { HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 10, userData); - signedValueTester(roc, i, o, int[].class, true); + this.signedValueTester(roc, i, o, int[].class, true); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -491,7 +542,43 @@ public void testPositiveGenerateSignedInteger_4(){ try { HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 16, userData); - signedValueTester(roc, i, o, String[].class, true); + this.signedValueTester(roc, i, o, String[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedInteger_5(){ + // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, + // int base, JsonObject userData, String ticketId) -- decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 10, userData, ticketId); + + this.signedValueTester(roc, i, o, int[].class, true, ticketId); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedInteger_6(){ + // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, + // int base, JsonObject userData, String ticketId) -- non-decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 16, userData, ticketId); + + this.signedValueTester(roc, i, o, String[].class, true, ticketId); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -507,7 +594,7 @@ public void testPositiveGenerateSignedIntegerSequences_1(){ try { HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10); - signedValueTester(roc, i, o, int[][].class); + this.signedValueTester(roc, i, o, int[][].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -525,7 +612,7 @@ public void testPositiveGenerateSignedIntegerSequences_2(){ try { HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 10, userData); - signedValueTester(roc, i, o, int[][].class); + this.signedValueTester(roc, i, o, int[][].class, true); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -543,7 +630,7 @@ public void testPositiveGenerateSignedIntegerSequences_3(){ try { HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 16, userData); - signedValueTester(roc, i, o, String[][].class, true); + this.signedValueTester(roc, i, o, String[][].class, true); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -553,13 +640,53 @@ public void testPositiveGenerateSignedIntegerSequences_3(){ @Test public void testPositiveGenerateSignedIntegerSequences_4(){ + // Testing generateSignedIntegerSequences(int n, int length, int min, int max, + // boolean replacement, int base, JsonObject userData, String ticketId) + // -- decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 10, + userData, ticketId); + + this.signedValueTester(roc, i, o, int[][].class, true, ticketId); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_5(){ + // Testing generateSignedIntegerSequences(int n, int length, int min, int max, + // boolean replacement, int base, JsonObject userData, String ticketId) + // -- non-decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 16, + userData, ticketId); + + this.signedValueTester(roc, i, o, String[][].class, true, ticketId); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_6(){ // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max) int i = 1; for (RandomOrgClient roc : rocs) { try { HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX); - signedValueTester(roc, i, o, int[][].class); + this.signedValueTester(roc, i, o, int[][].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -568,7 +695,7 @@ public void testPositiveGenerateSignedIntegerSequences_4(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_5(){ + public void testPositiveGenerateSignedIntegerSequences_7(){ // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData) // -- decimal @@ -579,7 +706,7 @@ public void testPositiveGenerateSignedIntegerSequences_5(){ try { HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, decimalBase, userData); - signedValueTester(roc, i, o, int[][].class); + this.signedValueTester(roc, i, o, int[][].class, true); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -588,7 +715,7 @@ public void testPositiveGenerateSignedIntegerSequences_5(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_6(){ + public void testPositiveGenerateSignedIntegerSequences_8(){ // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData) // -- non-decimal @@ -598,7 +725,50 @@ public void testPositiveGenerateSignedIntegerSequences_6(){ try { HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, BASE, userData); - signedValueTester(roc, i, o, String[][].class, true); + this.signedValueTester(roc, i, o, String[][].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_9(){ + // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, JsonObject userData, String ticketId) + // -- decimal + int[] decimalBase = {10, 10, 10, 10}; + int i = 1; + + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, + MAX, REPLACEMENT, decimalBase, userData, ticketId); + + this.signedValueTester(roc, i, o, int[][].class, true, ticketId); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_10(){ + // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, JsonObject userData, String ticketId) + // -- non-decimal + int i = 1; + + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, + BASE, userData, ticketId); + + this.signedValueTester(roc, i, o, String[][].class, true, ticketId); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -615,7 +785,7 @@ public void testPositiveGenerateSignedDecimalFractions_1(){ try { HashMap o = roc.generateSignedDecimalFractions(10, 5); - signedValueTester(roc, i, o, double[].class); + this.signedValueTester(roc, i, o, double[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -631,7 +801,7 @@ public void testPositiveGenerateSignedDecimalFractions_2(){ try { HashMap o = roc.generateSignedDecimalFractions(10, 5, false); - signedValueTester(roc, i, o, double[].class); + this.signedValueTester(roc, i, o, double[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -648,7 +818,26 @@ public void testPositiveGenerateSignedDecimalFractions_3(){ try { HashMap o = roc.generateSignedDecimalFractions(10, 5, false, userData); - signedValueTester(roc, i, o, double[].class, true); + this.signedValueTester(roc, i, o, double[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedDecimalFractions_4(){ + // Testing generateSignedDecimalFractions(int n, int decimalPlaces, + // boolean replacement, JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedDecimalFractions(10, 5, false, + userData, ticketId); + + this.signedValueTester(roc, i, o, double[].class, true, ticketId); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -664,7 +853,7 @@ public void testPositiveGenerateSignedGaussians_1(){ try { HashMap o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4); - signedValueTester(roc, i, o, double[].class); + this.signedValueTester(roc, i, o, double[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -681,7 +870,26 @@ public void testPositiveGenerateSignedGaussians_2(){ try { HashMap o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4, userData); - signedValueTester(roc, i, o, double[].class, true); + this.signedValueTester(roc, i, o, double[].class, true); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedGaussians_3(){ + // Testing generateSignedGaussians(int n, double mean, double standardDeviation, + // int significantDigits, JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4, + userData, ticketId); + + this.signedValueTester(roc, i, o, double[].class, true, ticketId); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -697,7 +905,7 @@ public void testPositiveGenerateSignedStrings_1(){ try { HashMap o = roc.generateSignedStrings(10, 5, "abcd"); - signedValueTester(roc, i, o, String[].class); + this.signedValueTester(roc, i, o, String[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -713,7 +921,7 @@ public void testPositiveGenerateSignedStrings_2(){ try { HashMap o = roc.generateSignedStrings(10, 5, "abcd", false); - signedValueTester(roc, i, o, String[].class); + this.signedValueTester(roc, i, o, String[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -729,14 +937,33 @@ public void testPositiveGenerateSignedStrings_3(){ try { HashMap o = roc.generateSignedStrings(10, 5, "abcd", false, userData); - signedValueTester(roc, i, o, String[].class, true); + this.signedValueTester(roc, i, o, String[].class, true); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } i++; } } - + + @Test + public void testPositiveGenerateSignedStrings_4(){ + // Testing generateSignedStrings(int n, int length, String characters, + // boolean replacement, JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedStrings(10, 5, "abcd", false, + userData, ticketId); + + this.signedValueTester(roc, i, o, String[].class, true, ticketId); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateSignedUUIDs_1(){ // Testing generateSignedUUIDs(int n) @@ -745,7 +972,7 @@ public void testPositiveGenerateSignedUUIDs_1(){ try { HashMap o = roc.generateSignedUUIDs(10); - signedValueTester(roc, i, o, UUID[].class); + this.signedValueTester(roc, i, o, UUID[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -761,14 +988,31 @@ public void testPositiveGenerateSignedUUIDs_2(){ try { HashMap o = roc.generateSignedUUIDs(10, userData); - signedValueTester(roc, i, o, UUID[].class, true); + this.signedValueTester(roc, i, o, UUID[].class, true); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } i++; } } - + + @Test + public void testPositiveGenerateSignedUUIDs_3(){ + // Testing generateSignedUUIDs(int n, JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedUUIDs(10, userData, ticketId); + + this.signedValueTester(roc, i, o, UUID[].class, true, ticketId); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateSignedBlobs_1(){ // Testing generateSignedBlobs(int n, int size) @@ -777,7 +1021,7 @@ public void testPositiveGenerateSignedBlobs_1(){ try { HashMap o = roc.generateSignedBlobs(10, 16); - signedValueTester(roc, i, o, String[].class); + this.signedValueTester(roc, i, o, String[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -793,7 +1037,7 @@ public void testPositiveGenerateSignedBlobs_2(){ try { HashMap o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX); - signedValueTester(roc, i, o, String[].class); + this.signedValueTester(roc, i, o, String[].class); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -809,7 +1053,7 @@ public void testPositiveGenerateSignedBlobs_3(){ try { HashMap o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, userData); - signedValueTester(roc, i, o, String[].class, true); + this.signedValueTester(roc, i, o, String[].class, true); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -817,6 +1061,24 @@ public void testPositiveGenerateSignedBlobs_3(){ } } + @Test + public void testPositiveGenerateSignedBlobs_4(){ + // Testing generateSignedBlobs(int n, int size, String format, JsonObject userData, + // String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + HashMap o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + userData, ticketId); + + this.signedValueTester(roc, i, o, String[].class, true, ticketId); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } // Test additional functions @Test @@ -831,7 +1093,93 @@ public void testGetResult(){ JsonObject data = ((JsonObject)o2.get("random")).getAsJsonObject(); int[] response = new Gson().fromJson(data.get("data"), int[].class); - collector.checkThat(Arrays.equals((int[])o.get("data"), response), equalTo(true)); + collector.checkThat((int[]) o.get("data"), equalTo(response)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testCreateTickets(){ + // Testing createTickets(int n, boolean showResult) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + JsonObject[] result = roc.createTickets(1, true); + collector.checkThat(result[0], notNullValue()); + + result = roc.createTickets(1, false); + collector.checkThat(result[0], notNullValue()); + + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testListTickets(){ + // Testing listTickets(String type) for each type + int i = 1; + String[] types = {"singleton", "head", "tail"}; + JsonObject[] tickets = new JsonObject[0]; + for (RandomOrgClient roc : rocs) { + for (String t : types) { + try { + tickets = roc.listTickets(t); + if (tickets != null) { + JsonObject ticket = tickets[0]; + if (t.equals("singleton")) { + collector.checkThat(ticket.get("nextTicketId").isJsonNull(), equalTo(true)); + collector.checkThat(ticket.get("previousTicketId").isJsonNull(), equalTo(true)); + } else if (t.equals("head")) { + collector.checkThat(ticket.get("nextTicketId").isJsonNull(), equalTo(false)); + collector.checkThat(ticket.get("previousTicketId").isJsonNull(), equalTo(true)); + } else if (t.equals("tail")) { + collector.checkThat(ticket.get("nextTicketId").isJsonNull(), equalTo(true)); + collector.checkThat(ticket.get("previousTicketId").isJsonNull(), equalTo(false)); + } else { + collector.addError(new Error("Invalid ticket type. ")); + } + } + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + } + i++; + } + } + + @Test + public void testGetTicket(){ + // Testing getTicket(String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticket = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + String hiddenTicket = roc.createTickets(1, false)[0].get("ticketId").getAsString(); + + // unused ticket with showResult == true + HashMap o2 = roc.getTicket(ticket); + collector.checkThat(((JsonObject) o2.get("result")).get("result").isJsonNull(), equalTo(true)); + + // used ticket with showResult == true + HashMap o = roc.generateSignedIntegers(3, 0, 10, false, 10, null, ticket); + o2 = roc.getTicket(ticket); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + // unused ticket with showResult == false + o2 = roc.getTicket(hiddenTicket); + collector.checkThat(((JsonObject) o2.get("result")).get("usedTime").isJsonNull(), equalTo(true)); + + // used ticket with showResult == false + roc.generateSignedIntegers(3, 0, 10, false, 10, null, hiddenTicket); + o2 = roc.getTicket(hiddenTicket); + collector.checkThat(((JsonObject) o2.get("result")).has("result"), equalTo(false)); + collector.checkThat(((JsonObject) o2.get("result")).get("usedTime").isJsonNull(), equalTo(false)); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e, true))); } @@ -1257,7 +1605,7 @@ private String errorMessage(int i, Exception e, boolean networking) { * */ private void signedValueTester(RandomOrgClient roc, int i, HashMap o, Class cls) { - signedValueTester(roc, i, o, cls, false); + this.signedValueTester(roc, i, o, cls, false); } /** @@ -1273,6 +1621,24 @@ private void signedValueTester(RandomOrgClient roc, int i, HashMap o, Class cls, boolean hasUserData) { + this.signedValueTester(roc, i, o, cls, hasUserData, null); + } + + /** + * Helper function for testing methods returning signed values + * + * @param roc RandomOrgClient instance being used + * @param i index of RandomOrgClient instance in rocs + * @param o HashMap returned from call to a RandomOrgClient method + * returning signed values + * @param cls Class of the data expected to be returned from the call to the + * RandomOrgClient method + * @param hasUserData boolean stating whether the request included userData (true) or not (false) + * @param ticketId String returned from a call to {@link org.random.api.RandomOrgClient#createTickets(int n, boolean showResult) + * createTickets}. {@code null} if none is used. + * + */ + private void signedValueTester(RandomOrgClient roc, int i, HashMap o, Class cls, boolean hasUserData, String ticketId) { collector.checkThat(o, notNullValue()); collector.checkThat(o.containsKey("data"), equalTo(true)); @@ -1287,6 +1653,15 @@ private void signedValueTester(RandomOrgClient roc, int i, HashMap o2 = roc.getTicket(ticketId); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + } + try { collector.checkThat(roc.verifySignature((JsonObject)o.get("random"), (String)o.get("signature")), equalTo(true)); From 38ec489161ab1f8fe9d73468e728c91659840e4e Mon Sep 17 00:00:00 2001 From: = <=> Date: Fri, 11 Jun 2021 15:19:38 +0100 Subject: [PATCH 3/5] Release 4 Updates This library now supports Release 4 of the RANDOM.ORG JSON-RPC API. Updates: - Method overloading for all (basic and signed) value-returning methods to contain the optional 'pregeneratedRandomization' parameter - Method overloading for all signed value-returning methods to contain the optional 'licenseData' parameter - Added methods to generate the signature verification URL and HTML forms (createURL and createHTML) using the random object and signature returned from any of the signed (value generating) methods; the URL and HTML form link to the same web page that is also shown when a result is verified using the online Signature Verification Form, see: https://api.random.org/signatures/form - Added tests for methods with the 'pregeneratedRandomization' parameter --- README.rst | 6 +- .../src/org/random/api/RandomOrgClient.java | 1589 +++++++++++++++-- .../api/exception/RandomOrgJSONRPCError.java | 2 +- .../random/test/RandomOrgClientBasicTest.java | 622 ++++++- 4 files changed, 2064 insertions(+), 155 deletions(-) diff --git a/README.rst b/README.rst index 20dd923..1fac6cb 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,9 @@ JSON-RPC-Java =============== -RANDOM.ORG JSON-RPC API (Release 3) implementation. +RANDOM.ORG JSON-RPC API (Release 4) implementation. -This is a Java implementation of the RANDOM.ORG JSON-RPC API (R3). It provides either serialized or unserialized access to both the signed and unsigned methods of the API through the RandomOrgClient class. It also provides a convenience class through the RandomOrgClient class, the RandomOrgCache, for precaching requests. In the context of this module, a serialized client is one for which the sequence of requests matches the sequence of responses. +This is a Java implementation of the RANDOM.ORG JSON-RPC API (R4). It provides either serialized or unserialized access to both the signed and unsigned methods of the API through the RandomOrgClient class. It also provides a convenience class through the RandomOrgClient class, the RandomOrgCache, for precaching requests. In the context of this module, a serialized client is one for which the sequence of requests matches the sequence of responses. Installation ------------ @@ -86,7 +86,7 @@ This library now also includes a RANDOM.ORG implementation of the `java.util.Ran Documentation ------------- -For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/3 +For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/4 Tests ----- diff --git a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java index 93577ed..eefff8b 100644 --- a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java +++ b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java @@ -7,6 +7,7 @@ import java.net.MalformedURLException; import java.net.URL; import java.util.Arrays; +import java.util.Base64; import java.util.Calendar; import java.util.GregorianCalendar; import java.util.HashMap; @@ -15,6 +16,7 @@ import java.util.UUID; import java.util.logging.Level; import java.util.logging.Logger; +import java.util.regex.Pattern; import javax.net.ssl.HttpsURLConnection; @@ -47,7 +49,7 @@ * This class will only allow the creation of one instance per API key. If an instance of this class * already exists for a given key, that instance will be returned instead of a new instance. * - * This class obeys most of the guidelines set forth in https://api.random.org/json-rpc/3 + * This class obeys most of the guidelines set forth in https://api.random.org/json-rpc/4 * All requests respect the server's advisoryDelay returned in any responses, or use DEFAULT_DELAY * if no advisoryDelay is returned. If the supplied API key is paused, i.e., has exceeded its daily * bit/request allowance, this implementation will back off until midnight UTC. @@ -58,7 +60,7 @@ */ public class RandomOrgClient { - // Basic RANDOM.ORG API functions https://api.random.org/json-rpc/3/basic + // Basic RANDOM.ORG API functions https://api.random.org/json-rpc/4/basic private static final String INTEGER_METHOD = "generateIntegers"; private static final String INTEGER_SEQUENCE_METHOD = "generateIntegerSequences"; private static final String DECIMAL_FRACTION_METHOD = "generateDecimalFractions"; @@ -68,7 +70,7 @@ public class RandomOrgClient { private static final String BLOB_METHOD = "generateBlobs"; private static final String GET_USAGE_METHOD = "getUsage"; - // Signed RANDOM.ORG API functions https://api.random.org/json-rpc/3/signed + // Signed RANDOM.ORG API functions https://api.random.org/json-rpc/4/signed private static final String SIGNED_INTEGER_METHOD = "generateSignedIntegers"; private static final String SIGNED_INTEGER_SEQUENCE_METHOD = "generateSignedIntegerSequences"; private static final String SIGNED_DECIMAL_FRACTION_METHOD = "generateSignedDecimalFractions"; @@ -95,21 +97,26 @@ public class RandomOrgClient { // Default data sizes in bits private static final int UUID_SIZE = 122; - // Default parameter values + // Default values public static final boolean DEFAULT_REPLACEMENT = true; public static final int DEFAULT_INT_BASE = 10; public static final JsonObject DEFAULT_USER_DATA = null; public static final String DEFAULT_TICKET_ID = null; + public static final JsonObject DEFAULT_PREGENERATED_RANDOMIZATION = null; + public static final JsonObject DEFAULT_LICENSE_DATA = null; public static final int DEFAULT_CACHE_SIZE = 20; public static final int DEFAULT_CACHE_SIZE_SMALL = 10; //UUID and BLOB caches - + public static final long DEFAULT_BLOCKING_TIMEOUT = 24 * 60 * 60 * 1000; + public static final int DEFAULT_HTTP_TIMEOUT = 120 * 1000; + public static final int MAX_URL_LENGTH = 2046; + // Maintain a dictionary of API keys and their instances. private static HashMap keyIndexedInstances = new HashMap(); private static HashSet randomOrgErrors = new HashSet(); static { int[] ints = {100, 101, 200, 201, 202, 203, 204, 300, 301, 302, 303, 304, 305, 306, 307, - 400, 401, 402, 403, 404, 405, 420, 421, 422, 423, 500, 32000}; + 400, 401, 402, 403, 404, 405, 420, 421, 422, 423, 424, 425, 500, 32000}; for (int i : ints) { RandomOrgClient.randomOrgErrors.add(i); } @@ -153,7 +160,8 @@ public class RandomOrgClient { * @return new instance if instance doesn't already exist for this key, else existing instance. */ public static RandomOrgClient getRandomOrgClient(String apiKey) { - return RandomOrgClient.getRandomOrgClient(apiKey, 24*60*60*1000, 120*1000, true); + return RandomOrgClient.getRandomOrgClient(apiKey, DEFAULT_BLOCKING_TIMEOUT, + DEFAULT_HTTP_TIMEOUT, true); } /** @@ -227,11 +235,11 @@ public void run() { } } - // Basic methods for generating randomness, see: https://api.random.org/json-rpc/3/basic + // Basic methods for generating randomness, see: https://api.random.org/json-rpc/4/basic /** * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegers + * See: https://api.random.org/json-rpc/4/basic#generateIntegers * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -269,7 +277,7 @@ public int[] generateIntegers(int n, int min, int max) /** * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegers + * See: https://api.random.org/json-rpc/4/basic#generateIntegers * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -305,12 +313,12 @@ public int[] generateIntegers(int n, int min, int max, boolean replacement) RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.extractInts(this.integerMethod(n, min, max, replacement, DEFAULT_INT_BASE)); + return this.generateIntegers(n, min, max, replacement, DEFAULT_PREGENERATED_RANDOMIZATION); } /** * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegers + * See: https://api.random.org/json-rpc/4/basic#generateIntegers * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -350,13 +358,126 @@ public String[] generateIntegers(int n, int min, int max, boolean replacement, i RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.extractStrings(this.integerMethod(n, min, max, replacement, base)); + return this.generateIntegers(n, min, max, replacement, base, DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return an array of true random integers within a user-defined range from the server. + * See: https://api.random.org/json-rpc/4/basic#generateIntegers + * + * @param n the number of random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return int[] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[] generateIntegers(int n, int min, int max, boolean replacement, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractInts(this.integerMethod(n, min, max, replacement, DEFAULT_INT_BASE, + pregeneratedRandomization, DEFAULT_LICENSE_DATA, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); + } + + /** + * Request and return an array of true random integers within a user-defined range from the server. + * See: https://api.random.org/json-rpc/4/basic#generateIntegers + * + * @param n the number of random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). For base 10, if you would prefer an int[] to be returned instead + * of a String[], please use the {@link #generateIntegers(int n, int min, int max, + * boolean replacement) generateIntegers} method without the base parameter. + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return String[] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[] generateIntegers(int n, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractStrings(this.integerMethod(n, min, max, replacement, base, + pregeneratedRandomization, DEFAULT_LICENSE_DATA, DEFAULT_USER_DATA, + DEFAULT_TICKET_ID, false)); } /** * Request and return uniform sequences of true random integers within user-defined ranges * from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -397,7 +518,7 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max) /** * Request and return uniform sequences of true random integers within user-defined ranges * from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -435,14 +556,14 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max, boo RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.extractIntSequences(this.integerSequencesMethod(n, length, min, max, replacement, - DEFAULT_INT_BASE, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); + return this.generateIntegerSequences(n, length, min, max, replacement, + DEFAULT_PREGENERATED_RANDOMIZATION); } /** * Request and return uniform sequences of true random integers within user-defined ranges * from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -485,14 +606,135 @@ public String[][] generateIntegerSequences(int n, int length, int min, int max, RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateIntegerSequences(n, length, min, max, replacement, base, + DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return uniform sequences of true random integers within user-defined ranges + * from the server. + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return int[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.extractIntSequences(this.integerSequencesMethod(n, length, min, max, replacement, + DEFAULT_INT_BASE, pregeneratedRandomization, DEFAULT_LICENSE_DATA, DEFAULT_USER_DATA, + DEFAULT_TICKET_ID, false)); + } + + /** + * Request and return uniform sequences of true random integers within user-defined ranges + * from the server. + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 + * and 16 (default 10). For base 10, if you would prefer an int[][] to be returned + * instead of a String[][] please use the {@link #generateIntegerSequences(int n, int length, + * int min, int max, boolean replacement) generateIntegerSequences} method without + * the base parameter. + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return String[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { return this.extractIntSequencesString(this.integerSequencesMethod(n, length, - min, max, replacement, base, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); + min, max, replacement, base, pregeneratedRandomization, DEFAULT_LICENSE_DATA, + DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); } /** * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -536,7 +778,7 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma /** * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -575,17 +817,127 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateIntegerSequences(n, length, min, max, replacement, + DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param replacement an array with n Boolean values, each specifying whether the sequence + * identified by its index will be created with or without replacement. If true, the + * resulting numbers may contain duplicate values, otherwise the numbers will all be + * unique within each sequence (default true). + * @param base an array with n integer values, each specifying the base that will be used to + * display the sequence identified by its index. Values allowed are 2, 8, 10 and 16 + * (default 10). For base 10, if you require an int[][] instead of a String[][], please + * use the {@link #generateIntegerSequences(int n, int[] length, int[] min, int[] max, + * boolean[] replacement) generateIntegerSequences} method without the base parameter. + * + * @return String[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateIntegerSequences(n, length, min, max, + replacement, base, DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the sequence + * identified by its index. Each value in the array must be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of the sequence + * identified by its index. Each value in the array must be within the [-1e9,1e9] range. + * @param replacement an array with n Boolean values, each specifying whether the sequence + * identified by its index will be created with or without replacement. If true, the + * resulting numbers may contain duplicate values, otherwise the numbers will all be + * unique within each sequence (default true). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return int[][] of true random integers. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { int[] base = new int[n]; Arrays.fill(base, DEFAULT_INT_BASE); return this.extractIntSequences(this.integerSequencesMethod(n, length, min, max, replacement, - base, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); + base, pregeneratedRandomization, DEFAULT_LICENSE_DATA, DEFAULT_USER_DATA, + DEFAULT_TICKET_ID, false)); } - + /** * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. - * See: https://api.random.org/json-rpc/3/basic#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -603,7 +955,19 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma * (default 10). For base 10, if you require an int[][] instead of a String[][], please * use the {@link #generateIntegerSequences(int n, int[] length, int[] min, int[] max, * boolean[] replacement) generateIntegerSequences} method without the base parameter. - * + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * * @return String[][] of true random integers. * * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request @@ -619,7 +983,7 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base) + public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -630,14 +994,15 @@ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] MalformedURLException, IOException { return this.extractIntSequencesString(this.integerSequencesMethod(n, length, min, max, - replacement, base, DEFAULT_USER_DATA, DEFAULT_TICKET_ID, false)); + replacement, base, pregeneratedRandomization, DEFAULT_LICENSE_DATA, DEFAULT_USER_DATA, + DEFAULT_TICKET_ID, false)); } - + /** * Request and return a list (size n) of true random decimal fractions, from a uniform * distribution across the [0,1] interval with a user-defined number of decimal places * from the server. - * See: https://api.random.org/json-rpc/3/basic#generateDecimalFractions + * See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -674,7 +1039,7 @@ public double[] generateDecimalFractions(int n, int decimalPlaces) * Request and return a list (size n) of true random decimal fractions, from a uniform * distribution across the [0,1] interval with a user-defined number of decimal places * from the server. - * See: https://api.random.org/json-rpc/3/basic#generateDecimalFractions + * See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -707,11 +1072,64 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateDecimalFractions(n, decimalPlaces, replacement, DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return a list (size n) of true random decimal fractions, from a uniform + * distribution across the [0,1] interval with a user-defined number of decimal places + * from the server. + * See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return double[] of true random decimal fractions. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public double[] generateDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("decimalPlaces", decimalPlaces); request.addProperty("replacement", replacement); + request.add("pregeneratedRandomization", pregeneratedRandomization); request = this.generateKeyedRequest(request, DECIMAL_FRACTION_METHOD); @@ -724,7 +1142,7 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla * Request and return a list (size n) of true random numbers from a Gaussian distribution * (also known as a normal distribution). The form uses a Box-Muller Transform to generate * the Gaussian distribution from uniformly distributed numbers. - * See: https://api.random.org/json-rpc/3/basic#generateGaussians + * See: https://api.random.org/json-rpc/4/basic#generateGaussians * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -758,12 +1176,67 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateGaussians(n, mean, standardDeviation, significantDigits, + DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return a list (size n) of true random numbers from a Gaussian distribution + * (also known as a normal distribution). The form uses a Box-Muller Transform to generate + * the Gaussian distribution from uniformly distributed numbers. + * See: https://api.random.org/json-rpc/4/basic#generateGaussians + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return double[] of true random doubles from a Gaussian distribution. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public double[] generateGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("mean", mean); request.addProperty("standardDeviation", standardDeviation); request.addProperty("significantDigits", significantDigits); + request.add("pregeneratedRandomization", pregeneratedRandomization); request = this.generateKeyedRequest(request, GAUSSIAN_METHOD); @@ -774,7 +1247,7 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, /** * Request and return a list (size n) of true random unicode strings from the server. - * See: https://api.random.org/json-rpc/3/basic#generateStrings + * See: https://api.random.org/json-rpc/4/basic#generateStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -812,7 +1285,7 @@ public String[] generateStrings(int n, int length, String characters) /** * Request and return a list (size n) of true random unicode strings from the server. - * See: https://api.random.org/json-rpc/3/basic#generateStrings + * See: https://api.random.org/json-rpc/4/basic#generateStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -838,7 +1311,154 @@ public String[] generateStrings(int n, int length, String characters) * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public String[] generateStrings(int n, int length, String characters, boolean replacement) + public String[] generateStrings(int n, int length, String characters, boolean replacement) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateStrings(n, length, characters, replacement, DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return a list (size n) of true random unicode strings from the server. + * See: https://api.random.org/json-rpc/4/basic#generateStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to occur + * in the random strings. The maximum number of characters is 80. + * @param replacement specifies whether the random strings should be picked with replacement. + * If true, the resulting list of strings may contain duplicates, otherwise the strings + * will all be unique (default true). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return String[] of true random Strings. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public String[] generateStrings(int n, int length, String characters, boolean replacement, JsonObject pregeneratedRandomization) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject request = new JsonObject(); + + request.addProperty("n", n); + request.addProperty("length", length); + request.addProperty("characters", characters); + request.addProperty("replacement", replacement); + request.add("pregeneratedRandomization", pregeneratedRandomization); + + request = this.generateKeyedRequest(request, STRING_METHOD); + + JsonObject response = this.sendRequest(request); + + return this.extractStrings(response); + } + + /** + * Request and return a list (size n) of version 4 true random Universally Unique IDentifiers + * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. + * See: https://api.random.org/json-rpc/4/basic#generateUUIDs + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * + * @return UUID[] of true random UUIDs. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public UUID[] generateUUIDs(int n) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateUUIDs(n, DEFAULT_PREGENERATED_RANDOMIZATION); + } + + /** + * Request and return a list (size n) of version 4 true random Universally Unique IDentifiers + * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. + * See: https://api.random.org/json-rpc/4/basic#generateUUIDs + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * + * @return UUID[] of true random UUIDs. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public UUID[] generateUUIDs(int n, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -849,27 +1469,27 @@ public String[] generateStrings(int n, int length, String characters, boolean re MalformedURLException, IOException { JsonObject request = new JsonObject(); - + request.addProperty("n", n); - request.addProperty("length", length); - request.addProperty("characters", characters); - request.addProperty("replacement", replacement); + request.add("pregeneratedRandomization", pregeneratedRandomization); - request = this.generateKeyedRequest(request, STRING_METHOD); + request = this.generateKeyedRequest(request, UUID_METHOD); JsonObject response = this.sendRequest(request); - return this.extractStrings(response); + return this.extractUUIDs(response); } /** - * Request and return a list (size n) of version 4 true random Universally Unique IDentifiers - * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. - * See: https://api.random.org/json-rpc/3/basic#generateUUIDs + * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings + * containing true random data from the server. + * See: https://api.random.org/json-rpc/4/basic#generateBlobs * - * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range + * and must be divisible by 8. * - * @return UUID[] of true random UUIDs. + * @return String[] of true random blobs as Strings. * * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request * can be sent. @@ -884,7 +1504,7 @@ public String[] generateStrings(int n, int length, String characters, boolean re * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public UUID[] generateUUIDs(int n) + public String[] generateBlobs(int n, int size) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -894,25 +1514,19 @@ public UUID[] generateUUIDs(int n) RandomOrgJSONRPCError, MalformedURLException, IOException { - JsonObject request = new JsonObject(); - - request.addProperty("n", n); - - request = this.generateKeyedRequest(request, UUID_METHOD); - - JsonObject response = this.sendRequest(request); - - return this.extractUUIDs(response); + return this.generateBlobs(n, size, BLOB_FORMAT_BASE64); } /** * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings * containing true random data from the server. - * See: https://api.random.org/json-rpc/3/basic#generateBlobs + * See: https://api.random.org/json-rpc/4/basic#generateBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range * and must be divisible by 8. + * @param format specifies the format in which the blobs will be returned. Values allowed + * are BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). * * @return String[] of true random blobs as Strings. * @@ -929,7 +1543,7 @@ public UUID[] generateUUIDs(int n) * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public String[] generateBlobs(int n, int size) + public String[] generateBlobs(int n, int size, String format) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -939,20 +1553,32 @@ public String[] generateBlobs(int n, int size) RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.generateBlobs(n, size, BLOB_FORMAT_BASE64); + return this.generateBlobs(n, size, format, DEFAULT_PREGENERATED_RANDOMIZATION); } - + /** * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings * containing true random data from the server. - * See: https://api.random.org/json-rpc/3/basic#generateBlobs + * See: https://api.random.org/json-rpc/4/basic#generateBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range * and must be divisible by 8. * @param format specifies the format in which the blobs will be returned. Values allowed * are BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). - * + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * * @return String[] of true random blobs as Strings. * * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request @@ -968,7 +1594,7 @@ public String[] generateBlobs(int n, int size) * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public String[] generateBlobs(int n, int size, String format) + public String[] generateBlobs(int n, int size, String format, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -983,6 +1609,7 @@ public String[] generateBlobs(int n, int size, String format) request.addProperty("n", n); request.addProperty("size", size); request.addProperty("format", format); + request.add("pregeneratedRandomization", pregeneratedRandomization); request = this.generateKeyedRequest(request, BLOB_METHOD); @@ -991,13 +1618,13 @@ public String[] generateBlobs(int n, int size, String format) return this.extractStrings(response); } - // Signed methods for generating randomness, see: https://api.random.org/json-rpc/3/signed + // Signed methods for generating randomness, see: https://api.random.org/json-rpc/4/signed /** * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers + * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1039,7 +1666,7 @@ public HashMap generateSignedIntegers(int n, int min, int max) * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers + * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1052,8 +1679,8 @@ public HashMap generateSignedIntegers(int n, int min, int max) * * @return HashMap with "random": random JsonObject, * "signature": signature String, - * "data": random int[] - * + * "data": random int[] + * * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request * can be sent. * @throws RandomOrgKeyNotRunningError API key has been stopped. @@ -1084,7 +1711,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers + * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1134,7 +1761,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedIntegers + * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1181,19 +1808,82 @@ public HashMap generateSignedIntegers(int n, int min, int max, b RandomOrgJSONRPCError, MalformedURLException, IOException { - JsonObject request = new JsonObject(); - - request.addProperty("n", n); - request.addProperty("min", min); - request.addProperty("max", max); - request.addProperty("replacement", replacement); - request.addProperty("base", base); - request.add("userData", userData); - request.addProperty("ticketId", ticketId); - - request = this.generateKeyedRequest(request, SIGNED_INTEGER_METHOD); - - JsonObject response = this.sendRequest(request); + return this.generateSignedIntegers(n, min, max, replacement, base, DEFAULT_PREGENERATED_RANDOMIZATION, + DEFAULT_LICENSE_DATA, userData, ticketId); + } + + /** + * Request a list (size n) of true random integers within a user-defined range from the server. + * Returns a dictionary object with the parsed integer list mapped to 'data', the original + * response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers + * + * @param n how many random integers you need. Must be within the [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, + * 8, 10 and 16 (default 10). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[] if decimal (base 10) + * or random String[] if non-decimal (any other base value) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject response = this.integerMethod(n, min, max, replacement, base, pregeneratedRandomization, + licenseData, userData, ticketId, true); HashMap result = new HashMap(); if (base == 10) { @@ -1208,7 +1898,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * Request and return uniform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1253,7 +1943,7 @@ public HashMap generateSignedIntegerSequences(int n, int length, * Request and return uniform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1298,14 +1988,15 @@ public HashMap generateSignedIntegerSequences(int n, int length, RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.generateSignedIntegerSequences(n, length, min, max, replacement, base, userData, DEFAULT_TICKET_ID); + return this.generateSignedIntegerSequences(n, length, min, max, replacement, base, + userData, DEFAULT_TICKET_ID); } /** * Request and return uniform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1354,8 +2045,84 @@ public HashMap generateSignedIntegerSequences(int n, int length, RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedIntegerSequences(n, length, min, max, replacement, base, + DEFAULT_PREGENERATED_RANDOMIZATION, DEFAULT_LICENSE_DATA, userData, ticketId); + } + + /** + * Request and return uniform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length the length of each array of random integers requested. Must be within the + * [1,1e4] range. + * @param min the lower boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param max the upper boundary for the range from which the random numbers will be picked. + * Must be within the [-1e9,1e9] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). + * @param base the base that will be used to display the numbers. Values allowed are 2, 8, + * 10 and 16 (default 10). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] if decimal (base 10) + * or random String[][] if non-decimal (any other base value) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject response = this.integerSequencesMethod(n, length, min, max, - replacement, base, userData, ticketId, true); + replacement, base, pregeneratedRandomization, licenseData, userData, ticketId, true); HashMap result = new HashMap(); if (base == 10) { @@ -1371,7 +2138,7 @@ public HashMap generateSignedIntegerSequences(int n, int length, * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1421,7 +2188,7 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the @@ -1480,7 +2247,7 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * Request and return uniform or multiform sequences of true random integers within user-defined * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateIntegerSequences + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the @@ -1535,11 +2302,93 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedIntegerSequences(n, length, min, max, replacement, base, + DEFAULT_PREGENERATED_RANDOMIZATION, DEFAULT_LICENSE_DATA, userData, ticketId); + } + + /** + * Request and return uniform or multiform sequences of true random integers within user-defined + * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to + * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * + * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. + * @param length an array with n integers each specifying the length of the + * sequence identified by its index. Each value in the array must + * be within the [1,1e4] range. + * @param min an array with n integers, each specifying the lower boundary of + * the sequence identified by its index. Each value in the array must + * be within the [-1e9,1e9] range. + * @param max an array with n integers, each specifying the upper boundary of + * the sequence identified by its index. Each value in the array must + * be within the [-1e9,1e9] range. + * @param replacement an array with n Boolean values, each specifying whether + * the sequence identified by its index will be created with or without + * replacement. If true, the resulting numbers may contain + * duplicate values, otherwise the numbers will all be unique within + * each sequence (default true). + * @param base an array with n integer values, each specifying the base + * that will be used to display the sequence identified by its index. + * Values allowed are 2, 8, 10 and 16 (default 10). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, + * "data": random int[][] if decimal (all base values are 10) + * or random String[][] if non-decimal (any other mix of base values) + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { int[] defaultBase = new int[n]; Arrays.fill(defaultBase, DEFAULT_INT_BASE); JsonObject response = this.integerSequencesMethod(n, length, min, max, - replacement, base, userData, ticketId, true); + replacement, base, pregeneratedRandomization, licenseData, userData, ticketId, true); HashMap result = new HashMap(); if (Arrays.equals(base, defaultBase)) { @@ -1556,10 +2405,52 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions + * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions + * + * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. + * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedDecimalFractions(n, decimalPlaces, DEFAULT_REPLACEMENT); + } + + /** + * Request a list (size n) of true random decimal fractions, from a uniform distribution + * across the [0,1] interval with a user-defined number of decimal places from the server. + * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the + * original response mapped to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. + * @param replacement specifies whether the random numbers should be picked with replacement. + * If true, the resulting numbers may contain duplicate values, otherwise the numbers + * will all be unique (default true). * * @return HashMap with "random": random JsonObject, * "signature": signature String, "data": random double[] @@ -1577,7 +2468,7 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public HashMap generateSignedDecimalFractions(int n, int decimalPlaces) + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1587,21 +2478,23 @@ public HashMap generateSignedDecimalFractions(int n, int decimal RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.generateSignedDecimalFractions(n, decimalPlaces, DEFAULT_REPLACEMENT); + return this.generateSignedDecimalFractions(n, decimalPlaces, replacement, DEFAULT_USER_DATA); } - + /** * Request a list (size n) of true random decimal fractions, from a uniform distribution * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions + * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. * @param replacement specifies whether the random numbers should be picked with replacement. * If true, the resulting numbers may contain duplicate values, otherwise the numbers * will all be unique (default true). + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). * * @return HashMap with "random": random JsonObject, * "signature": signature String, "data": random double[] @@ -1619,7 +2512,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement) + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1629,7 +2522,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.generateSignedDecimalFractions(n, decimalPlaces, replacement, DEFAULT_USER_DATA); + return this.generateSignedDecimalFractions(n, decimalPlaces, replacement, userData, DEFAULT_TICKET_ID); } /** @@ -1637,7 +2530,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions + * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -1646,6 +2539,10 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * will all be unique (default true). * @param userData JsonObject that will be included in unmodified form. Its maximum size in * encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). * * @return HashMap with "random": random JsonObject, * "signature": signature String, "data": random double[] @@ -1663,7 +2560,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData) + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1673,7 +2570,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.generateSignedDecimalFractions(n, decimalPlaces, replacement, userData, DEFAULT_TICKET_ID); + return this.generateSignedDecimalFractions(n, decimalPlaces, replacement, DEFAULT_PREGENERATED_RANDOMIZATION, + DEFAULT_LICENSE_DATA, userData, ticketId); } /** @@ -1681,13 +2579,32 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedDecimalFractions + * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. * @param replacement specifies whether the random numbers should be picked with replacement. * If true, the resulting numbers may contain duplicate values, otherwise the numbers * will all be unique (default true). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed * @param userData JsonObject that will be included in unmodified form. Its maximum size in * encoded (String) form is 1,000 characters (default null). * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, @@ -1711,7 +2628,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData, String ticketId) + public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -1726,6 +2643,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal request.addProperty("n", n); request.addProperty("decimalPlaces", decimalPlaces); request.addProperty("replacement", replacement); + request.add("pregeneratedRandomization", pregeneratedRandomization); + request.add("licenseData", licenseData); request.add("userData", userData); request.addProperty("ticketId", ticketId); @@ -1745,7 +2664,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedGaussians + * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -1790,7 +2709,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedGaussians + * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -1837,7 +2756,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedGaussians + * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -1878,12 +2797,84 @@ public HashMap generateSignedGaussians(int n, double mean, doubl RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedGaussians(n, mean, standardDeviation, significantDigits, + DEFAULT_PREGENERATED_RANDOMIZATION, DEFAULT_LICENSE_DATA, userData, ticketId); + } + + /** + * Request a list (size n) of true random numbers from a Gaussian distribution (also known + * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian + * distribution from uniformly distributed numbers. Returns a dictionary object with the + * parsed random number list mapped to 'data', the original response mapped to 'random', + * and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians + * + * @param n how many random numbers you need. Must be within the [1,1e4] range. + * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. + * @param standardDeviation the distribution's standard deviation. Must be within the + * [-1e6,1e6] range. + * @param significantDigits the number of significant digits to use. Must be within the + * [2,20] range. + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random double[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("mean", mean); request.addProperty("standardDeviation", standardDeviation); request.addProperty("significantDigits", significantDigits); + request.add("pregeneratedRandomization", pregeneratedRandomization); + request.add("licenseData", licenseData); request.add("userData", userData); request.addProperty("ticketId", ticketId); @@ -1901,7 +2892,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings + * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1942,7 +2933,7 @@ public HashMap generateSignedStrings(int n, int length, String c * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data',the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings + * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1979,15 +2970,14 @@ public HashMap generateSignedStrings(int n, int length, String c RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.generateSignedStrings(n, length, characters, replacement, - DEFAULT_USER_DATA); + return this.generateSignedStrings(n, length, characters, replacement, DEFAULT_USER_DATA); } /** * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings + * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -2033,7 +3023,7 @@ public HashMap generateSignedStrings(int n, int length, String c * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedStrings + * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -2067,6 +3057,76 @@ public HashMap generateSignedStrings(int n, int length, String c * @throws IOException @see java.io.IOException */ public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + return this.generateSignedStrings(n, length, characters, replacement, DEFAULT_PREGENERATED_RANDOMIZATION, + DEFAULT_LICENSE_DATA, userData, ticketId); + } + + /** + * Request a list (size n) of true random strings from the server. Returns a dictionary + * object with the parsed random string list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings + * + * @param n how many random strings you need. Must be within the [1,1e4] range. + * @param length the length of each string. Must be within the [1,20] range. All strings + * will be of the same length. + * @param characters a string that contains the set of characters that are allowed to + * occur in the random strings. The maximum number of characters is 80. + * @param replacement specifies whether the random strings should be picked with replacement. + * If true, the resulting list of strings may contain duplicates, otherwise the strings + * will all be unique (default true). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -2082,6 +3142,8 @@ public HashMap generateSignedStrings(int n, int length, String c request.addProperty("length", length); request.addProperty("characters", characters); request.addProperty("replacement", replacement); + request.add("pregeneratedRandomization", pregeneratedRandomization); + request.add("licenseData", licenseData); request.add("userData", userData); request.addProperty("ticketId", ticketId); @@ -2100,7 +3162,7 @@ public HashMap generateSignedStrings(int n, int length, String c * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedUUIDs + * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @@ -2138,7 +3200,7 @@ public HashMap generateSignedUUIDs(int n) * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedUUIDs + * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @param userData JsonObject that will be included in unmodified form. Its maximum size @@ -2178,7 +3240,7 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData) * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedUUIDs + * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @param userData JsonObject that will be included in unmodified form. Its maximum size @@ -2214,9 +3276,75 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData, S RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedUUIDs(n, DEFAULT_PREGENERATED_RANDOMIZATION, DEFAULT_LICENSE_DATA, + userData, ticketId); + } + + /** + * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) + * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary + * object with the parsed random UUID list mapped to 'data', the original response mapped + * to 'random', and the response's signature mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs + * + * @param n how many random UUIDs you need. Must be within the [1,1e3] range. + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random UUID[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedUUIDs(int n, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); + request.add("pregeneratedRandomization", pregeneratedRandomization); + request.add("licenseData", licenseData); request.add("userData", userData); request.addProperty("ticketId", ticketId); @@ -2235,7 +3363,7 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData, S * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature * mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs + * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -2275,7 +3403,7 @@ public HashMap generateSignedBlobs(int n, int size) * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature * mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs + * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -2309,7 +3437,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma RandomOrgJSONRPCError, MalformedURLException, IOException { - return this.generateSignedBlobs(n, size, format, DEFAULT_USER_DATA); + return this.generateSignedBlobs(n, size, format, DEFAULT_USER_DATA); } /** @@ -2317,7 +3445,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature * mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs + * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -2361,7 +3489,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature * mapped to 'signature'. - * See: https://api.random.org/json-rpc/3/signed#generateSignedBlobs + * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -2401,11 +3529,81 @@ public HashMap generateSignedBlobs(int n, int size, String forma RandomOrgJSONRPCError, MalformedURLException, IOException { + return this.generateSignedBlobs(n, size, format, DEFAULT_PREGENERATED_RANDOMIZATION, + DEFAULT_LICENSE_DATA, userData, ticketId); + } + + /** + * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data + * from the server. Returns a dictionary object with the parsed random BLOB list mapped + * to 'data', the original response mapped to 'random', and the response's signature + * mapped to 'signature'. + * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs + * + * @param n how many random blobs you need. Must be within the [1,100] range. + * @param size the size of each blob, measured in bits. Must be within the [1,1048576] + * range and must be divisible by 8. + * @param format specifies the format in which the blobs will be returned. Values allowed + * are BLOB_FORMAT_BASE64 and BLOB_FORMAT_HEX (default BLOB_FORMAT_BASE64). + * @param pregeneratedRandomization A JsonObject which allows the client to specify that the + * random values should be generated from a pregenerated, historical randomization instead + * of a one-time on-the-fly randomization. There are three possible cases: + *
    + *
  • null: the standard way of calling for random values, i.e.true randomness is + * generated and discarded afterwards + *
  • date: RANDOM.ORG uses historical true randomness generated on the corresponding + * date (past or present, key "date" and value "YYYY-MM-DD") + *
  • id: RANDOM.ORG uses historical true randomness derived from the corresponding + * identifier in a deterministic manner. Key "id" and value is a string with length + * in the [1,64] range + *
+ * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. This is mandatory for API Keys with the + * license type "Flexible Gambling" and follows the format { "maxPayout": { "currency": + * "XTS", "amount": 0.0 } }. This information is used in licensing requested random values + * and in billing. The currently supported currencies are: "USD", "EUR", "GBP", "BTC", "ETH". + * Please check the official documentation for the most up-to-date information on this parameter: + * https://api.random.org/json-rpc/4/signed + * @param userData JsonObject that will be included in unmodified form. Its maximum size + * in encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * + * @return HashMap with "random": random JsonObject, + * "signature": signature String, "data": random String[] + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + */ + public HashMap generateSignedBlobs(int n, int size, String format, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { JsonObject request = new JsonObject(); request.addProperty("n", n); request.addProperty("size", size); request.addProperty("format", format); + request.add("pregeneratedRandomization", pregeneratedRandomization); + request.add("licenseData", licenseData); request.add("userData", userData); request.addProperty("ticketId", ticketId); @@ -2420,13 +3618,13 @@ public HashMap generateSignedBlobs(int n, int size, String forma } // Retrieve a signed result generated within the last 24h, - // see https://api.random.org/json-rpc/3/signed#getResult + // see https://api.random.org/json-rpc/4/signed#getResult /** * Retrieve signed random values generated within the last 24h, using a serial number. * If the historical response was found, a response with the result property containing * the same values that were returned by the method that was used to generate the values. - * See: https://api.random.org/json-rpc/3/signed#getResult + * See: https://api.random.org/json-rpc/4/signed#getResult * * @param serialNumber an integer containing the serial number associated with the response * you wish to retrieve. @@ -2473,7 +3671,7 @@ public HashMap getResult(int serialNumber) /** * Create n tickets to be used in signed value-generating methods. - * See: https://api.random.org/json-rpc/3/signed#createTickets + * See: https://api.random.org/json-rpc/4/signed#createTickets * * @param n The number of tickets requested. This must be a number in the [1, 50] range. * @param showResult A boolean value that determines how much information calls to {@link @@ -2523,7 +3721,7 @@ public JsonObject[] createTickets(int n, boolean showResult) /** * Obtain information about tickets linked with your API key. The maximum number of tickets * that can be returned by this method is 2000. - * See: https://api.random.org/json-rpc/3/signed#listTickets + * See: https://api.random.org/json-rpc/4/signed#listTickets * * @param ticketType A string describing the type of tickets you want to obtain information * about. Possible values are {@code singleton, head} and {@code tail}. @@ -2576,7 +3774,7 @@ public JsonObject[] listTickets(String ticketType) * Obtain information about a single ticket using the {@code ticketId} associated with it. * If the ticket has {@code showResult} set to true and has been used, this method will return the * values generated. - * See:https://api.random.org/json-rpc/3/signed#getTicket + * See:https://api.random.org/json-rpc/4/signed#getTicket * * @param ticketId A string containing a ticket identifier returned by a prior call to the * {@link #createTickets(int n, boolean showResult) createTicket} method. @@ -2690,13 +3888,13 @@ public HashMap getTicket(String ticketId) } } - // Signature verification for signed methods, see: https://api.random.org/json-rpc/3/signed + // Signature verification for signed methods, see: https://api.random.org/json-rpc/4/signed /** * Verify the signature of a response previously received from one of the methods in * the Signed API with the server. This is used to examine the authenticity of numbers. * Return True on verification success. - * See: https://api.random.org/json-rpc/3/signed#verifySignature + * See: https://api.random.org/json-rpc/4/signed#verifySignature * * @param random the random field from a response returned by RANDOM.ORG through one of * the Signed API methods. @@ -2739,6 +3937,59 @@ public boolean verifySignature(JsonObject random, String signature) return this.extractVerificationResponse(response); } + + /** + * Create the URL for the signature verification page of a response previously + * received from one of the methods in the Signed API with the server. The web-page + * accessible from this URL will contain the details of the response used in this + * method, provided that the signature can be verified. This URL is also shown + * under "Show Technical Details" when the online Signature Verification Form is + * used to validate a signature. See: https://api.random.org/signatures/form + * @param random the random field from a response returned by RANDOM.ORG through one of + * the Signed API methods. + * @param signature the signature field from the same response that the random field + * originates from. + * @return String containing the signature verification URL + * @throws RandomOrgRANDOMORGError when the URL is too long (max. 2,046 characters) + */ + public String createURL(JsonObject random, String signature) throws RandomOrgRANDOMORGError { + String formattedRandom = formatURL(random.toString()); + String formattedSignature = formatURL(signature); + + String url = "https://api.random.org/signatures/form?format=json"; + url += "&random=" + formattedRandom; + url += "&signature=" + formattedSignature; + + if (url.length() > MAX_URL_LENGTH) { + throw new RandomOrgRANDOMORGError("Error: URL exceeds maximum length" + + "(" + MAX_URL_LENGTH + " characters)."); + } + + return url; + } + + /** + * Create the HTML form for the signature verification page of a response previously + * received from one of the methods in the Signed API with the server. The web-page + * accessible from the "Validate" button created will contain the details of the + * response used in this method, provided that the signature can be verified. The + * same HTML form is also shown under "Show Technical Details" when the online + * Signature Verification Form is used to validate a signature. + * See: https://api.random.org/signatures/form + * @param random the random field from a response returned by RANDOM.ORG through + * one of the Signed API methods. + * @param signature the signature field from the same response that the random + * field originates from. + * @return string containing the code for the HTML form + */ + public String createHTML(JsonObject random, String signature) { + String s = "
\n"; + s += " " + inputHTML("hidden", "format", "json") + "\n"; + s += " " + inputHTML("hidden", "random", random.toString()) + "\n"; + s += " " + inputHTML("hidden", "signature", signature) + "\n"; + s += " \n
"; + return s; + } // Methods used to create a cache for any given randomness request. @@ -3760,7 +5011,7 @@ public int getBitsLeft() throws RandomOrgSendTimeoutException, } // Server communications & helper functions. - + /** * Issue a getUsage request to update bits and requests left. * @@ -4367,7 +5618,7 @@ protected HashMap sendRequestCore(JsonObject request) { String message = error.get("message").getAsString(); // RandomOrgAllowanceExceededError, API key not running, backoff until midnight UTC, - // from RANDOM.ORG Errors: https://api.random.org/json-rpc/3/error-codes + // from RANDOM.ORG Errors: https://api.random.org/json-rpc/4/error-codes if (code == 402) { Calendar date = new GregorianCalendar(); @@ -4392,14 +5643,14 @@ protected HashMap sendRequestCore(JsonObject request) { return ret; // RandomOrgRANDOMORGError from RANDOM.ORG Errors: - // https://api.random.org/json-rpc/3/error-codes + // https://api.random.org/json-rpc/4/error-codes } else if (RandomOrgClient.randomOrgErrors.contains(code)) { ret.put("exception", new RandomOrgRANDOMORGError("Error " + code + ": " + message)); return ret; // RandomOrgJSONRPCError from JSON-RPC Errors: - // https://api.random.org/json-rpc/3/error-codes + // https://api.random.org/json-rpc/4/error-codes } else { ret.put("exception", new RandomOrgJSONRPCError("Error " + code + ": " + message)); @@ -4409,7 +5660,7 @@ protected HashMap sendRequestCore(JsonObject request) { String method = request.get("method").getAsString(); - if (method.equals("listTickets") || method.equals("createTickets") || method.equals("getTicket")) { + if (method.equals("listTickets") || method.equals("createTickets") || method.equals("getTicket") || method.equals("getResult")) { // Set default server advisory delay synchronized (this.advisoryDelayLock) { this.advisoryDelay = RandomOrgClient.DEFAULT_DELAY; @@ -4456,7 +5707,7 @@ protected HashMap sendRequestCore(JsonObject request) { private JsonObject post(JsonObject json) throws IOException, MalformedURLException, RandomOrgBadHTTPResponseException { - HttpsURLConnection con = (HttpsURLConnection) new URL("https://api.random.org/json-rpc/3/invoke").openConnection(); + HttpsURLConnection con = (HttpsURLConnection) new URL("https://api.random.org/json-rpc/4/invoke").openConnection(); con.setConnectTimeout(this.httpTimeout); // headers @@ -4494,7 +5745,7 @@ private JsonObject post(JsonObject json) throws IOException, throw new RandomOrgBadHTTPResponseException("Error " + responseCode + ": " + con.getResponseMessage()); } - } + } /** Helper function for generateIntegers * @@ -4508,6 +5759,19 @@ private JsonObject post(JsonObject json) throws IOException, * will all be unique (default true). * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 * and 16 (default 10). + * @param pregeneratedRandomization JsonObject to determine whether random values should be + * generated from a pregenerated, historical randomization ("date" or "id") instead + * of a one-time on-the-fly randomization giving true randomness ({@code null}). + * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. + * @param userData JsonObject that will be included in unmodified form. Its maximum size in + * encoded (String) form is 1,000 characters (default null). + * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, + * boolean showResult) createTickets} method. Specifying a value for {@code ticketId} will + * cause RANDOM.ORG to record that the ticket was used to generate the requested random + * values. Each ticket can only be used once (default null). + * @param signed boolean representing whether the request uses Basic API (false) or signed + * API (true). * * @return JsonObject returned from the request * @@ -4524,7 +5788,7 @@ private JsonObject post(JsonObject json) throws IOException, * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - private JsonObject integerMethod(int n, int min, int max, boolean replacement, int base) + private JsonObject integerMethod(int n, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId, boolean signed) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -4541,8 +5805,17 @@ private JsonObject integerMethod(int n, int min, int max, boolean replacement, i request.addProperty("max", max); request.addProperty("replacement", replacement); request.addProperty("base", base); + request.add("pregeneratedRandomization", pregeneratedRandomization); - request = this.generateKeyedRequest(request, INTEGER_METHOD); + if (signed) { + request.add("licenseData", licenseData); + request.add("userData", userData); + request.addProperty("ticketId", ticketId); + + request = this.generateKeyedRequest(request, SIGNED_INTEGER_METHOD); + } else { + request = this.generateKeyedRequest(request, INTEGER_METHOD); + } return this.sendRequest(request); } @@ -4562,6 +5835,11 @@ private JsonObject integerMethod(int n, int min, int max, boolean replacement, i * will all be unique (default true). * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 * and 16 (default 10). + * @param pregeneratedRandomization JsonObject to determine whether random values should be + * generated from a pregenerated, historical randomization ("date" or "id") instead + * of a one-time on-the-fly randomization giving true randomness ({@code null}). + * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. * @param userData JsonObject that will be included in unmodified form. Its maximum size in * encoded (String) form is 1,000 characters (default null). * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, @@ -4586,7 +5864,7 @@ private JsonObject integerMethod(int n, int min, int max, boolean replacement, i * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - private JsonObject integerSequencesMethod(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData, String ticketId, boolean signed) + private JsonObject integerSequencesMethod(int n, int length, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId, boolean signed) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -4604,8 +5882,10 @@ private JsonObject integerSequencesMethod(int n, int length, int min, int max, b request.addProperty("max", max); request.addProperty("replacement", replacement); request.addProperty("base", base); + request.add("pregeneratedRandomization", pregeneratedRandomization); if (signed) { + request.add("licenseData", licenseData); request.add("userData", userData); request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_INTEGER_SEQUENCE_METHOD); @@ -4631,6 +5911,11 @@ private JsonObject integerSequencesMethod(int n, int length, int min, int max, b * will all be unique (default true). * @param base the base that will be used to display the numbers. Values allowed are 2, 8, 10 * and 16 (default 10). + * @param pregeneratedRandomization JsonObject to determine whether random values should be + * generated from a pregenerated, historical randomization ("date" or "id") instead + * of a one-time on-the-fly randomization giving true randomness ({@code null}). + * @param licenseData A JsonObject which allows the caller to include data of relevance to the + * license that is associated with the API Key. * @param userData JsonObject that will be included in unmodified form. Its maximum size in * encoded (String) form is 1,000 characters (default null). * @param ticketId A string with ticket identifier obtained via the {@link #createTickets(int n, @@ -4655,7 +5940,7 @@ private JsonObject integerSequencesMethod(int n, int length, int min, int max, b * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException */ - private JsonObject integerSequencesMethod(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData, String ticketId, boolean signed) + private JsonObject integerSequencesMethod(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId, boolean signed) throws RandomOrgSendTimeoutException, RandomOrgKeyNotRunningError, RandomOrgInsufficientRequestsError, @@ -4673,8 +5958,10 @@ private JsonObject integerSequencesMethod(int n, int[] length, int[] min, int[] request.add("max", gson.toJsonTree(max).getAsJsonArray()); request.add("replacement", gson.toJsonTree(replacement).getAsJsonArray()); request.add("base", gson.toJsonTree(base).getAsJsonArray()); + request.add("pregeneratedRandomization", pregeneratedRandomization); if (signed) { + request.add("licenseData", licenseData); request.add("userData", userData); request.addProperty("ticketId", ticketId); request = this.generateKeyedRequest(request, SIGNED_INTEGER_SEQUENCE_METHOD); @@ -4702,7 +5989,7 @@ private int max(int[] a) { /** Helper function for createIntegerSequenceCache with array ([]) parameters */ private int[] adjust(int[] a, int n) { int[] adjusted = new int[n]; - for(int i = 1, k = 0; i <= n / a.length; i++) { + for (int i = 1, k = 0; i <= n / a.length; i++) { for (int j = 0; j < a.length; j++) { adjusted[k++] = a[j]; } @@ -4713,11 +6000,33 @@ private int[] adjust(int[] a, int n) { /** Helper function for createIntegerSequenceCache with array ([]) parameters */ private boolean[] adjust(boolean[] a, int n) { boolean[] adjusted = new boolean[n]; - for(int i = 1, k = 0; i <= n / a.length; i++) { + for (int i = 1, k = 0; i <= n / a.length; i++) { for (int j = 0; j < a.length; j++) { adjusted[k++] = a[j]; } } return adjusted; } + + /** Helper function to make a string URL-safe (base64 and percent-encoding) */ + public String formatURL(String s) { + String base64Pattern = "^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$"; + boolean isBase64 = Pattern.matches(base64Pattern, s); + + if (!isBase64) { + s = Base64.getEncoder().encodeToString((s).getBytes()); + } + + // Percent-Encoding as described in RFC 3986 for PHP + s = s.replace("=", "%3D"); + s = s.replace("+", "%2B"); + s = s.replace("/", "%2F"); + + return s; + } + + /** Helper function to create a HTML input tag */ + public static String inputHTML(String type, String name, String value) { + return ""; + } } \ No newline at end of file diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java index 176276f..ce17846 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgJSONRPCError.java @@ -4,7 +4,7 @@ * Exception raised by the RandomOrgClient class when the server * returns a JSON-RPC Error. * - * @see https://api.random.org/json-rpc/2/error-codes + * @see https://api.random.org/json-rpc/4/error-codes */ public class RandomOrgJSONRPCError extends RuntimeException { diff --git a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java index 364011f..bbbd8e3 100644 --- a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java +++ b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java @@ -39,6 +39,8 @@ public class RandomOrgClientBasicTest { private static final int[] BASE = {2, 8, 10, 16}; private static JsonObject userData = new JsonObject(); + private static JsonObject identifier = new JsonObject(); + private static JsonObject date = new JsonObject(); @BeforeClass public static void testSetup() { @@ -47,6 +49,9 @@ public static void testSetup() { userData.addProperty("Test", "Text"); userData.addProperty("Test2", "Text2"); + + identifier.addProperty("id", "foo"); + date.addProperty("date", "2020-01-01"); } @Test @@ -281,6 +286,56 @@ public void testPositiveGenerateInteger_3(){ } } + @Test + public void testPositiveGenerateInteger_4(){ + // Testing generateIntgers(int n, in min, int max, boolean replacement, + // JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + int[] response = roc.generateIntegers(10, 0, 10, false, identifier); + collector.checkThat(response, notNullValue()); + + int[] response2 = roc.generateIntegers(10, 0, 10, false, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateIntegers(10, 0, 10, false, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateIntegers(10, 0, 10, false, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateInteger_5(){ + // Testing generateIntgers(int n, in min, int max, boolean replacement, int base, + // JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String[] response = roc.generateIntegers(10, 0, 10, false, 16, identifier); + collector.checkThat(response, notNullValue()); + + String[] response2 = roc.generateIntegers(10, 0, 10, false, 16, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateIntegers(10, 0, 10, false, 16, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateIntegers(10, 0, 10, false, 16, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateIntegerSequences_1(){ // Testing generateIntegerSequences(int n, int length, int min, int max) @@ -325,6 +380,56 @@ public void testPositiveGenerateIntegerSequences_3(){ @Test public void testPositiveGenerateIntegerSequences_4(){ + // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement, + // JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + int[][] response = roc.generateIntegerSequences(3, 5, 0, 10, false, identifier); + collector.checkThat(response, notNullValue()); + + int[][] response2 = roc.generateIntegerSequences(3, 5, 0, 10, false, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateIntegerSequences(3, 5, 0, 10, false, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateIntegerSequences(3, 5, 0, 10, false, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_5(){ + // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement, + // int base, JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String[][] response = roc.generateIntegerSequences(3, 5, 0, 10, false, 16, identifier); + collector.checkThat(response, notNullValue()); + + String[][] response2 = roc.generateIntegerSequences(3, 5, 0, 10, false, 16, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateIntegerSequences(3, 5, 0, 10, false, 16, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateIntegerSequences(3, 5, 0, 10, false, 16, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_6(){ // Testing generateIntegerSequences(int n, int[] length, int[] min, int[] max) int i = 1; for (RandomOrgClient roc : rocs) { @@ -338,7 +443,7 @@ public void testPositiveGenerateIntegerSequences_4(){ } @Test - public void testPositiveGenerateIntegerSequences_5(){ + public void testPositiveGenerateIntegerSequences_7(){ // Testing generateIntegerSequences(int n, int[] length, int[] min, // int[] max, boolean[] replacement) int i = 1; @@ -353,7 +458,7 @@ public void testPositiveGenerateIntegerSequences_5(){ } @Test - public void testPositiveGenerateIntegerSequences_6(){ + public void testPositiveGenerateIntegerSequences_8(){ // Testing generateIntegerSequences(int n, int[] length, int[] min, // int[] max, boolean[] replacement, int[] base) int i = 1; @@ -366,6 +471,65 @@ public void testPositiveGenerateIntegerSequences_6(){ i++; } } + + @Test + public void testPositiveGenerateIntegerSequences_9(){ + // Testing generateIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + int[][] response = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, identifier); + collector.checkThat(response, notNullValue()); + + int[][] response2 = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateIntegerSequences_10(){ + // Testing generateIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, JsonObject pregenerateRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String[][] response = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, BASE, identifier); + collector.checkThat(response, notNullValue()); + + String[][] response2 = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, BASE, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, BASE, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateIntegerSequences(4, LENGTH, MIN, MAX, + REPLACEMENT, BASE, date); + collector.checkThat(response, equalTo(response2)); + + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } @Test public void testPositiveGenerateDecimalFractions_1(){ @@ -396,7 +560,32 @@ public void testPositiveGenerateDecimalFractions_2(){ } @Test - public void testPositiveGenerateGaussians(){ + public void testPositiveGenerateDecimalFractions_3(){ + // Testing generateDecimalFractions(int n, int decimalPlaces, boolean replacement, + // JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + double[] response = roc.generateDecimalFractions(10, 5, false, identifier); + collector.checkThat(response, notNullValue()); + + double[] response2 = roc.generateDecimalFractions(10, 5, false, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateDecimalFractions(10, 5, false, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateDecimalFractions(10, 5, false, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateGaussians_1(){ // Testing generateGaussians(int n, double mean, double standardDeviation, // double significantDigits) int i = 1; @@ -409,6 +598,31 @@ public void testPositiveGenerateGaussians(){ i++; } } + + @Test + public void testPositiveGenerateGaussians_2(){ + // Testing generateGaussians(int n, double mean, double standardDeviation, + // double significantDigits, JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + double[] response = roc.generateGaussians(10, 3.41d, 2.1d, 4, identifier); + collector.checkThat(response, notNullValue()); + + double[] response2 = roc.generateGaussians(10, 3.41d, 2.1d, 4, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateGaussians(10, 3.41d, 2.1d, 4, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateGaussians(10, 3.41d, 2.1d, 4, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } @Test public void testPositiveGenerateStrings_1(){ @@ -440,7 +654,32 @@ public void testPositiveGenerateStrings_2(){ } @Test - public void testPositiveGenerateUUIDs(){ + public void testPositiveGenerateStrings_3(){ + // Testing generateStrings(int n, int length, String characters, + // boolean replacement, JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String[] response = roc.generateStrings(10, 5, "abcd", false, identifier); + collector.checkThat(response, notNullValue()); + + String[] response2 = roc.generateStrings(10, 5, "abcd", false, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateStrings(10, 5, "abcd", false, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateStrings(10, 5, "abcd", false, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateUUIDs_1(){ // Testing generateUUIDs(int n) int i = 1; for (RandomOrgClient roc : rocs) { @@ -452,6 +691,30 @@ public void testPositiveGenerateUUIDs(){ i++; } } + + @Test + public void testPositiveGenerateUUIDs_2(){ + // Testing generateUUIDs(int n, JsonObject pregeneratedRandomization) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + UUID[] response = roc.generateUUIDs(10, identifier); + collector.checkThat(response, notNullValue()); + + UUID[] response2 = roc.generateUUIDs(10, identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateUUIDs(10, date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateUUIDs(10, date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } @Test public void testPositiveGenerateBlobs_1(){ @@ -481,6 +744,34 @@ public void testPositiveGenerateBlobs_2(){ i++; } } + + @Test + public void testPositiveGenerateBlobs_3(){ + // Testing generateBlobs(int n, int size, String format) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String[] response = roc.generateBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + identifier); + collector.checkThat(response, notNullValue()); + + String[] response2 = roc.generateBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + identifier); + collector.checkThat(response, equalTo(response2)); + + response = roc.generateBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + date); + collector.checkThat(response, notNullValue()); + + response2 = roc.generateBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + date); + collector.checkThat(response, equalTo(response2)); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } // Test Functions (Signed) @@ -586,6 +877,62 @@ public void testPositiveGenerateSignedInteger_6(){ } } + @Test + public void testPositiveGenerateSignedInteger_7(){ + // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, + // int base, JsonObject pregeneratedRandomization, JsonObject licenseData, + // JsonObject userData, String ticketId) + // -- decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 10, identifier, null, + userData, null); + + this.signedValueTester(roc, i, o, int[].class, true); + + HashMap o2 = roc.generateSignedIntegers(10, 0, 10, false, 10, identifier, null, + userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedIntegers(10, 0, 10, false, 10, date, null, userData, null); + o2 = roc.generateSignedIntegers(10, 0, 10, false, 10, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedInteger_8(){ + // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, + // int base, JsonObject pregeneratedRandomization, JsonObject licensseData, + // JsonObject userData, String ticketId) + // -- non-decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegers(10, 0, 10, false, 16, identifier, null, + userData, null); + + this.signedValueTester(roc, i, o, String[].class, true); + + HashMap o2 = roc.generateSignedIntegers(10, 0, 10, false, 16, identifier, null, + userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedIntegers(10, 0, 10, false, 16, date, null, userData, null); + o2 = roc.generateSignedIntegers(10, 0, 10, false, 16, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateSignedIntegerSequences_1(){ // Testing generateSignedIntegerSequences(int n, int length, int min, int max) @@ -639,7 +986,7 @@ public void testPositiveGenerateSignedIntegerSequences_3(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_4(){ + public void testPositiveGenerateSignedIntegerSequences_4_decimal(){ // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject userData, String ticketId) // -- decimal base @@ -659,7 +1006,7 @@ public void testPositiveGenerateSignedIntegerSequences_4(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_5(){ + public void testPositiveGenerateSignedIntegerSequences_4_nondecimal(){ // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject userData, String ticketId) // -- non-decimal base @@ -678,6 +1025,62 @@ public void testPositiveGenerateSignedIntegerSequences_5(){ } } + @Test + public void testPositiveGenerateSignedIntegerSequences_5_decimal(){ + // Testing generateSignedIntegerSequences(int n, int length, int min, int max, + // boolean replacement, int base, JsonObject pregeneratedRandomization, + // JsonObject licenseData, JsonObject userData, String ticketId) + // -- decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 10, + identifier, null, userData, null); + + this.signedValueTester(roc, i, o, int[][].class, true); + + HashMap o2 = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 10, + identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 10, date, null, userData, null); + o2 = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 10, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_5_nondecimal(){ + // Testing generateSignedIntegerSequences(int n, int length, int min, int max, + // boolean replacement, int base, JsonObject pregeneratedRandomization, + // JsonObject licenseData, JsonObject userData, String ticketId) + // -- non-decimal base + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 16, + identifier, null, userData, null); + + this.signedValueTester(roc, i, o, String[][].class, true); + + HashMap o2 = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 16, + identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 16, date, null, userData, null); + o2 = roc.generateSignedIntegerSequences(3, 5, 0, 10, false, 16, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateSignedIntegerSequences_6(){ // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max) @@ -734,7 +1137,7 @@ public void testPositiveGenerateSignedIntegerSequences_8(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_9(){ + public void testPositiveGenerateSignedIntegerSequences_9_decimal(){ // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData, String ticketId) // -- decimal @@ -756,7 +1159,7 @@ public void testPositiveGenerateSignedIntegerSequences_9(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_10(){ + public void testPositiveGenerateSignedIntegerSequences_9_nondecimal(){ // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData, String ticketId) // -- non-decimal @@ -776,6 +1179,68 @@ public void testPositiveGenerateSignedIntegerSequences_10(){ } } + @Test + public void testPositiveGenerateSignedIntegerSequences_10_decimal(){ + // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, JsonObject pregeneratedRandomization, + // JsonObject licenseData, JsonObject userData, String ticketId) + // -- decimal + int[] decimalBase = {10, 10, 10, 10}; + int i = 1; + + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, + MAX, REPLACEMENT, decimalBase, identifier, null, userData, null); + + this.signedValueTester(roc, i, o, int[][].class, true); + + HashMap o2 = roc.generateSignedIntegerSequences(4, LENGTH, MIN, + MAX, REPLACEMENT, decimalBase, identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, decimalBase, + date, null, userData, null); + o2 = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, decimalBase, + date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + + @Test + public void testPositiveGenerateSignedIntegerSequences_10_nondecimal(){ + // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, + // boolean[] replacement, int[] base, JsonObject userData, String ticketId) + // -- non-decimal + int i = 1; + + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, + BASE, identifier, null, userData, null); + + this.signedValueTester(roc, i, o, String[][].class, true); + + HashMap o2 = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, + BASE, identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, BASE, + date, null, userData, null); + o2 = roc.generateSignedIntegerSequences(4, LENGTH, MIN, MAX, REPLACEMENT, BASE, + date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateSignedDecimalFractions_1(){ // Testing generateSignedDecimalFractions(int n, int decimalPlaces) @@ -844,6 +1309,33 @@ public void testPositiveGenerateSignedDecimalFractions_4(){ i++; } } + + @Test + public void testPositiveGenerateSignedDecimalFractions_5(){ + // Testing generateSignedDecimalFractions(int n, int decimalPlaces, + // boolean replacement, JsonObject pregeneratedRandomization, + // JsonObject licenseData, JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedDecimalFractions(10, 5, false, + identifier, null, userData, null); + + this.signedValueTester(roc, i, o, double[].class, true); + + HashMap o2 = roc.generateSignedDecimalFractions(10, 5, false, + identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedDecimalFractions(10, 5, false, date, null, userData, null); + o2 = roc.generateSignedDecimalFractions(10, 5, false, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } @Test public void testPositiveGenerateSignedGaussians_1(){ @@ -896,6 +1388,33 @@ public void testPositiveGenerateSignedGaussians_3(){ i++; } } + + @Test + public void testPositiveGenerateSignedGaussians_4(){ + // Testing generateSignedGaussians(int n, double mean, double standardDeviation, + // int significantDigits, JsonObject pregeneratedRandomization, JsonObject licenseData, + // JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4, + identifier, null, userData, null); + + this.signedValueTester(roc, i, o, double[].class, true); + + HashMap o2 = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4, + identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4, date, null, userData, null); + o2 = roc.generateSignedGaussians(10, 3.41d, 2.1d, 4, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } @Test public void testPositiveGenerateSignedStrings_1(){ @@ -964,6 +1483,33 @@ public void testPositiveGenerateSignedStrings_4(){ } } + @Test + public void testPositiveGenerateSignedStrings_5(){ + // Testing generateSignedStrings(int n, int length, String characters, + // boolean replacement, JsonObject pregeneratedRandomization, + // JsonObject licenseData,JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedStrings(10, 5, "abcd", false, + identifier, null, userData, null); + + this.signedValueTester(roc, i, o, String[].class, true); + + HashMap o2 = roc.generateSignedStrings(10, 5, "abcd", false, + identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedStrings(10, 5, "abcd", false, date, null, userData, null); + o2 = roc.generateSignedStrings(10, 5, "abcd", false, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateSignedUUIDs_1(){ // Testing generateSignedUUIDs(int n) @@ -1013,6 +1559,30 @@ public void testPositiveGenerateSignedUUIDs_3(){ } } + @Test + public void testPositiveGenerateSignedUUIDs_4(){ + // Testing generateSignedUUIDs(int n, JsonObject pregeneratedRandomization, + // JsonObject licenseData, JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedUUIDs(10, identifier, null, userData, null); + + this.signedValueTester(roc, i, o, UUID[].class, true); + + HashMap o2 = roc.generateSignedUUIDs(10, identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedUUIDs(10, date, null, userData, null); + o2 = roc.generateSignedUUIDs(10, date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + @Test public void testPositiveGenerateSignedBlobs_1(){ // Testing generateSignedBlobs(int n, int size) @@ -1079,6 +1649,36 @@ public void testPositiveGenerateSignedBlobs_4(){ i++; } } + + @Test + public void testPositiveGenerateSignedBlobs_5(){ + // Testing generateSignedBlobs(int n, int size, String format, + // JsonObject pregeneratedRandomization, JsonObject licenseData, + // JsonObject userData, String ticketId) + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + HashMap o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + identifier, null, userData, null); + + this.signedValueTester(roc, i, o, String[].class, true); + + HashMap o2 = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + identifier, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + + o = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + date, null, userData, null); + o2 = roc.generateSignedBlobs(10, 16, RandomOrgClient.BLOB_FORMAT_HEX, + date, null, userData, null); + collector.checkThat(o.get("data"), equalTo(o2.get("data"))); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e, true))); + } + i++; + } + } + // Test additional functions @Test @@ -1130,7 +1730,7 @@ public void testListTickets(){ for (String t : types) { try { tickets = roc.listTickets(t); - if (tickets != null) { + if (tickets != null && tickets.length > 0) { JsonObject ticket = tickets[0]; if (t.equals("singleton")) { collector.checkThat(ticket.get("nextTicketId").isJsonNull(), equalTo(true)); @@ -1249,7 +1849,7 @@ public void testIntegerCache_2(){ // int base, int cacheSize) RandomOrgCache c = rocs[0].createIntegerCache(5, 50, 100, false, 16, 5); c.stop(); - + try { c.get(); collector.addError(new Error("should have thrown NoSuchElementException")); @@ -1635,7 +2235,7 @@ private void signedValueTester(RandomOrgClient roc, int i, HashMap o, Class cls, boolean hasUserData, String ticketId) { From 6e8ecc0b1b01321470cd95662aded738e635e03a Mon Sep 17 00:00:00 2001 From: "RANDOM.ORG" Date: Fri, 17 Dec 2021 11:41:32 +0000 Subject: [PATCH 4/5] Update README.rst --- README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.rst b/README.rst index 1fac6cb..28148d6 100644 --- a/README.rst +++ b/README.rst @@ -83,6 +83,10 @@ This library now also includes a RANDOM.ORG implementation of the `java.util.Ran 6 +Signature Verification +---------------------- +There are two additional methods to generate signature verification URLs and HTML forms (*createURL* and *createHTML*) using the random object and signature returned from any of the signed (value generating) methods. The generated URLs and HTML forms link to the same web page that is also shown when a result is verified using the online `Signature Verification Form `_. + Documentation ------------- From e29869176c943f148a24937214129a8b75824843 Mon Sep 17 00:00:00 2001 From: RandomOrg Date: Tue, 11 Apr 2023 13:56:50 +0100 Subject: [PATCH 5/5] Added revealTickets method Added the new revealTickets method and the accompanying error (426). Also includes tests for the method (revealing a single ticket and multiple tickets) and the error. Updated the RandomOrgRANDOMORGError class to include the error code as a (private) property, accessible by using the getCode() method. Also updated the links in the descriptions. --- .../src/org/random/api/RandomOrgClient.java | 486 ++++++++++++------ .../exception/RandomOrgRANDOMORGError.java | 25 +- .../random/test/RandomOrgClientBasicTest.java | 325 ++++++++---- 3 files changed, 561 insertions(+), 275 deletions(-) diff --git a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java index eefff8b..faa0c05 100644 --- a/RandomJSONRPC/src/org/random/api/RandomOrgClient.java +++ b/RandomJSONRPC/src/org/random/api/RandomOrgClient.java @@ -80,6 +80,7 @@ public class RandomOrgClient { private static final String SIGNED_BLOB_METHOD = "generateSignedBlobs"; private static final String GET_RESULT_METHOD = "getResult"; private static final String CREATE_TICKET_METHOD = "createTickets"; + private static final String REVEAL_TICKETS_METHOD = "revealTickets"; private static final String LIST_TICKET_METHOD = "listTickets"; private static final String GET_TICKET_METHOD = "getTicket"; private static final String VERIFY_SIGNATURE_METHOD = "verifySignature"; @@ -116,7 +117,7 @@ public class RandomOrgClient { private static HashSet randomOrgErrors = new HashSet(); static { int[] ints = {100, 101, 200, 201, 202, 203, 204, 300, 301, 302, 303, 304, 305, 306, 307, - 400, 401, 402, 403, 404, 405, 420, 421, 422, 423, 424, 425, 500, 32000}; + 400, 401, 402, 403, 404, 405, 420, 421, 422, 423, 424, 425, 426, 500, 32000}; for (int i : ints) { RandomOrgClient.randomOrgErrors.add(i); } @@ -155,7 +156,8 @@ public class RandomOrgClient { * New instance will have a blockingTimeout of 24*60*60*1000 milliseconds, i.e., 1 day, * a httpTimeout of 120*1000 milliseconds, and will issue serialized requests. * - * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys + * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see here. * * @return new instance if instance doesn't already exist for this key, else existing instance. */ @@ -168,7 +170,8 @@ public static RandomOrgClient getRandomOrgClient(String apiKey) { * Ensure only one instance of RandomOrgClient exists per API key. Create a new instance * if the supplied key isn't already known, otherwise return the previously instantiated one. * - * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys + * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see here. * @param blockingTimeout maximum time in milliseconds to wait before being allowed to send * a request. Note this is a hint not a guarantee. Be advised advisory delay from server * must always be obeyed. Supply a value of -1 to allow blocking forever @@ -196,7 +199,8 @@ public static RandomOrgClient getRandomOrgClient(String apiKey, long blockingTim * Constructor. Initialize class and start serialized request sending Thread running as * a daemon if applicable. * - * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see: https://api.random.org/api-keys + * @param apiKey of instance to create/find, obtained from RANDOM.ORG, see here. * @param blockingTimeout maximum time in milliseconds to wait before being allowed to * send a request. Note this is a hint not a guarantee. Be advised advisory delay * from server must always be obeyed. Supply a value of -1 to allow blocking forever @@ -238,8 +242,7 @@ public void run() { // Basic methods for generating randomness, see: https://api.random.org/json-rpc/4/basic /** - * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegers + * Request and return an array of true random integers within a user-defined range from the server. * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -261,6 +264,8 @@ public void run() { * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegers */ public int[] generateIntegers(int n, int min, int max) throws RandomOrgSendTimeoutException, @@ -276,9 +281,8 @@ public int[] generateIntegers(int n, int min, int max) } /** - * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegers - * + * Request and return an array of true random integers within a user-defined range from the server. + * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. * Must be within the [-1e9,1e9] range. @@ -302,6 +306,8 @@ public int[] generateIntegers(int n, int min, int max) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegers */ public int[] generateIntegers(int n, int min, int max, boolean replacement) throws RandomOrgSendTimeoutException, @@ -317,9 +323,8 @@ public int[] generateIntegers(int n, int min, int max, boolean replacement) } /** - * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegers - * + * Request and return an array of true random integers within a user-defined range from the server. + * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. * Must be within the [-1e9,1e9] range. @@ -347,6 +352,8 @@ public int[] generateIntegers(int n, int min, int max, boolean replacement) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegers */ public String[] generateIntegers(int n, int min, int max, boolean replacement, int base) throws RandomOrgSendTimeoutException, @@ -362,9 +369,8 @@ public String[] generateIntegers(int n, int min, int max, boolean replacement, i } /** - * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegers - * + * Request and return an array of true random integers within a user-defined range from the server. + * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. * Must be within the [-1e9,1e9] range. @@ -400,6 +406,8 @@ public String[] generateIntegers(int n, int min, int max, boolean replacement, i * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegers */ public int[] generateIntegers(int n, int min, int max, boolean replacement, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -416,8 +424,7 @@ public int[] generateIntegers(int n, int min, int max, boolean replacement, Json } /** - * Request and return an array of true random integers within a user-defined range from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegers + * Request and return an array of true random integers within a user-defined range from the server. * * @param n the number of random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -458,6 +465,8 @@ public int[] generateIntegers(int n, int min, int max, boolean replacement, Json * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegers */ public String[] generateIntegers(int n, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -476,9 +485,8 @@ public String[] generateIntegers(int n, int min, int max, boolean replacement, i /** * Request and return uniform sequences of true random integers within user-defined ranges - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences - * + * from the server. + * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the * [1,1e4] range. @@ -501,6 +509,8 @@ public String[] generateIntegers(int n, int min, int max, boolean replacement, i * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public int[][] generateIntegerSequences(int n, int length, int min, int max) throws RandomOrgSendTimeoutException, @@ -517,8 +527,7 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max) /** * Request and return uniform sequences of true random integers within user-defined ranges - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -545,6 +554,8 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public int[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement) throws RandomOrgSendTimeoutException, @@ -562,8 +573,7 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max, boo /** * Request and return uniform sequences of true random integers within user-defined ranges - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -595,6 +605,8 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max, boo * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public String[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement, int base) throws RandomOrgSendTimeoutException, @@ -612,8 +624,7 @@ public String[][] generateIntegerSequences(int n, int length, int min, int max, /** * Request and return uniform sequences of true random integers within user-defined ranges - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -652,6 +663,8 @@ public String[][] generateIntegerSequences(int n, int length, int min, int max, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public int[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -670,8 +683,7 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max, boo /** * Request and return uniform sequences of true random integers within user-defined ranges - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -715,6 +727,8 @@ public int[][] generateIntegerSequences(int n, int length, int min, int max, boo * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public String[][] generateIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -733,8 +747,7 @@ public String[][] generateIntegerSequences(int n, int length, int min, int max, /** * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * ranges from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -758,6 +771,8 @@ public String[][] generateIntegerSequences(int n, int length, int min, int max, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max) throws RandomOrgSendTimeoutException, @@ -777,8 +792,7 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma /** * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * ranges from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -806,6 +820,8 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement) throws RandomOrgSendTimeoutException, @@ -823,8 +839,7 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma /** * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * ranges from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -857,6 +872,8 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base) throws RandomOrgSendTimeoutException, @@ -874,8 +891,7 @@ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] /** * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * ranges from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -915,6 +931,8 @@ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -936,8 +954,7 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma /** * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. - * See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences + * ranges from the server. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the sequence @@ -982,6 +999,8 @@ public int[][] generateIntegerSequences(int n, int[] length, int[] min, int[] ma * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateIntegerSequences */ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -1001,8 +1020,7 @@ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] /** * Request and return a list (size n) of true random decimal fractions, from a uniform * distribution across the [0,1] interval with a user-defined number of decimal places - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions + * from the server. * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -1021,6 +1039,8 @@ public String[][] generateIntegerSequences(int n, int[] length, int[] min, int[] * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateDecimalFractions */ public double[] generateDecimalFractions(int n, int decimalPlaces) throws RandomOrgSendTimeoutException, @@ -1038,8 +1058,7 @@ public double[] generateDecimalFractions(int n, int decimalPlaces) /** * Request and return a list (size n) of true random decimal fractions, from a uniform * distribution across the [0,1] interval with a user-defined number of decimal places - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions + * from the server. * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -1061,6 +1080,8 @@ public double[] generateDecimalFractions(int n, int decimalPlaces) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateDecimalFractions */ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean replacement) throws RandomOrgSendTimeoutException, @@ -1078,9 +1099,8 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla /** * Request and return a list (size n) of true random decimal fractions, from a uniform * distribution across the [0,1] interval with a user-defined number of decimal places - * from the server. - * See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions - * + * from the server. + * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. * @param replacement specifies whether the random numbers should be picked with replacement. @@ -1113,6 +1133,8 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateDecimalFractions */ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -1141,8 +1163,7 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla /** * Request and return a list (size n) of true random numbers from a Gaussian distribution * (also known as a normal distribution). The form uses a Box-Muller Transform to generate - * the Gaussian distribution from uniformly distributed numbers. - * See: https://api.random.org/json-rpc/4/basic#generateGaussians + * the Gaussian distribution from uniformly distributed numbers. * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -1165,6 +1186,8 @@ public double[] generateDecimalFractions(int n, int decimalPlaces, boolean repla * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateDecimalGaussians */ public double[] generateGaussians(int n, double mean, double standardDeviation, int significantDigits) throws RandomOrgSendTimeoutException, @@ -1183,8 +1206,7 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, /** * Request and return a list (size n) of true random numbers from a Gaussian distribution * (also known as a normal distribution). The form uses a Box-Muller Transform to generate - * the Gaussian distribution from uniformly distributed numbers. - * See: https://api.random.org/json-rpc/4/basic#generateGaussians + * the Gaussian distribution from uniformly distributed numbers. * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -1219,6 +1241,8 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateDecimalGaussians */ public double[] generateGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -1246,8 +1270,7 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, } /** - * Request and return a list (size n) of true random unicode strings from the server. - * See: https://api.random.org/json-rpc/4/basic#generateStrings + * Request and return a list (size n) of true random unicode strings from the server. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1269,6 +1292,8 @@ public double[] generateGaussians(int n, double mean, double standardDeviation, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateStrings */ public String[] generateStrings(int n, int length, String characters) throws RandomOrgSendTimeoutException, @@ -1284,8 +1309,7 @@ public String[] generateStrings(int n, int length, String characters) } /** - * Request and return a list (size n) of true random unicode strings from the server. - * See: https://api.random.org/json-rpc/4/basic#generateStrings + * Request and return a list (size n) of true random unicode strings from the server. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1310,6 +1334,8 @@ public String[] generateStrings(int n, int length, String characters) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateStrings */ public String[] generateStrings(int n, int length, String characters, boolean replacement) throws RandomOrgSendTimeoutException, @@ -1325,8 +1351,7 @@ public String[] generateStrings(int n, int length, String characters, boolean re } /** - * Request and return a list (size n) of true random unicode strings from the server. - * See: https://api.random.org/json-rpc/4/basic#generateStrings + * Request and return a list (size n) of true random unicode strings from the server. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -1363,6 +1388,8 @@ public String[] generateStrings(int n, int length, String characters, boolean re * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateStrings */ public String[] generateStrings(int n, int length, String characters, boolean replacement, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -1391,8 +1418,7 @@ public String[] generateStrings(int n, int length, String characters, boolean re /** * Request and return a list (size n) of version 4 true random Universally Unique IDentifiers - * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. - * See: https://api.random.org/json-rpc/4/basic#generateUUIDs + * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @@ -1410,6 +1436,8 @@ public String[] generateStrings(int n, int length, String characters, boolean re * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateUUIDs */ public UUID[] generateUUIDs(int n) throws RandomOrgSendTimeoutException, @@ -1426,8 +1454,7 @@ public UUID[] generateUUIDs(int n) /** * Request and return a list (size n) of version 4 true random Universally Unique IDentifiers - * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. - * See: https://api.random.org/json-rpc/4/basic#generateUUIDs + * (UUIDs) in accordance with section 4.4 of RFC 4122, from the server. * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @param pregeneratedRandomization A JsonObject which allows the client to specify that the @@ -1457,6 +1484,8 @@ public UUID[] generateUUIDs(int n) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateUUIDs */ public UUID[] generateUUIDs(int n, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -1482,8 +1511,7 @@ public UUID[] generateUUIDs(int n, JsonObject pregeneratedRandomization) /** * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings - * containing true random data from the server. - * See: https://api.random.org/json-rpc/4/basic#generateBlobs + * containing true random data from the server. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range @@ -1503,6 +1531,8 @@ public UUID[] generateUUIDs(int n, JsonObject pregeneratedRandomization) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateBlobs */ public String[] generateBlobs(int n, int size) throws RandomOrgSendTimeoutException, @@ -1519,8 +1549,7 @@ public String[] generateBlobs(int n, int size) /** * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings - * containing true random data from the server. - * See: https://api.random.org/json-rpc/4/basic#generateBlobs + * containing true random data from the server. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range @@ -1542,6 +1571,8 @@ public String[] generateBlobs(int n, int size) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateBlobs */ public String[] generateBlobs(int n, int size, String format) throws RandomOrgSendTimeoutException, @@ -1558,8 +1589,7 @@ public String[] generateBlobs(int n, int size, String format) /** * Request and return a list (size n) of Binary Large OBjects (BLOBs) as unicode strings - * containing true random data from the server. - * See: https://api.random.org/json-rpc/4/basic#generateBlobs + * containing true random data from the server. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] range @@ -1593,6 +1623,8 @@ public String[] generateBlobs(int n, int size, String format) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/basic#generateBlobs */ public String[] generateBlobs(int n, int size, String format, JsonObject pregeneratedRandomization) throws RandomOrgSendTimeoutException, @@ -1623,8 +1655,7 @@ public String[] generateBlobs(int n, int size, String format, JsonObject pregene /** * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original - * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers + * response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1648,6 +1679,8 @@ public String[] generateBlobs(int n, int size, String format, JsonObject pregene * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegers */ public HashMap generateSignedIntegers(int n, int min, int max) throws RandomOrgSendTimeoutException, @@ -1665,8 +1698,7 @@ public HashMap generateSignedIntegers(int n, int min, int max) /** * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original - * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers + * response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1693,6 +1725,8 @@ public HashMap generateSignedIntegers(int n, int min, int max) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegers */ public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement) throws RandomOrgSendTimeoutException, @@ -1710,8 +1744,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b /** * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original - * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers + * response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1743,6 +1776,8 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegers */ public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement, int base, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -1760,8 +1795,7 @@ public HashMap generateSignedIntegers(int n, int min, int max, b /** * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original - * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers + * response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. @@ -1797,6 +1831,8 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegers */ public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement, int base, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -1815,9 +1851,8 @@ public HashMap generateSignedIntegers(int n, int min, int max, b /** * Request a list (size n) of true random integers within a user-defined range from the server. * Returns a dictionary object with the parsed integer list mapped to 'data', the original - * response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers - * + * response mapped to 'random', and the response's signature mapped to 'signature'. + * * @param n how many random integers you need. Must be within the [1,1e4] range. * @param min the lower boundary for the range from which the random numbers will be picked. * Must be within the [-1e9,1e9] range. @@ -1871,6 +1906,8 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegers */ public HashMap generateSignedIntegers(int n, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -1896,9 +1933,9 @@ public HashMap generateSignedIntegers(int n, int min, int max, b /** * Request and return uniform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * ranges from the server. Returns a dictionary object with the parsed 2D integer array + * mapped to 'data', the original response mapped to 'random', and the response's + * signature mapped to 'signature'. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1924,6 +1961,8 @@ public HashMap generateSignedIntegers(int n, int min, int max, b * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int length, int min, int max) throws RandomOrgSendTimeoutException, @@ -1941,9 +1980,9 @@ public HashMap generateSignedIntegerSequences(int n, int length, /** * Request and return uniform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * ranges from the server. Returns a dictionary object with the parsed 2D integer array + * mapped to 'data', the original response mapped to 'random', and the response's + * signature mapped to 'signature'. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -1977,6 +2016,8 @@ public HashMap generateSignedIntegerSequences(int n, int length, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -1994,9 +2035,9 @@ public HashMap generateSignedIntegerSequences(int n, int length, /** * Request and return uniform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * ranges from the server. Returns a dictionary object with the parsed 2D integer array + * mapped to 'data', the original response mapped to 'random', and the response's + * signature mapped to 'signature'. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -2034,6 +2075,8 @@ public HashMap generateSignedIntegerSequences(int n, int length, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2051,9 +2094,9 @@ public HashMap generateSignedIntegerSequences(int n, int length, /** * Request and return uniform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * ranges from the server. Returns a dictionary object with the parsed 2D integer array + * mapped to 'data', the original response mapped to 'random', and the response's + * signature mapped to 'signature'. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -2110,6 +2153,8 @@ public HashMap generateSignedIntegerSequences(int n, int length, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int length, int min, int max, boolean replacement, int base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2135,10 +2180,10 @@ public HashMap generateSignedIntegerSequences(int n, int length, } /** - * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * Request and return uniform or multiform sequences of true random integers within + * user-defined ranges from the server. Returns a dictionary object with the parsed + * 2D integer array mapped to 'data', the original response mapped to 'random', and + * the response's signature mapped to 'signature'. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length the length of each array of random integers requested. Must be within the @@ -2164,6 +2209,8 @@ public HashMap generateSignedIntegerSequences(int n, int length, * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max) throws RandomOrgSendTimeoutException, @@ -2185,10 +2232,10 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt } /** - * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * Request and return uniform or multiform sequences of true random integers within + * user-defined ranges from the server. Returns a dictionary object with the parsed + * 2D integer array mapped to 'data', the original response mapped to 'random', and + * the response's signature mapped to 'signature'. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the @@ -2228,6 +2275,8 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -2244,11 +2293,11 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt } /** - * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences - * + * Request and return uniform or multiform sequences of true random integers within + * user-defined ranges from the server. Returns a dictionary object with the parsed + * 2D integer array mapped to 'data', the original response mapped to 'random', and + * the response's signature mapped to 'signature'. + * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the * sequence identified by its index. Each value in the array must @@ -2291,6 +2340,8 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2307,10 +2358,10 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt } /** - * Request and return uniform or multiform sequences of true random integers within user-defined - * ranges from the server. Returns a dictionary object with the parsed 2D integer array mapped to - * 'data', the original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences + * Request and return uniform or multiform sequences of true random integers within + * user-defined ranges from the server. Returns a dictionary object with the parsed + * 2D integer array mapped to 'data', the original response mapped to 'random', and + * the response's signature mapped to 'signature'. * * @param n how many arrays of random integers you need. Must be within the [1,1e3] range. * @param length an array with n integers each specifying the length of the @@ -2373,6 +2424,8 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedIntegerSequences */ public HashMap generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, boolean[] replacement, int[] base, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2404,8 +2457,7 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * Request a list (size n) of true random decimal fractions, from a uniform distribution * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the - * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions + * original response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -2425,6 +2477,8 @@ public HashMap generateSignedIntegerSequences(int n, int[] lengt * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions */ public HashMap generateSignedDecimalFractions(int n, int decimalPlaces) throws RandomOrgSendTimeoutException, @@ -2443,9 +2497,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * Request a list (size n) of true random decimal fractions, from a uniform distribution * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the - * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions - * + * original response mapped to 'random', and the response's signature mapped to 'signature'. + * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. * @param replacement specifies whether the random numbers should be picked with replacement. @@ -2467,6 +2520,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions */ public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement) throws RandomOrgSendTimeoutException, @@ -2485,8 +2540,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * Request a list (size n) of true random decimal fractions, from a uniform distribution * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the - * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions + * original response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -2511,6 +2565,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions */ public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -2529,8 +2585,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * Request a list (size n) of true random decimal fractions, from a uniform distribution * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the - * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions + * original response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -2559,6 +2614,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions */ public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2578,8 +2635,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * Request a list (size n) of true random decimal fractions, from a uniform distribution * across the [0,1] interval with a user-defined number of decimal places from the server. * Returns a dictionary object with the parsed decimal fraction list mapped to 'data', the - * original response mapped to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions + * original response mapped to 'random', and the response's signature mapped to 'signature'. * * @param n how many random decimal fractions you need. Must be within the [1,1e4] range. * @param decimalPlaces the number of decimal places to use. Must be within the [1,20] range. @@ -2627,6 +2683,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions */ public HashMap generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2663,8 +2721,7 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', - * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians + * and the response's signature mapped to 'signature'. * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -2688,6 +2745,8 @@ public HashMap generateSignedDecimalFractions(int n, int decimal * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedGaussians */ public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits) throws RandomOrgSendTimeoutException, @@ -2708,8 +2767,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', - * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians + * and the response's signature mapped to 'signature'. * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -2735,6 +2793,8 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedGaussians */ public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -2755,8 +2815,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', - * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians + * and the response's signature mapped to 'signature'. * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -2786,6 +2845,8 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedGaussians */ public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2806,8 +2867,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian * distribution from uniformly distributed numbers. Returns a dictionary object with the * parsed random number list mapped to 'data', the original response mapped to 'random', - * and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedGaussians + * and the response's signature mapped to 'signature'. * * @param n how many random numbers you need. Must be within the [1,1e4] range. * @param mean the distribution's mean. Must be within the [-1e6,1e6] range. @@ -2856,6 +2916,8 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedGaussians */ public HashMap generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -2891,8 +2953,7 @@ public HashMap generateSignedGaussians(int n, double mean, doubl /** * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -2915,6 +2976,8 @@ public HashMap generateSignedGaussians(int n, double mean, doubl * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedStrings */ public HashMap generateSignedStrings(int n, int length, String characters) throws RandomOrgSendTimeoutException, @@ -2932,8 +2995,7 @@ public HashMap generateSignedStrings(int n, int length, String c /** * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data',the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -2959,6 +3021,8 @@ public HashMap generateSignedStrings(int n, int length, String c * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedStrings */ public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement) throws RandomOrgSendTimeoutException, @@ -2976,8 +3040,7 @@ public HashMap generateSignedStrings(int n, int length, String c /** * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -3005,6 +3068,8 @@ public HashMap generateSignedStrings(int n, int length, String c * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedStrings */ public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -3022,8 +3087,7 @@ public HashMap generateSignedStrings(int n, int length, String c /** * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -3055,6 +3119,8 @@ public HashMap generateSignedStrings(int n, int length, String c * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedStrings */ public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -3073,8 +3139,7 @@ public HashMap generateSignedStrings(int n, int length, String c /** * Request a list (size n) of true random strings from the server. Returns a dictionary * object with the parsed random string list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedStrings + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random strings you need. Must be within the [1,1e4] range. * @param length the length of each string. Must be within the [1,20] range. All strings @@ -3125,6 +3190,8 @@ public HashMap generateSignedStrings(int n, int length, String c * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedStrings */ public HashMap generateSignedStrings(int n, int length, String characters, boolean replacement, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -3161,8 +3228,7 @@ public HashMap generateSignedStrings(int n, int length, String c * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @@ -3181,6 +3247,8 @@ public HashMap generateSignedStrings(int n, int length, String c * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedUUIDs */ public HashMap generateSignedUUIDs(int n) throws RandomOrgSendTimeoutException, @@ -3199,8 +3267,7 @@ public HashMap generateSignedUUIDs(int n) * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @param userData JsonObject that will be included in unmodified form. Its maximum size @@ -3221,6 +3288,8 @@ public HashMap generateSignedUUIDs(int n) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedUUIDs */ public HashMap generateSignedUUIDs(int n, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -3239,8 +3308,7 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData) * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @param userData JsonObject that will be included in unmodified form. Its maximum size @@ -3265,6 +3333,8 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedUUIDs */ public HashMap generateSignedUUIDs(int n, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -3284,8 +3354,7 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData, S * Request a list (size n) of version 4 true random Universally Unique IDentifiers (UUIDs) * in accordance with section 4.4 of RFC 4122, from the server. Returns a dictionary * object with the parsed random UUID list mapped to 'data', the original response mapped - * to 'random', and the response's signature mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedUUIDs + * to 'random', and the response's signature mapped to 'signature'. * * @param n how many random UUIDs you need. Must be within the [1,1e3] range. * @param pregeneratedRandomization A JsonObject which allows the client to specify that the @@ -3329,6 +3398,8 @@ public HashMap generateSignedUUIDs(int n, JsonObject userData, S * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedUUIDs */ public HashMap generateSignedUUIDs(int n, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -3362,8 +3433,7 @@ public HashMap generateSignedUUIDs(int n, JsonObject pregenerate * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature - * mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs + * mapped to 'signature'. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -3384,6 +3454,8 @@ public HashMap generateSignedUUIDs(int n, JsonObject pregenerate * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedBlobs */ public HashMap generateSignedBlobs(int n, int size) throws RandomOrgSendTimeoutException, @@ -3402,8 +3474,7 @@ public HashMap generateSignedBlobs(int n, int size) * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature - * mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs + * mapped to 'signature'. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -3426,6 +3497,8 @@ public HashMap generateSignedBlobs(int n, int size) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedBlobs */ public HashMap generateSignedBlobs(int n, int size, String format) throws RandomOrgSendTimeoutException, @@ -3444,8 +3517,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature - * mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs + * mapped to 'signature'. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -3470,6 +3542,8 @@ public HashMap generateSignedBlobs(int n, int size, String forma * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedBlobs */ public HashMap generateSignedBlobs(int n, int size, String format, JsonObject userData) throws RandomOrgSendTimeoutException, @@ -3488,8 +3562,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature - * mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs + * mapped to 'signature'. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -3518,6 +3591,8 @@ public HashMap generateSignedBlobs(int n, int size, String forma * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedBlobs */ public HashMap generateSignedBlobs(int n, int size, String format, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -3537,8 +3612,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma * Request a list (size n) of Binary Large OBjects (BLOBs) containing true random data * from the server. Returns a dictionary object with the parsed random BLOB list mapped * to 'data', the original response mapped to 'random', and the response's signature - * mapped to 'signature'. - * See: https://api.random.org/json-rpc/4/signed#generateSignedBlobs + * mapped to 'signature'. * * @param n how many random blobs you need. Must be within the [1,100] range. * @param size the size of each blob, measured in bits. Must be within the [1,1048576] @@ -3586,6 +3660,8 @@ public HashMap generateSignedBlobs(int n, int size, String forma * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#generateSignedBlobs */ public HashMap generateSignedBlobs(int n, int size, String format, JsonObject pregeneratedRandomization, JsonObject licenseData, JsonObject userData, String ticketId) throws RandomOrgSendTimeoutException, @@ -3623,8 +3699,7 @@ public HashMap generateSignedBlobs(int n, int size, String forma /** * Retrieve signed random values generated within the last 24h, using a serial number. * If the historical response was found, a response with the result property containing - * the same values that were returned by the method that was used to generate the values. - * See: https://api.random.org/json-rpc/4/signed#getResult + * the same values that were returned by the method that was used to generate the values. * * @param serialNumber an integer containing the serial number associated with the response * you wish to retrieve. @@ -3643,6 +3718,8 @@ public HashMap generateSignedBlobs(int n, int size, String forma * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#getResult */ public HashMap getResult(int serialNumber) throws RandomOrgSendTimeoutException, @@ -3670,8 +3747,7 @@ public HashMap getResult(int serialNumber) // Ticket methods /** - * Create n tickets to be used in signed value-generating methods. - * See: https://api.random.org/json-rpc/4/signed#createTickets + * Create n tickets to be used in signed value-generating methods. * * @param n The number of tickets requested. This must be a number in the [1, 50] range. * @param showResult A boolean value that determines how much information calls to {@link @@ -3694,6 +3770,8 @@ public HashMap getResult(int serialNumber) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#createTickets */ public JsonObject[] createTickets(int n, boolean showResult) throws RandomOrgSendTimeoutException, @@ -3718,10 +3796,68 @@ public JsonObject[] createTickets(int n, boolean showResult) return this.extractTickets(response); } + /** + * This method marks a specific ticket and all its predecessors in its chain as + * being revealed, meaning that subsequent calls to {@link #getTicket(String ticketId) + * getTicket} will return the full details of the tickets, including the random + * values produced when the tickets were used. Using this method effectively + * changes the value of {@code showResult} (which was specified when the first + * ticket in the chain was created using {@link #createTickets(int n, boolean showResult) + * createTicket}) from {@code false} to {@code true}. The reason that not only + * the ticket specified (but also its predecessors in its chain) are revealed + * is to ensure maximum transparency. This method does not affect any successors + * to the ticket in the chain. + *

+ * If this method is used on a ticket that has not yet been used, a RandomOrgRANDOMORGError + * (426) will be thrown. + * + * @param ticketId A string value that uniquely identifies the ticket. + * + * @return int A number value that specifies how many tickets were revealed. This + * will include the ticket specified as well as all its predecessors. If + * this method is invoked on a ticket that is already revealed (or which + * was created with {@code howResult} set to {@code true}), then the value + * returned will be zero. + * + * @throws RandomOrgSendTimeoutException blocking timeout is exceeded before the request + * can be sent. + * @throws RandomOrgKeyNotRunningError API key has been stopped. + * @throws RandomOrgInsufficientRequestsError API key's server requests allowance has + * been exceeded. + * @throws RandomOrgInsufficientBitsError API key's server bits allowance has been exceeded. + * @throws RandomOrgBadHTTPResponseException if a HTTP 200 OK response not received. + * @throws RandomOrgRANDOMORGError server returns a RANDOM.ORG Error. + * @throws RandomOrgJSONRPCError server returns a JSON-RPC Error. + * @throws MalformedURLException in the unlikely event something goes wrong with URL + * creation. @see java.net.MalformedURLException + * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#revealTickets + */ + public int revealTickets(String ticketId) + throws RandomOrgSendTimeoutException, + RandomOrgKeyNotRunningError, + RandomOrgInsufficientRequestsError, + RandomOrgInsufficientBitsError, + RandomOrgBadHTTPResponseException, + RandomOrgRANDOMORGError, + RandomOrgJSONRPCError, + MalformedURLException, + IOException { + JsonObject request = new JsonObject(); + + request.addProperty("ticketId", ticketId); + + request = this.generateKeyedRequest(request, REVEAL_TICKETS_METHOD); + + JsonObject response = this.sendRequest(request); + + return this.extractTicketCount(response); + } + /** * Obtain information about tickets linked with your API key. The maximum number of tickets - * that can be returned by this method is 2000. - * See: https://api.random.org/json-rpc/4/signed#listTickets + * that can be returned by this method is 2000. * * @param ticketType A string describing the type of tickets you want to obtain information * about. Possible values are {@code singleton, head} and {@code tail}. @@ -3747,6 +3883,8 @@ public JsonObject[] createTickets(int n, boolean showResult) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#listTickets */ public JsonObject[] listTickets(String ticketType) throws RandomOrgSendTimeoutException, @@ -3773,8 +3911,7 @@ public JsonObject[] listTickets(String ticketType) /** * Obtain information about a single ticket using the {@code ticketId} associated with it. * If the ticket has {@code showResult} set to true and has been used, this method will return the - * values generated. - * See:https://api.random.org/json-rpc/4/signed#getTicket + * values generated. * * @param ticketId A string containing a ticket identifier returned by a prior call to the * {@link #createTickets(int n, boolean showResult) createTicket} method. @@ -3805,6 +3942,8 @@ public JsonObject[] listTickets(String ticketType) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#getTicket */ public HashMap getTicket(String ticketId) throws RandomOrgSendTimeoutException, @@ -3893,8 +4032,7 @@ public HashMap getTicket(String ticketId) /** * Verify the signature of a response previously received from one of the methods in * the Signed API with the server. This is used to examine the authenticity of numbers. - * Return True on verification success. - * See: https://api.random.org/json-rpc/4/signed#verifySignature + * Return True on verification success. * * @param random the random field from a response returned by RANDOM.ORG through one of * the Signed API methods. @@ -3915,6 +4053,8 @@ public HashMap getTicket(String ticketId) * @throws MalformedURLException in the unlikely event something goes wrong with URL * creation. @see java.net.MalformedURLException * @throws IOException @see java.io.IOException + * @see + * https://api.random.org/json-rpc/4/signed#verifySignature */ public boolean verifySignature(JsonObject random, String signature) throws RandomOrgSendTimeoutException, @@ -3944,13 +4084,16 @@ public boolean verifySignature(JsonObject random, String signature) * accessible from this URL will contain the details of the response used in this * method, provided that the signature can be verified. This URL is also shown * under "Show Technical Details" when the online Signature Verification Form is - * used to validate a signature. See: https://api.random.org/signatures/form + * used to validate a signature. + * * @param random the random field from a response returned by RANDOM.ORG through one of * the Signed API methods. * @param signature the signature field from the same response that the random field * originates from. * @return String containing the signature verification URL * @throws RandomOrgRANDOMORGError when the URL is too long (max. 2,046 characters) + * @see + * https://api.random.org/signatures/form */ public String createURL(JsonObject random, String signature) throws RandomOrgRANDOMORGError { String formattedRandom = formatURL(random.toString()); @@ -3975,12 +4118,14 @@ public String createURL(JsonObject random, String signature) throws RandomOrgRAN * response used in this method, provided that the signature can be verified. The * same HTML form is also shown under "Show Technical Details" when the online * Signature Verification Form is used to validate a signature. - * See: https://api.random.org/signatures/form + * * @param random the random field from a response returned by RANDOM.ORG through * one of the Signed API methods. * @param signature the signature field from the same response that the random * field originates from. * @return string containing the code for the HTML form + * @see + * https://api.random.org/signatures/form */ public String createHTML(JsonObject random, String signature) { String s = "

\n"; @@ -5244,6 +5389,17 @@ private HashMap extractSignedResponse(JsonObject response, HashM private boolean extractVerificationResponse(JsonObject response) { return response.get("result").getAsJsonObject().get("authenticity").getAsBoolean(); } + + /** + * Gets the response from the revealTickets method, i.e., the number + * of tickets that were revealed. + * + * @param response JSON from which to extract the revealTicket response. + * @return the number of tickets revealed. + */ + private int extractTicketCount(JsonObject response) { + return response.get("result").getAsJsonObject().get("ticketCount").getAsInt(); + } /** * Send request as determined by serialized boolean. @@ -5646,7 +5802,7 @@ protected HashMap sendRequestCore(JsonObject request) { // https://api.random.org/json-rpc/4/error-codes } else if (RandomOrgClient.randomOrgErrors.contains(code)) { ret.put("exception", new RandomOrgRANDOMORGError("Error " + code - + ": " + message)); + + ": " + message, code)); return ret; // RandomOrgJSONRPCError from JSON-RPC Errors: diff --git a/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java b/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java index f464b2e..68fd263 100644 --- a/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java +++ b/RandomJSONRPC/src/org/random/api/exception/RandomOrgRANDOMORGError.java @@ -4,10 +4,11 @@ * Exception raised by the RandomOrgClient class when the server * returns a RANDOM.ORG Error. * - * @see https://api.random.org/json-rpc/2/error-codes + * @see https://api.random.org/json-rpc/4/error-codes */ public class RandomOrgRANDOMORGError extends RuntimeException { - + int code = -1; + /** * Constructs a new exception with the specified detail message. * @@ -16,4 +17,24 @@ public class RandomOrgRANDOMORGError extends RuntimeException { public RandomOrgRANDOMORGError(String message) { super(message); } + + /** + * Constructs a new exception with the specified detail message and + * error code. + * + * @param message @see java.lang.Exception#Exception(java.lang.String) + * @param code The error code as specified here: https://api.random.org/json-rpc/4/error-codes + */ + public RandomOrgRANDOMORGError(String message, int code) { + super(message); + this.code = code; + } + + /** + * Returns the error code (or -1 if none was specified). See here for + * more information: https://api.random.org/json-rpc/4/error-codes + */ + public int getCode() { + return code; + } } \ No newline at end of file diff --git a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java index bbbd8e3..e428190 100644 --- a/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java +++ b/RandomJSONRPC/src/org/random/test/RandomOrgClientBasicTest.java @@ -1,6 +1,7 @@ package org.random.test; import java.util.HashMap; +import java.util.Map; import java.util.NoSuchElementException; import java.util.UUID; @@ -81,7 +82,7 @@ public void testAPIKeyDuplication() { @Test - public void testPositiveGetBitsLeft(){ + public void testPositiveGetBitsLeft() { int i = 1; for (RandomOrgClient roc : rocs) { try { @@ -98,14 +99,14 @@ public void testPositiveGetBitsLeft(){ // Test Errors @Test - public void testNegativeErrorMessage202(){ + public void testNegativeErrorMessage202() { int i = 1; for (RandomOrgClient roc : rocs) { try { roc.generateIntegers(100000, 0, 10); collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 202); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -114,14 +115,14 @@ public void testNegativeErrorMessage202(){ } @Test - public void testNegativeErrorMessage203(){ + public void testNegativeErrorMessage203() { int i = 1; for (RandomOrgClient roc : rocs) { try { roc.generateIntegerSequences(3, LENGTH, MIN, MAX); collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 203); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -130,14 +131,14 @@ public void testNegativeErrorMessage203(){ } @Test - public void testNegativeErrorMessage204(){ + public void testNegativeErrorMessage204() { int i = 1; for (RandomOrgClient roc : rocs) { try { roc.generateIntegerSequences(4, new int[] {1}, MIN, MAX); collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 204); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -146,14 +147,14 @@ public void testNegativeErrorMessage204(){ } @Test - public void testNegativeErrorMessage300(){ + public void testNegativeErrorMessage300() { int i = 1; for (RandomOrgClient roc : rocs) { try { roc.generateIntegers(10, 10, 0); collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 300); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -162,14 +163,14 @@ public void testNegativeErrorMessage300(){ } @Test - public void testNegativeErrorMessage301(){ + public void testNegativeErrorMessage301() { int i = 1; for (RandomOrgClient roc : rocs) { try { roc.generateIntegers(20, 0, 10, false); collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 301); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -178,27 +179,27 @@ public void testNegativeErrorMessage301(){ } @Test - public void testNegativeErrorMessage400(){ - try{ + public void testNegativeErrorMessage400() { + try { RandomOrgClient rpc2 = RandomOrgClient.getRandomOrgClient("ffffffff-ffff-ffff-ffff-ffffffffffff"); rpc2.generateIntegers(1, 0, 1); collector.addError(new Error(errorMessage())); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 400); } catch (Exception e) { collector.addError(new Error(errorMessage(e))); } } @Test - public void testNegativeErrorMessage420(){ + public void testNegativeErrorMessage420() { int i = 1; for (RandomOrgClient roc : rocs) { try { roc.generateSignedIntegers(5, 0, 10, false, 10, null, "ffffffffffffffff"); collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 420); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -207,14 +208,14 @@ public void testNegativeErrorMessage420(){ } @Test - public void testNegativeErrorMessage421(){ + public void testNegativeErrorMessage421() { int i = 1; for (RandomOrgClient roc : rocs) { try { roc.generateSignedIntegers(5, 0, 10, false, 10, null, "d5b8f6d03f99a134"); collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 421); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -223,7 +224,7 @@ public void testNegativeErrorMessage421(){ } @Test - public void testNegativeErrorMessage422(){ + public void testNegativeErrorMessage422() { int i = 1; for (RandomOrgClient roc : rocs) { try { @@ -234,7 +235,25 @@ public void testNegativeErrorMessage422(){ collector.addError(new Error(errorMessage(i))); } catch(RandomOrgRANDOMORGError e) { - System.out.println(e.getMessage()); + negativeErrorHandler(e, 422); + } catch (Exception e) { + collector.addError(new Error(errorMessage(i, e))); + } + i++; + } + } + + @Test + public void testNegativeErrorMessage426() { + int i = 1; + for (RandomOrgClient roc : rocs) { + try { + String ticketId = roc.createTickets(1, true)[0].get("ticketId").getAsString(); + roc.revealTickets(ticketId); + + collector.addError(new Error(errorMessage(i))); + } catch(RandomOrgRANDOMORGError e) { + negativeErrorHandler(e, 426); } catch (Exception e) { collector.addError(new Error(errorMessage(i, e))); } @@ -243,9 +262,9 @@ public void testNegativeErrorMessage422(){ } // Test Functions - + @Test - public void testPositiveGenerateInteger_1(){ + public void testPositiveGenerateInteger_1() { // Testing generateIntgers(int n, in min, int max) int i = 1; for (RandomOrgClient roc : rocs) { @@ -259,7 +278,7 @@ public void testPositiveGenerateInteger_1(){ } @Test - public void testPositiveGenerateInteger_2(){ + public void testPositiveGenerateInteger_2() { // Testing generateIntgers(int n, in min, int max, boolean replacement) int i = 1; for (RandomOrgClient roc : rocs) { @@ -273,7 +292,7 @@ public void testPositiveGenerateInteger_2(){ } @Test - public void testPositiveGenerateInteger_3(){ + public void testPositiveGenerateInteger_3() { // Testing generateIntgers(int n, in min, int max, boolean replacement, int base) int i = 1; for (RandomOrgClient roc : rocs) { @@ -287,7 +306,7 @@ public void testPositiveGenerateInteger_3(){ } @Test - public void testPositiveGenerateInteger_4(){ + public void testPositiveGenerateInteger_4() { // Testing generateIntgers(int n, in min, int max, boolean replacement, // JsonObject pregeneratedRandomization) int i = 1; @@ -312,7 +331,7 @@ public void testPositiveGenerateInteger_4(){ } @Test - public void testPositiveGenerateInteger_5(){ + public void testPositiveGenerateInteger_5() { // Testing generateIntgers(int n, in min, int max, boolean replacement, int base, // JsonObject pregeneratedRandomization) int i = 1; @@ -337,7 +356,7 @@ public void testPositiveGenerateInteger_5(){ } @Test - public void testPositiveGenerateIntegerSequences_1(){ + public void testPositiveGenerateIntegerSequences_1() { // Testing generateIntegerSequences(int n, int length, int min, int max) int i = 1; for (RandomOrgClient roc : rocs) { @@ -351,7 +370,7 @@ public void testPositiveGenerateIntegerSequences_1(){ } @Test - public void testPositiveGenerateIntegerSequences_2(){ + public void testPositiveGenerateIntegerSequences_2() { // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement) int i = 1; for (RandomOrgClient roc : rocs) { @@ -365,7 +384,7 @@ public void testPositiveGenerateIntegerSequences_2(){ } @Test - public void testPositiveGenerateIntegerSequences_3(){ + public void testPositiveGenerateIntegerSequences_3() { // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement, int base) int i = 1; for (RandomOrgClient roc : rocs) { @@ -379,7 +398,7 @@ public void testPositiveGenerateIntegerSequences_3(){ } @Test - public void testPositiveGenerateIntegerSequences_4(){ + public void testPositiveGenerateIntegerSequences_4() { // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement, // JsonObject pregeneratedRandomization) int i = 1; @@ -404,7 +423,7 @@ public void testPositiveGenerateIntegerSequences_4(){ } @Test - public void testPositiveGenerateIntegerSequences_5(){ + public void testPositiveGenerateIntegerSequences_5() { // Testing generateIntegerSequences(int n, int length, int min, int max, boolean replacement, // int base, JsonObject pregeneratedRandomization) int i = 1; @@ -429,7 +448,7 @@ public void testPositiveGenerateIntegerSequences_5(){ } @Test - public void testPositiveGenerateIntegerSequences_6(){ + public void testPositiveGenerateIntegerSequences_6() { // Testing generateIntegerSequences(int n, int[] length, int[] min, int[] max) int i = 1; for (RandomOrgClient roc : rocs) { @@ -443,7 +462,7 @@ public void testPositiveGenerateIntegerSequences_6(){ } @Test - public void testPositiveGenerateIntegerSequences_7(){ + public void testPositiveGenerateIntegerSequences_7() { // Testing generateIntegerSequences(int n, int[] length, int[] min, // int[] max, boolean[] replacement) int i = 1; @@ -458,7 +477,7 @@ public void testPositiveGenerateIntegerSequences_7(){ } @Test - public void testPositiveGenerateIntegerSequences_8(){ + public void testPositiveGenerateIntegerSequences_8() { // Testing generateIntegerSequences(int n, int[] length, int[] min, // int[] max, boolean[] replacement, int[] base) int i = 1; @@ -473,7 +492,7 @@ public void testPositiveGenerateIntegerSequences_8(){ } @Test - public void testPositiveGenerateIntegerSequences_9(){ + public void testPositiveGenerateIntegerSequences_9() { // Testing generateIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, JsonObject pregeneratedRandomization) int i = 1; @@ -502,7 +521,7 @@ public void testPositiveGenerateIntegerSequences_9(){ } @Test - public void testPositiveGenerateIntegerSequences_10(){ + public void testPositiveGenerateIntegerSequences_10() { // Testing generateIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject pregenerateRandomization) int i = 1; @@ -532,7 +551,7 @@ public void testPositiveGenerateIntegerSequences_10(){ } @Test - public void testPositiveGenerateDecimalFractions_1(){ + public void testPositiveGenerateDecimalFractions_1() { // Testing generateDecimalFractions(int n, int decimalPlaces) int i = 1; for (RandomOrgClient roc : rocs) { @@ -546,7 +565,7 @@ public void testPositiveGenerateDecimalFractions_1(){ } @Test - public void testPositiveGenerateDecimalFractions_2(){ + public void testPositiveGenerateDecimalFractions_2() { // Testing generateDecimalFractions(int n, int decimalPlaces, boolean replacement) int i = 1; for (RandomOrgClient roc : rocs) { @@ -560,7 +579,7 @@ public void testPositiveGenerateDecimalFractions_2(){ } @Test - public void testPositiveGenerateDecimalFractions_3(){ + public void testPositiveGenerateDecimalFractions_3() { // Testing generateDecimalFractions(int n, int decimalPlaces, boolean replacement, // JsonObject pregeneratedRandomization) int i = 1; @@ -585,7 +604,7 @@ public void testPositiveGenerateDecimalFractions_3(){ } @Test - public void testPositiveGenerateGaussians_1(){ + public void testPositiveGenerateGaussians_1() { // Testing generateGaussians(int n, double mean, double standardDeviation, // double significantDigits) int i = 1; @@ -600,7 +619,7 @@ public void testPositiveGenerateGaussians_1(){ } @Test - public void testPositiveGenerateGaussians_2(){ + public void testPositiveGenerateGaussians_2() { // Testing generateGaussians(int n, double mean, double standardDeviation, // double significantDigits, JsonObject pregeneratedRandomization) int i = 1; @@ -625,7 +644,7 @@ public void testPositiveGenerateGaussians_2(){ } @Test - public void testPositiveGenerateStrings_1(){ + public void testPositiveGenerateStrings_1() { // Testing generateStrings(int n, int length, String characters) int i = 1; for (RandomOrgClient roc : rocs) { @@ -639,7 +658,7 @@ public void testPositiveGenerateStrings_1(){ } @Test - public void testPositiveGenerateStrings_2(){ + public void testPositiveGenerateStrings_2() { // Testing generateStrings(int n, int length, String characters, // boolean replacement) int i = 1; @@ -654,7 +673,7 @@ public void testPositiveGenerateStrings_2(){ } @Test - public void testPositiveGenerateStrings_3(){ + public void testPositiveGenerateStrings_3() { // Testing generateStrings(int n, int length, String characters, // boolean replacement, JsonObject pregeneratedRandomization) int i = 1; @@ -679,7 +698,7 @@ public void testPositiveGenerateStrings_3(){ } @Test - public void testPositiveGenerateUUIDs_1(){ + public void testPositiveGenerateUUIDs_1() { // Testing generateUUIDs(int n) int i = 1; for (RandomOrgClient roc : rocs) { @@ -693,7 +712,7 @@ public void testPositiveGenerateUUIDs_1(){ } @Test - public void testPositiveGenerateUUIDs_2(){ + public void testPositiveGenerateUUIDs_2() { // Testing generateUUIDs(int n, JsonObject pregeneratedRandomization) int i = 1; for (RandomOrgClient roc : rocs) { @@ -717,7 +736,7 @@ public void testPositiveGenerateUUIDs_2(){ } @Test - public void testPositiveGenerateBlobs_1(){ + public void testPositiveGenerateBlobs_1() { // Testing generateBlobs(int n, int size) int i = 1; for (RandomOrgClient roc : rocs) { @@ -731,7 +750,7 @@ public void testPositiveGenerateBlobs_1(){ } @Test - public void testPositiveGenerateBlobs_2(){ + public void testPositiveGenerateBlobs_2() { // Testing generateBlobs(int n, int size, String format) int i = 1; for (RandomOrgClient roc : rocs) { @@ -746,7 +765,7 @@ public void testPositiveGenerateBlobs_2(){ } @Test - public void testPositiveGenerateBlobs_3(){ + public void testPositiveGenerateBlobs_3() { // Testing generateBlobs(int n, int size, String format) int i = 1; for (RandomOrgClient roc : rocs) { @@ -792,7 +811,7 @@ public void testPositiveGenerateSignedInteger_1() { } @Test - public void testPositiveGenerateSignedInteger_2(){ + public void testPositiveGenerateSignedInteger_2() { // Testing generateSignedStrings(int n, int min, int max, boolean replacement) int i = 1; for (RandomOrgClient roc : rocs) { @@ -808,7 +827,7 @@ public void testPositiveGenerateSignedInteger_2(){ } @Test - public void testPositiveGenerateSignedInteger_3(){ + public void testPositiveGenerateSignedInteger_3() { // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, // int base, JsonObject userData) -- decimal base int i = 1; @@ -825,7 +844,7 @@ public void testPositiveGenerateSignedInteger_3(){ } @Test - public void testPositiveGenerateSignedInteger_4(){ + public void testPositiveGenerateSignedInteger_4() { // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, // int base, JsonObject userData) -- non-decimal base int i = 1; @@ -842,7 +861,7 @@ public void testPositiveGenerateSignedInteger_4(){ } @Test - public void testPositiveGenerateSignedInteger_5(){ + public void testPositiveGenerateSignedInteger_5() { // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, // int base, JsonObject userData, String ticketId) -- decimal base int i = 1; @@ -860,7 +879,7 @@ public void testPositiveGenerateSignedInteger_5(){ } @Test - public void testPositiveGenerateSignedInteger_6(){ + public void testPositiveGenerateSignedInteger_6() { // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, // int base, JsonObject userData, String ticketId) -- non-decimal base int i = 1; @@ -878,7 +897,7 @@ public void testPositiveGenerateSignedInteger_6(){ } @Test - public void testPositiveGenerateSignedInteger_7(){ + public void testPositiveGenerateSignedInteger_7() { // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, // int base, JsonObject pregeneratedRandomization, JsonObject licenseData, // JsonObject userData, String ticketId) @@ -906,7 +925,7 @@ public void testPositiveGenerateSignedInteger_7(){ } @Test - public void testPositiveGenerateSignedInteger_8(){ + public void testPositiveGenerateSignedInteger_8() { // Testing generateSignedIntegers(int n, int min, int max, boolean replacement, // int base, JsonObject pregeneratedRandomization, JsonObject licensseData, // JsonObject userData, String ticketId) @@ -934,7 +953,7 @@ public void testPositiveGenerateSignedInteger_8(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_1(){ + public void testPositiveGenerateSignedIntegerSequences_1() { // Testing generateSignedIntegerSequences(int n, int length, int min, int max) int i = 1; for (RandomOrgClient roc : rocs) { @@ -950,7 +969,7 @@ public void testPositiveGenerateSignedIntegerSequences_1(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_2(){ + public void testPositiveGenerateSignedIntegerSequences_2() { // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject userData) // -- decimal base @@ -968,7 +987,7 @@ public void testPositiveGenerateSignedIntegerSequences_2(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_3(){ + public void testPositiveGenerateSignedIntegerSequences_3() { // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject userData) // -- non-decimal base @@ -986,7 +1005,7 @@ public void testPositiveGenerateSignedIntegerSequences_3(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_4_decimal(){ + public void testPositiveGenerateSignedIntegerSequences_4_decimal() { // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject userData, String ticketId) // -- decimal base @@ -1006,7 +1025,7 @@ public void testPositiveGenerateSignedIntegerSequences_4_decimal(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_4_nondecimal(){ + public void testPositiveGenerateSignedIntegerSequences_4_nondecimal() { // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject userData, String ticketId) // -- non-decimal base @@ -1026,7 +1045,7 @@ public void testPositiveGenerateSignedIntegerSequences_4_nondecimal(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_5_decimal(){ + public void testPositiveGenerateSignedIntegerSequences_5_decimal() { // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject pregeneratedRandomization, // JsonObject licenseData, JsonObject userData, String ticketId) @@ -1054,7 +1073,7 @@ public void testPositiveGenerateSignedIntegerSequences_5_decimal(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_5_nondecimal(){ + public void testPositiveGenerateSignedIntegerSequences_5_nondecimal() { // Testing generateSignedIntegerSequences(int n, int length, int min, int max, // boolean replacement, int base, JsonObject pregeneratedRandomization, // JsonObject licenseData, JsonObject userData, String ticketId) @@ -1082,7 +1101,7 @@ public void testPositiveGenerateSignedIntegerSequences_5_nondecimal(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_6(){ + public void testPositiveGenerateSignedIntegerSequences_6() { // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1098,7 +1117,7 @@ public void testPositiveGenerateSignedIntegerSequences_6(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_7(){ + public void testPositiveGenerateSignedIntegerSequences_7() { // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData) // -- decimal @@ -1118,7 +1137,7 @@ public void testPositiveGenerateSignedIntegerSequences_7(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_8(){ + public void testPositiveGenerateSignedIntegerSequences_8() { // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData) // -- non-decimal @@ -1137,7 +1156,7 @@ public void testPositiveGenerateSignedIntegerSequences_8(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_9_decimal(){ + public void testPositiveGenerateSignedIntegerSequences_9_decimal() { // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData, String ticketId) // -- decimal @@ -1159,7 +1178,7 @@ public void testPositiveGenerateSignedIntegerSequences_9_decimal(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_9_nondecimal(){ + public void testPositiveGenerateSignedIntegerSequences_9_nondecimal() { // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData, String ticketId) // -- non-decimal @@ -1180,7 +1199,7 @@ public void testPositiveGenerateSignedIntegerSequences_9_nondecimal(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_10_decimal(){ + public void testPositiveGenerateSignedIntegerSequences_10_decimal() { // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject pregeneratedRandomization, // JsonObject licenseData, JsonObject userData, String ticketId) @@ -1212,7 +1231,7 @@ public void testPositiveGenerateSignedIntegerSequences_10_decimal(){ } @Test - public void testPositiveGenerateSignedIntegerSequences_10_nondecimal(){ + public void testPositiveGenerateSignedIntegerSequences_10_nondecimal() { // Testing generateSignedIntegerSequences(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, JsonObject userData, String ticketId) // -- non-decimal @@ -1242,7 +1261,7 @@ public void testPositiveGenerateSignedIntegerSequences_10_nondecimal(){ } @Test - public void testPositiveGenerateSignedDecimalFractions_1(){ + public void testPositiveGenerateSignedDecimalFractions_1() { // Testing generateSignedDecimalFractions(int n, int decimalPlaces) int i = 1; @@ -1259,7 +1278,7 @@ public void testPositiveGenerateSignedDecimalFractions_1(){ } @Test - public void testPositiveGenerateSignedDecimalFractions_2(){ + public void testPositiveGenerateSignedDecimalFractions_2() { // Testing generateSignedDecimalFractions(int n, int decimalPlaces, boolean replacement) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1275,7 +1294,7 @@ public void testPositiveGenerateSignedDecimalFractions_2(){ } @Test - public void testPositiveGenerateSignedDecimalFractions_3(){ + public void testPositiveGenerateSignedDecimalFractions_3() { // Testing generateSignedDecimalFractions(int n, int decimalPlaces, // boolean replacement, JsonObject userData) int i = 1; @@ -1292,7 +1311,7 @@ public void testPositiveGenerateSignedDecimalFractions_3(){ } @Test - public void testPositiveGenerateSignedDecimalFractions_4(){ + public void testPositiveGenerateSignedDecimalFractions_4() { // Testing generateSignedDecimalFractions(int n, int decimalPlaces, // boolean replacement, JsonObject userData, String ticketId) int i = 1; @@ -1311,7 +1330,7 @@ public void testPositiveGenerateSignedDecimalFractions_4(){ } @Test - public void testPositiveGenerateSignedDecimalFractions_5(){ + public void testPositiveGenerateSignedDecimalFractions_5() { // Testing generateSignedDecimalFractions(int n, int decimalPlaces, // boolean replacement, JsonObject pregeneratedRandomization, // JsonObject licenseData, JsonObject userData, String ticketId) @@ -1338,7 +1357,7 @@ public void testPositiveGenerateSignedDecimalFractions_5(){ } @Test - public void testPositiveGenerateSignedGaussians_1(){ + public void testPositiveGenerateSignedGaussians_1() { // Testing generateSignedGaussians(int n, double mean, double standardDeviation, int significantDigits) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1354,7 +1373,7 @@ public void testPositiveGenerateSignedGaussians_1(){ } @Test - public void testPositiveGenerateSignedGaussians_2(){ + public void testPositiveGenerateSignedGaussians_2() { // Testing generateSignedGaussians(int n, double mean, double standardDeviation, // int significantDigits, JsonObject userData) int i = 1; @@ -1371,7 +1390,7 @@ public void testPositiveGenerateSignedGaussians_2(){ } @Test - public void testPositiveGenerateSignedGaussians_3(){ + public void testPositiveGenerateSignedGaussians_3() { // Testing generateSignedGaussians(int n, double mean, double standardDeviation, // int significantDigits, JsonObject userData, String ticketId) int i = 1; @@ -1390,7 +1409,7 @@ public void testPositiveGenerateSignedGaussians_3(){ } @Test - public void testPositiveGenerateSignedGaussians_4(){ + public void testPositiveGenerateSignedGaussians_4() { // Testing generateSignedGaussians(int n, double mean, double standardDeviation, // int significantDigits, JsonObject pregeneratedRandomization, JsonObject licenseData, // JsonObject userData, String ticketId) @@ -1417,7 +1436,7 @@ public void testPositiveGenerateSignedGaussians_4(){ } @Test - public void testPositiveGenerateSignedStrings_1(){ + public void testPositiveGenerateSignedStrings_1() { // Testing generateSignedStrings(int n, int length, String characters) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1433,7 +1452,7 @@ public void testPositiveGenerateSignedStrings_1(){ } @Test - public void testPositiveGenerateSignedStrings_2(){ + public void testPositiveGenerateSignedStrings_2() { // Testing generateSignedStrings(int n, int length, String characters, boolean replacement) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1448,7 +1467,7 @@ public void testPositiveGenerateSignedStrings_2(){ } } - public void testPositiveGenerateSignedStrings_3(){ + public void testPositiveGenerateSignedStrings_3() { // Testing generateSignedStrings(int n, int length, String characters, // boolean replacement, JsonObject userData) int i = 1; @@ -1465,7 +1484,7 @@ public void testPositiveGenerateSignedStrings_3(){ } @Test - public void testPositiveGenerateSignedStrings_4(){ + public void testPositiveGenerateSignedStrings_4() { // Testing generateSignedStrings(int n, int length, String characters, // boolean replacement, JsonObject userData, String ticketId) int i = 1; @@ -1484,7 +1503,7 @@ public void testPositiveGenerateSignedStrings_4(){ } @Test - public void testPositiveGenerateSignedStrings_5(){ + public void testPositiveGenerateSignedStrings_5() { // Testing generateSignedStrings(int n, int length, String characters, // boolean replacement, JsonObject pregeneratedRandomization, // JsonObject licenseData,JsonObject userData, String ticketId) @@ -1511,7 +1530,7 @@ public void testPositiveGenerateSignedStrings_5(){ } @Test - public void testPositiveGenerateSignedUUIDs_1(){ + public void testPositiveGenerateSignedUUIDs_1() { // Testing generateSignedUUIDs(int n) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1527,7 +1546,7 @@ public void testPositiveGenerateSignedUUIDs_1(){ } @Test - public void testPositiveGenerateSignedUUIDs_2(){ + public void testPositiveGenerateSignedUUIDs_2() { // Testing generateSignedUUIDs(int n, JsonObject userData) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1543,7 +1562,7 @@ public void testPositiveGenerateSignedUUIDs_2(){ } @Test - public void testPositiveGenerateSignedUUIDs_3(){ + public void testPositiveGenerateSignedUUIDs_3() { // Testing generateSignedUUIDs(int n, JsonObject userData, String ticketId) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1560,7 +1579,7 @@ public void testPositiveGenerateSignedUUIDs_3(){ } @Test - public void testPositiveGenerateSignedUUIDs_4(){ + public void testPositiveGenerateSignedUUIDs_4() { // Testing generateSignedUUIDs(int n, JsonObject pregeneratedRandomization, // JsonObject licenseData, JsonObject userData, String ticketId) int i = 1; @@ -1584,7 +1603,7 @@ public void testPositiveGenerateSignedUUIDs_4(){ } @Test - public void testPositiveGenerateSignedBlobs_1(){ + public void testPositiveGenerateSignedBlobs_1() { // Testing generateSignedBlobs(int n, int size) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1600,7 +1619,7 @@ public void testPositiveGenerateSignedBlobs_1(){ } @Test - public void testPositiveGenerateSignedBlobs_2(){ + public void testPositiveGenerateSignedBlobs_2() { // Testing generateSignedBlobs(int n, int size, String format) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1616,7 +1635,7 @@ public void testPositiveGenerateSignedBlobs_2(){ } @Test - public void testPositiveGenerateSignedBlobs_3(){ + public void testPositiveGenerateSignedBlobs_3() { // Testing generateSignedBlobs(int n, int size, String format, JsonObject userData) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1632,7 +1651,7 @@ public void testPositiveGenerateSignedBlobs_3(){ } @Test - public void testPositiveGenerateSignedBlobs_4(){ + public void testPositiveGenerateSignedBlobs_4() { // Testing generateSignedBlobs(int n, int size, String format, JsonObject userData, // String ticketId) int i = 1; @@ -1651,7 +1670,7 @@ public void testPositiveGenerateSignedBlobs_4(){ } @Test - public void testPositiveGenerateSignedBlobs_5(){ + public void testPositiveGenerateSignedBlobs_5() { // Testing generateSignedBlobs(int n, int size, String format, // JsonObject pregeneratedRandomization, JsonObject licenseData, // JsonObject userData, String ticketId) @@ -1682,7 +1701,7 @@ public void testPositiveGenerateSignedBlobs_5(){ // Test additional functions @Test - public void testGetResult(){ + public void testGetResult() { // Testing getResult(int serialNumber) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1702,7 +1721,7 @@ public void testGetResult(){ } @Test - public void testCreateTickets(){ + public void testCreateTickets() { // Testing createTickets(int n, boolean showResult) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1721,7 +1740,29 @@ public void testCreateTickets(){ } @Test - public void testListTickets(){ + public void testRevealTicketsSingle() { + // Testing revealTickets(String ticketId) - using and revealing + // a single ticket. + int i = 1; + for (RandomOrgClient roc : rocs) { + revealTicket(roc, i, 1); + i++; + } + } + + @Test + public void testRevealTicketsMultiple() { + // Testing revealTickets(String ticketId) - using and revealing + // a chain of tickets. + int i = 1; + for (RandomOrgClient roc : rocs) { + revealTicket(roc, i, 3); + i++; + } + } + + @Test + public void testListTickets() { // Testing listTickets(String type) for each type int i = 1; String[] types = {"singleton", "head", "tail"}; @@ -1754,7 +1795,7 @@ public void testListTickets(){ } @Test - public void testGetTicket(){ + public void testGetTicket() { // Testing getTicket(String ticketId) int i = 1; for (RandomOrgClient roc : rocs) { @@ -1790,7 +1831,7 @@ public void testGetTicket(){ // Test Functions (Cache) @Test - public void testIntegerCache_1(){ + public void testIntegerCache_1() { // Testing createIntegerCache(int n, int min, int max) RandomOrgCache c = rocs[0].createIntegerCache(5, 0, 10); c.stop(); @@ -1844,7 +1885,7 @@ public void testIntegerCache_1(){ } @Test - public void testIntegerCache_2(){ + public void testIntegerCache_2() { // Testing createIntegerCache(int n, int min, int max, boolean replacement, // int base, int cacheSize) RandomOrgCache c = rocs[0].createIntegerCache(5, 50, 100, false, 16, 5); @@ -1877,7 +1918,7 @@ public void testIntegerCache_2(){ } @Test - public void testIntegerSequenceCache_1(){ + public void testIntegerSequenceCache_1() { // Testing createIntegerSequenceCache(int n, int length int min, int max) RandomOrgCache c = rocs[0].createIntegerSequenceCache(2, 5, 0, 10); c.stop(); @@ -1907,7 +1948,7 @@ public void testIntegerSequenceCache_1(){ } @Test - public void testIntegerSequenceCache_2(){ + public void testIntegerSequenceCache_2() { // Testing createIntegerSequenceCache(int n, int length int min, int max, // boolean replacement, int base, int cacheSize) RandomOrgCache c = rocs[0].createIntegerSequenceCache(2, 5, 0, 10, false, 16, 3); @@ -1938,7 +1979,7 @@ public void testIntegerSequenceCache_2(){ } @Test - public void testIntegerSequenceCache_3(){ + public void testIntegerSequenceCache_3() { // Testing createIntegerSequenceCache(int n, int[] length, int[] min, int[] max) RandomOrgCache c = rocs[0].createIntegerSequenceCache(4, LENGTH, MIN, MAX); c.stop(); @@ -1968,7 +2009,7 @@ public void testIntegerSequenceCache_3(){ } @Test - public void testIntegerSequenceCache_4(){ + public void testIntegerSequenceCache_4() { // Testing createIntegerSequenceCache(int n, int[] length, int[] min, int[] max, // boolean[] replacement, int[] base, int cacheSize) boolean[] replacement = {true, true, true, true}; @@ -2004,7 +2045,7 @@ public void testIntegerSequenceCache_4(){ } @Test - public void testDecimalFractionCache(){ + public void testDecimalFractionCache() { // Testing createDecimalFractionCache(int n, int decimalPlaces) RandomOrgCache c = rocs[1].createDecimalFractionCache(1, 5); c.stop(); @@ -2034,7 +2075,7 @@ public void testDecimalFractionCache(){ } @Test - public void testGaussianCache(){ + public void testGaussianCache() { // Testing createGaussianCache(int n, double mean, double standardDeviation, // int significantDigits) RandomOrgCache c = rocs[0].createGaussianCache(10, 3.41d, 2.1d, 4); @@ -2065,7 +2106,7 @@ public void testGaussianCache(){ } @Test - public void testStringCache(){ + public void testStringCache() { // Testing createStringCache(int n, int length, String characters) RandomOrgCache c = rocs[1].createStringCache(5, 5, "abcds"); c.stop(); @@ -2095,7 +2136,7 @@ public void testStringCache(){ } @Test - public void testUUIDCache(){ + public void testUUIDCache() { // Testing createUUIDCache(int n) RandomOrgCache c = rocs[0].createUUIDCache(5); c.stop(); @@ -2125,7 +2166,7 @@ public void testUUIDCache(){ } @Test - public void testBlobCache(){ + public void testBlobCache() { // Testing createBlobCache(int n, int size) RandomOrgCache c = rocs[1].createBlobCache(5, 8); c.stop(); @@ -2193,6 +2234,20 @@ private String errorMessage(int i, Exception e, boolean networking) { } } + /** + * Helper function to check if the RandomOrgRANDOMORGError thrown + * is the expected error. + * + * @param e RandomOrgRANDOMORGError thrown in the test. + * @param expectedErrorCode The code of the expected RandomOrgRANDOMORGError. + */ + private void negativeErrorHandler(RandomOrgRANDOMORGError e, int expectedErrorCode) { + if (e.getCode() != expectedErrorCode) { + collector.addError(new Error("Should have thrown RandomOrgRANDOMORGError " + + expectedErrorCode + ", instead threw: " + e.getMessage())); + } + } + /** * Helper function for testing methods returning signed values * @@ -2269,4 +2324,58 @@ private void signedValueTester(RandomOrgClient roc, int i, HashMap> results = new HashMap>(); + + JsonObject ticket = roc.createTickets(1, false)[0]; + String ticketId = ticket.get("ticketId").getAsString(); + + + for (int i = 0; i < n; i++) { + // Use the ticket to generate integers. + HashMap result = roc.generateSignedIntegers(5, 0, 10, false, 10, null, ticketId); + + // Check that the generated data is not visible pre-reveal. + HashMap get = roc.getTicket(ticketId); + collector.checkThat(get.get("data"), nullValue()); + + // Update last ticket (which will be revealed) and results. + lastTicket = ticketId; + results.put(ticketId, result); + + // Get the next ticket. + ticketId = ((JsonObject) roc.getTicket(ticketId).get("result")).get("nextTicketId").toString(); + ticketId = ticketId.replaceAll("\"", ""); + } + + // Reveal the last ticket, which also automatically reveals + // all other tickets used (predecessors). + int ticketCount = roc.revealTickets(lastTicket); + collector.checkThat(ticketCount, is(n)); + + for(Map.Entry> entry : results.entrySet()) { + String id = entry.getKey(); + HashMap result = entry.getValue(); + + // Check that the results are now available for each revealed ticket + // and that they are the correct results. + HashMap get = roc.getTicket(id); + collector.checkThat(result.get("data"), equalTo(get.get("data"))); + } + } catch (Exception e) { + collector.addError(new Error(errorMessage(rocIndex, e, true))); + } + } }