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 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 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 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());
           }

      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()`