Tutorial: Custom UPCRoom Handler

Source File: see UPCBanRoom.java in examples/rooms/.
This tutorial demonstrates:

Using handleMessage to create a new UPCMessage handler in UPCRoom
Creating a secure UPCRoom
Banning a Client from the Server.

Building the Room

Our Room will extend UPCRoom. "implements RoomListener" is not necessary as UPCRoom implements RoomListener already.

public class UPCBanRoom extends UPCRoom {

We won't be overriding any of the events in RoomListener we want UPCRoom to handle them. The method we do want to override is handleMessage. Start by creating the empty method.


public void handleMessage(UPCMessage upcMessage, Message message) {
}

For this tutorial we only want to handle one extra message. The method name of the UPCMessage will be "banClient" and the first and only argument it uses will be the ClientID of the Client we want to ban. Inside the method add:


        if (upcMessage.getMethod().equals("banClient")) {
            try {
                ClientServices clientServices = Services.getClientServices(upcMessage.getArgText(0));
                Bouncer.ban(clientServices.getIP());
            } catch (ClientNotFoundException e) {
                // --- handle error
            }
        }

The first line after the try grabs the ClientServices for the Client specified by the ClientID given in the UPCMessage. We will use the ClientServices for the Client to get it's IP address.
The Bouncer class contains static methods related to banning Clients. See javadoc for more details.

That's it! To improve this you would want to do more meaninful error checking.

I mentioned this Room was Secure. UPCRoom can already handle that so we don't have to worry about it in our UPCBanRoom class. Instead we deploy it with a password.

Deploying the Room

Ensure the example_rooms.jar file that came with the Server is in the ./rooms directory.

Edit uconfig.xml as below.

<UNITY>
    <SERVER>
        <SERVER_PORT>9100</SERVER_PORT>
        <ADMIN_PORT>9101</ADMIN_PORT>
        <ADMIN_PASSWORD>password</ADMIN_PASSWORD>
    </SERVER>
    <TYPES>
        <ROOM>
            <ID>UPCBanRoom</ID>
         <CLASS>org.moock.unity.examples.rooms.UPCBanRoom</CLASS>
       </ROOM>
    </TYPES>  
    <INSTANCES> 
        <ROOM>
            <ID>adminBanRoom</ID>
            <TYPE_ID>UPCBanRoom</TYPE_ID>
            <ATTRIBUTES>
                <PASSWORD>thePassword</PASSWORD>
            </ATTRIBUTES>
        </ROOM>
        <ROOM>
            <ID>lobby</ID>
            <AUTOJOIN>true</AUTOJOIN>
        </ROOM>
    </INSTANCES>  
</UNITY>

Note the PASSWORD attribute. When you set a PASSWORD attribute for a UPCRoom (or in this case a subclass of UPCRoom) then it becomes a secure Room and clients join it by passing the password as the first argument and only argument. See client documentation for using the uClient to pass an argument when joining a Room.

Again with UPCRoom the work is already done for you. UPCRoom's already know how to validate clients to join other UPCRoom's which have been made secure with a password. Notice the lobby Room we've asked to be created in the config above. No type ID is given so by default it is created as a UPCRoom. Also it's set to be autojoined so every client who connects to the server will join this Room. Now all a client has to do to join the adminBanRoom and start banning clients is send the following message:

<UPC>
<ROOMID>lobby</ROOMID>
<METHOD>joinRoom</METHOD>
<ARGS>
<ARG>adminBanRoom</ARG><ARG>udefault</ARG><ARG>thePassword</ARG>
</ARGS>
</UPC>

Of course you'll need to know the password that was set first.

Note: As an alternative to having clients AUTOJOIN our lobby Room we could instead have had the lobby Room ACCEPT_OUTSIDE_MESSAGES tag set to true:

<ACCEPT_OUTSIDE_MESSAGES>true</ACCEPT_OUTSIDE_MESSAGES>

Then Clients could send messages to the lobby Room without actually having to have joined it.