Package uk.ac.manchester.spinnaker.alloc.admin

Interface AdminAPI

All Known Implementing Classes:
AdminImpl
@PreAuthorize("hasRole(\'ADMIN\')")
public interface AdminAPI
Administration interface.
Author:
Donal Fellows

  • Method Details

    • describeOperations

      @GET @Produces("application/json") @Path("/") default AdminAPI.Description describeOperations​(@Context UriInfo ui)
      Describe the admin interface.
      Parameters:
      ui - How to mint URIs.
      Returns:
      Machine-readable description.

    • describeImport

      @GET @Produces("text/plain") @Path("import") default String describeImport()
      "Describes" the import resource.
      Returns:
      Human-readable description.

    • importMachinesByContent

      @POST @Consumes("application/json") @Path("import") void importMachinesByContent​(@NotNull @Valid MachineDefinitionLoader.Configuration definitions)
      Import a machine definition by posting it.
      Parameters:
      definitions - The definitions.

    • getBoardState

      @GET @Produces("text/plain") @Path("board") default boolean getBoardState​(@NotBlank(message="machine name is required") @QueryParam("machine") @NotBlank(message="machine name is required") String machineName, @QueryParam("x") @ValidTriadX @ValidTriadX Integer x, @QueryParam("y") @ValidTriadY @ValidTriadY Integer y, @QueryParam("z") @ValidTriadZ @ValidTriadZ Integer z, @QueryParam("cabinet") @ValidCabinetNumber @ValidCabinetNumber Integer c, @QueryParam("frame") @ValidFrameNumber @ValidFrameNumber Integer f, @QueryParam("board") @ValidBoardNumber @ValidBoardNumber Integer b, @QueryParam("address") @IPAddress(nullOK=true) @IPAddress(nullOK=true) String address)
      Describe the enable state of a board.
      Parameters:
      machineName - The name of the machine; required
      x - The X coordinate, used to identify a board by triad coords
      y - The Y coordinate, used to identify a board by triad coords
      z - The Z coordinate, used to identify a board by triad coords
      c - The cabinet number, used to identify a board physically
      f - The frame number, used to identify a board physically
      b - The board number, used to identify a board physically
      address - The IP address of the board (dotted quad)
      Returns:
      Whether the board is enabled
      Throws:
      RequestFailedException - If bad query combinations are supplied

    • getBoardStateXYZ

      boolean getBoardStateXYZ​(String name, @ValidTriadX @uk.ac.manchester.spinnaker.machine.board.ValidTriadX int x, @ValidTriadY @uk.ac.manchester.spinnaker.machine.board.ValidTriadY int y, @ValidTriadZ @uk.ac.manchester.spinnaker.machine.board.ValidTriadZ int z)
      Find board by logical triad coordinates and return its state.
      Parameters:
      name - The name of the machine
      x - The X coordinate
      y - The Y coordinate
      z - The Z coordinate
      Returns:
      Whether the board is enabled

    • getBoardStateCFB

      boolean getBoardStateCFB​(String name, @ValidCabinetNumber @uk.ac.manchester.spinnaker.machine.board.ValidCabinetNumber int c, @ValidFrameNumber @uk.ac.manchester.spinnaker.machine.board.ValidFrameNumber int f, @ValidBoardNumber @uk.ac.manchester.spinnaker.machine.board.ValidBoardNumber int b)
      Find board by physical coordinates and return its state.
      Parameters:
      name - The name of the machine
      c - The cabinet number
      f - The frame number
      b - The board number
      Returns:
      Whether the board is enabled

    • getBoardStateAddress

      boolean getBoardStateAddress​(String name, @IPAddress @IPAddress String address)
      Find board by IP address and return its state.
      Parameters:
      name - The name of the machine
      address - The IP address of the board (dotted quad)
      Returns:
      Whether the board is enabled

    • setBoardState

      @PUT @Consumes("text/plain") @Produces("text/plain") @Path("board") default boolean setBoardState​(@NotBlank(message="machine name is required") @QueryParam("machine") @NotBlank(message="machine name is required") String machineName, @QueryParam("x") @ValidTriadX @ValidTriadX Integer x, @QueryParam("y") @ValidTriadY @ValidTriadY Integer y, @QueryParam("z") @ValidTriadZ @ValidTriadZ Integer z, @QueryParam("cabinet") @ValidCabinetNumber @ValidCabinetNumber Integer c, @QueryParam("frame") @ValidFrameNumber @ValidFrameNumber Integer f, @QueryParam("board") @ValidBoardNumber @ValidBoardNumber Integer b, @QueryParam("address") @IPAddress(nullOK=true) @IPAddress(nullOK=true) String address, boolean enabled)
      Enable or disable a board.
      Parameters:
      machineName - The name of the machine
      x - The X coordinate, used to identify a board by triad coords
      y - The Y coordinate, used to identify a board by triad coords
      z - The Z coordinate, used to identify a board by triad coords
      c - The cabinet number, used to identify a board physically
      f - The frame number, used to identify a board physically
      b - The board number, used to identify a board physically
      address - The IP address of the board (dotted quad)
      enabled - Whether the board should be set to the enabled state
      Returns:
      Whether the board is enabled
      Throws:
      RequestFailedException - If bad query combinations are supplied

    • setBoardStateXYZ

      boolean setBoardStateXYZ​(@NotBlank @NotBlank String name, @ValidTriadX @uk.ac.manchester.spinnaker.machine.board.ValidTriadX int x, @ValidTriadY @uk.ac.manchester.spinnaker.machine.board.ValidTriadY int y, @ValidTriadZ @uk.ac.manchester.spinnaker.machine.board.ValidTriadZ int z, boolean enabled)
      Enable or disable a board. Find by logical triad coordinates.
      Parameters:
      name - The name of the machine
      x - The X coordinate
      y - The Y coordinate
      z - The Z coordinate
      enabled - Whether the board should be set to the enabled state
      Returns:
      Whether the board is enabled

    • setBoardStateCFB

      boolean setBoardStateCFB​(@NotBlank @NotBlank String name, @NotNull @ValidCabinetNumber @javax.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidCabinetNumber int c, @NotNull @ValidFrameNumber @javax.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidFrameNumber int f, @NotNull @ValidBoardNumber @javax.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidBoardNumber int b, boolean enabled)
      Enable or disable a board. Find by physical coordinates.
      Parameters:
      name - The name of the machine
      c - The cabinet number
      f - The frame number
      b - The board number
      enabled - Whether the board should be set to the enabled state
      Returns:
      Whether the board is enabled

    • setBoardStateAddress

      boolean setBoardStateAddress​(@NotBlank @NotBlank String name, @IPAddress @IPAddress String address, boolean enabled)
      Enable or disable a board. Find by IP address.
      Parameters:
      name - The name of the machine
      address - The IP address of the board (dotted quad)
      enabled - Whether the board should be set to the enabled state
      Returns:
      Whether the board is enabled

    • listUsers

      @GET @Path("users") @Produces("application/json") Map<String,​URI> listUsers​(@Context UriInfo ui)
      List the usernames and the URIs used to describe and manipulate them.
      Parameters:
      ui - For building URIs.
      Returns:
      A sorted map from username to details-handling URI

    • createUser

      @POST @Path("users") @Consumes("application/json") @Produces("application/json") Response createUser​(@Valid @Valid UserRecord user, @Context UriInfo ui)
      Create a new user.
      Parameters:
      user - Description of user to create. Username must be unique.
      ui - For building URIs.
      Returns:
      REST response (CREATED on success)

    • describeUser

      @GET @Path("users/{id}") @Produces("application/json") UserRecord describeUser​(@PathParam("id") int id, @Context UriInfo ui)
      Read a particular user's details.
      Parameters:
      id - The ID of the user
      ui - For building URIs.
      Returns:
      Description of the user.

    • updateUser

      @PUT @Path("users/{id}") @Consumes("application/json") @Produces("application/json") UserRecord updateUser​(@PathParam("id") int id, @Valid @Valid UserRecord user, @Context UriInfo ui, @Context SecurityContext security)
      Update a particular user's details.
      Parameters:
      id - The ID of the user
      user - What to set the details to. null fields are ignored.
      ui - For building URIs.
      security - Used to check who the current user actually is.
      Returns:
      The updated user details.

    • deleteUser

      @DELETE @Path("users/{id}") @Produces("text/plain") String deleteUser​(@PathParam("id") int id, @Context SecurityContext security)
      Delete a user.
      Parameters:
      id - The ID of the user
      security - Used to check who the current user actually is.
      Returns:
      Description of what user was deleted.

    • listGroups

      @GET @Path("groups") @Produces("application/json") Map<String,​URI> listGroups​(@Context UriInfo ui)
      List the groups and the URIs used to describe and manipulate them.
      Parameters:
      ui - For building URIs.
      Returns:
      A sorted map from group name to details-handling URI

    • createGroup

      @POST @Path("groups") @Consumes("application/json") @Produces("application/json") Response createGroup​(@Valid @Valid GroupRecord group, @Context UriInfo ui)
      Create a new group.
      Parameters:
      group - Description of group to create. Group name must be unique.
      ui - For building URIs.
      Returns:
      REST response (CREATED on success)

    • describeGroup

      @GET @Path("groups/{groupId}") @Produces("application/json") GroupRecord describeGroup​(@PathParam("groupId") int groupId, @Context UriInfo ui)
      Read a particular group's details.
      Parameters:
      groupId - The ID of the group
      ui - For building URIs.
      Returns:
      Description of the group.

    • updateGroup

      @PUT @Path("groups/{groupId}") @Consumes("application/json") @Produces("application/json") GroupRecord updateGroup​(@PathParam("groupId") int groupId, @Valid @Valid GroupRecord group, @Context UriInfo ui)
      Update a particular group's details. This particularly includes the name and the quota, but excludes the memberships; those are separate resources.
      Parameters:
      groupId - The ID of the group
      group - The description of the group to update to be like.
      ui - For building URIs.
      Returns:
      Description of the group.

    • deleteGroup

      @DELETE @Path("groups/{groupId}") @Produces("text/plain") String deleteGroup​(@PathParam("groupId") int groupId)
      Delete a group.
      Parameters:
      groupId - The ID of the group
      Returns:
      Description of what group was deleted

    • addMember

      @POST @Path("groups/{groupId}/members") @Consumes("application/json") @Produces("application/json") Response addMember​(@PathParam("groupId") int groupId, @Valid @Valid MemberRecord user, @Context UriInfo ui)
      Add a user to a group.
      Parameters:
      groupId - Which group to add to.
      user - Description of user to add. User name must be present.
      ui - For building URIs.
      Returns:
      REST response (CREATED on success)

    • describeMember

      @GET @Path("groups/{groupId}/members/{memberId}") @Produces("application/json") MemberRecord describeMember​(@PathParam("groupId") int groupId, @PathParam("memberId") int memberId, @Context UriInfo ui)
      Read a particular group's details.
      Parameters:
      groupId - The ID of the group
      memberId - The ID of the membership.
      ui - For building URIs.
      Returns:
      Description of the membership.

    • removeMember

      @DELETE @Path("groups/{groupId}/members/{memberId}") Response removeMember​(@PathParam("groupId") int groupId, @PathParam("memberId") int memberId)
      Delete a membership of a group.
      Parameters:
      groupId - The ID of the group
      memberId - The ID of the membership
      Returns:
      REST response