The Game Object Space (GoS) is a distributed cache which exists "between" the game nodes in order to share table data. Each table will at any given point exist in the memory space of at least two servers for each cluster in order to provide failover should one server fail unexpectedly.

The System State is a loosely distributed state shared by the entire server for the lobby and transient player data. This distributed cache is replicated between the servers in batches, where the GoS (see above) instantly replicates delta changes the system state will group changes into batches and replicate on a configurable interval.

The message bus (MBus) is the event layer binding nodes together in a cluster. It contains several "channels" for distributing events to game nodes, to services, or to client nodes.

This section describes the replication and fail-over (if enabled) process for game nodes. It also applies for tournament nodes, the only change is that the game object used (i.e. the actor) is a tournament object instead of a table object).

Replication

An object will be replicated between servers (i.e. space instances) when an object is put to the space. For regular table and tournament executions this is when the event handling has been completed and the state is returned to the space (by a 'put'). The replication can be configured in multiple ways, depending on the requirements by the user.

Below is a sequence diagram of executing an event for a table including the space calls.

Figure 2.1. Replication Sequence Diagram

Transactions

When accessing a game object (table or tournament) with a 'take'/'put' we will always access it within a transaction. Thus, the execution of events on game objects are also always performed within a transaction.

Below is the replication sequence again but with the transaction boundaries added.

Figure 2.2. Replication with Transaction Sequence Diagram

Firebase supports two different types of transactions to be used. The default mode is a local user transaction that will not be visible to the game implementation. The optional mode is using a JTA transaction manager which will provide an XA transaction that the game implementation can use. The JTA manager implementation used at the time of writing is Bitronix.

The advantage of using a JTA manager is that you get a single commit for the state replication and your own game specific transaction (database calls would be the top candidate here) although performance may suffer. This has nothing to do with the internal wirings of Firebase and everything to do with the fact that two phase XA transaction implementations are expensive.

User Transaction

When not using a JTA manager you will most likely start your own user transactions for database calls (and any other transactional resources). This will result in a nestled transaction for the event handling like in the sequence below (some calls have been omitted for clarity).

Figure 2.3. User Transaction Sequence Diagram

For the scenario above is it important to realize that the nestled transaction ('game transaction' in the sequence diagram) can very well be committed without the 'internal transaction' being committed properly. A roll-back of the 'internal transaction' will not cause a roll-back of the 'game transaction'. In this scenario it is therefore important to write robust handling for roll-back scenarios for the 'game transaction'.

If 'game transaction' fails and is rolled back, you can throw a RuntimeException to roll back the 'internal transaction'. This cannot, however, be applied the other way around.

Example 2.1. Failing User Transaction

Let's say you are executing a user event ('event1') regarding a monetary transaction from an account to the given table. You make the database writings within a user transaction and commits, then something goes awry and an exception is thrown which will result in the 'internal transaction' getting rolled back. The state of the table have now been rolled back and will not reflect the state-changes you started to make while executing event1, but the storage facility (database) will have moved money according to the event. To properly handle this case you need a robust idempotent handling for the monetary transactions (this is something that is probably recommended regardless application) so that the money is not moved again.

A similar real world use case is where you have a remote server that publishes a service for executing monetary transactions. Calls to such services are normally not contained in a distributed transaction, so if the call never returns you will not know if the call was handled or not. The same scenario applies for the example. A good way of solving the unknown variable is letting the service manage duplicate calls (i.e. idempotency). Failing to do so in a service implementation will for most systems lead to unwanted behaviour.

[TBW]

[TBW]

Firebase utilises a JTA implementation from Bitronix

Database and JDBC driver support for XA is somewhat lacking. Please make sure your choice of database supports XA properly before integrating. Firebase can emulate XA for JDBC drivers, but for complex scenarios this may not be enough. A partial investigation of databases and XA support have been made by the Bitronix team here.

Firebase does not support XA recovery.

Firebase does not support distributed XA transactions.

If XA integration is required developers are encouraged to investigate possible repercussions before system design. This is particularly true if XAResource integration is needed.

Some recommended reading is:

Firebase support databases via deployment of data sources as XML files in the server deployment folder. A data source is a basic JDBC connection to a database. All deployed datasource setup by Firebase, and all connection will be pooled for performance.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <entry key="url">jdbc:mysql://localhost:3306/test</entry>
  <entry key="driver">com.mysql.jdbc.Driver</entry>
  <entry key="user">root</entry>	
  <entry key="password"></entry>
</properties>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <entry key="url">jdbc:mysql://localhost:3306/test</entry>
  <entry key="driver">com.mysql.jdbc.Driver</entry>
  <entry key="user">user1</entry>	
  <entry key="password">password1</entry>
  <entry key="validation-statement">SELECT 1</entry>
  <entry key="min-pool-size">2</entry>
  <entry key="max-pool-size">20</entry>
</properties>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <entry key="tx-type">LOCAL-TX</entry>
  <entry key="xa-data-source">
  	oracle.jdbc.xa.client.OracleXADataSource
  </entry>
  <entry key="pool-size">50</entry>
  <!-- Data Source Properties -->
  <entry key="ds.url">jdbc:oracle:thin:@localhost:1521:XE</entry>
  <entry key="ds.password">password1</entry>
  <entry key="ds.user">user1</entry>
</properties>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <entry key="tx-type">LOCAL-TX</entry>
  <entry key="driver">com.mysql.jdbc.Driver</entry>
  <entry key="pool-size">10</entry>
  <entry key="url">jdbc:mysql://localhost/test1</entry>
  <entry key="password">password1</entry>
  <entry key="user">user1</entry>
</properties>

Firebase enables Java Persistence archives to be deployed similarly to JDBC data sources. It uses Hibernate as the underlying JPA implementation.

You can deploy a persistence archive as a stand alone persistence archive ('.par') or bundled with the game ('.gar'). Using a separate persistence archive ('.par') allows all resources to access the persistence archive. Using a persistence archive inside a game archive ('.gar') scopes the persistence archive to that specific game only.

Reference documentation for Hibernate can be found here.

Below is some example code for persisting a TestItem within a game, using a persistence context named 'test':

GameContext context; // This will be injected ini 'init' method

private void createTestItem() {
  // Get the persistence service from the service registry
  ServiceRegistry reg = context.getServices();
  Class key = PublicPersistenceService.class;
  PublicPersistenceService service = reg.getServiceInstance(key)
  // Get the entity manager for the persistence unit named 'test'
  EntityManager em = service.getEntityManager("test"); 
  // Create the bean
  TestItem item = new TestItem();
  item.setText("some data");
  persist(em, item); 
}
          
private void persist(EntityManager em, TestItem unit) {
  // Omitted for now, see below
}

The method for performing the persist call will be different depending on if you are using local transactions or XA transactions. This can be specified in the datasource and in the 'persistence.xml'.

Persisting using a non-JTA data source.  When using a data source which does not support JTA you need to begin and commit a local transaction yourself. It is important that you always release the transaction after executing.

protected void persist(EntityManager em, TestItem unit) {
  EntityTransaction transaction = em.getTransaction();
  try {
    transaction.begin(); 
    em.persist(unit);
    transaction.commit(); 
  } catch (Exception e) {
    transaction.rollback();
  }
}

Persisting using a JTA data source.  If you are using a JTA data source you will be using XA transactions. If you are executing inside a game there will already be a transaction declared and you do not need to begin a transaction.

protected void persist(EntityManager em, TestItem unit) {	
  em.persist(unit);
}

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
   	http://java.sun.com/xml/ns/persistence 
  	http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
  version="1.0">
   
  <persistence-unit name="test" transaction-type="RESOURCE_LOCAL">
    <non-jta-data-source>system</non-jta-data-source>
    <class>com.cubeia.firebase.api.entity.User</class>
    <properties>
      <property 
        name="hibernate.dialect" 
        value="org.hibernate.dialect.MySQL5Dialect"/>
      <property 
        name="hibernate.hbm2ddl.auto" 
        value="update"/>
    </properties>
  </persistence-unit>
</persistence>

All tables created in the system are automatically arranged in a lobby. The lobby is a data structure organising its members in a tree of objects. Each table in the lobby has a path, for example. /realMoney/10plyrs/table21, and a set of attributes describing the table. The platform will automatically arrange the lobby, but also has options for customising the lobby path and the attributes of a table when the table is created.

The structure of the lobby as static and defined when a game is developed. Client and server developers will have to agree on a lobby model to use, the server game developers populate the lobby and make sure changes are properly propagated, and the client developers uses a subscription model with delta changes to manage the lobby representation in the actual game clients.

The chat channels managed by Firebase work much like ordinary IRC channels. If a channel does not exist it will be created when the first message is sent and client can choose to listen or send chat events for particular channels. As such, it is trivial for the developers to add, remove and use the chat system.

You connect to firebase by opening a TCP socket on a server running a gateway node and using the port specified in the server configuration file 'cluster.props'. The default port is 4123. The server will not send out any handshake packet or expect any specific first packet from the client (this is likely to change in the future).

The client can issue the following platform specific commands before being logged in:

It is highly recommended that the client verifies the platform protocol version first and then verifies the specific game version before continuing. If a mismatch is detected it will not be safe to continue.

A client can send a login request. The packet is defined with the following fields: '

The credentials is a byte array with arbitrary data which can be used by the LoginHandler. The LoginHandler is service which can be deployed to handle authentication for an installation.

import com.cubeia.firebase.api.action.local.LoginRequestAction;
import com.cubeia.firebase.api.login.LoginHandler;
import com.cubeia.firebase.api.login.LoginLocator;
import com.cubeia.firebase.api.service.Service;

public class TestLoginLocator implements Service, LoginLocator {

  private TestLoginHandler handler = new TestLoginHandler();

  [...]

  @Override
  public LoginHandler locateLoginHandler(LoginRequestAction request) {
    // Here we could use different login handlers for different 
    // operators, but for simplicity we're restricting ourselves
    // to one unified login handler
    return handler;
  }
}

import java.util.concurrent.atomic.AtomicInteger;
import com.cubeia.firebase.api.action.local.LoginRequestAction;
import com.cubeia.firebase.api.action.local.LoginResponseAction;
import com.cubeia.firebase.api.login.LoginHandler;

public class TestLoginHandler implements LoginHandler {

  private AtomicInteger pid = new AtomicInteger(0);
	
  @Override
  public LoginResponseAction handle(LoginRequestAction req) {
    // At this point, we should get the user name and password
    // from the request and verify them, but for this example
    // we'll just assign a dynamic player ID and grant the login
    return new LoginResponseAction(true, 
    				req.getUser(), 
    				pid.incrementAndGet());
  }
}

The client use system JoinTableRequest to join tables. After which game play is defined by the games themselves. The system will keep track of which tables each client is watching and which tables they are seated at. If a client joins or watches a table, a reference for that client will be set in the system state.

Then the server receives a logout command it will clean up resources for the client on the server. This includes:

If a user disconnects - loses connection without a logout - the system will take the following actions:

When the client has been in status WAITING_REJOIN in the system state for a set time period (configurable in server configuration for 'cluster.props' as the property 'node.client.client-reconnect-timeout'), a reaper will remove the client from the system state.

If the client reconnects before the reaper time, then he will receive notifications for each table watching and seated at. Lobby and filtered join requests will not be resumed so if you want a transparent fail-over you need to re-subscribe in your client.

If the client reconnects after the reaper time, then the reference to seated tables etc. have been cleaned up and he will not receive any notifications.

If a client logs in with a player ID that is already logged in, the first client will be forcibly logged out and its socket will be closed.

Class loaders are formed in a hierarchy use parent / child relations ships. Below is a flattened tree of the class loader types involved in a Firebase installation. A '*' at a class loader marks that the class loader occurs mutliple times, for example there will be one class loader for each game.

Figure 2.4. Class Hierarchy Outline

The above class loaders are sourced from different locations in the Firebase installation directory, with the exception if the 'shared' class loader which maintains an export table for classes that need to be available through the entire server.

From this follows that all JAR files placed './lib/common' will be shared by both servers and games, and the JAR files in './game/lib' will be universal for the deployed games and services. Also, that no JAR or SAR files in './lib/internal' will be available to the deployed games.

Services are deployed and made available across the entire server. This is done via the method called 'exporting', where the service contract is automatically exported by virtue of extending Contract.

Class referenced by the service contract must either also be exported, by explicitly declaring them in the service descriptor, or be placed in 'lib/common'. This is because service contracts are loaded by the 'shared' class loader in order to be accessible through the entire server.

A common task will be to share utility libraries across games and services. Understanding of the class loader hierarchy is vital to achieve this, but in short the following short rules apply:

If both games and services needs to share classes they can only be placed in 'game/lib' or 'lib/common'. However, it is worth noticing that in the system class loader will never be eligible for hot re-deployment, and will be universal for the entire server.

The denial of service (DOS) protector service is a simple service which contains server-wide frequency access rules. It can be used for rudimentary DOS control. You can lookup the service by using the contract like this:

serviceRegistry.getServiceInstance(DosProtector.class);

The login locator extends Firebase to provide authentication for an installation. Please refer to the 'Writing a Login Handler' section for details.

Player lookup is connected to the player query request/response available to the clients. The player query response contains a byte array which can be used for implementation specific data. To be able to take advantage of this you need to implement a specific PlayerLookupService.

A player query request is generated by the client, the request is received and dispatched in the client node locally, i.e. the request will only be handled locally and will not be distributed in the system.

To provide you own lookup service, implement and deploy a service that implements the PlayerLookupService interface.

The local handler service is a service that can receive data from a client that is not logged in. Routable services need a logged in client since the player/client id is the unique identifier used for routing events throughout the system. There can only be only local handler service deployed, so if you need to send different events you will need to implement a dispatcher.

Below is an example of the java implementation of a simple local handler implementation. Code that is not directly related to the implementation specifics of the service has been omitted:

[...]
   				
public class SimpleLocalService implements 
  LocalHandlerService, Service {
	
  [...]
	
  public void handleAction(
    LocalServiceAction action, 
    LocalActionHandler loopback) {
    
    String text = new String(action.getData());
    String resp = text.toUpperCase();	
    int seq = action.getSequence();
    LocalServiceAction response = new LocalServiceAction(seq);
    response.setData(resp.getBytes());
    loopback.handleAction(response);
  }
}

The chat filter plugin service can be used to filter or modify chat messages server-side. The filter service will be instantiated on each server node in a cluster, this gives rise to a possibly unexpected behaviour (see below). The main use for this service should be to filter messages.

The notification of creation and destruction of a chat channel is not "atomic across multiple virtual machines". In effect, this means a multi-server cluster may get notifications of creation or destruction simultaneously on two separate server. No attempt to synchronise this is made by Firebase itself, and as such implementers must be aware that this may happen in some circumstances.

The message flow for an incoming chat message in Firebase looks like this:

Please refer to the Java API documentation for more information on the ChatFilter.

A client can query Firebase for system information by sending a SystemInfoRequestPacket. The response will be populated with some predefined data (e.g. player count), but it is also possible for 3rd parties to amend extra information to the response. To be able to take advantage of this you need to implement a specific SystemInfoQueryService.

A system info request is generated by the client, the request is received and dispatched in the client node locally, i.e. the request will only be handled locally and will not be distributed in the system. The call to the system info service will be asynchronous by a different thread to make sure that any custom implementation is not blocking game packets from execution if the logic is stalling (e.g. database calls with high latency).

Below is en example of the java implementation of a simple lookup implementation. Code that is not directly related to the implementation specifics of the system info service has been omitted:

[...]

public class SystemInfoMutator implements 
  Service, SystemInfoQueryService {

  private Random rng = new Random();
    
  /** Adding a randomly generated number as 'Jackpot' */
  public SystemInfoResponseAction appendResponseData(
  	SystemInfoResponseAction action) {
  	
  	int next = rng.nextInt(100000);
  	Parameter p = new Parameter<Integer>("Jackpot", next, Type.INT);
  	action.getParameters().add();
    return action;
  }

  [...]

}

Firebase support loopback scheduling by providing a TableScheduler which is available via the table, through the Table.getScheduler() method. Scheduled game actions are delivered back to the game after a given delay in milliseconds.

The TableScheduler.scheduleAction(GameAction, long) method is sued to schedule an action, and returns a UUID which acts as an identifier for the action. Please note that this is a loopback actions, which will be inserted into the Game when scheduled, it will not be sent to any client. It is typically used for scheduling a timeout when a player should act.

The TableScheduler.cancelScheduledAction(UUID) can be used to cancel an already scheduled action using the ID returned when the action was scheduled. This is typically done when an action is scheduled for a timeout for a player, but the player did act in time.

It should be noted here, that Firebase cannot guarantee that the timeout does not occur at the same time as the player's action is being handled, in which case the scheduled action cannot be cancelled. Therefore, the game must still verify that a timeout that occurs is expected. This can be done by checking the identifier of the scheduled action when it is received by the game.

The Game interface is mandatory. It specifies two life time methods for the game instance, and one accessor for the processor responsible for the game. Below is an abbreviated view of the game interface, please refer to the Java API documentation for more information.

public interface Game [...] {
	
  /**
   * @param con Game context, never null
   * @throws SystemException If the game fails to initialize
   */
  public void init(GameContext con) throws SystemException;
	
  /**
   * Get the Game Data processor class for actions. This method will 
   * be accessed concurrently, but only for one table at a time. By 
   * returning new game processors for each call, the game processors
   * does not need to be concurrent.
   * 
   * @return A game processor, never null
   */
  public GameProcessor getGameProcessor();

  /**
   * Called when the game will no longer be used.
   */
  public void destroy();

}

The TableInterceptor interface can be implemented by the game in order to control seat, leave and reservation requests on the table, which is otherwise handled transparently by Firebase.

For example, if a player is involved in a game, that for some reason does not allow players to leave mid-game, the TableInterceptor can return false when the TableInterceptor.allowLeave(Table, int) method is called for a player who is currently in the game. It is up to the game to then remember that the player wants to leave and then remove the player at a later time, if that is the desirable behaviour.

If the game does not want to implement TableInterceptor directly, it can instead implement the TableInterceptorProvider which only contains a getter for a TableInterceptor.

The TableListener interface can be implemented to listen for table events that are handled external to the game by Firebase. These events include join, leave, reservations, status changes etc.

If the game does not want to implement TableListener directly, it can instead implement the TableListenerProvider which only contains a getter for a TableListener.

If a game participates in a tournament, this interface should be implemented. It provides a tournament processor used to start and stop tournament 'rounds'. Please refer to the tournament documentation for more details.

A game is configured with a game activator in the deployment descriptor using the "activator" element. For example:

<game-definition id="112">
  <name>MyGame</name>
  <version>v0.2</version>
  <classname>com.mygame.server.MyGame</classname>
  <activator>com.mygame.server.MyGameActivator</activator>
</game-definition>

The configured 'activator' element must indicate a class which implements the interface GameActivator and has a default constructor.

If no activator is configured the system DefaultActivator will be used. The activator is primarily responsible for creating and destroying tables. It is guaranteed to be a singleton within a cluster. That is: if Firebase is configured as a cluster with many game nodes there will only ever be one activator created at any time.

The default activator is a simple instance of a GameActivator shipped with Firebase in the API classes. It uses a very simple naming pattern and lobby path. It can be configured via an XML file (see above) in the following format:

<activator>
  <!--
    - Frequency in wich the activator scans the available tables
    - to check for changes in millis. Default value is 5 seconds. 
    -->
  <scan-frequency>5000</scan-frequency>
  <initial-delay>10000</initial-delay> 
  <tables>
    <!-- Number of seats at the table -->
    <seats>10</seats>
    <!-- Minimum number of tables -->
    <min-tables>10</min-tables>
    <!-- Min available empty tables -->
    <min-available-tables>10</min-available-tables>
    <!-- Increment size, ie. how many 
       - tables do we create at one time -->
    <increment-size>10</increment-size>
    <!-- Timeout value for empty tables in millis. 
       - Default value is 2 minutes. -->
    <timeout>120000</timeout> 
    </tables>
</activator>

The DefaultActivator may be sub-classed, but developers are encouraged to write their own activator instead as the DefaultActivator is primarily intended as an example.

A game is deployed in a game archive. The game archive is defined as a ZIP file with the extension "gar" (Game Archive). The content of the game archive should match:

The class implementing the Game interface should be placed in a JAR in the root of the GAR file. JAR files placed in the root or in the lib ('/' or '/GAME-INF/lib') will be loaded by the class loader. However, only JAR files in the root will be scanned for annotations that may be used for persistence services for instance.

[TBW]

Within a SAR file a service must be declared using a service descriptor. This is an XML formatted file which describes the service the archive contains. Below is an example service descriptor, containing all legal elements:

<service auto-start="false">
  <name>A Simple Example Service</name>
  <public-id>ns://www.cubeia.com/examples/service</public-id>
  <contract>com.cubeia.example.service.SimpleService</contract>
  <service>com.cubeia.example.service.impl.ServiceImpl</service>
  <description>This is a simple example service.</description>
  <dependencies />
  <exported>
    <package>com.cubeia.example.service.*</package>
  </exported>
</service>

The service descriptor must be named 'service.xml' and be placed in a 'META-INF' folder in the root of the service archive. In other words:

/META-INF/service.xml

Of the elements in the example above, 'name', 'public-id', 'contract' and 'service' are mandatory. The name should a readable title for the service. The public ID is a globally unique string identifier, normally modelled on a name space, and is used to identify the service. The contract should detail the service contract interface class (fully qualified class name). And finally the service should detail the fully qualified class name of the implementing service class.

The SAR file follows a simple structure. The service and its associated classes should be packaged in a JAR file and placed in the SAR file root. The name of the JAR file is inconsequential. The service descriptor should be placed in a "META-INF" directory and external libraries in the "META-INF/lib" directory. The structure should match:

Services may depend on each other. In practical terms this only means that depending services will be initiated after their dependents. As a result it is safe for a depending service to reference its dependent during its own initiation.

Dependencies are declared using the service descriptor 'dependencies' element. This element accepts child elements 'contract' or 'public-id'. For example:

[...]
  <dependencies>
    <contract>com.cubeia.example.SimpleService</contract>
    <public-id>my-second-service</public-id>
  </dependencies>
[...]

The above declaration explains that the declared service depends on any service implementing the SimpleService contract and the service declared with the public id 'my-second-service'.

Circular dependencies are not allowed.

Services are normally isolated. This means that services will be loaded by their own class loader and manage their own resources. However, if this would only be the case services would not be usable as they could not be referenced from classes loaded by other class loaders. To be usable by games or other services, a service exports classes or entire packages. An exported class is usable by the entire server. The service contract interface is always exported.

Exported classes or packages are declared using the 'exported' element and its child elements 'class' and 'package'. The 'class' element should details a fully qualified class name of a class to export. The 'package' element is used to export entire packages and optionally their sub-packages as well. It must end with either a hyphen or a star, where a package name ending with '*' represents the current package but no sub-packages and a '-' means the current package and all sub-packages. For example:

[...]
  <exported>
    <class>com.cubeia.example.SimpleClass</class>
    <package>com.cubeia.example.common.*</package>
    <package>com.cubeia.util.-</package>
  </exported>
[...]

The above example exports the SimpleClass. It also exports the 'com.cubeia.example.common' package but none of its sub-packages. And finally it exports the 'com.cubeia.util' package, including all its sub-packages.

Please refer to the class loading reference in this manual for more information on exported classes.

Services may use external libraries. These can either be placed globally in the server, or be packaged in the service SAR file.

The entire server loads JAR files from the 'lib/commons' folder in the server installation directory. Consequently, services may place required libraries there. However, this is strongly discouraged as this (1) increases the maintenance burden on the server; (2) decreases service isolation; (3) invalidates future hot re-deployment of services; and (4) forces the given library on the entire server with possible class loading clashes as a result.

Dependencies can also be shared if they are placed in 'game/lib' which is common for all deployed artifacts.

Finally JAR files can also be embedded in the SAR, under '/META-INF/lib'.

Service may read resources from their own SAR file. This is done via the ResourceLocator module which is made available to them in their ServiceContext.

A service is deployed in a service (SAR) archive. The archive is defined as a ZIP file with the extension "sar". The content of the service archive should match:

JAR files placed in the root or in the lib ('/' or '/META-INF/lib') will be loaded by the class loader, with the exception of exported classes (please refer to this page for class loading issues).

The UAR does not have to be a ZIP archive. For rapid deployment it can be a folder instead, however, the folder name must still end with ".uar".

Deployment units within a unified archive will use a shared class loader making it possible to share classes between for example tournaments and games. It is also possible to place utility libraries directly within the UAR file itself to have them shared between the deployment units, at the following locations:

Services deployed as members of a unified archive will loose their internal isolation as a result of the shared class loader. In other words, even though the implementation classes of a service may not be exported they can still be seen and used by other members of the same UAR. This usage, however, is discouraged and the services will still be isolated in respect to the rest of the system.

The following properties can be set in the cluster properties (shown with default values):

Intervals are configured in milliseconds, however some of them may be truncated down to seconds depending on underlying transport mechanism. It is recommended to configure the service in even seconds only.

In order to enable ping failure detection, set 'service.ping.ping-enabled' to 'true'.

A client will be deemed 'idle' if the server does not get any data from it within 'service.ping.initial-ping-delay' milliseconds. By keeping this value a multiple of the ping interval an installation can dramatically decrease the actual number of pings sent.

The frequency of the pings is configured by 'service.ping.ping-interval' in milliseconds.

A ping will be considered failed after 'service.ping.ping-timeout' milliseconds, and when the number of failed pings reaches 'service.ping.failure-threshold' the client will be disconnected.

If one server handles very many client, you may want to increase the number of threads used for scheduling purposes by setting 'service.ping.number-of-threads', although this should rarely by needed.

The Firebase API's automatically handles ping messages on the client side. Developers using their own connection code needs to handle the PingPacket by simply returning it as soon as it is received. The packet must not be modified on the client side as it contains a unique id which will need to be preserved for the entire ping round-trip.

To create a new game (GAR) module, execute:

mvn archetype:generate \
  -DarchetypeGroupId=com.cubeia.tools \
  -DarchetypeArtifactId=firebase-game-archetype \
  -DarchetypeVersion=1.7

To create a new service (SAR) module, execute:

mvn archetype:generate \
  -DarchetypeGroupId=com.cubeia.tools \
  -DarchetypeArtifactId=firebase-service-archetype \
  -DarchetypeVersion=1.7

To create a new tournament (TAR) module, execute:

mvn archetype:generate \
  -DarchetypeGroupId=com.cubeia.tools \
  -DarchetypeArtifactId=firebase-tournament-archetype \
  -DarchetypeVersion=1.7

To create a new multi-module (UAR) project, execute:

mvn archetype:generate \
  -DarchetypeGroupId=com.cubeia.tools \
  -DarchetypeArtifactId=firebase-project-archetype \
  -DarchetypeVersion=1.7

The Firebase archive plugin should be included in the build section of the POM, like so:

[...] 

<build>
  <plugins>
    <plugin>
      <groupId>com.cubeia.tools</groupId>
      <artifactId>archive-plugin</artifactId>
      <version>1.7</version>
      <extensions>true</extensions>
    </plugin>
  </plugins>
</build>

[...]

The Firebase archive plugin recognises the 'firebase-sar', 'firebase-gar', 'firebase-tar', and 'firebase-uar' as packaging in the POM. For example:

<packaging>firebase-gar</packaging>

<project 
  xmlns="http://maven.apache.org/POM/4.0.0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
  http://maven.apache.org/maven-v4_0_0.xsd">
  
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.my-company.test</groupId>
  <artifactId>funkyGame</artifactId>
  <packaging>firebase-gar</packaging>
  <name>Funky Game</name>
  <version>1.0-SNAPSHOT</version>

  <dependencies>
    <dependency>
      <groupId>com.cubeia.firebase</groupId>
      <artifactId>firebase-api</artifactId>
      <version>1.7.0-CE</version>
      <scope>provided</scope>
    </dependency>	
    <dependency>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
      <version>1.2.14</version>
    </dependency>
  </dependencies>
  
  <build>
    <plugins>
      <plugin>
        <groupId>com.cubeia.tools</groupId>
        <artifactId>archive-plugin</artifactId>
        <version>1.7</version>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

A client can join a table either by:

Which flow you should use is usually dictated by the game design. For example, in most poker clients you open a table first (watch) and then select a seat (join).

The communication flow differs for the two cases. When a watch is sent Firebase will respond with seat info packets for all players currently at the table. If you then join the table, then no seat info packets will be sent (they are regarded redundant). However, should you join a table without watching first then you will receive a seat info packet for each player.

If the client for some reason drops the connection or crashes and is restarted, then when the user re-logs in (manually or automatically) then Firebase will notify the client what tables he/she was seated at and/or watching.

Clients can request tables to be created and automatically receive a reservation on the new table. They can also, in the same step, send invitations to other player who will also get reserved seats at the new table. This is done by sending a CreateTableRequest from the client to the server. This request will be handled by the server together with the game activator and a new table will eventually be created. The server will answer with a CreateTableResponse which will have its status set to '0' if the table have been created and the seat id reserved for the player, the client should claim the reserved seat using an ordinary join request.

A CreateTableRequest may optionally contain a list of invitee ids. The ID's will be matched to players and these players will receive a NotifyInvited action informing them that there is a seat reserved for them at a table. Again, if a client receives this event, it should answer with an ordinary join request, otherwise the seat reservation may lapse.

In order for this to work, the game activator, on the server, must implement the RequestAwareActivator interface. This interface allows the activator to react on incoming requests and participate when the table is created. This is similar to ordinary table creation but also contains options for modifying the list of invitees and determining if seats should be reserved for invitees. The activator may also reject the request. If the activator does not implement the RequestAwareActivator interface an error will be printed in the logs.

Clients may be invited to games, in which case a NotifyInvited will be received. The client should use a join request to claim the reserved seat. Clients may invite other clients by sending a InvitePlayersRequest. The server may simply reserve a seat and send out NotifyInvited to the affected clients.

In the server, the following actions are taken when a client disconnects (without an explicit logout):

In the event of a disconnect right after a join request to a table, we might have a boundary case where the player status on the table is still CONNECTED.

In the client, when reconnecting and logging in you will receive the following:

In the event of a reconnect directly after a join request was sent, you might be able to receive a join response for that table. The reason for this is that messaging is asynchronous within the system, and if you have successfully reconnected before the response is delivered to the gateway tier, then we will deliver it to you.

In the event of a reconnect after the response was discarded but before the player/table association state has propagated (for the newly joined table), you may have a player seated at a table with the status CONNECTED. The client session will pick this up when the table is communicating and send a notify seated for that table. There will only be one NotifySeated per table.

For example:

This packet means that you were watching the provided table in your previous session. You should either acknowledge this by sending a watch request or unwatch request. If you send a watch request you will start to receive table events. If you send an unwatch request the association will be removed from your session and should you reconnect again you will not receive a notify watching. If you do not acknowledge the notification then the association will still be present in your session until either you acknowledge it or the reaper cleans up your session (timeout or logout).

To register to a tournament, send a MTTRegisterRequest packet for the tournament ID you want to register to. You will receive an MTTRequestResponse from the server. If the registration was successful, the response status will be OK. Note that if the same client registers to the same tournament again, the server will return response status OK again.

When the tournament starts, players registered for the tournament will receive an MTTSeated packet. At this point, the player will be registered as a seated player at a table in the tournament and will thus be sent packets for everything that happens in the tournament. The client must therefore make sure to react on the MTTSeated packet by opening up a table where the actions can be shown.

When a player is out of the tournament, he will receive an MTTPickedUp packet. The packet's 'keep_watching' flag will be set to true. This means that the player can keep watching the action at the table where he was seated. It is up to the client to decide when to stop watching the table, by sending an UnwatchRequest packet.

When a player is moved to a new table, he will receive an MTTPickedUp packet. The packet's 'keep_watching' flag will be set to false. This means that the client should close (or clear) the current table. As with the MTTSeated packet, the player will automatically receive all subsequent actions on the new table.

There is currently no Firebase packet for notifying a client that the tournament is finished. This is intentional, because it is up to the tournament implementation to define the logic and send messages to the client as appropriate.