edu.csus.ecs.pc2.api

Class ServerConnection

java.lang.Object

edu.csus.ecs.pc2.api.ServerConnection

public class ServerConnection
extends Object

This class represents a connection to a PC² server. Instantiating the class creates a local ServerConnection object which can then be used to connect to the PC² server via the login(String, String) method. The PC² 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 PC² API, which is subject to change.

Version:

$Id: ServerConnection.java 1756 2009-01-23 07:29:01Z laned $

Author:

pc2@ecs.csus.edu

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ServerConnection.ConnectionEventListenerImplementation A Connection Event used by ServerConnection.

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
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 PC² server.

Method Detail

login

public IContest login(String login,
             String password)
               throws LoginFailureException

Login to the PC² 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 PC² server using the connection information specified in the pc2v9.ini file in the current directory. The PC² 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 PC² 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 PC² 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());
 }
 

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 PC² 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()