edu.csus.ecs.pc2.api
Class ServerConnection

java.lang.Object
  extended by edu.csus.ecs.pc2.api.ServerConnection

public class ServerConnection
extends Object

This class represents a connection to a PC2 server. Instantiating the class creates a local ServerConnection object which can then be used to connect to the PC2 server via the login(String, String) method. The PC2 server must already be running, and the local client must have a pc2v9.ini file specifying valid server connection information, prior to invoking login(String, String) method.

This documentation describes the current draft of the PC2 API, which is subject to change.

Version:
$Id: ServerConnection.java 2067 2010-03-26 04:33:37Z laned $
Author:
pc2@ecs.csus.edu

Nested Class Summary
protected  class ServerConnection.ConnectionEventListener
          A Connection Event used by ServerConnection.
 
Constructor Summary
ServerConnection()
          Construct a local ServerConnection object which can subsequently be used to connect to a currently-running PC2 server.
 
Method Summary
 edu.csus.ecs.pc2.api.implementation.Contest getContest()
          Returns a IContest, if not connected to a server throws a NotLoggedInException.
 IClient getMyClient()
          Returns a IClient if logged into a server.
 boolean isLoggedIn()
          Is this ServerConnection connected to a server ?
 IContest login(String login, String password)
          Login to the PC2 server represented by this ServerConnection using the specified login account name and password.
 boolean logoff()
          Logoff/disconnect from the PC2 server.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ServerConnection

public ServerConnection()
Construct a local ServerConnection object which can subsequently be used to connect to a currently-running PC2 server.

Method Detail

login

public IContest login(String login,
                      String password)
               throws LoginFailureException
Login to the PC2 server represented by this ServerConnection using the specified login account name and password. If the login is successful, the method returns an IContest object which can then be used to obtain information about the contest being controlled by the server. If the login fails the method throws LoginFailureException, in which case the message contained in the exception can be used to determine the nature of the login failure.

Note that invoking login(String, String) causes an attempt to establish a network connection to a PC2 server using the connection information specified in the pc2v9.ini file in the current directory. The PC2 server must already be running prior to invoking login(String, String), and the pc2v9.ini must specify legitmate server connection information; otherwise, LoginFailureException is thrown. See the PC2 Contest Administrator's Guide for information regarding specifying server connection information in pc2v9.ini files.

The following code snippet shows typical usage for connecting to and logging in to a PC2 server.

 String login = "team4";
 String password = "team4";
 try {
     ServerConnection serverConnection = new ServerConnection();
     IContest contest = serverConnection.login(login, password);
     // ... code here to invoke methods in "contest";
     serverConnection.logoff();
 } catch (LoginFailureException e) {
     System.out.println("Could not login because " + e.getMessage());
 } catch (NotLoggedInException e) {
     System.out.println("Unable to execute API method");
     e.printStackTrace();
 }
 

Parameters:
login - client login name (for example: "team5" or "judge3")
password - password for the login name
Throws:
LoginFailureException - if login fails, the message contained in the exception will provide and indication of the reason for the failure.

logoff

public boolean logoff()
               throws NotLoggedInException
Logoff/disconnect from the PC2 server.

Returns:
true if logged off, else false.
Throws:
NotLoggedInException - if attempt to logoff without being logged in

getContest

public edu.csus.ecs.pc2.api.implementation.Contest getContest()
                                                       throws NotLoggedInException
Returns a IContest, if not connected to a server throws a NotLoggedInException.

Returns:
contest
Throws:
NotLoggedInException - if attempt to invoke this method without being logged in

isLoggedIn

public boolean isLoggedIn()
Is this ServerConnection connected to a server ?

Returns:
true if connected to server, false if not connected to server.

getMyClient

public IClient getMyClient()
                    throws NotLoggedInException
Returns a IClient if logged into a server.

Returns:
Client class
Throws:
NotLoggedInException - if attempt to invoke this method without being logged in
See Also:
IContest.getMyClient()