Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 19718ac

Browse files
author
=
committed
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)
1 parent ff6119f commit 19718ac

13 files changed

+4410
-2056
lines changed

‎README.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
JSON-RPC-Java
22
===============
33

4-
RANDOM.ORG JSON-RPC API (Release 1) implementation.
4+
RANDOM.ORG JSON-RPC API (Release 2) implementation.
55

6-
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.
6+
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.
77

88
Installation
99
------------
1010

11-
Requires the `gson <https://code.google.com/p/google-gson/>`_ lib and `Commons Codec <http://commons.apache.org/proper/commons-codec/>`_ lib for normal operation, and the `junit <http://junit.org/>`_ lib to run tests.
11+
Requires the `gson <https://code.google.com/p/google-gson/>`_ lib and `Commons Codec <http://commons.apache.org/proper/commons-codec/>`_ lib for normal operation, and the `junit <http://junit.org/>`_ lib and `hamcrest <http://hamcrest.org/JavaHamcrest/>`_ lib to run tests.
1212

1313
Usage
1414
-----
@@ -86,7 +86,7 @@ This library now also includes a RANDOM.ORG implementation of the `java.util.Ran
8686
Documentation
8787
-------------
8888

89-
For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/1/
89+
For a full list of available randomness generation functions and other features see RandomOrgClient.java documentation and https://api.random.org/json-rpc/2
9090

9191
Tests
9292
-----

‎RandomJSONRPC/src/org/random/api/RandomOrgCache.java‎

Lines changed: 88 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,20 @@
1010

1111
import com.google.gson.JsonObject;
1212

13-
/** Precache class for frequently used requests.
14-
**
15-
** ** WARNING **
16-
** Instances of this class should only be obtained using a RandomOrgClient's
17-
** createCache() methods.
18-
**
19-
** This class strives to keep a Queue of response results populated for instant
20-
** access via its public get() method. Work is done by a background Thread, which
21-
** issues the appropriate request at suitable intervals.
22-
**
23-
** @param <T> return array type, e.g., int[]
24-
**
25-
**/
13+
/**
14+
* Precache class for frequently used requests.
15+
*
16+
* ** WARNING **
17+
* Instances of this class should only be obtained using a RandomOrgClient's
18+
* createCache() methods.
19+
*
20+
* This class strives to keep a Queue of response results populated for instant
21+
* access via its public get() method. Work is done by a background Thread, which
22+
* issues the appropriate request at suitable intervals.
23+
*
24+
* @param <T> return array type, e.g., int[]
25+
*
26+
*/
2627
public class RandomOrgCache<T> {
2728

2829
private JsonObjectInputCallable<JsonObject> requestFunction;
@@ -48,19 +49,20 @@ public class RandomOrgCache<T> {
4849

4950
private static final Logger LOGGER = Logger.getLogger(RandomOrgClient.class.getPackage().getName());
5051

51-
/** Initialize class and start Queue population Thread running as a daemon.
52-
**
53-
** ** WARNING **
54-
** Should only be called by RandomOrgClient's createCache() methods.
55-
**
56-
** @param requestFunction function used to send supplied request to server.
57-
** @param processFunction function to process result of requestFunction into expected output.
58-
** @param request request to send to server via requestFunction.
59-
** @param cacheSize number of request responses to try maintain.
60-
** @param bulkRequestNumber if request is set to be issued in bulk, number of result sets in a bulk request, else 0.
61-
** @param requestNumber if request is set to be issued in bulk, number of results in a single request, else 0.
62-
** @param singleRequestSize in bits for adjusting bulk requests if bits are in short supply on the server.
63-
**/
52+
/**
53+
* Initialize class and start Queue population Thread running as a daemon.
54+
*
55+
* ** WARNING **
56+
* Should only be called by RandomOrgClient's createCache() methods.
57+
*
58+
* @param requestFunction function used to send supplied request to server.
59+
* @param processFunction function to process result of requestFunction into expected output.
60+
* @param request request to send to server via requestFunction.
61+
* @param cacheSize number of request responses to try maintain.
62+
* @param bulkRequestNumber if request is set to be issued in bulk, number of result sets in a bulk request, else 0.
63+
* @param requestNumber if request is set to be issued in bulk, number of results in a single request, else 0.
64+
* @param singleRequestSize in bits for adjusting bulk requests if bits are in short supply on the server.
65+
*/
6466
protected RandomOrgCache(JsonObjectInputCallable<JsonObject> requestFunction, JsonObjectInputCallable<T> processFunction,
6567
JsonObject request, int cacheSize, int bulkRequestNumber, int requestNumber, int singleRequestSize) {
6668

@@ -86,14 +88,15 @@ public void run() {
8688
t.start();
8789
}
8890

89-
/** Keep issuing requests to server until Queue is full. When Queue is full if requests
90-
** are being issued in bulk, wait until Queue has enough space to accommodate all of a
91-
** bulk request before issuing a new request, otherwise issue a new request every time
92-
** an item in the Queue has been consumed.
93-
**
94-
** Note that requests to the server are blocking, i.e., only one request will be issued by
95-
** the cache at any given time.
96-
**/
91+
/**
92+
* Keep issuing requests to server until Queue is full. When Queue is full if requests
93+
* are being issued in bulk, wait until Queue has enough space to accommodate all of a
94+
* bulk request before issuing a new request, otherwise issue a new request every time
95+
* an item in the Queue has been consumed.
96+
*
97+
* Note that requests to the server are blocking, i.e., only one request will be issued by
98+
* the cache at any given time.
99+
*/
97100
@SuppressWarnings("unchecked")
98101
protected void populateQueue() {
99102
while (true) {
@@ -219,27 +222,29 @@ public void resume() {
219222
}
220223
}
221224

222-
/** Return <code>true</code> if cache is currently not re-populating itself.
223-
** <p>
224-
** Values currently cached may still be retrieved with <code>get()</code>,
225-
** but no new values are being fetched from the server.
226-
** <p>
227-
** This state can be changed with <code>stop()</code> and <code>resume()</code>.
228-
**
229-
** @see #stop()
230-
** @see #resume()
231-
**
232-
** @return <code>true</code> if cache is currently not re-populating itself.
233-
**/
225+
/**
226+
* Return {@code true} if cache is currently not re-populating itself.
227+
* <p>
228+
* Values currently cached may still be retrieved with {@code get()},
229+
* but no new values are being fetched from the server.
230+
* <p>
231+
* This state can be changed with {@code stop()} and {@code resume()}.
232+
*
233+
* @see #stop()
234+
* @see #resume()
235+
*
236+
* @return {@code true} if cache is currently not re-populating itself.
237+
*/
234238
public boolean isPaused() {
235239
return this.paused;
236240
}
237241

238-
/** Get next response.
239-
**
240-
** @return next appropriate response for the request this RandomOrgCache represents
241-
** or if Queue is empty throws a NoSuchElementException.
242-
**/
242+
/**
243+
* Get next response.
244+
*
245+
* @return next appropriate response for the request this RandomOrgCache represents
246+
* or if Queue is empty throws a NoSuchElementException.
247+
*/
243248
public T get() {
244249
synchronized (this.lock) {
245250
T result = this.queue.remove();
@@ -248,19 +253,20 @@ public T get() {
248253
}
249254
}
250255

251-
/** Get next response or wait until the next value is available.
252-
** <p>
253-
** This method will block until a value is available.
254-
** <p>
255-
** Note: if the cache is paused or no more randomness is available from the server this call can result in a dead lock.
256-
**
257-
** @see #isPaused()
258-
**
259-
** @return next appropriate response for the request this RandomOrgCache represents
260-
**
261-
** @throws InterruptedException if any thread interrupted the current thread before or
262-
** while the current thread was waiting for a notification. The interrupted status of
263-
** the current thread is cleared when this exception is thrown.
256+
/**
257+
* Get next response or wait until the next value is available.
258+
* <p>
259+
* This method will block until a value is available.
260+
* <p>
261+
* Note: if the cache is paused or no more randomness is available from the server this call can result in a dead lock.
262+
*
263+
* @see #isPaused()
264+
*
265+
* @return next appropriate response for the request this RandomOrgCache represents
266+
*
267+
* @throws InterruptedException if any thread interrupted the current thread before or
268+
* while the current thread was waiting for a notification. The interrupted status of
269+
* the current thread is cleared when this exception is thrown.
264270
*/
265271
public T getOrWait() throws InterruptedException {
266272

@@ -275,29 +281,32 @@ public T getOrWait() throws InterruptedException {
275281
return result;
276282
}
277283

278-
/** Get number of results of type {@link #T} remaining in the cache.
279-
** <p>
280-
** This essentially returns how often <code>get()</code> may be called without a cache refill,
281-
** or <code>getOrWait()</code> may be called without blocking.
282-
**
283-
** @return current number of cached results
284-
**/
284+
/**
285+
* Get number of results of type {@link #T} remaining in the cache.
286+
* <p>
287+
* This essentially returns how often {@code get()} may be called without a cache refill,
288+
* or {@code getOrWait()} may be called without blocking.
289+
*
290+
* @return current number of cached results
291+
*/
285292
public int getCachedValues() {
286293
return this.queue.size();
287294
}
288295

289-
/** Get number of bits used by this cache.
290-
**
291-
** @return number of used bits
292-
**/
296+
/**
297+
* Get number of bits used by this cache.
298+
*
299+
* @return number of used bits
300+
*/
293301
public long getUsedBits() {
294302
return this.usedBits;
295303
}
296304

297-
/** Get number of requests used by this cache.
298-
**
299-
** @return number of used requests
300-
**/
305+
/**
306+
* Get number of requests used by this cache.
307+
*
308+
* @return number of used requests
309+
*/
301310
public long getUsedRequests() {
302311
return this.usedRequests;
303312
}

0 commit comments

Comments
 (0)