Package uk.ac.manchester.spinnaker.spalloc

Class SpallocClient

java.lang.Object

uk.ac.manchester.spinnaker.spalloc.SpallocConnection

uk.ac.manchester.spinnaker.spalloc.SpallocClient

All Implemented Interfaces:

Closeable, AutoCloseable, SpallocAPI

public class SpallocClient
extends SpallocConnection
implements SpallocAPI

A simple (blocking) client implementation of the spalloc-server protocol.

This minimal implementation is intended to serve both simple applications and as an example implementation of the protocol for other applications. This implementation simply implements the protocol, presenting an RPC-like interface to the server. For a higher-level interface built on top of this client, see SpallocJob.

Field Summary

Fields inherited from class uk.ac.manchester.spinnaker.spalloc.SpallocConnection

notifications

Constructor Summary

Constructors

Constructor	Description
SpallocClient(String hostname)	Define a new connection using the default spalloc port.
SpallocClient(String hostname, int port)	Define a new connection.
SpallocClient(String hostname, Integer timeout)	Define a new connection using the default spalloc port.
SpallocClient(String hostname, Integer port, Integer timeout)	Define a new connection.

Method Summary

Modifier and Type	Method	Description
int	createJob(List<Integer> args, Map<String,Object> kwargs, Integer timeout)	Deprecated, for removal: This API element is subject to removal in a future version.
int	createJob(CreateJob builder, Integer timeout)	Create a job.
static ObjectMapper	createMapper()	Static method to create the object mapper.
void	destroyJob(int jobID, String reason, Integer timeout)	Destroy a job.
protected String	formatRequest(Command<?> command)	Format a request as a line of newline-free JSON, suitable for sending to the spalloc server.
BoardCoordinates	getBoardPosition(String machineName, PhysicalCoords coords, Integer timeout)	Get the logical location of a board.
BoardPhysicalCoordinates	getBoardPosition(String machineName, TriadCoords coords, Integer timeout)	Get the physical location of a board.
JobMachineInfo	getJobMachineInfo(int jobID, Integer timeout)	Get information about a job's allocated machine.
JobState	getJobState(int jobID, Integer timeout)	Get the state of a job.
void	jobKeepAlive(int jobID, Integer timeout)	Keep a job alive.
List<JobDescription>	listJobs(Integer timeout)	List all jobs.
List<Machine>	listMachines(Integer timeout)	List all known machines.
void	notifyJob(Integer jobID, boolean enable, Integer timeout)	Enable or disable notifications of changes in job state.
void	notifyMachine(String machineName, boolean enable, Integer timeout)	Enable or disable notifications of changes in machine state.
protected Response	parseResponse(String line)	Parse a line of response from the spalloc server, which should be a complete JSON object.
void	powerOffJobBoards(int jobID, Integer timeout)	Turn off a job's allocated boards.
void	powerOnJobBoards(int jobID, Integer timeout)	Turn on a job's allocated boards.
Version	version(Integer timeout)	Request the version of the spalloc server.
Notification	waitForNotification(Integer timeout)	Return the next notification to arrive.
WhereIs	whereIs(int jobID, HasChipLocation chip, Integer timeout)	Locate a chip within a job's allocation.
WhereIs	whereIs(String machine, PhysicalCoords coords, Integer timeout)	Locate a board within a machine.
WhereIs	whereIs(String machine, TriadCoords coords, Integer timeout)	Locate a board within a machine.
WhereIs	whereIs(String machine, HasChipLocation chip, Integer timeout)	Locate a chip within a machine.

Methods inherited from class uk.ac.manchester.spinnaker.spalloc.SpallocConnection

call, close, connect, connect, receiveResponse, sendCommand, toString, withConnection

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface uk.ac.manchester.spinnaker.spalloc.SpallocAPI

createJob, createJob, destroyJob, getBoardPosition, getBoardPosition, getBoardPosition, getBoardPosition, getBoardPosition, getBoardPosition, getJobMachineInfo, getJobState, jobKeepAlive, listJobs, listMachines, notifyJob, notifyMachine, powerOffJobBoards, powerOnJobBoards, version, waitForNotification, whereIs, whereIs, whereIs, whereIs, whereIs, whereIs, whereIs, whereIs

Constructor Details

SpallocClient

@MustBeClosed
public SpallocClient(String hostname)

Define a new connection using the default spalloc port. NB: Does not connect to the server until SpallocConnection.connect() is called.

Parameters:

hostname - The hostname of the server.

SpallocClient

@MustBeClosed
public SpallocClient(String hostname,
 Integer timeout)

Define a new connection using the default spalloc port. NB: Does not connect to the server until SpallocConnection.connect() is called.

Parameters:

hostname - The hostname of the server.

timeout - The default timeout.

SpallocClient

@MustBeClosed
public SpallocClient(String hostname,
 int port)

Define a new connection. NB: Does not connect to the server until SpallocConnection.connect() is called.

Parameters:

hostname - The hostname of the server.

port - The port to use.

SpallocClient

@MustBeClosed
public SpallocClient(String hostname,
 Integer port,
 Integer timeout)

Define a new connection. NB: Does not connect to the server until SpallocConnection.connect() is called.

Parameters:

hostname - The hostname of the server.

port - The port to use.

timeout - The default timeout.

Method Details

createMapper

public static ObjectMapper createMapper()

Static method to create the object mapper.

This method makes sure that all JSON unmarshallers use the same Mapper set up the exact same way.

Returns:

The Object Mapper used by the Spalloc client,

waitForNotification

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

Description copied from interface: SpallocAPI

Return the next notification to arrive.

Specified by:

waitForNotification in interface SpallocAPI

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:

SpallocProtocolException - If the socket is unusable or becomes disconnected.

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

InterruptedException - If interrupted while waiting.

See Also:

• JobsChangedNotification
• MachinesChangedNotification

version

public Version version(Integer timeout)
                throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Request the version of the spalloc server.

Specified by:

version in interface SpallocAPI

Parameters:

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

Returns:

the server's version.

Throws:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

createJob

public int createJob(CreateJob builder,
 Integer timeout)
              throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Create a job.

Specified by:

createJob in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

createJob

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

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

Description copied from interface: SpallocAPI

Create a job.

Specified by:

createJob in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

jobKeepAlive

public void jobKeepAlive(int jobID,
 Integer timeout)
                  throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Keep a job alive. Needs to be regularly called.

Specified by:

jobKeepAlive in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

getJobState

public JobState getJobState(int jobID,
 Integer timeout)
                     throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Get the state of a job.

Specified by:

getJobState in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

getJobMachineInfo

public JobMachineInfo getJobMachineInfo(int jobID,
 Integer timeout)
                                 throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Get information about a job's allocated machine.

Specified by:

getJobMachineInfo in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

powerOnJobBoards

public void powerOnJobBoards(int jobID,
 Integer timeout)
                      throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Turn on a job's allocated boards.

Specified by:

powerOnJobBoards in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

powerOffJobBoards

public void powerOffJobBoards(int jobID,
 Integer timeout)
                       throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Turn off a job's allocated boards.

Specified by:

powerOffJobBoards in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

destroyJob

public void destroyJob(int jobID,
 String reason,
 Integer timeout)
                throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Destroy a job.

Specified by:

destroyJob in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

notifyJob

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

Description copied from interface: SpallocAPI

Enable or disable notifications of changes in job state.

Specified by:

notifyJob in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

See Also:

• JobsChangedNotification

notifyMachine

public void notifyMachine(String machineName,
 boolean enable,
 Integer timeout)
                   throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Enable or disable notifications of changes in machine state.

Specified by:

notifyMachine in interface SpallocAPI

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.

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

Throws:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

See Also:

• MachinesChangedNotification

listJobs

public List<JobDescription> listJobs(Integer timeout)
                              throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

List all jobs.

Specified by:

listJobs in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

listMachines

public List<Machine> listMachines(Integer timeout)
                           throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

List all known machines.

Specified by:

listMachines in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

getBoardPosition

public BoardPhysicalCoordinates getBoardPosition(String machineName,
 TriadCoords coords,
 Integer timeout)
                                          throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Get the physical location of a board.

Specified by:

getBoardPosition in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

getBoardPosition

public BoardCoordinates getBoardPosition(String machineName,
 PhysicalCoords coords,
 Integer timeout)
                                  throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Get the logical location of a board.

Specified by:

getBoardPosition in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

whereIs

public WhereIs whereIs(int jobID,
 HasChipLocation chip,
 Integer timeout)
                throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Locate a chip within a job's allocation.

Specified by:

whereIs in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

whereIs

public WhereIs whereIs(String machine,
 HasChipLocation chip,
 Integer timeout)
                throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Locate a chip within a machine.

Specified by:

whereIs in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

whereIs

public WhereIs whereIs(String machine,
 PhysicalCoords coords,
 Integer timeout)
                throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Locate a board within a machine.

Specified by:

whereIs in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

whereIs

public WhereIs whereIs(String machine,
 TriadCoords coords,
 Integer timeout)
                throws IOException,
SpallocServerException,
InterruptedException

Description copied from interface: SpallocAPI

Locate a board within a machine.

Specified by:

whereIs in interface SpallocAPI

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:

SpallocProtocolTimeoutException - if the request times out.

IOException - if network communications fail.

SpallocServerException - if the server returns an exception response.

InterruptedException - If interrupted while waiting.

formatRequest

protected String formatRequest(Command<?> command)
                        throws IOException

Format a request as a line of newline-free JSON, suitable for sending to the spalloc server.

Specified by:

formatRequest in class SpallocConnection

Parameters:

command - The request to format for sending. Not null.

Returns:

The text to send to the server. Will have a newline added.

Throws:

IOException - If formatting goes wrong.

parseResponse

protected Response parseResponse(String line)
                          throws IOException

Parse a line of response from the spalloc server, which should be a complete JSON object.

Specified by:

parseResponse in class SpallocConnection

Parameters:

line - The line to parse. Not null. Has the terminating newline removed.

Returns:

The parsed response.

Throws:

IOException - If parsing completely fails.

SpallocProtocolException - If an unexpected valid JSON message is returned (e.g., null).