com.SecurePlay
Class SPTRandomClass

java.lang.Object
  com.SecurePlay.SPRootTransactionClass
      com.SecurePlay.SPAbstractTransactionClass
          com.SecurePlay.SPTRandomClass

All Implemented Interfaces:

SPAbstractTransactionInterface

public class SPTRandomClass

extends SPAbstractTransactionClass

This transaction class extends the SPAbstractTransaction class. It provides for the generation of fair random events over a network based on a Random. The APIconfigureTransaction method sets the 3 unique parameters - deckSize, repacement, and expirecount for the Random. The Random class can be used for a typical game with a shared Random and a dealer or for games without shared Randoms (in which case each Random is a separate instance of the class). Randoms can contain multiple "decks", but this is handled at the game rules level outside of the SecurePlay library

Author:

IT GlobalSecure

See Also:

SecurePlay License Information

Field Summary

private boolean	built This property is set to boolean TRUE if the Random has been constructed and FALS E, if not
private java.lang.String[]	dealtEventList This property holds the sequential array of dealt random events.
private int	lastcount This property holds the last requested number of random events generated.
private java.lang.String	mt_completetransaction
private java.lang.String	mt_preparerandom
private java.lang.String	mt_randomevents
private java.lang.String	mt_requestrandomevents
private java.lang.String	mt_sendplayerkey
private java.lang.String	mt_sendplayerkeytransform
private int	prdeckSize This property holds the size of the deck or Random.
private int	prexpireeventcount This property sets the number of random events that can be generated from the deck.
private java.lang.Integer[]	prkeyArray The keyArray is the computed key generated from all of the player keys.
private int	prkeySize This property holds the size of the Random key.
private SPMap	prplayerKeyList This is an associative array that holds the player key string associated with each player.
private SPMap	prplayerKeyTransformList This property holds the associative array of transforms of the player keys.
private java.lang.Integer[]	prremainingValuesList This array holds the remaining values that are possible for Randoms that are sampled without replacement.
private boolean	prreplacement This flag determines whether the Random uses sampling with replacement (like rolling a dice) or sampling without replacement (like dealing cards from a deck or a lottery number draw).
private java.lang.Integer[]	prvremainingValuesList This is a duplicate of the prremainingValuesList property that is used for Random verification.
private java.lang.String	status_complete
private java.lang.String	status_new
private java.lang.String[]	vdealtEventList This is a duplicate of the dealtEventList array that is used for verification purposes only.
(package private) SPUEctf	verified This property holds three states: TRUE, if the Random can be completely verified, FALSE, if verification fails or the Random is not complete, and CONSISTENT if the Random is complete and the data is consistent with a valid Random but the Random cannot be completely verified (due to private random events).

Fields inherited from class com.SecurePlay.SPAbstractTransactionClass

AGE, configuration, gameinstance, mt_completeTransaction, mt_error, privateflag, releaseversion, status_error, status_ready, transactionstatus, transtype

Fields inherited from class com.SecurePlay.SPRootTransactionClass

comms, EventListenerList, gameID, insend, master, playerIDList, ReSend_altmessage, ReSend_encryptflag, ReSend_messagebody, ReSend_messageID, ReSend_messagetype, ReSend_privateflag, ReSend_receivers, ReSend_sender, secureplay, transactionID

Constructor Summary

private	SPTRandomClass() Default Constructor
	SPTRandomClass(SPGameInterface gameobj, java.lang.String master, java.lang.String[] playerIDList, boolean privateflag, java.lang.String transactionID, java.lang.String AGE, int decksize, boolean replacement, int expiration) Overloaded Constructor

Method Summary

boolean	APIcompleteTransaction(java.lang.String pid) This method overrides the SPAbstractTransactionClass method.
boolean	APIconfigureTransaction(java.lang.String sender) This method handles the specific configuration required for a Random
SPAbstractTransactionInterface	APIcreateTransaction(SPGameInterface gameapiobj, SPMessageClass message) Creates a new instance of an Abstract Transaction class.
boolean	APIgenerateRandomEvent(java.lang.String sender, java.lang.String[] receivers, boolean privacy, int count) This method handles either requests or local generation of random events by the Random master.
java.lang.String[]	APIgetlastRandomEvents() This method returns an array that includes the last set of random events provided by the Random master.
int	APIgetRandomEvent(int index) This method returns a random event from the dealtEventList property as specified by the index.
int	APIgetRandomEventCount()
SPUEctf	APIverifyRandom() This method verifies a Random once the transaction has been completed.
static SPAbstractTransactionInterface	createRandom(SPGameInterface gameobj, java.lang.String master, java.lang.String[] playerIDList, boolean pflag, java.lang.String AGE, int decksize, boolean replacement, int expiration) This method creates a new Random Class
java.lang.String[]	getDealtEventList() Getter function that returns the property: dealtEventList
int	getDeckSize() Getter function that returns the property: prdeckSize
int	getExpireEventCount() Getter function that returns the property: prexpireeventcount
protected java.lang.Integer[]	getKeyArray() Getter function that returns the property: prkeyArray
int	getKeySize() Getter function that returns the property: prkeySize
int	getLastCount() Getter function that returns the property: lastcount
SPMap	getPlayerKeyList() Getter function that returns the property: prplayerKeyList
SPMap	getPlayerKeyTransformList() Getter function that returns the property: prplayerKeyTransformList
java.lang.Integer[]	getRemainingValuesList() Getter function that returns the property: prremainingValuesList
static java.lang.String	gettranstype() This method gets the transaction type.
boolean	isBuilt() Getter function that returns the property: built
boolean	isReplacement() Getter function that returns the property: prreplacement
private boolean	oncompleteTransaction(SPMessageClass incoming) This method handles incoming mt_completetransaction messages.
private boolean	oncompleteTransaction(java.lang.String sourceid, java.lang.String[] body) This method handles incoming mt_completetransaction messages.
private boolean	onprepareRandom(SPMessageClass incoming) This method/event handles the initial response to the APIconfigureTransaction call by the Transaction Master.
private boolean	onRandomEvents(SPMessageClass incoming) This method handles incoming random events from the Random master.
private void	onrequestconfigureTransaction(SPMessageClass incoming) This method handles the unique processing associated with incoming requests to configure a Random Class.
private boolean	onrequestRandomEvents(SPMessageClass incoming) This method handles incoming requests to generate Random events.
private boolean	onsendPlayerKey(SPMessageClass incoming) This method handles incoming mt_sendplayerkey messages.
private boolean	onsendPlayerKeyTransform(SPMessageClass incoming) This method handles incoming mt_sendplayerkeytransform messages.
private boolean	prbuildRandom() This method provides the core configuration common to all Randoms.
private boolean	prcheckPlayerKeyLoad() This method is used to check the status of the loading of Player Keys during the Random configuration process.
private void	prcreateRandomKey() This method actually builds the game key from the various player keys.
private boolean	prgetRandomValue(java.lang.String playverifyflag) This method actually generates the random values.
boolean	pronincomingTransaction(SPMessageClass incoming) This method provides the unique handlers for incoming Secret turn message types
void	pruniqueinit() Unique initialization method
static boolean	registerTransaction() Registers this transaction.

Methods inherited from class com.SecurePlay.SPAbstractTransactionClass

APIgetAGE, APIgetConfiguration, APIgetGameinstance, APIgetPrivacyFlag, APIgetTransactionstatus, APIgetTransactionType, APIisPlayerInternal, APIisTransError, APIsetTransactionID, logError, onincomingTransaction, prinit, setAGE

Methods inherited from class com.SecurePlay.SPRootTransactionClass

APIaddListener, APIclearListeners, APIgetGameID, APIgetGetReplayList, APIgetListenerCount, APIgetListeners, APIgetMaster, APIgetPlayerIDList, APIgetTransactionID, APIisPlayerIncluded, APIremoveListener, APIReplayRemoveOldSender, APIresendLastMessage, APIsetReplayList, APIsetSecurePlayClass, detectReplay, sendMessage, SPnotify

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.SecurePlay.SPAbstractTransactionInterface

APIgetGameID, APIgetMaster, APIgetPlayerIDList, APIgetTransactionID, sendMessage

Field Detail

dealtEventList

private java.lang.String[] dealtEventList

This property holds the sequential array of dealt random events.

lastcount

private int lastcount

This property holds the last requested number of random events generated. It is used by the APIgetlastRandomEvents method.

prdeckSize

private int prdeckSize

This property holds the size of the deck or Random. It is set during the configuration of the Random.

prexpireeventcount

private int prexpireeventcount

This property sets the number of random events that can be generated from the deck. If the value is 0 or negative, the Random does not expire due to this limit (though it may expire if the Random has other size limits, such as sampling with out replacement). This parameter is important in that generating an excessive number of random events from a single Random may endanger the performance of the game (the obvious example being the "burning" of a Random in Blackjack).

prkeySize

private int prkeySize

This property holds the size of the Random key. The default is set by the SecurePlay library. Careful selection of this parameter is important as it determines the strength of the randomization function.

prkeyArray

private java.lang.Integer[] prkeyArray

The keyArray is the computed key generated from all of the player keys.

prplayerKeyList

private SPMap prplayerKeyList

This is an associative array that holds the player key string associated with each player.

prplayerKeyTransformList

private SPMap prplayerKeyTransformList

This property holds the associative array of transforms of the player keys.

prremainingValuesList

private java.lang.Integer[] prremainingValuesList

This array holds the remaining values that are possible for Randoms that are sampled without replacement. Actual random values are generated and then indexed into this array to determine the dealt random event.

prreplacement

private boolean prreplacement

This flag determines whether the Random uses sampling with replacement (like rolling a dice) or sampling without replacement (like dealing cards from a deck or a lottery number draw). If this is set to false, the prremainingValuesList array is created.

prvremainingValuesList

private java.lang.Integer[] prvremainingValuesList

This is a duplicate of the prremainingValuesList property that is used for Random verification. See the other object for additional details.

vdealtEventList

private java.lang.String[] vdealtEventList

This is a duplicate of the dealtEventList array that is used for verification purposes only. See the dealtEventList property for further details.

built

private boolean built

This property is set to boolean TRUE if the Random has been constructed and FALS E, if not

verified

SPUEctf verified

This property holds three states: TRUE, if the Random can be completely verified, FALSE, if verification fails or the Random is not complete, and CONSISTENT if the Random is complete and the data is consistent with a valid Random but the Random cannot be completely verified (due to private random events).

status_complete

private java.lang.String status_complete

status_new

private java.lang.String status_new

mt_preparerandom

private final java.lang.String mt_preparerandom

See Also:

Constant Field Values

mt_sendplayerkeytransform

private final java.lang.String mt_sendplayerkeytransform

See Also:

Constant Field Values

mt_sendplayerkey

private final java.lang.String mt_sendplayerkey

See Also:

Constant Field Values

mt_requestrandomevents

private final java.lang.String mt_requestrandomevents

See Also:

Constant Field Values

mt_randomevents

private final java.lang.String mt_randomevents

See Also:

Constant Field Values

mt_completetransaction

private final java.lang.String mt_completetransaction

See Also:

Constant Field Values

Constructor Detail

SPTRandomClass

private SPTRandomClass()

Default Constructor

SPTRandomClass

public SPTRandomClass(SPGameInterface gameobj,
                      java.lang.String master,
                      java.lang.String[] playerIDList,
                      boolean privateflag,
                      java.lang.String transactionID,
                      java.lang.String AGE,
                      int decksize,
                      boolean replacement,
                      int expiration)

Overloaded Constructor

Parameters:

gameobj - SPGameInterface - the game object with which the transaction will be associated

master - String - the master of the transaction

playerIDList - String[] - the player id list

privateflag - boolean - private flag

transactionID - String - the transaction id

Method Detail

pruniqueinit

public void pruniqueinit()

Unique initialization method

Overrides:

pruniqueinit in class SPAbstractTransactionClass

APIconfigureTransaction

public boolean APIconfigureTransaction(java.lang.String sender)

This method handles the specific configuration required for a Random

Parameters:

sender - String - player id of the sender

onprepareRandom

private boolean onprepareRandom(SPMessageClass incoming)

This method/event handles the initial response to the APIconfigureTransaction call by the Transaction Master. It verifies that the message was from the transaction master, loads the master player key transform, and triggers the configuration of the Random (prbuildRandom) method. It also initiates sending of all internal player key transforms to the other remote players.

Parameters:

incoming - SPMessageClass - incoming message

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

onsendPlayerKeyTransform

private boolean onsendPlayerKeyTransform(SPMessageClass incoming)

This method handles incoming mt_sendplayerkeytransform messages. This is the second stage of the Random configuration process. Once all of the player key transforms are received, all of the player keys are sent to the remote players, excluding the Random master/transaction master key.

Parameters:

incoming - SPMessageClass - incoming message

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

onsendPlayerKey

private boolean onsendPlayerKey(SPMessageClass incoming)

This method handles incoming mt_sendplayerkey messages. It is the third stage in the configuration of the Random. Once all player keys are recieved, excluding the Random master's, the Random master will create the game key (prKeyArray) and the Random status will move to "ready";

Parameters:

incoming - SPMessageClass - incoming message

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

prcheckPlayerKeyLoad

private boolean prcheckPlayerKeyLoad()

This method is used to check the status of the loading of Player Keys during the Random configuration process. It is used internally to determine that the initialization phase has been complete.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

prbuildRandom

private boolean prbuildRandom()

This method provides the core configuration common to all Randoms. It sets the deckSize, replacement, and expireevent counter.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

prcreateRandomKey

private void prcreateRandomKey()

This method actually builds the game key from the various player keys. It combines them by essentially doing "character by character" addition.

APIgenerateRandomEvent

public boolean APIgenerateRandomEvent(java.lang.String sender,
                                      java.lang.String[] receivers,
                                      boolean privacy,
                                      int count)

This method handles either requests or local generation of random events by the Random master. Either a request message will be sent to the Random master or the Random master will generate the number of random events specified by (count) and send them to the specified receivers. This value is protected based on the privacy flag.

Parameters:

sender - String - sender

receivers - String - player id list of the recievers

privacy - boolean - privacy policy

count - int - the number of random events to be generated

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

prgetRandomValue

private boolean prgetRandomValue(java.lang.String playverifyflag)

This method actually generates the random values. It generates a single random value based on the settings in the Random and stores and updates the Random properties appropriately.

Parameters:

playverifyflag - String

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

onrequestRandomEvents

private boolean onrequestRandomEvents(SPMessageClass incoming)

This method handles incoming requests to generate Random events. This message must be sent by a party not the Random master with a recipient of the Random master. It also includes the proposed parameters for the Random master to use. api.rulesgenerateRandomEvent is used to determine if this request is accepted.

Parameters:

incoming - SPMessageClass - incoming message

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

onRandomEvents

private boolean onRandomEvents(SPMessageClass incoming)

This method handles incoming random events from the Random master. The new random events are appended to the dealtEventlist array.

Parameters:

incoming - SPMessageClass - incoming message

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

APIgetRandomEvent

public int APIgetRandomEvent(int index)

This method returns a random event from the dealtEventList property as specified by the index.

Parameters:

index - int - the specifier of the random event

Returns:

rmevent - int - the corresponding dealtEventList entry to the index

APIgetlastRandomEvents

public java.lang.String[] APIgetlastRandomEvents()

This method returns an array that includes the last set of random events provided by the Random master.

Returns:

rmevents - String[] - the last batch of random events

APIcompleteTransaction

public boolean APIcompleteTransaction(java.lang.String pid)

This method overrides the SPAbstractTransactionClass method. It supports the distribution of the Random master player key to allow the Random to be subsequently verified.

Specified by:

APIcompleteTransaction in interface SPAbstractTransactionInterface

Overrides:

APIcompleteTransaction in class SPAbstractTransactionClass

Parameters:

pid - String - ID of requesting Player

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

oncompleteTransaction

private boolean oncompleteTransaction(java.lang.String sourceid,
                                      java.lang.String[] body)

This method handles incoming mt_completetransaction messages. It overrides the default SPAbstractTransactionClass method. It also stores the incoming Random master player key.

Parameters:

sourceid - String - id of the sender.

body - String[] - the mody of the message.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

APIverifyRandom

public SPUEctf APIverifyRandom()

This method verifies a Random once the transaction has been completed. There is a third state that is possible - where a Random was used for private events that did not include specific players. If those events are not exchanged elsewhere, a partial verification is all that is possible - that the Random is "consistent" with known data.

Returns:

result - Boolean: TRUE, if successful, FALSE, if not, "consistent" if consistent, but not completely verified

pronincomingTransaction

public boolean pronincomingTransaction(SPMessageClass incoming)

This method provides the unique handlers for incoming Secret turn message types

Overrides:

pronincomingTransaction in class SPAbstractTransactionClass

Parameters:

incoming - SPMessageClass - incoming message

Returns:

Boolean - TRUE, if handled internally, FALSE, if not

onrequestconfigureTransaction

private void onrequestconfigureTransaction(SPMessageClass incoming)

This method handles the unique processing associated with incoming requests to configure a Random Class.

Parameters:

incoming - SPMessageClass - incoming message

oncompleteTransaction

private boolean oncompleteTransaction(SPMessageClass incoming)

This method handles incoming mt_completetransaction messages. It overrides the default SPAbstractTransactionClass method. It also stores the incoming Random master player key.

Parameters:

incoming - SPMessageClass - incoming message

Returns:

result - Boolean: TRUE, if successful, FALSE, if not

APIgetRandomEventCount

public int APIgetRandomEventCount()

isBuilt

public boolean isBuilt()

Getter function that returns the property: built

Returns:

built - bolean

getDealtEventList

public java.lang.String[] getDealtEventList()

Getter function that returns the property: dealtEventList

Returns:

dealtEventList - String[]

getLastCount

public int getLastCount()

Getter function that returns the property: lastcount

Returns:

lastcount - int

getDeckSize

public int getDeckSize()

Getter function that returns the property: prdeckSize

Returns:

prdeckSize - int

getExpireEventCount

public int getExpireEventCount()

Getter function that returns the property: prexpireeventcount

Returns:

prexpireeventcount - int

getKeyArray

protected java.lang.Integer[] getKeyArray()

Getter function that returns the property: prkeyArray

Returns:

prkeyArray - Integer[]

getKeySize

public int getKeySize()

Getter function that returns the property: prkeySize

Returns:

prkeySize - int

getPlayerKeyList

public SPMap getPlayerKeyList()

Getter function that returns the property: prplayerKeyList

Returns:

prplayerKeyList - SPHashtable

getPlayerKeyTransformList

public SPMap getPlayerKeyTransformList()

Getter function that returns the property: prplayerKeyTransformList

Returns:

prplayerKeyTransformList - SPHashtable

getRemainingValuesList

public java.lang.Integer[] getRemainingValuesList()

Getter function that returns the property: prremainingValuesList

Returns:

prremainingValuesList - Integer[]

isReplacement

public boolean isReplacement()

Getter function that returns the property: prreplacement

Returns:

prreplacement - boolean

gettranstype

public static java.lang.String gettranstype()

This method gets the transaction type.

Returns:

String

registerTransaction

public static boolean registerTransaction()

Registers this transaction.

Returns:

boolean

createRandom

public static SPAbstractTransactionInterface createRandom(SPGameInterface gameobj,
                                                          java.lang.String master,
                                                          java.lang.String[] playerIDList,
                                                          boolean pflag,
                                                          java.lang.String AGE,
                                                          int decksize,
                                                          boolean replacement,
                                                          int expiration)

This method creates a new Random Class

Parameters:

gameobj -

master -

playerIDList -

pflag -

AGE -

decksize -

replacement -

expiration -

Returns:

SPAbstractTransactionInterface - returns random class created

APIcreateTransaction

public SPAbstractTransactionInterface APIcreateTransaction(SPGameInterface gameapiobj,
                                                           SPMessageClass message)

Description copied from class: SPAbstractTransactionClass

Creates a new instance of an Abstract Transaction class.

Specified by:

APIcreateTransaction in interface SPAbstractTransactionInterface

Overrides:

APIcreateTransaction in class SPAbstractTransactionClass

Parameters:

gameapiobj - SPGameInterface - game associated with this transaction.

message - SPMessageClass - message that contains all the configure info

Returns:

SPAbstractTransactionInterface