Many server based web architectures use the mediator-view architecture, which relies on the ability of a server to delegate or "dispatch" a request to another resource. Request delegation is handled by the response object which can dispatch a request to static resources such as HTML pages or dynamic CSP code. This dispatching occurs by either "including" a page or "forwarding" the request to another page. The dispatched resource can access the current state of the request, the session, or the application/server object.
If you are familiar with JSP, you will see that we use a more simple approach. We bind the include and forward methods to the response object.
The response include method enables another resource to be included dynamically in the response to a client request. Included resources cannot modify the HTTP response headers; whatever is set by the calling resource will hold true. All attempts to set any header values will be ignored. If the included resource is a CSP, any objects that are bound to the request can be accessed by the included resource.
The forward method forwards the client request to another resource, such as a static HTML file or a CSP. The original resource can perform some preliminary work before sending the request to a resource that will provide the response. As with the include method, any objects that are bound to the request can be accessed by the forwarded resource. Note that the calling CSP/HttpPage/HttpDir service function should not write anything to the response prior to the forward action. Any data in the response buffer will be cleared. The resource forwarding the request can add or change any HTTP header, such as creating a session object, adding cookies, setting date headers, etc..
The include and forward methods can be used by a resource to completely hide the underlying architecture. Visitors will see the same URL, but the page will look different for each request.
One of the unique features of the include and forward methods is that one can use a relative path when including another resource. The virtual file system automatically combines directory branches with duplicate names so that the two directory structures look like one. It is possible to include, for example, a HTML file in a duplicate directory that may be in a HttpResRdr instance using a relative path.
Note that HttpResponse::forward and HttpResponse::sendRedirect work very differently. The sendRedirect method instructs the server to send an HTTP 302 message back to the client, instructing the client to access a new resource at the specified URL. The initial request object that was accessed by the original CSP/HttpPage/HttpDir terminates when that page completes its execution (that is, at the end of the service method), so the new resource loses the initial request state.
The include and forward method can include any type of file, but most files can also be directly fetched by the visitor. You should use server side include files if you want to protect the pages form being directly accessed by a visitor. Please see Server Side Include Files for more information.