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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    AdminAPI.Description
    Where the other resources are.
    static interface 
    AdminAPI.Paths
    Common paths in the interface.

  • Method Summary

    Modifier and Type
    Method
    Description
    jakarta.ws.rs.core.Response
    addMember(int groupId, @Valid MemberRecord user, jakarta.ws.rs.core.UriInfo ui)
    Add a user to a group.
    jakarta.ws.rs.core.Response
    createGroup(@Valid GroupRecord group, jakarta.ws.rs.core.UriInfo ui)
    Create a new group.
    jakarta.ws.rs.core.Response
    createUser(@Valid UserRecord user, jakarta.ws.rs.core.UriInfo ui)
    Create a new user.
    String
    deleteGroup(int groupId)
    Delete a group.
    String
    deleteUser(int id, jakarta.ws.rs.core.SecurityContext security)
    Delete a user.
    GroupRecord
    describeGroup(int groupId, jakarta.ws.rs.core.UriInfo ui)
    Read a particular group's details.
    default String
    describeImport()
    "Describes" the import resource.
    MemberRecord
    describeMember(int groupId, int memberId, jakarta.ws.rs.core.UriInfo ui)
    Read a particular group's details.
    default AdminAPI.Description
    describeOperations(jakarta.ws.rs.core.UriInfo ui)
    Describe the admin interface.
    UserRecord
    describeUser(int id, jakarta.ws.rs.core.UriInfo ui)
    Read a particular user's details.
    default boolean
    getBoardState(@NotBlank(message="machine name is required") String machineName, @ValidTriadX Integer x, @ValidTriadY Integer y, @ValidTriadZ Integer z, @ValidCabinetNumber Integer c, @ValidFrameNumber Integer f, @ValidBoardNumber Integer b, @IPAddress(nullOK=true) String address)
    Describe the enable state of a board.
    boolean
    getBoardStateAddress(String name, @IPAddress String address)
    Find board by IP address and return its state.
    boolean
    getBoardStateCFB(String name, @uk.ac.manchester.spinnaker.machine.board.ValidCabinetNumber int c, @uk.ac.manchester.spinnaker.machine.board.ValidFrameNumber int f, @uk.ac.manchester.spinnaker.machine.board.ValidBoardNumber int b)
    Find board by physical coordinates and return its state.
    boolean
    getBoardStateXYZ(String name, @uk.ac.manchester.spinnaker.machine.board.ValidTriadX int x, @uk.ac.manchester.spinnaker.machine.board.ValidTriadY int y, @uk.ac.manchester.spinnaker.machine.board.ValidTriadZ int z)
    Find board by logical triad coordinates and return its state.
    void
    importMachinesByContent(MachineDefinitionLoader.Configuration definitions)
    Import a machine definition by posting it.
    Map<String,URI>
    listGroups(jakarta.ws.rs.core.UriInfo ui)
    List the groups and the URIs used to describe and manipulate them.
    Map<String,URI>
    listUsers(jakarta.ws.rs.core.UriInfo ui)
    List the usernames and the URIs used to describe and manipulate them.
    jakarta.ws.rs.core.Response
    removeMember(int groupId, int memberId)
    Delete a membership of a group.
    default boolean
    setBoardState(@NotBlank(message="machine name is required") String machineName, @ValidTriadX Integer x, @ValidTriadY Integer y, @ValidTriadZ Integer z, @ValidCabinetNumber Integer c, @ValidFrameNumber Integer f, @ValidBoardNumber Integer b, @IPAddress(nullOK=true) String address, boolean enabled)
    Enable or disable a board.
    boolean
    setBoardStateAddress(@NotBlank String name, @IPAddress String address, boolean enabled)
    Enable or disable a board.
    boolean
    setBoardStateCFB(@NotBlank String name, @jakarta.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidCabinetNumber int c, @jakarta.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidFrameNumber int f, @jakarta.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidBoardNumber int b, boolean enabled)
    Enable or disable a board.
    boolean
    setBoardStateXYZ(@NotBlank String name, @uk.ac.manchester.spinnaker.machine.board.ValidTriadX int x, @uk.ac.manchester.spinnaker.machine.board.ValidTriadY int y, @uk.ac.manchester.spinnaker.machine.board.ValidTriadZ int z, boolean enabled)
    Enable or disable a board.
    GroupRecord
    updateGroup(int groupId, @Valid GroupRecord group, jakarta.ws.rs.core.UriInfo ui)
    Update a particular group's details.
    UserRecord
    updateUser(int id, @Valid UserRecord user, jakarta.ws.rs.core.UriInfo ui, jakarta.ws.rs.core.SecurityContext security)
    Update a particular user's details.

  • Method Details

    • describeOperations

      @GET @Produces("application/json") @Path("/") default AdminAPI.Description describeOperations(@Context jakarta.ws.rs.core.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 @jakarta.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidCabinetNumber int c, @NotNull @ValidFrameNumber @jakarta.validation.constraints.NotNull,@uk.ac.manchester.spinnaker.machine.board.ValidFrameNumber int f, @NotNull @ValidBoardNumber @jakarta.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 jakarta.ws.rs.core.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") jakarta.ws.rs.core.Response createUser(@Valid @Valid UserRecord user, @Context jakarta.ws.rs.core.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 jakarta.ws.rs.core.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 jakarta.ws.rs.core.UriInfo ui, @Context jakarta.ws.rs.core.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 jakarta.ws.rs.core.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 jakarta.ws.rs.core.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") jakarta.ws.rs.core.Response createGroup(@Valid @Valid GroupRecord group, @Context jakarta.ws.rs.core.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 jakarta.ws.rs.core.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 jakarta.ws.rs.core.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") jakarta.ws.rs.core.Response addMember(@PathParam("groupId") int groupId, @Valid @Valid MemberRecord user, @Context jakarta.ws.rs.core.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 jakarta.ws.rs.core.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}") jakarta.ws.rs.core.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