FlockEngine

FlockEngine is the main class of the framework and needs to be implemented by every Activity using it. You can instantiate FlockEngine in two ways:

  1. Extending FlockActivity instead of Activity. This will automatically instantiate FlockEngine as the local object Flock (accessible via Flock.*). FlockActivity is a small wrapper to simplify developing with the engine.
  2. Instantiating FlockEngine manually (have a look inside FlockActivity.java for a reference implementation).

See Also:
FlockActivity, Examples, Tutorial

Summary

Nested Class Summary
static interface FlockEngine.FlockEngineConnectedCallback
          Callback used for instantiating FlockEngine manually, which will be invoked when the Activity is bound to the background service and ready to communicate.
static interface FlockEngine.FlockEventCallback
          Interface definition for a callback to be invoked when a status-event is received from the engine.
 
Field Summary
static int LOG_ALL
           
static int LOG_CRITICAL
           
static int LOG_NOTHING
           
 UserManager User
          Class used by developers for authenticating the local user, creating accounts, checking whether user is currently authenticated, etc.
 
Constructor Summary
FlockEngine(Context context)
          Constructor of main class, which checks the settings (dev-id, etc.), starts the service if it's not running and binds to Service
FlockEngine(Context context, FlockEngine.FlockEngineConnectedCallback callbackWhenBound)
          Constructor of main class including a callback which is started when successfully bound to the service.
 
Method Summary
 boolean connect(java.lang.String groups, int playersPerGame)
          Start connection with game-server (with test-server if setTestServer(true)).
 DBQueryBuilder createDBQueryBuilder()
          Create a new database query builder (eg for displaying highscore, etc.).
 UserAttributeSyncer createUserAttributeSyncer()
          Create an AttributeSyncer to save up to 250 attributes for the local user to the global database.
 void disconnect()
          Immediately disconnect the socket connection if established.
 Participant[] getAllParticipants()
          Array with all Participants of the current session, even those who have quit.
 Participant getLocalParticipant()
          Participant object of the local user.
 int getLocalUserId()
          Get the id of the local user in the current session [0..n].
 Participant getParticipant(int user_id)
          Get one Participant via it's user-id.
 boolean isAnonymousSession()
          Check whether anonymous or authenticated session.
 boolean isConnected()
          Check whether the socket connection is active or not.
 boolean isGameActive()
          Check whether the framework is in a game (session), and not just in the lobby.
 boolean prioritizeActivity()
          Priorize the current Activity's callback at the service.
 void requestUserAttributeNumber(java.lang.String key, long defValue)
          Numeric attribute to include automatically for all participants when the game starts.
 void requestUserAttributeString(java.lang.String key, java.lang.String defValue)
          String attribute to include automatically for all participants when the game starts.
 boolean sendChatMessage(java.lang.String msg)
          Send this chat message to all other participants, which will receive FlockEvent.NEW_CHATMESSAGE
 boolean sendMessage(java.lang.String msg)
          Send this message to all other participants, which will receive FlockEvent.NEW_MESSAGE with this user's id as sender-id and the String msg
 void setAnonymousSession(boolean anonymous)
          Set the engine to start sessions with anonymous participants (default=false).
 void setLogLevel(int loglevel)
           
 void setOnEventListener(FlockEngine.FlockEventCallback listener)
          Register a callback to be invoked when a new event arrives from the engine/server.
 void setTestServer(boolean useTestServer)
          If you want to use the test-servers, set this to true before authenticating, creating accounts or connecting.
 void unbind()
          Remove this Activity's connection to the background service.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Details

Field Detail

LOG_ALL

public static final int LOG_ALL
See Also:
Constant Field Values

LOG_CRITICAL

public static final int LOG_CRITICAL
See Also:
Constant Field Values

LOG_NOTHING

public static final int LOG_NOTHING
See Also:
Constant Field Values

User

public UserManager User
Class used by developers for authenticating the local user, creating accounts, checking whether user is currently authenticated, etc.

See Also:
UserManager
Constructor Detail

FlockEngine

public FlockEngine(Context context)
Constructor of main class, which checks the settings (dev-id, etc.), starts the service if it's not running and binds to Service


FlockEngine

public FlockEngine(Context context,
                   FlockEngine.FlockEngineConnectedCallback callbackWhenBound)
Constructor of main class including a callback which is started when successfully bound to the service.

Method Detail

unbind

public void unbind()
Remove this Activity's connection to the background service. Service keeps running as long as at least one Activity is still bound.

Automatically done by FlockActivity at onDestroy!


prioritizeActivity

public boolean prioritizeActivity()

Priorize the current Activity's callback at the service. FlockEvents are always sent _only_ to 1 Activity; either the latest with onCreate(), or the latest with prioritize(). FlockActivity automatically prioritizes at onResume().

Helpful at onResume of first Activity, before that happens before the other Activity's onStop event.

Returns:
true if service accepted prioritize, false if not bound to service (eg. at onCreate; but there it will be automatically prioritized on binding), or too high id

setOnEventListener

public void setOnEventListener(FlockEngine.FlockEventCallback listener)
Register a callback to be invoked when a new event arrives from the engine/server.

Parameters:
listener - The callback to handle the events

isConnected

public boolean isConnected()
Check whether the socket connection is active or not.

Returns:
true if connecting or connected, false if disconnected

isGameActive

public boolean isGameActive()
Check whether the framework is in a game (session), and not just in the lobby.

Returns:
true if in a game, false if disconnected, connecting or in lobby

connect

public boolean connect(java.lang.String groups,
                       int playersPerGame)
Start connection with game-server (with test-server if setTestServer(true)).

Possible responses via FlockEventListener:

  1. CONNECTION_FAILED ........ Technical problem with connection
  2. CONNECTION_ESTABLISHED ... Connection established; waiting for other participants

Before connecting, the user has to be authenticated, or setAnonymousSession has to be set to true.

Parameters:
groups - One or more groups where players shall be matched (separated with comma (',')). Example groups = "beginners,experts". Trailing comma will be ignored.
playersPerGame - Number of required players for starting the game
Returns:
true if connecting in background, false if [has already an active connection, user is not authenticated/not anonymous mode/anonymous mode + username not long enough
See Also:
#setTestServer(boolean)}, #setAnonymousSession(boolean)}, UserManager#createAccount(String, String, String)}, UserManager#createAccount(String, String, String)}, UserManager#setUsername(String)} '

disconnect

public void disconnect()
Immediately disconnect the socket connection if established.

Possible responses via FlockEventListener:

  1. CONNECTION_CLOSED


requestUserAttributeString

public void requestUserAttributeString(java.lang.String key,
                                       java.lang.String defValue)
String attribute to include automatically for all participants when the game starts. You need to set it before calling Flock.connect(). Useful for string-attributes such as achievements, preferences, etc. It does not do anything instantly, but includes those attributes for all players at SESSION_STARTS.

Parameters:
key - Id of attribute
defValue - Default value
See Also:
requestUserAttributeNumber(String, long), Examples

requestUserAttributeNumber

public void requestUserAttributeNumber(java.lang.String key,
                                       long defValue)
Numeric attribute to include automatically for all participants when the game starts. You need to set it before calling Flock.connect(). Useful for attributes such as points, level, wins, losses, etc. It does not do anything instantly, but includes those attributes for all players at SESSION_STARTS.

Parameters:
key - Id of attribute
defValue - Default value
See Also:
requestUserAttributeString(String, String), Examples

getAllParticipants

public Participant[] getAllParticipants()

Array with all Participants of the current session, even those who have quit. The array-index matches the user-id's available in the Participants objects and as arguments when receiving an event. Only available after being bound to service and after receiving the GAME_STARTS event.

Returns:
Array with all participants; if not bound or not in a session, array with size 0.
See Also:
Participant

getParticipant

public Participant getParticipant(int user_id)
Get one Participant via it's user-id. Only available after being bound to service and after receiving the GAME_STARTS event.

Returns:
before GAME_STARTS event: null, after GAME_STARTS event: either found Participant or null (eg if too high id)
See Also:
Participant

getLocalParticipant

public Participant getLocalParticipant()
Participant object of the local user.

Returns:
before GAME_STARTS event: null, after GAME_STARTS event: either found Participant or null
See Also:
Participant

getLocalUserId

public int getLocalUserId()
Get the id of the local user in the current session [0..n].

Returns:
user id [0..n], or -1 not in a game

setAnonymousSession

public void setAnonymousSession(boolean anonymous)

Set the engine to start sessions with anonymous participants (default=false). Must be set before connecting / authenticating.

Anonymous sessions have the following characteristics:

  1. All username/password combinations are be accepted by server
  2. No usernames can be registered
  3. No attributes can be saved or retrieved for the users
  4. Set local username with Flock.User.setUsername(String)

For non-anonymous sessions, the user can create an account with an unique username, or sign in to an existing account. Developers can store up to 250 attributes per authenticated user.

Parameters:
anonymous - true if session shall be anonymous, false if not
See Also:
UserManager.setUsername(String), UserManager#setUsernameMinlength(int), UserManager.createAccount(String, String, String), UserManager.authenticate(String, String), createUserAttributeSyncer()

isAnonymousSession

public boolean isAnonymousSession()
Check whether anonymous or authenticated session.

Returns:
true if anonymous session set, false if not anonymous session (default)

createUserAttributeSyncer

public UserAttributeSyncer createUserAttributeSyncer()

Create an AttributeSyncer to save up to 250 attributes for the local user to the global database.

Please use this object for adding as many objects as you want at once, instead of creating many small syncs! If two syncs follow too soon, we will get write-write collisions and overwrites in the database. Therefore always store as many attributes as you like at once, and leave at least 1 second between syncs.

Returns:
UserAttributeSyncer class

sendMessage

public boolean sendMessage(java.lang.String msg)
Send this message to all other participants, which will receive FlockEvent.NEW_MESSAGE with this user's id as sender-id and the String msg

Parameters:
msg - Message which will be received by all other participants
Returns:
true if sent to others, false if not in a game

sendChatMessage

public boolean sendChatMessage(java.lang.String msg)
Send this chat message to all other participants, which will receive FlockEvent.NEW_CHATMESSAGE

Parameters:
msg -
Returns:
true if sent to others, false if not in a game

setTestServer

public void setTestServer(boolean useTestServer)

If you want to use the test-servers, set this to true before authenticating, creating accounts or connecting.

The test-server accepts all developer-id's and supports anonymous as well as authenticated sessions just as a dedicated gameserver.

The test-servers have the following limitations:

  • Shared user database with all other developers using testservers
  • Maximum of 10 simultaneous connected clients (can be adjusted on request)

Default: false

Parameters:
useTestServer -

createDBQueryBuilder

public DBQueryBuilder createDBQueryBuilder()

Create a new database query builder (eg for displaying highscore, etc.). If you are using the test-servers, be sure to use Flock.setAnonymousSession(true) before creating the query builder.

The builder returns a HTTP GET URL which you can pass to the WebView, or you can request the results in JSON format.

Steps to build a query:

  1. Create builder with primary key
  2. Set options and add other keys
  3. call .toQueryURI() to get the URL of the query

Parameters:
search_attribute_key - primary key where the items will be sorted for
Returns:
DBQueryBuilder
See Also:
DBQueryBuilder

setLogLevel

public void setLogLevel(int loglevel)