View Javadoc

1   /*
2    * AI Soccer Project - network gaming environment for AI warriors.
3    * Copyright (C) 2001-2004  Marcin Werla, Pawel Widera
4    *
5    * This program is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU General Public License
7    * as published by the Free Software Foundation; either version 2
8    * of the License, or (at your option) any later version.
9    *
10   * This program is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   * GNU General Public License for more details.
14   *
15   * You should have received a copy of the GNU General Public License
16   * along with this program; if not, you can find it here:
17   * http://www.gnu.org/licenses/gpl.html
18   */
19  
20  package snifos.application;
21  
22  import org.dom4j.Document;
23  
24  import snifos.common.UserId;
25  
26  import snifos.exception.ConfigurationException;
27  import snifos.exception.InvalidUserException;
28  
29  import snifos.server.Server;
30  
31  import java.util.Properties;
32  
33  
34  /***
35   * This interface describes main application class for applications
36   * designed for SNIFOS application server.
37   * @version $Id: Application.java,v 1.2 2004/05/08 21:55:29 mwerla Exp $
38   */
39  public interface Application extends Runnable {
40      /***
41       * Configures instance of Application with given parameters.
42       * @param configuration Configuration which will be used.
43       * @param isUnique True if application is uniqe.
44       * @throws ConfigurationException Thrown when configuration is malformed
45       * or cannot be used for some reason.
46       */
47      public void configure(Properties configuration, boolean isUnique)
48          throws ConfigurationException;
49  
50      /***
51       * Sets instance of server which will be
52       * used to communicate with to users.
53       * @param server Server instance.
54       */
55      public void setServer(Server server);
56  
57      /***
58       * Unregisters user with given id (for example after user
59       * disconnects).
60       * @param userId Id of user.
61       * @throws InvalidUserException Thrown when problem
62       * with deregistering occurs.
63       */
64      public void unregisterUser(UserId userId) throws InvalidUserException;
65  
66      /***
67       * Registers user with given id.
68       * @param userId Id of user to register.
69       * @param message First message sent by user (can contain some
70       * user specific informations)
71       * @throws InvalidUserException Thrown when user cannot be registered
72       * by given application instance
73       */
74      public void registerUser(UserId userId, Document message)
75          throws InvalidUserException;
76  
77      /***
78       * Called by server to pass message from user
79       * to this instance of application. If message is invalid for some reason,
80       * application should send message to the user with proper information
81       * - throwing an exception is not advised.
82       * @param userId Id of user which sends message.
83       * @param message Received message.
84       * @throws InvalidUserException Thrown when user id is invalid.
85       */
86      public void receiveMessage(UserId userId, Document message)
87          throws InvalidUserException;
88  }