ResourceController class

Controller for operating on an HTTP Resource.

ResourceControllers provide a means to organize the logic for all operations on an HTTP resource. They also provide conveniences for handling these operations.

This class must be subclassed. Its instance methods handle operations on an HTTP resource. For example, the following are operations: 'GET /employees', 'GET /employees/:id' and 'POST /employees'. An instance method is assigned to handle one of these operations. For example:

    class EmployeeController extends ResourceController {
       @Operation.post()
       Future<Response> createEmployee(...) async => Response.ok(null);
    }

Instance methods must have Operation annotation to respond to a request (see also Operation.get, Operation.post, Operation.put and Operation.delete). These methods are called operation methods. Operation methods also take a variable list of path variables. An operation method is called if the incoming request's method and present path variables match the operation annotation.

For example, the route /employees/[:id] contains an optional route variable named id. A subclass can implement two operation methods, one for when id was present and the other for when it was not:

    class EmployeeController extends ResourceController {
       // This method gets invoked when the path is '/employees'
       @Operation.get()
       Future<Response> getEmployees() async {
        return Response.ok(employees);
       }

       // This method gets invoked when the path is '/employees/id'
       @Operation.get('id')
       Future<Response> getEmployees(@Bind.path("id") int id) async {
        return Response.ok(employees[id]);
       }
    }

If there isn't an operation method for a request, an 405 Method Not Allowed error response is sent to the client and no operation methods are called.

For operation methods to correctly function, a request must have previously been handled by a Router to parse path variables.

Values from a request may be bound to operation method parameters. Parameters must be annotated with Bind.path, Bind.query, Bind.header, or Bind.body. For example, the following binds an optional query string parameter 'name' to the 'name' argument:

    class EmployeeController extends ResourceController {
      @Operation.get()
      Future<Response> getEmployees({@Bind.query("name") String name}) async {
        if (name == null) {
          return Response.ok(employees);
        }

        return Response.ok(employees.where((e) => e.name == name).toList());
      }
    }

Bindings will automatically parse values into other types and validate that requests have the desired values. See Bind for all possible bindings and https://aqueduct.io/docs/http/resource_controller/ for more details.

To access the request directly, use request. Note that the Request.body of request will be decoded prior to invoking an operation method.

Inheritance
Implemented types
Implementers

Constructors

ResourceController()

Properties

acceptedContentTypes ↔ List<ContentType>
Types of content this ResourceController will accept. [...]
read / write
pathVariables → Map<String, String>
Parameters parsed from the URI of the request, if any exist. [...]
read-only
recycledState → BoundController
Returns state information that is reused across instances of this type. [...]
read-only, override
request Request
The request being processed by this ResourceController. [...]
read / write
responseContentType ↔ ContentType
The default content type of responses from this ResourceController. [...]
read / write
hashCode → int
The hash code for this object.
read-only, inherited
logger Logger
An instance of the 'aqueduct' logger.
read-only, inherited
nextController Controller
Receives requests that this controller does not respond to. [...]
read-only, inherited
policy CORSPolicy
The CORS policy of this controller.
read / write, inherited
runtimeType → Type
A representation of the runtime type of the object.
read-only, inherited

Methods

didDecodeRequestBody(RequestBody body) → void
Callback to indicate when a request body has been processed. [...]
documentComponents(APIDocumentContext context) → void
Tells this object to add its components to context. [...]
override
documentOperationDescription(APIDocumentContext context, Operation operation) → String
Returns a documented description for operation. [...]
documentOperationParameters(APIDocumentContext context, Operation operation) → List<APIParameter>
Returns a documented list of APIParameter for operation. [...]
@mustCallSuper
documentOperationRequestBody(APIDocumentContext context, Operation operation) APIRequestBody
Returns a documented request body for operation. [...]
documentOperationResponses(APIDocumentContext context, Operation operation) → Map<String, APIResponse>
Returns a map of possible responses for operation. [...]
documentOperations(APIDocumentContext context, String route, APIPath path) → Map<String, APIOperation>
Tells this object to return all APIOperations it handles. [...]
override
documentOperationSummary(APIDocumentContext context, Operation operation) → String
Returns a documented summary for operation. [...]
documentOperationTags(APIDocumentContext context, Operation operation) → List<String>
Returns a list of tags for operation. [...]
handle(Request request) → FutureOr<RequestOrResponse>
The primary request handling method of this object. [...]
override
restore(BoundController state) → void
Provides a new instance of this type with the recycledState of this type. [...]
override
willDecodeRequestBody(RequestBody body) → void
Callback invoked prior to decoding a request body. [...]
willProcessRequest(Request req) → FutureOr<RequestOrResponse>
Executed prior to handling a request, but after the request has been set. [...]
applyCORSHeadersIfNecessary(Request req, Response resp) → void
inherited
didAddToChannel() → void
Lifecycle callback, invoked after added to channel, but before any requests are served. [...]
inherited
documentPaths(APIDocumentContext context) → Map<String, APIPath>
Tells this object to return all APIPaths it handles. [...]
inherited
handleError(Request request, dynamic caughtValue, StackTrace trace) → Future
Sends an HTTP response for a request that yields an exception or error. [...]
inherited
Links a controller to the receiver to form a request channel. [...]
inherited
linkFunction(FutureOr<RequestOrResponse> handle(Request request)) Linkable
Links a function controller to the receiver to form a request channel. [...]
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed.
inherited
receive(Request req) → Future
Delivers req to this instance to be processed. [...]
inherited
toString() → String
Returns a string representation of this object.
inherited
willSendResponse(Response response) → void
Executed prior to Response being sent. [...]
inherited

Operators

operator ==(dynamic other) → bool
The equality operator.
inherited