Routing

class Routing : Route

Root routing node for an Application

Parameters

application - is an instance of Application for this routing

Types

Feature

companion object Feature : 
    ApplicationFeature<Application, Routing, Routing>

Installable feature for Routing

Constructors

<init>

Routing(application: Application)

Root routing node for an Application

Properties

application

val application: Application

is an instance of Application for this routing

Inherited Properties

children

val children: List<Route>

List of child routes for this node

parent

val parent: Route?

is a parent node in the tree, or null for root node

selector

val selector: RouteSelector

is an instance of RouteSelector for this node

Functions

trace

fun trace(block: (RoutingResolveTrace) -> Unit): Unit

Register a route resolution trace function. See https://ktor.io/servers/features/routing.html#tracing for details

Inherited Functions

afterIntercepted

open fun afterIntercepted(): Unit

Invoked after an interceptor has been installed

createChild

fun createChild(selector: RouteSelector): Route

Creates a child node in this node with a given selector or returns an existing one with the same selector

handle

fun handle(
    handler: PipelineInterceptor<Unit, ApplicationCall>
): Unit

Installs a handler into this route which will be called when the route is selected for a call

invoke

operator fun invoke(body: Route.() -> Unit): Unit

Allows using route instance for building additional routes

toString

open fun toString(): String

Companion Object Properties

RoutingCallFinished

val RoutingCallFinished: EventDefinition<RoutingApplicationCall>

Event definition for when a routing-based call processing finished

RoutingCallStarted

val RoutingCallStarted: EventDefinition<RoutingApplicationCall>

Event definition for when a routing-based call processing starts

key

Unique key that identifies a feature

Companion Object Functions

install

fun install(
    pipeline: Application,
    configure: Routing.() -> Unit
): Routing

Feature installation script

Extension Properties

application

val Route.application: Application

Gets an Application for this Route by scanning the hierarchy to the root

conversionService

Lookup for a conversion service. Returns the default one if the feature wasn’t installed

staticBasePackage

var Route.staticBasePackage: String?

Base package for relative resources calculations for static content

staticRootFolder

var Route.staticRootFolder: File?

Base folder for relative files calculations for static content

Extension Functions

accept

fun Route.accept(
    contentType: ContentType,
    build: Route.() -> Unit
): Route

Builds a route to match requests with HttpHeaders.Accept header matching specified contentType

authenticate

fun Route.authenticate(
    vararg configurations: String? = arrayOf<String?>(null),
    optional: Boolean = false,
    build: Route.() -> Unit
): Route

Creates an authentication route that does handle authentication by the specified providers referred by configurations names. null could be used to point to the default provider and could be also mixed with other provider names. Other routes, handlers and interceptors could be nested into this node

contentType

fun Route.contentType(
    contentType: ContentType,
    build: Route.() -> Unit
): Route

Builds a route to match requests with HttpHeaders.ContentType header matching specified contentType

createRouteFromPath

fun Route.createRouteFromPath(path: String): Route

Create a routing entry for specified path

default

fun Route.default(localPath: String): Unit
fun Route.default(localPath: File): Unit

Specifies localPath as a default file to serve when folder is requested

defaultResource

fun Route.defaultResource(
    resource: String,
    resourcePackage: String? = null
): Unit

Specifies resource as a default resources to serve when folder is requested

delete

fun <T : Any> Route.delete(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Route

Registers a typed handler body for a DELETE location defined by class T.

delete

fun Route.delete(
    path: String,
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match DELETE requests with specified path

fun Route.delete(
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match DELETE requests

execute

suspend fun <TContext : Any> Pipeline<Unit, TContext>.execute(
    context: TContext
): Unit

Executes this pipeline

file

fun Route.file(
    remotePath: String,
    localPath: String = remotePath
): Unit
fun Route.file(remotePath: String, localPath: File): Unit

Sets up routing to serve localPath file as remotePath

files

fun Route.files(folder: String): Unit
fun Route.files(folder: File): Unit

Sets up routing to serve all files from folder

get

fun <T : Any> Route.get(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Route

Registers a typed handler body for a GET location defined by class T.

get

fun Route.get(
    path: String,
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match GET requests with specified path

fun Route.get(
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match GET requests

handle

fun <T : Any> Route.handle(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Unit

Registers a handler body for a location defined by class T.

fun <T : Any> Route.handle(
    dataClass: KClass<T>,
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Unit

Registers a handler body for a location defined by class dataClass.

head

fun <T : Any> Route.head(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Route

Registers a typed handler body for a HEAD location defined by class T.

head

fun Route.head(
    path: String,
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match HEAD requests with specified path

fun Route.head(
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match HEAD requests

header

fun Route.header(
    name: String,
    value: String,
    build: Route.() -> Unit
): Route

Builds a route to match header with specified name and value

host

fun Route.host(
    host: String,
    port: Int = 0,
    build: Route.() -> Unit
): Route
fun Route.host(
    hostPattern: Regex,
    port: Int = 0,
    build: Route.() -> Unit
): Route
fun Route.host(
    hosts: List<String>,
    ports: List<Int> = emptyList(),
    build: Route.() -> Unit
): Route
fun Route.host(
    hosts: List<String>,
    hostPatterns: List<Regex>,
    ports: List<Int> = emptyList(),
    build: Route.() -> Unit
): Route

Create a route to match request host and port. There are no any host resolutions/transformations applied to a host: a request host is treated as a string.

intercept

fun <TSubject : Any, TContext : Any> Pipeline<*, TContext>.intercept(
    phase: PipelinePhase,
    block: suspend PipelineContext<TSubject, TContext>.(TSubject) -> Unit
): Unit

Intercepts an untyped pipeline when the subject is of the given type

location

fun <T : Any> Route.location(body: Route.() -> Unit): Route

Registers a route body for a location defined by class T.

fun <T : Any> Route.location(
    data: KClass<T>,
    body: Route.() -> Unit
): Route

Registers a route body for a location defined by class data.

method

fun Route.method(
    method: HttpMethod,
    body: Route.() -> Unit
): Route

Builds a route to match specified method

optionalParam

fun Route.optionalParam(
    name: String,
    build: Route.() -> Unit
): Route

Builds a route to optionally capture parameter with specified name, if it exists

options

fun <T : Any> Route.options(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Route

Registers a typed handler body for a OPTIONS location defined by class T.

options

fun Route.options(
    path: String,
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match OPTIONS requests with specified path

fun Route.options(
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match OPTIONS requests

param

fun Route.param(
    name: String,
    value: String,
    build: Route.() -> Unit
): Route

Builds a route to match parameter with specified name and value

fun Route.param(name: String, build: Route.() -> Unit): Route

Builds a route to match parameter with specified name and capture its value

patch

fun <T : Any> Route.patch(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Route

Registers a typed handler body for a PATCH location defined by class T.

patch

fun Route.patch(
    path: String,
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match PATCH requests with specified path

fun Route.patch(
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match PATCH requests

port

fun Route.port(
    vararg ports: Int,
    build: Route.() -> Unit
): Route

Create a route to match request port.

post

fun <T : Any> Route.post(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Route

Registers a typed handler body for a POST location defined by class T.

post

fun Route.post(
    path: String,
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match POST requests with specified path

fun <R : Any> Route.post(
    path: String,
    body: suspend PipelineContext<Unit, ApplicationCall>.(R) -> Unit
): Route

Builds a route to match POST requests with specified path receiving request body content of type R

fun Route.post(
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match POST requests

put

fun <T : Any> Route.put(
    body: suspend PipelineContext<Unit, ApplicationCall>.(T) -> Unit
): Route

Registers a typed handler body for a PUT location defined by class T.

put

fun Route.put(
    path: String,
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match PUT requests with specified path

fun Route.put(
    body: PipelineInterceptor<Unit, ApplicationCall>
): Route

Builds a route to match PUT requests

resource

fun Route.resource(
    remotePath: String,
    resource: String = remotePath,
    resourcePackage: String? = null
): Unit

Sets up routing to serve resource as remotePath in resourcePackage

resources

fun Route.resources(resourcePackage: String? = null): Unit

Sets up routing to serve all resources in resourcePackage

route

fun Route.route(path: String, build: Route.() -> Unit): Route

Builds a route to match specified path

fun Route.route(
    path: String,
    method: HttpMethod,
    build: Route.() -> Unit
): Route

Builds a route to match specified method and path

static

fun Route.static(configure: Route.() -> Unit): Route

Create a block for static content

fun Route.static(
    remotePath: String,
    configure: Route.() -> Unit
): Route

Create a block for static content at specified remotePath

webResources

fun Route.webResources(
    subPath: String = "/",
    configure: WebResourcesConfig.() -> Unit = {}
): Unit

Serve web resources (usually a directory named webapp containing WEB-INF/web.xml). Note that WEB-INF directory itself is not served by default.

webSocket

fun Route.webSocket(
    protocol: String? = null,
    handler: suspend DefaultWebSocketServerSession.() -> Unit
): Unit

Bind websocket at the current route optionally checking for websocket protocol (ignored if null) Requires WebSockets feature to be installed first

fun Route.webSocket(
    path: String,
    protocol: String? = null,
    handler: suspend DefaultWebSocketServerSession.() -> Unit
): Unit

Bind websocket at the current route + path optionally checking for websocket protocol (ignored if null) Requires WebSockets feature to be installed first

webSocketRaw

fun Route.webSocketRaw(
    path: String,
    protocol: String? = null,
    handler: suspend WebSocketServerSession.() -> Unit
): Unit

Bind RAW websocket at the current route + path optionally checking for websocket protocol (ignored if null) Requires WebSockets feature to be installed first

fun Route.webSocketRaw(
    protocol: String? = null,
    handler: suspend WebSocketServerSession.() -> Unit
): Unit

Bind RAW websocket at the current route optionally checking for websocket protocol (ignored if null) Requires WebSockets feature to be installed first