Classes

Classes

Class SFS2X.Entities.Match.MatchExpression

A matching expression used to compare custom variables or predefined properties when searching for users or Rooms.

Class Summary
Constructor Attributes Constructor Name and Description
 
SFS2X.Entities.Match.MatchExpression(varName, condition, value)
Creates a new MatchExpression instance.

Field Summary

Method Summary

Class Detail

SFS2X.Entities.Match.MatchExpression(varName, condition, value)
Creates a new MatchExpression instance.

Matching expression are used to compare custom variables or predefined properties when searching for users or Rooms. They are built like "if" statements in any common programming language. They work like queries in a database and can be used to search for Rooms or users using custom criteria: in fact a matching expression can compare predefined properties of the Room and user entities (see the RoomProperties and UserProperties classes), but also custom Room or User Variables.

These expressions are easy to create and concatenate, and they can be used for many different filtering operations within the SmartFoxServer 2X framework, for example to invite players to join a game (see the CreateSFSGameRequest request description), to look for specific Rooms or users (see the FindRoomsRequest and FindUsersRequest requests descriptions), etc.

Additionally:
- any number of expressions can be linked together with the logical AND and OR operators to create complex queries;
- searching through nested data structures such as objects and arrays can be done via a very simple dot-syntax.

Example #1 below shows how to create a simple matching expression made of two concatenated conditions: it compares the custom "rank" and "country" User Variables to the passed values. This expression could be used during the creation of a Game Room, to filter the users that the server should take into account when sending the invitations to join the game (only italian users with a ranking greater than 5 - whatever this number means to our game).

Example #2 creates a matching expression made of three concatenated conditions which compare two predefined Room properties and the custom "isGameStarted" Room Variable to the passed values; this expression could be used to retrieve all the Game Rooms still waiting for players to join them.

Example #3 creates a matching expression which compares a nested property in a complex data structure; an object called "avatarData" (could be a User Variable for example) contains the "shield" object (a nested object) which in turn contains, among others, the "inUse" property which could be used to retrieve all user whose avatars are currently equipped with a shield.

Example #4 is similar to the previous one, but it involves an array. The "avatarData" object contains the "weapons" array, from which the expression retrieves the third element (that .3 means "give me the element at index == 3") that we know being the weapon the user avatar has in his right hand. Again, this element is an object containing, among the others, the "name" property which can be compared to the passed string. This example could be used to retrieve all users whose avatars have the Narsil sword in the right hand.

// Example 1
var exp = new SFS2X.Entities.Match.MatchExpression('rank', SFS2X.Entities.Match.NumberMatch.GREATER_THAN, 5)
                                              .and('country', SFS2X.Entities.Match.StringMatch.EQUALS, 'Italy');
 
// Example 2
var exp = new SFS2X.Entities.Match.MatchExpression(SFS2X.Entities.Match.RoomProperties.IS_GAME, SFS2X.Entities.Match.BoolMatch.EQUALS, true)
                                              .and(SFS2X.Entities.Match.RoomProperties.HAS_FREE_PLAYER_SLOTS, SFS2X.Entities.Match.BoolMatch.EQUALS, true)
                                              .and('isGameStarted', SFS2X.Entities.Match.BoolMatch.EQUALS, false);
 
// Example 3
var exp = new SFS2X.Entities.Match.MatchExpression('avatarData.shield.inUse', SFS2X.Entities.Match.BoolMatch.EQUALS, true);
 
// Example 4
var exp = new SFS2X.Entities.Match.MatchExpression('avatarData.weapons.3.name', SFS2X.Entities.Match.StringMatch.EQUALS, "Narsil");
Parameters:
{String} varName
Name of the variable or property to match.
{<any>Match} condition
A matching condition among those provided by the BoolMatch, NumberMatch and StringMatch classes.
{*} value
The value to compare against the variable or property during the matching.
See also:
SFS2X.Entities.Match.RoomProperties
SFS2X.Entities.Match.UserProperties
SFS2X.Entities.Match.BoolMatch
SFS2X.Entities.Match.NumberMatch
SFS2X.Entities.Match.StringMatch
SFS2X.Requests.Game.CreateSFSGameRequest
SFS2X.Requests.System.FindRoomsRequest
SFS2X.Requests.System.FindUsersRequest

Field Detail

{<any>Match} condition
Returns the matching criteria used during values comparison among those provided by the BoolMatch, NumberMatch and StringMatch classes.
See also:
SFS2X.Entities.Match.BoolMatch
SFS2X.Entities.Match.NumberMatch
SFS2X.Entities.Match.StringMatch
{LogicOperator} logicOp
In case of concatenated expressions, returns the current logical operator.
Default Value:
null
See also:
SFS2X.Entities.Match.LogicOperator
Returns the next matching expression concatenated to the current one, if existing.
Default Value:
null
{*} value
Returns the value against which the variable or property corresponding to varName is compared.
{String} varName
Returns the name of the variable or property against which the comparison is made.

Depending what the matching expression is used for (searching a user or a Room), this can be the name of a User Variable or a Room Variable, or it can be one of the constants contained in the UserProperties or RoomProperties classes, representing some of the predefined properties of the user and Room entities respectively.

See also:
SFS2X.Entities.Match.RoomProperties
SFS2X.Entities.Match.UserProperties
SFS2X.Entities.Variables.SFSRoomVariable
SFS2X.Entities.Variables.SFSUserVariable

Method Detail

  • {MatchExpression} and(varName, condition, value)
    Concatenates the current expression with a new one using the logical AND operator.
    Parameters:
    {String} varName
    Name of the additional variable or property to match.
    {<any>Match} condition
    The additional matching condition among those provided by the BoolMatch, NumberMatch and StringMatch classes.
    {*} value
    The value to compare against the additional variable or property during the matching.
    Returns:
    {MatchExpression} A new MatchExpression resulting from the concatenation of the current expression with a new one generated from the specified parameters.
    See also:
    SFS2X.Entities.Match.LogicOperator.AND
  • {Boolean} hasNext()
    Checks if the current matching expression is concatenated to another one through a logical operator.
    Returns:
    {Boolean} true if the current matching expression is concatenated to another one.
  • {MatchExpression} or(varName, condition, value)
    Concatenates the current expression with a new one using the logical OR operator.
    Parameters:
    {String} varName
    Name of the additional variable or property to match.
    {<any>Match} condition
    The additional matching condition among those provided by the BoolMatch, NumberMatch and StringMatch classes.
    {*} value
    The value to compare against the additional variable or property during the matching.
    Returns:
    {MatchExpression} A new MatchExpression resulting from the concatenation of the current expression with a new one generated from the specified parameters.
    See also:
    SFS2X.Entities.Match.LogicOperator.OR
  • {MatchExpression} rewind()
    Moves the iterator cursor to the first matching expression in the chain.
    Returns:
    {MatchExpression} The MatchExpression object at the top of the chain of matching expressions.
  • {String} toString()
    Returns a string representation of the matching expression.
    Returns:
    {String} The string representation of the MatchExpression object.