////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////


== request



=== Purpose


The `request` object is an instance of the Servlet API's {jakartaee}jakarta/servlet/http/HttpServletRequest.html[HttpServletRequest] interface


=== Examples


[source,groovy]
----
class BookController {
    def list() {
        log.info "User agent: " + request.getHeader("User-Agent")

        render(view: actionName)
    }
}
----


=== Description


The {jakartaee}jakarta/servlet/http/HttpServletRequest.html[HttpServletRequest] class is useful for, amongst other things, obtaining request headers, storing request scoped attributes and establishing information about the client. Refer to the Servlet API's javadocs for further information.

Grails enhances the `HttpServletRequest` instance by adding the following new properties and methods:

* `XML` - An instance of `XmlSlurper`'s {groovyapi}groovy/xml/slurpersupport/GPathResult.html][GPathResult] class that allows parsing of an incoming XML request (useful for REST).
* `JSON` - An instance of Grails' link:{apiFromRef}org/grails/web/json/JSONObject.html[JSONObject] class that allows parsing of an incoming JSON request (useful for JSON based REST).
* `forwardURI` - Useful for obtaining the current request URI since the `request` object's `requestURI` property returns the original URI, not the matched one.
* `isRedirected()` - Returns `true` if a redirect has been issued for this request (Grails 2+).
* `get` - Returns true if the current request is an HTTP `GET` request.
* `post` - Returns true if the current request is an HTTP `POST` request.
* `each` - Implementation of Groovy's `each` method for iterating over request attributes.
* `find` - Implementation of Groovy's default `find` method for searching request attributes.
* `findAll` - Implementation of Groovy's default `findAll` method for searching request attributes.
* `format` - The request format, used for link:{guidePath}theWebLayer.html#contentNegotiation[Content Negotiation].
* `withFormat(Closure)` - The withFormat method, used for link:{guidePath}theWebLayer.html#contentNegotiation[Content Negotiation].
* `xhr` - Returns `true` if the current request is an Ajax request.

The `XML` and `JSON` properties are useful for XML APIs and can be used to parse incoming XML or JSON packages. For example given a request body of:

[source,xml]
----
<book>
   <title>The Stand</title>
</book>
----

This can be parsed easily:

[source,groovy]
----
def title = request.XML?.title
render "The Title is $title"
----

Request attributes which are normally accessible from the {jakartaee}jakarta/servlet/ServletRequest.html#getAttribute(java/lang/String)[getAttribute] can also be indexed into using the array index operator or de-reference operator:

[source,groovy]
----
def user = request['user']

request['user'] = 'John'

assert 'John' == request.user
----
