From the Java EE tutorial:
If the resource is static, the
includemethod enables programmatic server-side includes.If the resource is a web component, the effect of the method is to send the request to the included web component, execute the web component, and then include the result of the execution in the response from the containing servlet.
I'm not quite sure what they mean by "programmatic server-side includes" and how those differ from the web component case.
I mean, regardless of the resource I include, I pass a request/response object tuple to it and get some side-effects that I may or may not communicate to the client, right?
Could somebody please elaborate on this?
You've omitted the heading and text preceding your quotation. These provide important context for the comments you're asking about:
Including Other Resources in the Response
It is often useful to include another web resource, such as banner content or copyright information, in the response returned from a web component. To include another resource, invoke the include method of a RequestDispatcher object:
include(request, response);
Thus, when the comments continue with
If the resource is static, the include method enables programmatic server-side includes.
they are characterizing the effect of the preceding code snippet, not introducing some new concept. A "programmatic server-side include" in this context is invoking the include() method of a RequestDispatcher() associated with a static resource. It has the effect of including the resource associated with the dispatcher, inline in the response being prepared. As such, this is "server-side" because it is all done by the server, transparently to the client, as opposed to the client having to make a separate request for the included resource.*
The distinction between the static and web component cases is about the resource associated with the RequestDispatcher on which that include() method is invoked -- i.e. what resource is to be included -- not about the component whose code contains the method invocation. A static resource is exactly a resource that can be identified by a URL that is not associated with a web component. Normally this means it corresponds to a file. The file content could be anything, but a common use is for it to comprise an HTML fragment, such as a header or footer shared by many web pages.
I mean, regardless of the resource I include, I pass a request/response object tuple to it and get some side-effects that I may or may not communicate to the client, right?
It's more accurate to view it as passing a request and response object to the RequestDispatcher. In the event that the dispatcher is associated with a static resource, no, the request and response objects are not presented to that resource (itself) because it has no mechanism for receiving or manipulating them. Instead, the servlet engine in which the code runs manipulates the response object as it decides is appropriate.
In the event that the target resource is a web component, yes, it will be able to read data from the provided request, manipulate the request and its context, and manipulate the provided response, all at its discretion. Generally, it cannot distinguish this case from the one in which it is accessed directly. But no, the component invoking include() has at best limited control over what is communicated to the client via that mechanism.
*For more information on the history of and inspiration for the "server-side includes" part of the term, consult Wikipedia.