public class ServerConnection extends Object
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.Modifier and Type | Class and Description |
---|---|
protected class |
ServerConnection.ConnectionEventListener
This class defines a Connection Event used by ServerConnection.
|
Modifier and Type | Field and Description |
---|---|
protected edu.csus.ecs.pc2.api.implementation.Contest |
contest |
protected edu.csus.ecs.pc2.core.IInternalController |
controller |
protected edu.csus.ecs.pc2.core.model.IInternalContest |
internalContest |
Constructor and Description |
---|
ServerConnection()
Construct a local
ServerConnection object which can subsequently be used to connect to a currently-running PC2 server. |
Modifier and Type | Method and Description |
---|---|
void |
addAccount(String accountTypeName,
String displayName,
String password)
Add a single account (admin feature).
|
void |
addLanguage(String autoFillTitleName)
Add a language.
|
void |
addLanguage(String title,
String compilerCommandLine,
String executionCommandLine,
boolean interpreted,
String executableMask)
Add a language to the contest.
|
void |
addProblem(String title,
String shortName,
File judgesDataFile,
File judgesAnswerFile,
edu.csus.ecs.pc2.core.model.Problem.VALIDATOR_TYPE validator,
Properties problemProperties)
Add a Problem definition.
|
String[] |
getAutoFillLanguageList()
Get a list of the currently-defined "Auto-fill" languages.
|
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.
|
String[] |
getProblemPropertyNames()
Get a list of optional Problem settings names.
|
protected String |
getProperty(Properties problemProperties,
String key,
String defaultValue)
Return the value for a specified property.
|
boolean |
isLoggedIn()
Is this ServerConnection connected to a server ?
|
boolean |
isValidAccountTypeName(String name) |
boolean |
isValidAutoFillLangauageName(String name)
Returns an indication of whether the specified name matches one of the currently-defined languages
for which "auto-fill" in the PC2 Admin GUI is supported.
|
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.
|
static void |
main(String[] args)
Main method for testing this class.
|
protected void |
setClicsValidatorDefaults(edu.csus.ecs.pc2.core.model.Problem problem)
Marks the specified Problem as being validated using the CLICS Validator with a default set of Settings values.
|
void |
setContestLength(long contestLengthSeconds)
Change contest length.
|
void |
setContestTimes(long contestLengthSeconds,
long contestElapsedSeconds,
long contestRemainingSeconds)
Update/set contest clock.
|
protected void |
setCustomValidatorDefaults(edu.csus.ecs.pc2.core.model.Problem problem)
Marks the specified Problem as being validated using a Custom Validator with a default set of Settings values.
|
protected void |
setPC2ValidatorDefaults(edu.csus.ecs.pc2.core.model.Problem problem)
Marks the specified Problem as being validated using the PC2 Validator with a default set of Settings values.
|
void |
shutdownAllServers()
Shutdown all servers (that is, the PC2 Servers at all connected contest sites).
|
void |
shutdownServer()
Shutdown the PC2 server.
|
void |
startContestClock()
Start the contest clock.
|
void |
stopContestClock()
Stop the contest clock.
|
void |
submitClarification(IProblem problem,
String question)
Submit a clarification request to the PC2 Server.
|
void |
submitJudgeRun(IProblem problem,
ILanguage language,
edu.csus.ecs.pc2.core.model.IFile mainFile)
Submit a Judge run (a run which the Judges are expected to evaluate and count for scoring)
using
IFile s. |
void |
submitJudgeRun(IProblem problem,
ILanguage language,
edu.csus.ecs.pc2.core.model.IFile mainFile,
edu.csus.ecs.pc2.core.model.IFile[] additionalFiles)
Submit a Judge run (a run which the Judges are expected to evaluate and count for scoring)
using
IFile s. |
void |
submitJudgeRun(IProblem problem,
ILanguage language,
edu.csus.ecs.pc2.core.model.IFile mainFile,
edu.csus.ecs.pc2.core.model.IFile[] additionalFiles,
long overrideSubmissionTimeMS,
long overrideRunId)
Submit a Judge run (a run which the Judges are expected to evaluate and count for scoring)
using
IFile s. |
void |
submitJudgeRun(IProblem problem,
ILanguage language,
String mainFileName)
Submit a Judge Run (a run which the Judges are expected to evaluate and count for scoring)
using String filenames.
|
void |
submitJudgeRun(IProblem problem,
ILanguage language,
String mainFileName,
String[] additionalFileNames)
Submit a Judge run (a run which the Judges are expected to evaluate and count for scoring)
using String filenames.
|
void |
submitJudgeRun(IProblem problem,
ILanguage language,
String mainFileName,
String[] additionalFileNames,
long overrideSubmissionTimeMS,
long overrideRunId)
Submit a Judge run (a run which the Judges are expected to evaluate and count for scoring)
using String filenames.
|
void |
submitRunJudgement(IRun run,
IJudgement judgement)
Submit run judgement for a run.
|
void |
submitTestRun(IProblem problem,
ILanguage language,
edu.csus.ecs.pc2.core.model.IFile mainFile,
edu.csus.ecs.pc2.core.model.IFile testDataFile)
Submit a Test run (a run which will be executed but will not affect a team's score)
using
IFile s. |
void |
submitTestRun(IProblem problem,
ILanguage language,
edu.csus.ecs.pc2.core.model.IFile mainFile,
edu.csus.ecs.pc2.core.model.IFile testDataFile,
edu.csus.ecs.pc2.core.model.IFile[] additionalSourceFiles,
edu.csus.ecs.pc2.core.model.IFile[] additionalTestDataFiles)
Submit a Test run (a run which will be executed but will not affect a team's score)
using
IFile s. |
void |
submitTestRun(IProblem problem,
ILanguage language,
String mainFileName,
String testDataFileName)
Submit a Test run (a run which will be executed but will not affect a team's score)
using String filenames.
|
void |
submitTestRun(IProblem problem,
ILanguage language,
String mainFileName,
String testDataFileName,
String[] otherSourceFileNames,
String[] otherDataFileNames)
Submit a Test run (a run which will be executed but will not affect a team's score)
using String filenames.
|
protected String[] |
validateProperties(Properties properties)
Check property names against valid list of names.
|
protected edu.csus.ecs.pc2.core.IInternalController controller
protected edu.csus.ecs.pc2.core.model.IInternalContest internalContest
protected edu.csus.ecs.pc2.api.implementation.Contest contest
public ServerConnection()
ServerConnection
object which can subsequently be used to connect to a currently-running PC2 server.public IContest login(String login, String password) throws LoginFailureException
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 legitimate 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(); }
login
- client login name (for example: "team5" or "judge3")password
- password for the login nameLoginFailureException
- if login fails, the message contained in the exception will provide and indication of the reason for the failure.public boolean isValidAccountTypeName(String name)
public void addAccount(String accountTypeName, String displayName, String password) throws Exception
For the input accountTypeName, ex. TEAM, will add the next client number account. If adding a new TEAM account and there are 22 teams, this method will add team23 login account.
The current logged in user must be an Administrator user otherwise a SecurityException will be thrown.
The following code snippet shows a example for a addAccount invocation.
String login = "administrator2"; String password = "administrator2"; try { ServerConnection serverConnection = new ServerConnection(); IContest contest = serverConnection.login(login, password); connection.addAccount("TEAM", "Team Name", "teampassword"); Thread.sleep(1000); // sleep just long enough before logging off 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(); }
accountTypeName
- name of account, ex TEAMdisplayName
- title for account/team, if null will be login namepassword
- password for account, must not be null or emptystring (string length==0)IllegalArgumentException
- if the account type is invalid or the password is null or emptySecurityException
- if the user is not allowed to perform this action.IllegalArgumentException
- if the accountTypeName does not specify a valid account typeException
- if an error occurs when calling the server to add the accountpublic void submitClarification(IProblem problem, String question) throws Exception
problem
- the Problem for which the clarification request is being submittedquestion
- text of questionNotLoggedInException
- if the client is not currently logged in to the serverSecurityException
- if the user allowed to perform this action.Exception
- if the specified Problem is null or the clarification request could not be submitted to the serverpublic void submitRunJudgement(IRun run, IJudgement judgement) throws Exception
run
- The run to add a judgement to.judgement
- the judgement to add to run.SecurityException
- if the user is not allowed to perform this action.NotLoggedInException
- if the user is not logged in.Exception
- if unable to submit run.public void submitJudgeRun(IProblem problem, ILanguage language, String mainFileName) throws Exception
problem
- the Problem for which the run is being submittedlanguage
- the Language used for the Problem submission (Java, C++, etc.)mainFileName
- the name of the main source code file
Calling this method is equivalent to calling submitJudgeRun(IProblem, ILanguage, String, String[])
with String[0] as the last parameter (that is, not specifying any additional file names).NotLoggedInException
- if the client is not currently logged in to the serverSecurityException
- if the user is not allowed to perform this action.Exception
- if any of the specified files cannot be found, if the Problem or Language is null,
the contest is not running, or a failure occurred while submitting the run to the serversubmitJudgeRun(IProblem, ILanguage, String, String[])
public void submitJudgeRun(IProblem problem, ILanguage language, String mainFileName, String[] additionalFileNames) throws Exception
problem
- the Problem for which the run is being submittedlanguage
- the Language used for the Problem submission (Java, C++, etc.)mainFileName
- the name of the main source code fileadditionalFileNames
- an array of Strings giving the names of any additional files submitted
Calling this method is equivalent to calling submitJudgeRun(IProblem, ILanguage, String, String[], long, long)
with zero as the last two parameters (that is, not specifying override time/runid values).NotLoggedInException
- if the client is not currently logged in to the server.SecurityException
- if the user is not allowed to perform this action.Exception
- if any of the specified files cannot be found,
if the Problem or Language is null or cannot be found,
if the contest is not running,
or if a failure occurred while submitting the run to the server.submitJudgeRun(IProblem, ILanguage, String, String[], long, long)
public void submitJudgeRun(IProblem problem, ILanguage language, String mainFileName, String[] additionalFileNames, long overrideSubmissionTimeMS, long overrideRunId) throws Exception
problem
- the Problem for which the run is being submittedlanguage
- the Language used for the Problem submission (Java, C++, etc.)mainFileName
- the name of the main source code fileadditionalFileNames
- an array of Strings giving the names of any additional files submittedoverrideSubmissionTimeMS
- the submission time which should be assigned to the run; if greater than zero,
overrides the default (which is the current time).
Only has effect if contest information CCS test mode is set true.overrideRunId
- the Run ID which should be assigned to the run; if greater than zero, overrides the
default (which is that the server assigns the next available RunID to the run).
Only has effect if contest information CCS test mode is set true.NotLoggedInException
- if the client is not currently logged in to the serverSecurityException
- if the user is not allowed to perform this action.Exception
- if any of the specified files cannot be found,
if the Problem or Language is null or cannot be found,
if the contest is not running,
or if a failure occurred while submitting the run to the serverpublic void submitJudgeRun(IProblem problem, ILanguage language, edu.csus.ecs.pc2.core.model.IFile mainFile) throws Exception
IFile
s.
Calling this method is exactly the same as calling submitJudgeRun(IProblem, ILanguage, IFile, IFile[])
with the same first three parameters and null as the last parameter.problem
- the problem for which the Judge Run is being submittedlanguage
- the Language used for the Judge RunmainFile
- an IFile
object containing the main program for the Judge RunException
- if any of the specified files are invalid (have empty names or contain no data),
if the Problem or Language is null or cannot be found,
if the contest is not running,
or if a failure occurred while submitting the run to the serversubmitJudgeRun(IProblem, ILanguage, IFile, IFile[])
public void submitJudgeRun(IProblem problem, ILanguage language, edu.csus.ecs.pc2.core.model.IFile mainFile, edu.csus.ecs.pc2.core.model.IFile[] additionalFiles) throws Exception
IFile
s.
Calling this method is equivalent to calling submitJudgeRun(IProblem, ILanguage, IFile, IFile[], long, long)
with zero as the last two parameters (that is, not specifying override time/runid values).problem
- the problem for which the Judge Run is being submittedlanguage
- the Language used for the Judge RunmainFile
- an IFile
object containing the main program for the Judge RunadditionalFiles
- an array of IFile
objects with each element containing an
additional file being submitted as part of the Judge runNotLoggedInException
- if the client is not currently logged in to the serverSecurityException
- if the user is not allowed to perform this action.Exception
- if any of the specified files are invalid (have empty names or contain no data),
if the Problem or Language is null or cannot be found,
if the contest is not running,
or if a failure occurred while submitting the run to the serversubmitJudgeRun(IProblem, ILanguage, IFile, IFile[], long, long)
public void submitJudgeRun(IProblem problem, ILanguage language, edu.csus.ecs.pc2.core.model.IFile mainFile, edu.csus.ecs.pc2.core.model.IFile[] additionalFiles, long overrideSubmissionTimeMS, long overrideRunId) throws Exception
IFile
s.problem
- the problem for which the Judge Run is being submittedlanguage
- the Language used for the Judge RunmainFile
- an IFile
object containing the main program for the Judge RunadditionalFiles
- an array of IFile
objects with each element containing an
additional file being submitted as part of the Judge runoverrideSubmissionTimeMS
- a value of type long which, if non-zero, will be used as the submission time of
the Judge Run, overriding the actual submission time; only has effect if Contest Information
CCS Test Mode is trueoverrideRunId
- a value of type long which, if non-zero, will be used as the RunId of the Judge Run,
overriding the default (internally-assigned) RunId; only has effect if Contest Information
CCS Test Mode is trueNotLoggedInException
- if the client is not currently logged in to the serverSecurityException
- if the user is not allowed to perform this action.Exception
- if any of the specified files are invalid (have empty names or contain no data),
if the Problem or Language is null or cannot be found,
if the contest is not running,
or if a failure occurred while submitting the run to the serverpublic void submitTestRun(IProblem problem, ILanguage language, edu.csus.ecs.pc2.core.model.IFile mainFile, edu.csus.ecs.pc2.core.model.IFile testDataFile) throws Exception
IFile
s.
The results of a submitted Test Run are returned in a TestRunResults
object via a callback
to a registered ITestRunListener
. It is the caller's responsibility to register an appropriate
ITestRunListener
prior to invoking this method.
Invoking this method is equivalent to invoking
submitTestRun(IProblem, ILanguage, IFile, IFile, IFile[], IFile[])
with null as the last two parameters.problem
- the problem for which the Test Run is being submittedlanguage
- the Language used for the Test RunmainFile
- an IFile
object containing the main program for the Test RuntestDataFile
- an IFile
object containing the input data to be supplied to the Test RunException
- if an error occurs in submitting the Test RunsubmitTestRun(IProblem, ILanguage, IFile, IFile, IFile[], IFile[])
public void submitTestRun(IProblem problem, ILanguage language, edu.csus.ecs.pc2.core.model.IFile mainFile, edu.csus.ecs.pc2.core.model.IFile testDataFile, edu.csus.ecs.pc2.core.model.IFile[] additionalSourceFiles, edu.csus.ecs.pc2.core.model.IFile[] additionalTestDataFiles) throws Exception, UnsupportedOperationException
IFile
s.
NOTE: currently the PC2 Server does not support Test Runs; this method is guaranteed to throw either
Exception
(if the received parameters are invalid) or UnsupportedOperationException
.
The results of a submitted Test Run are returned in a TestRunResults
object via a callback
to a registered ITestRunListener
. It is the caller's responsibility to register an appropriate
ITestRunListener
prior to invoking this method.problem
- the problem for which the Test Run is being submittedlanguage
- the Language used for the Test RunmainFile
- an IFile
object containing the main program for the Test RuntestDataFile
- an IFile
object containing the file to be used as input data during execution of the Test RunadditionalSourceFiles
- an array containing IFile
objects, each representing an additional
source code file submitted as part of the Test RunadditionalTestDataFiles
- an array containing IFile
objects, each representing an additional
test data file submitted as part of the Test RunException
- if any of the specified IFiles are invalid (have no name or are zero length),
if the specified Problem or Language is null,
if the contest clock is not running,
or if an error occurred while submitting the Test Run to the serverUnsupportedOperationException
- if Exception
is not thrownpublic void submitTestRun(IProblem problem, ILanguage language, String mainFileName, String testDataFileName) throws Exception
TestRunResults
object via a callback
to a registered ITestRunListener
. It is the caller's responsibility to register an appropriate
ITestRunListener
prior to invoking this method.
Calling this method is equivalent to calling
submitTestRun(IProblem, ILanguage, String, String, String[], String[])
with null as the last two parameters.problem
- the problem for which the Test Run is being submittedlanguage
- the Language used for the Test RunmainFileName
- the name of the file containing the main program for the Test RuntestDataFileName
- the data file to be used as input during execution of the Test RunException
- if an error occurs in submitting the Test RunsubmitTestRun(IProblem, ILanguage, String, String, String[], String[])
public void submitTestRun(IProblem problem, ILanguage language, String mainFileName, String testDataFileName, String[] otherSourceFileNames, String[] otherDataFileNames) throws Exception, UnsupportedOperationException
Exception
(if the received parameters are invalid) or UnsupportedOperationException
.
The results of a submitted Test Run are returned in a TestRunResults
object via a callback
to a registered ITestRunListener
. It is the caller's responsibility to register an appropriate
ITestRunListener
prior to invoking this method.problem
- the problem for which the Test Run is being submittedlanguage
- the Language used for the Test RunmainFileName
- the name of the file containing the main program for the Test RuntestDataFileName
- the data file to be used as input during execution of the Test RunotherSourceFileNames
- an array containing the names of additional source code files to be submitted (currently unused)otherDataFileNames
- an array containing the names of other data files to be submitted (currently unused)NotLoggedInException
- is the client is not logged in to the serverSecurityException
- if the client is not allowed to perform this actionException
- if any of the specified files cannot be found, if the specified Problem or Language is null,
if the contest clock is not running, or if an error occurred while submitting the Test Run to
the serverUnsupportedOperationException
- if Exception
is not thrownpublic boolean logoff() throws NotLoggedInException
NotLoggedInException
- if attempt to logoff without being logged inpublic edu.csus.ecs.pc2.api.implementation.Contest getContest() throws NotLoggedInException
NotLoggedInException
- if attempt to invoke this method without being logged inpublic boolean isLoggedIn()
public IClient getMyClient() throws NotLoggedInException
NotLoggedInException
- if attempt to invoke this method without being logged inIContest.getMyClient()
public void startContestClock() throws Exception
SecurityException
- if the user is not allowed to perform this action.NotLoggedInException
- if the user is not logged in.Exception
- if unable to start contest.public void stopContestClock() throws Exception
SecurityException
- if the user is not allowed to perform this action.NotLoggedInException
- if the user is not logged in.Exception
- if unable to stop contestprotected void setPC2ValidatorDefaults(edu.csus.ecs.pc2.core.model.Problem problem)
problem
- the problem to be marked as being validated by the PC2 Validatorprotected void setClicsValidatorDefaults(edu.csus.ecs.pc2.core.model.Problem problem)
problem
- the problem to be marked as being validated by the CLICS Validatorprotected void setCustomValidatorDefaults(edu.csus.ecs.pc2.core.model.Problem problem)
problem
- the problem to be marked as being validated by a Custom Validatorpublic void addProblem(String title, String shortName, File judgesDataFile, File judgesAnswerFile, edu.csus.ecs.pc2.core.model.Problem.VALIDATOR_TYPE validator, Properties problemProperties)
title
- - title for problemshortName
- short name/id for problem.judgesDataFile
- - judges input data filejudgesAnswerFile
- - judges answer filevalidator
- - which validator to use (choices are: PC2VALIDATOR, CLICSVALIDATOR, CUSTOMVALIDATOR, NONE)problemProperties
- - optional properties, for a list of keys see getProblemPropertyNames()
, null is allowed.APIConstants
protected String getProperty(Properties problemProperties, String key, String defaultValue)
problemProperties
- the problem Propterieskey
- the key to look fordefaultValue
- the default value to return if the key is not found.protected String[] validateProperties(Properties properties)
properties
- properties to validatepublic String[] getProblemPropertyNames()
APIConstants
.APIConstants
public boolean isValidAutoFillLangauageName(String name)
name
- a String giving a language namepublic String[] getAutoFillLanguageList()
public void addLanguage(String autoFillTitleName)
getAutoFillLanguageList()
.autoFillTitleName
- a automatic language fill title namepublic void addLanguage(String title, String compilerCommandLine, String executionCommandLine, boolean interpreted, String executableMask)
String login = "administrator2"; String password = "administrator2"; try { ServerConnection serverConnection = new ServerConnection(); IContest contest = serverConnection.login(login, password); String title = "Ruby"; String compilerCommandLine = "ruby -c {:mainfile}"; String executionCommandLine = "ruby {:mainfile}"; String executableMask = "{:noexe}"; boolean interpreted = true; serverConnection.addLanguage(title, compilerCommandLine, executionCommandLine, interpreted, executableMask); // may need to pause for a second or two for the language to be added. ILanguage[] languages = contest.getLanguages(); System.out.println("Added language " + languages[languages.length - 1].getName()); 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(); }
title
- Display Name for the language, ex. JavacompilerCommandLine
- command to compile source codeexecutionCommandLine
- command to execute programinterpreted
- is this an interpreted language like Perl or PythonexecutableMask
- an expected output program namepublic void shutdownServer()
shutdownAllServers()
public void shutdownAllServers()
shutdownServer()
public void setContestTimes(long contestLengthSeconds, long contestElapsedSeconds, long contestRemainingSeconds) throws edu.csus.ecs.pc2.core.exception.IllegalContestState
Contest clock must be stopped to change contest length.
contestLengthSeconds
- number of seconds contest is longcontestElapsedSeconds
- number of seconds elapsed since start of contestcontestRemainingSeconds
- number of seconds until end of contestedu.csus.ecs.pc2.core.exception.IllegalContestState
- thrown if contest clock is started.IContest.isContestClockRunning()
public void setContestLength(long contestLengthSeconds) throws edu.csus.ecs.pc2.core.exception.IllegalContestState
Contest clock must be stopped to change contest length.
contestLengthSeconds
- number of seconds contest is longedu.csus.ecs.pc2.core.exception.IllegalContestState
- thrown if contest clock is started.IContest.isContestClockRunning()
public static void main(String[] args)
args
- an array of Strings containing arguments as follows: