Interface AdminAPI
- All Known Implementing Classes:
AdminImpl
Administration interface.
- Author:
- Donal Fellows
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic final class
Where the other resources are.static interface
Common paths in the interface. -
Method Summary
Modifier and TypeMethodDescriptionjakarta.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.deleteGroup
(int groupId) Delete a group.deleteUser
(int id, jakarta.ws.rs.core.SecurityContext security) Delete a user.describeGroup
(int groupId, jakarta.ws.rs.core.UriInfo ui) Read a particular group's details.default String
"Describes" the import resource.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.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
Import a machine definition by posting it.listGroups
(jakarta.ws.rs.core.UriInfo ui) List the groups and the URIs used to describe and manipulate them.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.updateGroup
(int groupId, @Valid GroupRecord group, jakarta.ws.rs.core.UriInfo ui) Update a particular group's details.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
"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; requiredx
- The X coordinate, used to identify a board by triad coordsy
- The Y coordinate, used to identify a board by triad coordsz
- The Z coordinate, used to identify a board by triad coordsc
- The cabinet number, used to identify a board physicallyf
- The frame number, used to identify a board physicallyb
- The board number, used to identify a board physicallyaddress
- 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 machinex
- The X coordinatey
- The Y coordinatez
- 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 machinec
- The cabinet numberf
- The frame numberb
- The board number- Returns:
- Whether the board is enabled
-
getBoardStateAddress
Find board by IP address and return its state.- Parameters:
name
- The name of the machineaddress
- 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 machinex
- The X coordinate, used to identify a board by triad coordsy
- The Y coordinate, used to identify a board by triad coordsz
- The Z coordinate, used to identify a board by triad coordsc
- The cabinet number, used to identify a board physicallyf
- The frame number, used to identify a board physicallyb
- The board number, used to identify a board physicallyaddress
- 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 machinex
- The X coordinatey
- The Y coordinatez
- The Z coordinateenabled
- 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 machinec
- The cabinet numberf
- The frame numberb
- The board numberenabled
- 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 machineaddress
- 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 userui
- 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 useruser
- 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 usersecurity
- 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 groupui
- 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 groupgroup
- 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 groupmemberId
- 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 groupmemberId
- The ID of the membership- Returns:
- REST response
-