Package uk.ac.manchester.spinnaker.spalloc

Interface SpallocAPI

All Known Implementing Classes:

SpallocClient

public interface SpallocAPI

The interface exposed by the low-level Spalloc Client.

Author:

Donal Fellows

Method Summary

Modifier and Type	Method	Description
default int	createJob(@Valid CreateJob builder)	Create a job.
int	createJob(@Valid CreateJob builder, @Positive Integer timeout)	Create a job.
default int	createJob(List<@PositiveOrZero Integer> args, Map<@NotBlank String,@NotNull Object> kwargs)	Deprecated, for removal: This API element is subject to removal in a future version. Consider using createJob(CreateJob) instead.
int	createJob(List<@PositiveOrZero Integer> args, Map<@NotBlank String,@NotNull Object> kwargs, @Positive Integer timeout)	Deprecated, for removal: This API element is subject to removal in a future version. Consider using createJob(CreateJob, Integer) instead.
default void	destroyJob(int jobID, @NotBlank String reason)	Destroy a job.
void	destroyJob(int jobID, @NotBlank String reason, @Positive Integer timeout)	Destroy a job.
default BoardCoordinates	getBoardPosition(@NotBlank String machineName, @Valid PhysicalCoords coords)	Get the logical location of a board.
BoardCoordinates	getBoardPosition(@NotBlank String machineName, @Valid PhysicalCoords coords, @Positive Integer timeout)	Get the logical location of a board.
default BoardPhysicalCoordinates	getBoardPosition(@NotBlank String machineName, @Valid TriadCoords coords)	Get the physical location of a board.
BoardPhysicalCoordinates	getBoardPosition(@NotBlank String machineName, @Valid TriadCoords coords, @Positive Integer timeout)	Get the physical location of a board.
default BoardPhysicalCoordinates	getBoardPosition(@NotBlank String machineName, @Valid BoardCoordinates coords)	Get the physical location of a board.
default BoardPhysicalCoordinates	getBoardPosition(@NotBlank String machineName, @Valid BoardCoordinates coords, @Positive Integer timeout)	Get the physical location of a board.
default BoardCoordinates	getBoardPosition(@NotBlank String machineName, @Valid BoardPhysicalCoordinates coords)	Get the logical location of a board.
default BoardCoordinates	getBoardPosition(@NotBlank String machineName, @Valid BoardPhysicalCoordinates coords, @Positive Integer timeout)	Get the logical location of a board.
default JobMachineInfo	getJobMachineInfo(int jobID)	Get information about a job's allocated machine.
JobMachineInfo	getJobMachineInfo(int jobID, @Positive Integer timeout)	Get information about a job's allocated machine.
default JobState	getJobState(int jobID)	Get the state of a job.
JobState	getJobState(int jobID, @Positive Integer timeout)	Get the state of a job.
default void	jobKeepAlive(int jobID)	Keep a job alive.
void	jobKeepAlive(int jobID, @Positive Integer timeout)	Keep a job alive.
default List<JobDescription>	listJobs()	List all jobs.
List<JobDescription>	listJobs(@Positive Integer timeout)	List all jobs.
default List<Machine>	listMachines()	List all known machines.
List<Machine>	listMachines(@Positive Integer timeout)	List all known machines.
default void	notifyJob(Integer jobID, boolean enable)	Enable or disable notifications of changes in job state.
void	notifyJob(Integer jobID, boolean enable, @Positive Integer timeout)	Enable or disable notifications of changes in job state.
default void	notifyMachine(String machineName, boolean enable)	Enable or disable notifications of changes in machine state.
void	notifyMachine(String machineName, boolean enable, @Positive Integer timeout)	Enable or disable notifications of changes in machine state.
default void	powerOffJobBoards(int jobID)	Turn off a job's allocated boards.
void	powerOffJobBoards(int jobID, @Positive Integer timeout)	Turn off a job's allocated boards.
default void	powerOnJobBoards(int jobID)	Turn on a job's allocated boards.
void	powerOnJobBoards(int jobID, @Positive Integer timeout)	Turn on a job's allocated boards.
default Version	version()	Request the version of the spalloc server.
Version	version(@Positive Integer timeout)	Request the version of the spalloc server.
default Notification	waitForNotification()	Return the next notification to arrive.
Notification	waitForNotification(Integer timeout)	Return the next notification to arrive.
default WhereIs	whereIs(int jobID, @Valid HasChipLocation chip)	Locate a chip within a job's allocation.
WhereIs	whereIs(int jobID, @Valid HasChipLocation chip, @Positive Integer timeout)	Locate a chip within a job's allocation.
default WhereIs	whereIs(@NotBlank String machine, @Valid PhysicalCoords coords)	Locate a board within a machine.
WhereIs	whereIs(@NotBlank String machine, @Valid PhysicalCoords coords, @Positive Integer timeout)	Locate a board within a machine.
default WhereIs	whereIs(@NotBlank String machine, @Valid TriadCoords coords)	Locate a board within a machine.
WhereIs	whereIs(@NotBlank String machine, @Valid TriadCoords coords, @Positive Integer timeout)	Locate a board within a machine.
default WhereIs	whereIs(@NotBlank String machine, @Valid HasChipLocation chip)	Locate a chip within a machine.
WhereIs	whereIs(@NotBlank String machine, @Valid HasChipLocation chip, @Positive Integer timeout)	Locate a chip within a machine.
default WhereIs	whereIs(@NotBlank String machine, @Valid BoardCoordinates coords)	Locate a board within a machine.
default WhereIs	whereIs(@NotBlank String machine, @Valid BoardCoordinates coords, @Positive Integer timeout)	Locate a board within a machine.
default WhereIs	whereIs(@NotBlank String machine, @Valid BoardPhysicalCoordinates coords)	Locate a board within a machine.
default WhereIs	whereIs(@NotBlank String machine, @Valid BoardPhysicalCoordinates coords, @Positive Integer timeout)	Locate a board within a machine.

Method Details

version

default Version version()
                 throws IOException,
SpallocServerException,
InterruptedException

Request the version of the spalloc server.

Returns:

the server's version.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

version

Version version(@Positive
 @Positive Integer timeout)
         throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Request the version of the spalloc server.

Parameters:

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

the server's version.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

createJob

@Deprecated(forRemoval=true)
default int createJob(List<@PositiveOrZero Integer> args,
 Map<@NotBlank String,@NotNull Object> kwargs)
               throws IOException,
SpallocServerException,
InterruptedException

Deprecated, for removal: This API element is subject to removal in a future version.

Consider using createJob(CreateJob) instead.

Create a job.

Parameters:

args - The arguments, describing default (empty), the number of boards (one arg), the triad size (two args) or the board location (three args).

kwargs - Additional arguments required. Must include the key owner. Values can be boxed primitive types or strings.

Returns:

the ID of the created job.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

createJob

default int createJob(@Valid
 @Valid CreateJob builder)
               throws IOException,
SpallocServerException,
InterruptedException

Create a job.

Parameters:

builder - The builder saying what sort of job to create.

Returns:

the ID of the created job.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

createJob

int createJob(@Valid
 @Valid CreateJob builder,
 @Positive
 @Positive Integer timeout)
       throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Create a job.

Parameters:

builder - The builder saying what sort of job to create.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

the ID of the created job.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

createJob

@Deprecated(forRemoval=true)
int createJob(List<@PositiveOrZero Integer> args,
 Map<@NotBlank String,@NotNull Object> kwargs,
 @Positive
 @Positive Integer timeout)
       throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Deprecated, for removal: This API element is subject to removal in a future version.

Consider using createJob(CreateJob, Integer) instead.

Create a job.

Parameters:

args - The arguments, describing default (empty), the number of boards (one arg), the triad size (two args) or the board location (three args).

kwargs - Additional arguments required. Must include the key owner. Values can be boxed primitive types or strings.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

the ID of the created job.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

jobKeepAlive

default void jobKeepAlive(int jobID)
                   throws IOException,
SpallocServerException,
InterruptedException

Keep a job alive. Needs to be regularly called.

Parameters:

jobID - The job to ask about.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

jobKeepAlive

void jobKeepAlive(int jobID,
 @Positive
 @Positive Integer timeout)
           throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Keep a job alive. Needs to be regularly called.

Parameters:

jobID - The job to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getJobState

default JobState getJobState(int jobID)
                      throws IOException,
SpallocServerException,
InterruptedException

Get the state of a job.

Parameters:

jobID - The job to get the state of.

Returns:

a description of the job's state.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getJobState

JobState getJobState(int jobID,
 @Positive
 @Positive Integer timeout)
              throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Get the state of a job.

Parameters:

jobID - The job to get the state of.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

a description of the job's state.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getJobMachineInfo

default JobMachineInfo getJobMachineInfo(int jobID)
                                  throws IOException,
SpallocServerException,
InterruptedException

Get information about a job's allocated machine.

Parameters:

jobID - The job whose machine you want to ask about.

Returns:

a description of the machine.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getJobMachineInfo

JobMachineInfo getJobMachineInfo(int jobID,
 @Positive
 @Positive Integer timeout)
                          throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Get information about a job's allocated machine.

Parameters:

jobID - The job whose machine you want to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

a description of the machine.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

powerOnJobBoards

default void powerOnJobBoards(int jobID)
                       throws IOException,
SpallocServerException,
InterruptedException

Turn on a job's allocated boards.

Parameters:

jobID - The job to request about.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

powerOnJobBoards

void powerOnJobBoards(int jobID,
 @Positive
 @Positive Integer timeout)
               throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Turn on a job's allocated boards.

Parameters:

jobID - The job to request about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

powerOffJobBoards

default void powerOffJobBoards(int jobID)
                        throws IOException,
SpallocServerException,
InterruptedException

Turn off a job's allocated boards.

Parameters:

jobID - The job to request about.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

powerOffJobBoards

void powerOffJobBoards(int jobID,
 @Positive
 @Positive Integer timeout)
                throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Turn off a job's allocated boards.

Parameters:

jobID - The job to request about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

destroyJob

default void destroyJob(int jobID,
 @NotBlank
 @NotBlank String reason)
                 throws IOException,
SpallocServerException,
InterruptedException

Destroy a job.

Parameters:

jobID - The ID of the job.

reason - Why the job is to be destroyed.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

destroyJob

void destroyJob(int jobID,
 @NotBlank
 @NotBlank String reason,
 @Positive
 @Positive Integer timeout)
         throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Destroy a job.

Parameters:

jobID - The ID of the job.

reason - Why the job is to be destroyed.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

notifyJob

default void notifyJob(Integer jobID,
 boolean enable)
                throws IOException,
SpallocServerException,
InterruptedException

Enable or disable notifications of changes in job state.

Parameters:

jobID - The job to request (or cancel requests) about, or null to be notified/not notified about all jobs.

enable - True to enable notifications, false to disable them.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

See Also:

• JobsChangedNotification

notifyJob

void notifyJob(Integer jobID,
 boolean enable,
 @Positive
 @Positive Integer timeout)
        throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Enable or disable notifications of changes in job state.

Parameters:

jobID - The job to request (or cancel requests) about, or null to be notified/not notified about all jobs.

enable - True to enable notifications, false to disable them.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

See Also:

• JobsChangedNotification

notifyMachine

default void notifyMachine(String machineName,
 boolean enable)
                    throws IOException,
SpallocServerException,
InterruptedException

Enable or disable notifications of changes in machine state.

Parameters:

machineName - The machine to request (or cancel requests) about, or null to be notified/not notified about all machines (known to spalloc).

enable - True to enable notifications, false to disable them.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

See Also:

• MachinesChangedNotification

notifyMachine

void notifyMachine(String machineName,
 boolean enable,
 @Positive
 @Positive Integer timeout)
            throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Enable or disable notifications of changes in machine state.

Parameters:

machineName - The machine to request (or cancel requests) about, or null to be notified/not notified about all machines (known to spalloc).

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

enable - True to enable notifications, false to disable them.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

See Also:

• MachinesChangedNotification

listJobs

default List<JobDescription> listJobs()
                               throws IOException,
SpallocServerException,
InterruptedException

List all jobs.

Returns:

A list of allocated/queued jobs in order of creation from oldest (first) to newest (last). This is unmodifiable.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

listJobs

List<JobDescription> listJobs(@Positive
 @Positive Integer timeout)
                       throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

List all jobs.

Parameters:

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

A list of allocated/queued jobs in order of creation from oldest (first) to newest (last). This is unmodifiable.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

listMachines

default List<Machine> listMachines()
                            throws IOException,
SpallocServerException,
InterruptedException

List all known machines.

Returns:

The list of machines known to the system in order of priority from highest (first) to lowest (last). This is unmodifiable.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

listMachines

List<Machine> listMachines(@Positive
 @Positive Integer timeout)
                    throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

List all known machines.

Parameters:

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

The list of machines known to the system in order of priority from highest (first) to lowest (last). This is unmodifiable.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

default BoardPhysicalCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid BoardCoordinates coords)
                                           throws IOException,
SpallocServerException,
InterruptedException

Get the physical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the logical location of the board.

Returns:

the physical location, or null if the logical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

default BoardPhysicalCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid TriadCoords coords)
                                           throws IOException,
SpallocServerException,
InterruptedException

Get the physical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the logical location of the board.

Returns:

the physical location, or null if the logical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

default BoardPhysicalCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid BoardCoordinates coords,
 @Positive
 @Positive Integer timeout)
                                           throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Get the physical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the logical location of the board.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

the physical location, or null if the logical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

BoardPhysicalCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid TriadCoords coords,
 @Positive
 @Positive Integer timeout)
                                   throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Get the physical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the logical location of the board.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

the physical location, or null if the logical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

default BoardCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid BoardPhysicalCoordinates coords)
                                   throws IOException,
SpallocServerException,
InterruptedException

Get the logical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the physical location of the board.

Returns:

the logical location, or null if the physical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

default BoardCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid PhysicalCoords coords)
                                   throws IOException,
SpallocServerException,
InterruptedException

Get the logical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the physical location of the board.

Returns:

the logical location, or null if the physical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

default BoardCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid BoardPhysicalCoordinates coords,
 @Positive
 @Positive Integer timeout)
                                   throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Get the logical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the physical location of the board.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

the logical location, or null if the physical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

getBoardPosition

BoardCoordinates getBoardPosition(@NotBlank
 @NotBlank String machineName,
 @Valid
 @Valid PhysicalCoords coords,
 @Positive
 @Positive Integer timeout)
                           throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Get the logical location of a board.

Parameters:

machineName - the name of the machine containing the board.

coords - the physical location of the board.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

the logical location, or null if the physical location doesn't map to a real board.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(int jobID,
 @Valid
 @Valid HasChipLocation chip)
                 throws IOException,
SpallocServerException,
InterruptedException

Locate a chip within a job's allocation.

Parameters:

jobID - The job to ask about.

chip - The coordinates of the chip to ask about.

Returns:

A description of the chip's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

WhereIs whereIs(int jobID,
 @Valid
 @Valid HasChipLocation chip,
 @Positive
 @Positive Integer timeout)
         throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Locate a chip within a job's allocation.

Parameters:

jobID - The job to ask about.

chip - The coordinates of the chip to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

A description of the chip's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid HasChipLocation chip)
                 throws IOException,
SpallocServerException,
InterruptedException

Locate a chip within a machine.

Parameters:

machine - The machine to ask about.

chip - The coordinates of the chip to ask about.

Returns:

A description of the chip's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid HasChipLocation chip,
 @Positive
 @Positive Integer timeout)
         throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Locate a chip within a machine.

Parameters:

machine - The machine to ask about.

chip - The coordinates of the chip to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

A description of the chip's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid BoardPhysicalCoordinates coords)
                 throws IOException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The physical coordinates of the board to ask about.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid PhysicalCoords coords)
                 throws IOException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The physical coordinates of the board to ask about.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid BoardPhysicalCoordinates coords,
 @Positive
 @Positive Integer timeout)
                 throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The physical coordinates of the board to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid PhysicalCoords coords,
 @Positive
 @Positive Integer timeout)
         throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The physical coordinates of the board to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid BoardCoordinates coords)
                 throws IOException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The logical coordinates of the board to ask about.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid TriadCoords coords)
                 throws IOException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The logical coordinates of the board to ask about.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

default WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid BoardCoordinates coords,
 @Positive
 @Positive Integer timeout)
                 throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The logical coordinates of the board to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

whereIs

WhereIs whereIs(@NotBlank
 @NotBlank String machine,
 @Valid
 @Valid TriadCoords coords,
 @Positive
 @Positive Integer timeout)
         throws IOException,
SpallocProtocolTimeoutException,
SpallocServerException,
InterruptedException

Locate a board within a machine.

Parameters:

machine - The machine to ask about.

coords - The logical coordinates of the board to ask about.

timeout - How long to wait for the request to complete, in milliseconds, or null to wait forever.

Returns:

A description of the board's location, or null if it can't be found.

Throws:

SpallocServerException - if the server returns an exception response.

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

InterruptedException - If interrupted while waiting.

waitForNotification

default Notification waitForNotification()
                                  throws SpallocProtocolException,
InterruptedException

Return the next notification to arrive. Waits indefinitely.

Returns:

The notification sent by the server.

Throws:

SpallocProtocolException - If the socket is unusable or becomes disconnected.

InterruptedException - If interrupted while waiting.

RuntimeException - If there is a timeout.

See Also:

• JobsChangedNotification
• MachinesChangedNotification

waitForNotification

Notification waitForNotification(Integer timeout)
                          throws SpallocProtocolException,
SpallocProtocolTimeoutException,
InterruptedException

Return the next notification to arrive.

Parameters:

timeout - The number of seconds to wait before timing out or null if this function should try again forever.

If negative, only responses already-received will be returned; if no responses are available, in this case the function does not raise a SpallocProtocolTimeoutException but returns null instead.

Returns:

The notification sent by the server.

Throws:

SpallocProtocolTimeoutException - If a timeout occurs (implying timeout is not negative).

SpallocProtocolException - If the socket is unusable or becomes disconnected.

InterruptedException - If interrupted while waiting.

See Also:

• JobsChangedNotification
• MachinesChangedNotification