dotsEnsembleUtilities Class Reference

Overview

Static utility methods for working with ensembles.

dotsEnsembleUtilities provides static methods which can be invoked from either the client or server side. Some methods define behaviors and conventions that the client and server need to "agree" on. Others are just utilities for users to call.

Static Methods
static ensemble isClient	makeEnsemble (name, isClient, clientIP, clientPort, serverIP, serverPort)
	Get an ensemble for local behavior or client behavior. More...
static txn	getTransactionTemplate ()
	Get a struct with a standard transaction format. More...
static txn	setTransactionParts (txn, command, result)
	Populate a transaction struct with command and result data. More...
static command result	getTransactionParts (txn)
	Extract command and result data from a transaction struct. More...
static txn	makeResetTransaction ()
	Make a reset-server transaction. More...
static txn	makeEnsembleTransaction (ensemble)
	Make a create-ensemble transaction. More...
static txn	makeObjectTransaction (ensemble, object, index)
	Make a create-object transaction. More...
static txn	makeMethodTransaction (ensemble, method, args, isResult)
	Make a method-call transaction. More...
static propStruct	getManyObjectProperties (object)
	Get the public properties of an object as a struct. More...
static	setManyObjectProperties (object, propStruct)
	Set the public properties of an object from a struct. More...

Methods

makeEnsemble()

static ensemble isClient makeEnsemble ( name  , isClient  , clientIP  , clientPort  , serverIP  , serverPort    )

static

Get an ensemble for local behavior or client behavior.

Parameters

name	unique name for the new ensemble
isClient	whether or not to make a client-type ensemble
clientIP	string IP address of the Snow Dots client
clientPort	network port number of the Snow Dots client
serverIP	string IP address of the ensemble server
serverPort	netowrk port number of the ensemble server

Returns a new topsEnsemble object, or a subclass which can act as a client for remote behaviors. makeEnsemble() is intended to be a "one-liner" which makes it easy for user code to "drop in" one type of of ensemble or the other.

The new ensemble will use the given name. If isClient is provided and true, attempts to return a client-type ensemble. If clientIP, clientPort, serverIP, and serverPort are provided, attempts to connect the client ensemble to a server using the given addresses. Otherwise, uses default addresses provided by dotsTheMessenger.

If a client ensemble fails to connect to a server, makeEnsemble() issues a warning and returns a basic topsEnsemble object instead. Returns isClient as a second argument, updated to match the type of ensemble returned.

getTransactionTemplate()

static txn getTransactionTemplate ( )

static

Get a struct with a standard transaction format.

Always returns the same struct, which has all of the correct field names to facilitate communication between a client ensemble and an ensemble server. All fields start out empty.

setTransactionParts()

static txn setTransactionParts ( txn  , command  , result    )

static

Populate a transaction struct with command and result data.

Parameters

txn	transaction struct, as from getTransactionTemplate()
command	command data, as from getTransactionParts()
result	result data, as from getTransactionParts()

Fills in the given txn with transaction command and result data given in command and result. command and result are both optional. Returns the updated txn.

getTransactionParts()

static command result getTransactionParts ( txn  )

static

Extract command and result data from a transaction struct.

Parameters

txn	transaction struct, as from getTransactionTemplate()

Extracts subsets of data from the given txn. Returns as the first the first output the transaction's command-related data. Returns as a second output the transaction's result-related data.

makeResetTransaction()

static txn makeResetTransaction ( )

static

Make a reset-server transaction.

Returns a struct which defines a transaction, telling an ensemble server to reset itself.

makeEnsembleTransaction()

static txn makeEnsembleTransaction ( ensemble  )

static

Make a create-ensemble transaction.

Parameters

ensemble

a client-side ensemble object

Returns a struct which defines a transaction, telling an ensemble server to add a new ensemble object. The new server-size object will mirror the given client-side ensemble.

makeObjectTransaction()

static txn makeObjectTransaction ( ensemble  , object  , index    )

static

Make a create-object transaction.

Parameters

ensemble	a client-side ensemble object
object	a client-size object which belongs to ensemble
index	optional index where to add object

Returns a struct which defines a transaction, telling an ensemble server to add a new object to an ensemble on the server side. The server-side ensemble will be the one that mirrors the given ensemble. Likewise, the new server-size object will mirror the given object. If index is provided, the server-size object will be added to the server-size ensemble at index.

makeMethodTransaction()

static txn makeMethodTransaction ( ensemble  , method  , args  , isResult    )

static

Make a method-call transaction.

Parameters

ensemble	a client-side ensemble object
funciton	handle of a method to call on ensemble
args	cell array of arguments to pass to method
isReult	whether or not to return a result from method

Returns a struct which defines a transaction, telling an ensemble server to call a method on an ensemble on the server side. The server-side ensemble will be the one that mirrors the given ensemble. The given method will be invoked with the given args, on the server side. If isResult is true, the server will capture the first output result from method and return it to the client side in the struct's result field.

getManyObjectProperties()

static propStruct getManyObjectProperties ( object  )

static

Get the public properties of an object as a struct.

Parameters

object

any object

Returns a struct summarizing the public properties of object. In this case, a "public" property has SetAccess and GetAccess both equal to "public". It does not matter whether a property is Hidden. Each struct field name will be the name of a public property, and each field will be filled in with the corresponding property value.

setManyObjectProperties()

static setManyObjectProperties ( object  , propStruct    )

static

Set the public properties of an object from a struct.

Parameters

object	any object
propStruct	properties and values in struct form

Assigns the fields of propStruct to the corresponding properties of object. Each field name of propStruct must match a property of object, and each matching property must have SetAccess equal to "public". dotsEnsembleUtilities.getManyObjectProperties() returns such a struct.

---

The documentation for this class was generated from the following file:

• dotsEnsembleUtilities.m