Server Side Includes

Contents / New Features / Administrator Docs / Developer Docs / Index / Servlet Features

Server-Side Includes (SSI) give you the ability to embed instructions to the server inside an HTML document. The instructions are given using extensions to the HTML tag language. A special file extension, .shtml, signals the server that the document contains SSI directives. The server parses the document, executing SSI code in-line. Results are embedded in the document before it is served to the client.

Server-side includes can be as simple as embedding boilerplate text (such as copyright notices) or as powerful as calling executable programs (such as servlets). Traditionally, there have been two considerations for web administrators in allowing server-side includes: security and performance. The security issue usually centers around whether you want document providers issuing executables on the server. The performance issue focuses on the impact of having a heavily loaded server parsing documents prior to serving them.

Standard Server-Side Include tags

The National Center for Supercomputing Applications (NCSA) format for SSI directives is a SGML/HTML comment. If, for any reason, a document containing SSI directives is served to the client unparsed, the comment format means the directive's coding will not be visible. Directives have the following format:

<--#command tag1="value1" -->

Notes:
Most commands take only one tag at a time.
There should be no spaces between the <-- and the #.

The set of standard commands are:

config

Controls various aspects of the file parsing process. Tags include:

errmsg: Specifies what message is sent to the client if an error occurs while parsing the document. It takes a quoted string.
sizefmt: Displays file size in either byte-only format (bytes) or an abbreviated format of megabytes, kilobytes, and bytes (abbrev).
timefmt: Displays the date in requested order.

For example:

include

Inserts a file into the document being served. The included file is subject to the normal access control restrictions. Available tags include:

virtual: Instructs the server to append the directory specified by the virtual tag to the document directory when locating the file.
file: When used with virtual, the file tag simply specifies the name of the file. When used alone, it specifies the path and name of the file relative to the current directory (the string "../" cannot be used).

For example:

echo

Outputs the value of the requested variable. Sizes or times are provided according to the setting of the config command above. It has one tag:

var: Name of the variable whose value you wish to echo.

For example:

fsize

Returns the size of the specified file. Again, the config command settings control the output format of the value. It has the same tags as the include command:

virtual: Instructs the server to append that directory to the document directory when locating the file.
file: Informs the server that the path given for the file is relative to the current directory (the string "../" cannot be used.)

For example,

flastmod

Returns the date when the specified file was last modified. It has the same tags as the include command:

virtual: Instructs the server to append that directory to the document directory when locating the file.
file: Informs the server that the path given for the file is relative to the current directory (the string "../" cannot be used.)

For example:

exec

Invokes the specified CGI or shell command script. It has two tags:

cmd: Causes the server to execute the script using /bin/sh.
cgi: Tells the server to run the specified script as a CGI script.

For example:

For more information on NCSA Server-Side Includes, see their on-line tutorial.

Server Side Include Tags for Servlets

The Java^TM Web Server^TM provides support for both standard and servlet-specific SSI commands. The servlet-specific SSI commands provide a convenient way to load and invoke servlets. Both local and remote servlets can be used in this manner.

The syntax of a SSI tag for inclusion of servlets differs from the NCSA syntax discussed above but is very similar to the applet tag. For example:

<servlet code=DateServlet.class codebase=http://blitz/ initParam1=val1 /
initParam2=val2>
<param name=serviceParam1 value=val3>
<param name=serviceParam2 value=val4>
.
.
</servlet>

The code is the name of the class file that is to be loaded. The codebase parameter is optional, if present it could refer to a remote location for the servlet. The rest of the line in the first servlet tag refers to the init parameters for the servlet. A list of name-value pairs can also be specified for request parameters before the closing /servlet tag.

In the example presented above, the contents of the file up to the servlet tag would be sent to the client unmodified. Then the DateServlet will be loaded from http://blitz and invoked with the appropriate init and request parameters. The output of the DateServlet is embedded into the response. The contents of the file after the ending servlet tag is then appended unmodified.

Files Searched for SSI

As mentioned earlier, only files with a "*.shtml" extension are searched for SSI tags. This is the default setting and can be changed using the Administration Tool.

Connect to Administration Tool, by entering:
Login by entering your username and password.
Select the HTTP service of the desired Web Server (for instance, the Web Service of the Java Web Server), then click Manage.
Click Setup and then select Servlet Aliases.
You will see that all *.shtml files are mapped to ssinclude. Modify the files or directories to be mapped to ssinclude as desired.

Top

java-server-feedback@java.sun.com