Package com.smartfoxserver.entities.match

Class MatchExpression

java.lang.Object
com.smartfoxserver.entities.match.MatchExpression
All Implemented Interfaces:
Serializable
public class MatchExpression extends Object implements Serializable

Overview

Match Expressions are conditional expressions used to filter Users or Rooms in specific API calls. They work like queries in a database and can be used to search for Rooms or Users using custom criteria. These expressions are very easy to build and concatenate to generate custom filters used to Match Users and Rooms.

Here's a quick example to get started: 


 MatchExpression exp = new MatchExpression('rank', NumberMatch.GREATER_THAN, 5).and('country', StringMatch.EQUALS, 'Italy')

Expressions are made of three elements:

  • Variable name
  • Match operator
  • Value
Additionally any number of expressions can be linked together with a logical AND / OR operator, just like in regular code. In the above example we have created an expression that will check for a rank value > 5 and a country value == "Italy".

The search options are not just limited to User/Room Variables name. In fact the Matching engine provides two extra classes, RoomProperties and UserProperties, where you can access other specific attributes of the Room and User class.

This is an example of matching specific Room properties and Variables: 


 // Prepare match expression
 MatchExpression exp = new MatchExpression(RoomProperties.IS_GAME, BoolMatch.EQUALS, true).and
 					(RoomProperties.HAS_FREE_PLAYER_SLOTS, BoolMatch.EQUALS, true).and
 					("isGameStarted", BoolMatch.EQUALS, false);
 
 // Search Rooms
 List<Rooms> joinableRooms = sfsApi.findRooms(zone.getRoomListFromGroup("chess"), exp, 0);

Advanced features

the Match expression offer advanced capabilities of searching through nested data structures such as SFSObject and SFSArray. This is done via a very simple dot-syntax. Here's an example of how it works: 

 MatchExpression exp = new MatchExpression("europe.italy.capital", StringMatch.EQUALS, "Rome")

The above example goes down deep into an SFSObject called europe, taking the italy object (another SFSObject) and finally reading its String field capital and matching it with another String. Here is one more examples using SFSObject and SFSArray: 

 MatchExpression exp = new MatchExpression("europe.italy.majorCities.3.name", StringMatch.EQUALS, "Milan")

From the italy object we obtain a majorCities SFSArray and we grab the third item in it (the .3 expression means 'give me the element at index == 3'). The item is again an SFSObject whose name property we finally compare to a String.

The power of Match Expression doesn't end here. You can run multiple passes of matching if you need complex searches to be performed. For example you can run a first match and obtain a list of filtered Rooms and then use it to apply another expression to further refine your search, and so on and so forth.
Also you will learn more interesting usages of Match Expressions in conjunction with the SFSGame class later in this very article.

See Also:

  • Constructor Details

    • MatchExpression

      public MatchExpression(String varName, com.smartfoxserver.entities.match.IMatcher condition, Object value)
      Example of matching a User to its variables: 
      
 	var matchExp = MatchExpression("avgScore", NumberMatch.GREATER_THAN, 20)
 					.or("rank", NumberMatch.GREATER_THAN, 5);
 		
 	var res = getApi().findUsers(getParentZone.getUserList(), matchExp, 10);
      This will search for all Users in the Zone that have a UserVariable called avgScore greater than 20, or a variable "rank" whose value is greater than 5.

      Example of matching a User to its properties: 

      
 	var matchExp = MatchExpression(UserProperties.NAME, StringMatch.CONTAINS, "Great")
 					.and(UserProperties.IS_PLAYER, BoolMatch.EQUALS, true);
 	
 	var res = getApi().findUsers(getParentRoom.getUserList(), matchExp, 10);
      This will search for all Users in the Extension's Room whose name contains Great and that is set as player in that Room.
      Parameters:
      varName - name of a Room/User variable or Room/User property
      condition - a condition to be matched
      value - a value to be compared

  • Method Details

    • and

      public MatchExpression and(String varName, com.smartfoxserver.entities.match.IMatcher condition, Object value)
      Concatenates two expressions with the logical AND operator.
      Parameters:
      varName - name of the variable or property
      condition - the match condition
      value - the value to match
      Returns:
      the new resulting MatchExpression
      See Also:
      • LogicOperator

    • or

      public MatchExpression or(String varName, com.smartfoxserver.entities.match.IMatcher condition, Object value)
      Concatenates two expressions with the logical OR operator.
      Parameters:
      varName - name of the variable or property
      condition - the match condition
      value - the value to match
      Returns:
      the new resulting MatchExpression
      See Also:
      • LogicOperator

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • hasNext

      public boolean hasNext()
      Internal

    • next

      public MatchExpression next()
      Internal

    • rewind

      public MatchExpression rewind()
      Internal

    • fromSFSArray

      public static MatchExpression fromSFSArray(ISFSArray sfsa)
      Internal

    • toSFSArray

      public ISFSArray toSFSArray()
      Internal