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
Response	addMember(int groupId, @Valid MemberRecord user, UriInfo ui)	Add a user to a group.
Response	createGroup(@Valid GroupRecord group, UriInfo ui)	Create a new group.
Response	createUser(@Valid UserRecord user, UriInfo ui)	Create a new user.
String	deleteGroup(int groupId)	Delete a group.
String	deleteUser(int id, SecurityContext security)	Delete a user.
GroupRecord	describeGroup(int groupId, UriInfo ui)	Read a particular group's details.
default String	describeImport()	"Describes" the import resource.
MemberRecord	describeMember(int groupId, int memberId, UriInfo ui)	Read a particular group's details.
default AdminAPI.Description	describeOperations(UriInfo ui)	Describe the admin interface.
UserRecord	describeUser(int id, 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, @ValidCabinetNumber int c, @ValidFrameNumber int f, @ValidBoardNumber int b)	Find board by physical coordinates and return its state.
boolean	getBoardStateXYZ(String name, @ValidTriadX int x, @ValidTriadY int y, @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(UriInfo ui)	List the groups and the URIs used to describe and manipulate them.
Map<String,URI>	listUsers(UriInfo ui)	List the usernames and the URIs used to describe and manipulate them.
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, @NotNull @ValidCabinetNumber int c, @NotNull @ValidFrameNumber int f, @NotNull @ValidBoardNumber int b, boolean enabled)	Enable or disable a board.
boolean	setBoardStateXYZ(@NotBlank String name, @ValidTriadX int x, @ValidTriadY int y, @ValidTriadZ int z, boolean enabled)	Enable or disable a board.
GroupRecord	updateGroup(int groupId, @Valid GroupRecord group, UriInfo ui)	Update a particular group's details.
UserRecord	updateUser(int id, @Valid UserRecord user, UriInfo ui, SecurityContext security)	Update a particular user's details.

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
 @ValidTriadX int x,
 @ValidTriadY
 @ValidTriadY int y,
 @ValidTriadZ
 @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
 @ValidCabinetNumber int c,
 @ValidFrameNumber
 @ValidFrameNumber int f,
 @ValidBoardNumber
 @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
 @ValidTriadX int x,
 @ValidTriadY
 @ValidTriadY int y,
 @ValidTriadZ
 @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
 @NotNull @ValidCabinetNumber int c,
 @NotNull @ValidFrameNumber
 @NotNull @ValidFrameNumber int f,
 @NotNull @ValidBoardNumber
 @NotNull @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