Package groovy.servlet

# Class ServletBinding

java.lang.Object
groovy.lang.GroovyObjectSupport
groovy.lang.Binding
groovy.servlet.ServletBinding

All Implemented Interfaces:
  `GroovyObject`

public class ServletBinding extends Binding
Servlet-specific binding extension to lazy load the writer or the output stream from the response.

### Eager variables

- `"request"` : the `HttpServletRequest` object
- `"response"` : the `HttpServletRequest` object
- `"context"` : the `ServletContext` object
- `"application"` : same as context
- `"session"` : shorthand for `request.getSession(`false`)` - can be null!
- `"params"` : map of all form parameters - can be empty
- `"headers"` : map of all `request` header fields

### Lazy variables

- `"out"` : `response.getWriter()`
- `"sout"` : `response.getOutputStream()`
- `"html"` : `new MarkupBuilder(response.getWriter())` - `expandEmptyElements` flag is set to true
- `"json"` : `new JsonBuilder()`

As per the Servlet specification, a call to `response.getWriter()` should not be done if a call to `response.getOutputStream()` has already occurred or the other way around. You may wonder then how the above lazy variables can possibly be provided - since setting them up would involve calling both of the above methods. The trick is catered for behind the scenes using lazy variables. Lazy bound variables can be requested without side effects; under the covers the writer and stream are wrapped. That means `response.getWriter()` is never directly called until some output is done using 'out' or 'html'. Once a write method call is done using either of these variable, then an attempt to write using 'sout' will cause an `IllegalStateException`. Similarly, if a write method call on 'sout' has been done already, then any further write method call on 'out' or 'html' will cause an `IllegalStateException`.

### Reserved internal variable names (see "Methods" below)

- `"forward"`
- `"include"`
- `"redirect"`

If `response.getWriter()` is called directly (without using out), then a write method call on 'sout' will not cause the `IllegalStateException`, but it will still be invalid. It is the responsibility of the user of this class to not mix these different usage styles. The same applies to calling `response.getOutputStream()` and using 'out' or 'html'.

### Methods

- `"forward(String path)"` : `request.getRequestDispatcher(path).forward(request, response)`
- `"include(String path)"` : `request.getRequestDispatcher(path).include(request, response)`
- `"redirect(String location)"` : `response.sendRedirect(location)`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ServletBinding(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, jakarta.servlet.ServletContext context)`
  Initializes a servlet binding.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `forward(String path)`
  Forwards the current request to another resource using the same request and response.
  `Object`
  `getVariable(String name)`
  `Map`
  `getVariables()`
  Returns the current binding variables after initializing the lazy servlet helpers.
  `void`
  `include(String path)`
  Includes another resource in the current response.
  `void`
  `redirect(String location)`
  Sends a redirect response to the supplied location.
  `void`
  `setVariable(String name, Object value)`
  Binds a servlet variable while protecting the reserved lazy helper names.

  ### Methods inherited from class groovy.lang.Binding

  `getProperty, hasVariable, removeVariable, setProperty`

  ### Methods inherited from class groovy.lang.GroovyObjectSupport

  `getMetaClass, setMetaClass`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface groovy.lang.GroovyObject

  `invokeMethod`

- ## Constructor Details

  - ### ServletBinding

    public ServletBinding(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, jakarta.servlet.ServletContext context)
    Initializes a servlet binding.
    Parameters:
      `request` - the HttpServletRequest object
      `response` - the HttpServletRequest object
      `context` - the ServletContext object

- ## Method Details

  - ### setVariable

    public void setVariable(String name, Object value)
    Binds a servlet variable while protecting the reserved lazy helper names.
    Overrides:
      `setVariable` in class `Binding`
    Parameters:
      `name` - the variable name to bind
      `value` - the value to expose through the binding

  - ### getVariables

    public Map getVariables()
    Returns the current binding variables after initializing the lazy servlet helpers.
    Overrides:
      `getVariables` in class `Binding`
    Returns:
      the binding variables map

  - ### getVariable

    public Object getVariable(String name)
    Overrides:
      `getVariable` in class `Binding`
    Parameters:
      `name` - the name of the variable to lookup
    Returns:
      a writer, an output stream, a markup builder or another requested object

  - ### forward

    public void forward(String path) throws jakarta.servlet.ServletException, IOException
    Forwards the current request to another resource using the same request and response.
    Parameters:
      `path` - the dispatcher path to forward to
    Throws:
      `jakarta.servlet.ServletException` - if the target resource fails
      `IOException` - if request dispatching fails

  - ### include

    public void include(String path) throws jakarta.servlet.ServletException, IOException
    Includes another resource in the current response.
    Parameters:
      `path` - the dispatcher path to include
    Throws:
      `jakarta.servlet.ServletException` - if the target resource fails
      `IOException` - if request dispatching fails

  - ### redirect

    public void redirect(String location) throws IOException
    Sends a redirect response to the supplied location.
    Parameters:
      `location` - the redirect target
    Throws:
      `IOException` - if the redirect cannot be sent