org.omus.ext
Interface GroupExtension

public interface GroupExtension

The main interface of the org.omus.ext package, used to build custom groups (or "rooms").

It contains a set of methods that get invoked when a special event occured. All groups in the Oregano Server are single-threaded, so you do not need to care about synchronization issues. There is no need to create your own threads or Timer instances. If there is a time consuming task you can delegate it to a pool of worker threads with one of the methods of the TaskManager.

There are two places in config.xml where a GroupExtension can be specified. The defaultExtension attribute of the enclosing <groupConfig>-node and the extension attribute of each particular <group>-node. The former is useful if you want to add features to every group that will be created on the server, the latter is used if you write a "local" extension, only intended for groups created with a particular configID. If you combine both approaches, make sure that your local extension is a subclass of your defaultExtension, otherwise the functionality of your defaultExtension would be wiped out by the methods in your local one.

Let's assume you develop a default extension with the following class body:

     class MyGlobalExtension implements org.omus.ext.GroupExtension { ... }
 

In this case the groupConfig node in config.xml should look as follows:

     <groupConfig defaultExtension="MyGlobalExtension" ...
 

If you want to add special behaviour to a particular set of groups, you can define a subclass:

     class MySpecialExtension extends MyGlobalExtension { ... }
 

Each method in this subclass should call the method in the superclass that it overrides if you want to combine the functionality of your local and global extensions. The node for the groups that are supposed to load this extension might look as follows:

     <group
         configID="spec"
         userLimit="50"
         extension="MySpecialExtension"
         />
         <startup server="serv1" name="spec_A" />
         <startup server="serv1" name="spec_B" />
     </group>
 

When the server boots, two groups named "spec_A" and "spec_B" will be created and both will load the extension class MySpecialExtension which in turn is a subclass of MyGlobalExtension. Furthermore each group that will be created dynamically due to a client calling org.omus.group.change("anyName","spec",false) will load the same extension too.

Method Summary

void	finishGroupCreation(Group group) Invoked after the group has been created.
void	groupRemoved() Invoked after the group has been removed.
void	messageFromClient(Message msg, User sender) Invoked after a message from the specified sender has been received.
boolean	messageToGroup(Message msg) Invoked before a message is sent to all the clients who are currently member of this group.
boolean	messageToUser(Message msg, User recipient) Invoked before a message is sent to the specified user.
boolean	prepareGroupCreation(GroupCreationData gcd) Invoked before the group will be created.
boolean	syncGroupProperties(PropertyUpdate newValues, User sender) Invoked before the properties of this group will be synchronized.
boolean	syncUserProperties(PropertyUpdate newValues, User sender, User owner) Invoked before the properties of the specified owner will be synchronized.
void	userJoined(User user, DataRow extraData) Invoked after a user has joined the group.
void	userLeft(User user) Invoked after a user has left the group.

Method Detail

prepareGroupCreation

public boolean prepareGroupCreation(GroupCreationData gcd)

Invoked before the group will be created. The GroupCreationData object contains methods to read the name and the configID of the group that is supposed to be created. If this method returns false, the creation of this group will be aborted. This way you can implement some kind of error checking on the server or load some additional data before the group is created. You can use the setErrorCode method of the GroupCreationData object to send customized error codes to the clients in case you want to prevent the creation of that group. Otherwise a default error code will be sent.

finishGroupCreation

public void finishGroupCreation(Group group)

Invoked after the group has been created. Each class that implements this interface should keep a reference to the group object in a field.

groupRemoved

public void groupRemoved()

Invoked after the group has been removed. You can still modify the properties of this group which will be written to the database after this method finished executing.

userJoined

public void userJoined(User user,
                       DataRow extraData)

Invoked after a user has joined the group. You can use the DataRow object, which is empty initially, to send additional data to the client which will be received in the paramater of the onChange event handler of the group object in the client. (if you develop an extension to the login group, the additional data will be receceived in the onLogin or onRegister events.

userLeft

public void userLeft(User user)

Invoked after a user has left the group. You can still change the properties of the user. This method gets invoked before the userJoined method of the new group will be invoked.

messageToUser

public boolean messageToUser(Message msg,
                             User recipient)

Invoked before a message is sent to the specified user. This event may originate from a client calling sendToUser or sendToAll in org.omus.messenger or from any server extension calling sendToGroup or sendToAll in the MessagingManager. Return true if you want the message to proceed on its way to the client.

messageToGroup

public boolean messageToGroup(Message msg)

Invoked before a message is sent to all the clients who are currently member of this group. This event may originate from a client calling sendToGroup in org.omus.messenger or from any server extension calling sendToGroup in the MessagingManager. Return true if you want the message to proceed on its way to the clients.

messageFromClient

public void messageFromClient(Message msg,
                              User sender)

Invoked after a message from the specified sender has been received. This event originates from a client calling sendToServer in org.omus.messenger.

syncUserProperties

public boolean syncUserProperties(PropertyUpdate newValues,
                                  User sender,
                                  User owner)

Invoked before the properties of the specified owner will be synchronized. The sender represents the client that modified the properties. PropertyUpdate is a subclass of PropertySet. This object does not contain all the properties that are associated with the owner, but only the modified ones. You can implement some kind of error checking and only return true if you want the new values to be accepted and synchronized. If you return false to reset all affected properties to their old value, you can use the setErrorCode method of the PropertyUpdate object to send customized error codes to the clients. Otherwise a default error code will be sent.

syncGroupProperties

public boolean syncGroupProperties(PropertyUpdate newValues,
                                   User sender)

Invoked before the properties of this group will be synchronized. The sender represents the client that modified the properties. PropertyUpdate is a subclass of PropertySet. This object does not contain all the properties that are associated with this group, but only the modified ones. You can implement some kind of error checking and only return true if you want the new values to be accepted and synchronized. If you return false to reset all affected properties to their old value, you can use the setErrorCode method of the PropertyUpdate object to send customized error codes to the clients. Otherwise a default error code will be sent.