Package oracle.dbtools.plugin.api.servlet

## Interface ForwardedRequests

-     public interface ForwardedRequests

  Provides services for servlets that wish to delegate the generation of a response to another service/servlet.

  It is common in RESTful APIs that update operations return the updated representation of the resource.

  ### Returning the representation of a newly created resource

  If a `POST` operation leads to the creation of a new resource then the response should include a `Location` header indicating the location of the new resource. It may also be convenient for the response to include the representation of the resource. To ensure the representation is cacheable the response should include a `Content-Location` header indicating that the response is an equivalent representation of the resource that would be obtained by performing a `GET` operation on the specified URI.

  A servlet can use the `ForwardedRequests` to automate this process as follows:

       @Provides
       class SomeServlet extends HttpServlet {
         @Inject
         SomeServlet(ForwardedRequests requests) {
           this.requests = requests;
         }

         protected void doPost(HttpServletRequest request,HttpServletResponse response) throws ServletException, IOException {
           final String newResourceLocation = ...; // create and store a new resource, producing it's location
           response.setLocation(newResourceLocation); // Indicate location of created resource
           response.setStatus(201); // 'Created' status
           requests.get(request,response); // generate a response that includes the current representation of the created resource
        }

         private final ForwardedRequests requests;
       }

  ### Returning the representation of an updated resource

  If a `PUT` operation updates the current representation of a resource then it may be convenient for the response to include the updated representation. To ensure the representation is cacheable the response should include a `Content-Location` header indicating that the response is an equivalent representation of the resource that would be obtained by performing a `GET` operation on the specified URI.

  A servlet can use the `ForwardedRequests` to automate this process as follows:

       @Provides
       class SomeServlet extends HttpServlet {
         @Inject
         SomeServlet(ForwardedRequests requests) {
           this.requests = requests;
         }

         protected void doPut(HttpServletRequest request,HttpServletResponse response) throws ServletException, IOException {
           ... ; // process the update request
           requests.get(request,response); // generate a representation of the resource at the requests location
        }

         private final ForwardedRequests requests;
       }

  Author:
    cdivilly

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `get​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` | Delegate the generation of a response by performing a GET operation on the specified resource.

- - ### Method Detail

    - #### get

          void get​(javax.servlet.http.HttpServletRequest request,
                   javax.servlet.http.HttpServletResponse response)
            throws javax.servlet.ServletException,
                   java.io.IOException

      Delegate the generation of a response by performing a GET operation on the specified resource. The location of the resource to `GET` is specified by either:
      - The value of the `Location` header in the `response` parameter if such a header exists. The value MUST must be located within the context root of this request (This prevents this service being used for open-redirect based attacks). If the location falls outside the context root then a `500 Internal Server Error` is raised.
      - If a `Location` header does not exist then the location of the `request` is used.
      The status code of the generated response will be the value of the status code set on the `response` parameter.
      Parameters:
        `request` - The servlet request that has been processed
        `response` - The servlet response object where the output of the `GET` operation will be written.
      Throws:
        `javax.servlet.ServletException` - if the request cannot be handled
        `java.io.IOException` - if an I/O error occurs while reading the request or writing the response