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

Modifier and Type	Method and 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,
         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

IOException - if an I/O error occurs while reading the request or writing the response