Packagenet.user1.reactor.filters
Interfacepublic interface IFilter
Implementors Filter, FilterSet

Since : Reactor 1.0.0

The IFilter interface defines the methods that must be implemented by Reactor's filter classes; filter classes are used to specify a logical group of clients, typically for the sake of targeted messaging. For example, a filter class could be used to specify "all moderators in a meeting room," or "all spectators of a celebrity chat," or "all players with a certain minimum score in a game." Reactor filter classes can be used with any client-to-server command that supports filtering-- primarily the "send message to clients" commands, such as the Room's sendMessage() method.

The built-in Filter, AttritbuteFilter, and FilterSet classes all implement IFilter, and are used to create messaging filters. Let's consider a filtering example demonstrating the usage of the AttributeFilter class. Imagine a trivia game with two teams of clients in the same room: a "red team" and a "blue team". When a client on the red team wants to send a chat message to teammates only, it uses a Room's sendMessage() method with a filter limiting recipients to the red team. The filter relies on an attribute named "team" that is set whenever a player joins a team. The attribute indicates the client's team, and is scoped to the trivia game room, as follows:

   clientManager.self().setAttribute("team", "red", "triviaroom");
   

To send a message to the red team, the sending client first creates an AttributeFilter (the most common type of filter):

   var filter:AttributeFilter = new AttributeFilter();
   

Next, the client creates an AttributeComparison object, which specifies the attribute name and value that clients must have in order to receive the team-chat message:

   var comparison:AttributeComparison = new AttributeComparison("triviaroom.team",
                                                     "red",
                                                     CompareType.EQUAL);
   

The preceding code stipulates that a client's "triviaroom.team" attribute must have the value "red" in order for that client to receive the message. CompareType.EQUAL indicates the type of comparison made on the attribute value. Other compare types are "not equal," "less than," "less than or equal," "greater than," and "greater than or equal."

To add the preceding AttributeComparison to the filter, the sending client uses the filter's addComparison() method:

   filter.addComparison(comparison);
   

And finally, the client sends the chat message to the trivia room, with the filter included in the sendMessage() call:

   room.sendMessage("TEAMCHAT", true, filter, "Anyone know the answer?");
   

Now suppose the sending client wants to send another team message, but this time only to the experts on the team, with ranking 10 or above. The client simply adds the additional "ranking" comparison to the filter, and sends the message. For brevity, this time the client creates the AttributeComparison inline.

   filter.addComparison(new AttributeComparison("triviaroom.ranking", 
                               10, CompareType.GREATER_THAN_OR_EQUAL));
   room.sendMessage("TEAMCHAT", true, filter, "Anyone know the answer?");
   

Example 1 shows the code in its entirety.

Example 1. Send a message to team red, ranking 10 or greater

   
   var filter:AttributeFilter = new AttributeFilter();
   var comparison:AttributeComparison = new AttributeComparison("triviaroom.team",
                                                       "red",
                                                       CompareType.EQUAL);
   filter.addComparison(comparison);
   filter.addComparison(new AttributeComparison("triviaroom.ranking",
                        10, CompareType.GREATER_THAN_OR_EQUAL));
   room.sendMessage("TEAMCHAT", true, filter, "Anyone know the answer?");
   

Notice that the two comparisons in Example 1 have a Boolean "AND" relationship in the filter. That is, the message is sent to any client whose team is "red" AND whose ranking is 10 or greater. All attribute filter comparisons use AND comparisons, but nested OR and AND comparisons can be created with the AndGroup and OrGroup classes. For example, the following uses an OrGroup instance to send a help message to all clients in the room "presentation" that have the attribute "role" set to either "moderator" OR "admin". This time, the attribute is scoped to the room "presentation". Once again, we start by creating the attribute filter.

   var filter:AttributeFilter = new AttributeFilter();
   
Next, we create an OrGroup instance to contain the two attribute comparisons:
   var orGroup:OrGroup = new OrGroup();
   
Then we add the attribute comparisons to the OrGroup:
   orGroup.addComparison(new AttributeComparison("presentation.role",
                                                 "admin",
                                                 CompareType.EQUAL));
   orGroup.addComparison(new AttributeComparison("presentation.role",
                                                 "moderator",
                                                 CompareType.EQUAL));
   
Finally, we add the OrGroup to the filter and send the message:
   filter.addComparison(orGroup);
   room.sendMessage("HELP", false, filter, "How do I change my password?");
   

Example 2 shows the code in its entirety:

Example 2. Send a message to moderators or admins

   var filter:AttributeFilter = new AttributeFilter();
   var orGroup:OrGroup = new OrGroup();
   orGroup.addComparison(new AttributeComparison("presentation.role",
                                                 "admin",
                                                 CompareType.EQUAL));
   orGroup.addComparison(new AttributeComparison("presentation.role",
                                                 "moderator",
                                                 CompareType.EQUAL));
   filter.addComparison(orGroup);
   room.sendMessage("HELP", false, filter, "How do I change my password?");
   

OrGroup objects can be mixed with AndGroup objects to create complex Boolean relationships. Example 3 shows how to send a message to level 5+ moderators that have been active within the last minute OR administrators that have been active within the last minute.

Example 3. A complex Boolean filter

   var filter:AttributeFilter = new AttributeFilter();
   var orGroup:OrGroup  = new OrGroup();
   var andGroup:AndGroup = new AndGroup();
   andGroup.addComparison(new AttributeComparison("presentation.role",
                                            "moderator",
                                            CompareType.EQUAL));
   andGroup.addComparison(new AttributeComparison("presentation.level",
                                            5,
                                            CompareType.GREATER_THAN_OR_EQUAL));
   orGroup.addComparison(andGroup);
   orGroup.addComparison(new AttributeComparison("presentation.role",
                                                 "admin",
                                                 CompareType.EQUAL));
   filter.addComparison(orGroup);
   filter.addComparison(new AttributeComparison("presentation.lastactive",
                                                60000,
                                                CompareType.LESS_THAN));
   room.sendMessage("HELP", false, filter, "How do I change my password?");
   

Multiple filters can also be combined using FilterSet objects.

XML Format

Internally, filters are represented in a simple XML transport format known as Union Filtering Protocol, or UFP. The following code shows Example 1, Example 2, and Example 3 in UFP format. In the code, f means filter, t="A" means type="Attribute", a means attribute, n means name, and c means compare.

Example 1 in UFP

   <f t="A">
     <a c="eq"><n>triviaroom.team</n><v>red</v></a>
     <a c="ge"><n>triviaroom.ranking</n><v>10</v></a>
   </f>
   

Example 2 in UFP

   <f t="A">
     <or>
       <a c="eq"><n>presentation.role</n><v>admin</v></a>
       <a c="eq"><n>presentation.role</n><v>moderator</v></a>
     </or>
   </f>
   

Example 3 in UFP

   <f t="A">
     <or>
       <and>
         <a c="eq"><n>presentation.role</n><v>moderator</v></a>
         <a c="ge"><n>presentation.level</n><v>5</v></a>
       </and>
       <a c="eq"><n>presentation.role</n><v>admin</v></a>
     </or>
     <a c="lt"><n>presentation.lastactive</n><v>60000</v></a>
   </f>
   
To retrieve the XML representation of a given filter, use theFilter.toXMLString().

See also

AttributeFilter
AndGroup
OrGroup
FilterSet
net.user1.reactor.Room.sendMessage()
net.user1.reactor.RoomManager.sendMessage()
net.user1.reactor.ClientManager.sendMessage()
net.user1.reactor.Server.sendMessage()


Public Methods
 MethodDefined By
  
toXMLString():String
Returns a string containing the XML representation of this filter, suitable for transmission to Union Server.
IFilter
Method Descriptions
toXMLString()method
public function toXMLString():String

Returns a string containing the XML representation of this filter, suitable for transmission to Union Server.

Returns
String