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 TypeMethodDescriptiondefault int
Create a job.int
Create a job.default int
Deprecated, for removal: This API element is subject to removal in a future version.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 usingcreateJob(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.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.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.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.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 all jobs.List all known machines.listMachines
(@Positive Integer timeout) List all known machines.default void
Enable or disable notifications of changes in job state.void
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.Request the version of the spalloc server.default Notification
Return the next notification to arrive.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
(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
(@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
(@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
(@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
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, ornull
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, InterruptedExceptionDeprecated, for removal: This API element is subject to removal in a future version.Consider usingcreateJob(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 keyowner
. 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, ornull
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, InterruptedExceptionDeprecated, for removal: This API element is subject to removal in a future version.Consider usingcreateJob(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 keyowner
. Values can be boxed primitive types or strings.timeout
- How long to wait for the request to complete, in milliseconds, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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:
-
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, ornull
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, ornull
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:
-
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, ornull
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:
-
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, ornull
to be notified/not notified about all machines (known to spalloc).timeout
- How long to wait for the request to complete, in milliseconds, ornull
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:
-
listJobs
default List<JobDescription> listJobs() throws IOException, SpallocServerException, InterruptedExceptionList 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, ornull
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, InterruptedExceptionList 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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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, ornull
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
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:
-
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 ornull
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 returnsnull
instead.- Returns:
- The notification sent by the server.
- Throws:
SpallocProtocolTimeoutException
- If a timeout occurs (implyingtimeout
is not negative).SpallocProtocolException
- If the socket is unusable or becomes disconnected.InterruptedException
- If interrupted while waiting.- See Also:
-
createJob(CreateJob)
instead.