Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to Web Applications

> ## Chapter 7
> Using Server-Parsed HTML

> HTML files can contain tags that are executed on the server. In addition to supporting the standard server-side tags, Sun Java System Application Server 7 allows you to embed servlets and define your own server-side tags.

> You can create custom server-parsed HTML tags. For more information, see the Sun Java System Application Server NSAPI Developer's Guide.

> For security, server-parsed HTML tags depend on the server’s security configuration. For more information, see “Security for SHTML and CGI” on page 90 and the Sun Java System Application Server Administrator's Guide to Security.

> This chapter has the following sections:

> - Server-Side HTML and J2EE Web Applications
> - Enabling Server-Side HTML
> - Using Server-Side HTML Commands
> - Embedding Servlets
> - Time Formats

> ##

> Server-Side HTML and J2EE Web Applications

> In Sun Java System Application Server, server-parsed HTML cannot interoperate with J2EE web applications. Specifically:

> - Do not place server-parsed HTML within web application context roots.
> - Do not include the output of server-parsed HTML in servlets or JSPs.
> - Do not forward requests to server-parsed HTML from servlets or JSPs.
> - You cannot apply J2EE security-constraint and filter-mapping features to server-parsed HTML.

> ##

> Enabling Server-Side HTML

> To enable server-side HTML:

> 1. Open the HTTP Server component under your server instance in the Administration interface.
> 2. Go to the Virtual Servers page.
> 3. Click on the name of the virtual server for which you are enabling server-side HTML.
> 4. Click on the HTTP/HTML tab.
> 5. Click on the Parse HTML option.
> 6. Choose a resource for which the server will parse HTML.

> Choose the virtual server or a specific directory within the virtual server.

> If you choose a directory, the server will parse HTML only when the server receives a URL for that directory or any file in that directory.

> 7. Choose whether to activate server-parsed HTML.

> You can activate for HTML files but not the exec tag, or for HTML files and the exec tag, which allows HTML files to execute other programs on the server.

> 8. Choose which files to parse.

> You can choose whether to parse only files with the .shtml extension, or all HTML files, which slows performance. If you are using UNIX, you can also choose to parse UNIX files with the execute permission turned on, though that can be unreliable.

> 9. Click on the OK button.
> 10. Go to the server instance page and select the Apply Changes button.

> When you activate parsing, you need to be sure that the following directives are added to your init.conf file (note that native threads are turned off):

> Init funcs="shtml_init,shtml_send" shlib="install _dir/lib/libShtml.so" NativeThread="no" fn="load-modules"

> Note that you must set NativeThread="no" for Sun Java System Application Server 7. In addition, these functions now originate from libShtml.so, which is located in install_dir/lib.

> In addition, be sure that the following directive is added to your obj.conf file:

> <Object name="default">
> ...
> ...
> Service fn="shtml_send" type="magnus-internal/parsed-html" method="(GET|HEAD)"
> ...
> </Object>

> ##

> Using Server-Side HTML Commands

> This section describes the HTML commands for including server-parsed tags in HTML files. These commands are embedded into HTML files, which are processed by the obj.conf file’s parse-html function.

> The server replaces each command with data determined by the command and its attributes. The format for a command is:

> <!--#command attribute1 attribute2 <Body>... -->

> The format for each attribute is a name-value pair such as:

> name="value"

> Commands and attribute names should be in lower case.

> The commands are “hidden” within HTML comments so they are ignored if not parsed by the server. The standard server-side commands are:

> - config
> - include
> - echo
> - fsize
> - flastmod
> - exec

> ### config

> The config command initializes the format for other commands.

> - The errmsg attribute defines a message sent to the client when an error occurs while parsing the file. This error is also logged in the server log file.
> - The timefmt attribute determines the format of the date for the flastmod command. It uses the same format characters as the util_strftime function. The default time format is: "%A, %d-%b-%y %T".

> Refer to Time Formats for details about time formats.

> - The sizefmt attribute determines the format of the file size for the fsize command. It can have one of these values:
> - bytes to report file size as a whole number in the format 12,345,678.
> - abbrev (the default) to report file size as a number of KB or MB.

> Example:

> <!--#config timefmt="%r %a %b %e, %Y" sizefmt="abbrev"-->

> This sets the date format to a value such as 08:23:15 AM Wed Apr 15, 1996, and the file size format to the number of KB or MB of characters used by the file.

> ### include

> The include command inserts a file into the parsed file. You can nest files by including another parsed file, which then includes another file, and so on. The client requesting the parsed document must also have access to the included file if your server uses access control for the directories where they reside.

> In Sun Java System Application Server 7, you can use the include command with the virtual attribute to include a CGI program file. You must also use an exec command to execute the CGI program.

> - The virtual attribute is the URI of a file on the server.
> - The file attribute is a relative path name from the current directory. It cannot contain elements such as ../ and it cannot be an absolute path.

> Example:

> <!--#include file="bottle.gif"-->

> ### echo

> The echo command inserts the value of an environment variable. The var attribute specifies the environment variable to insert. If the variable is not found, “(none)” is inserted. For a list of environment variables, see the section Environment Variables in Server-Side HTML Commands.

> Example:

> <!--#echo var="DATE_GMT"-->

> ### fsize

> The fsize command sends the size of a file. The attributes are the same as those for the include command (virtual and file). The file size format is determined by the sizefmt attribute in the config command.

> Example:

> <!--#fsize file="bottle.gif"-->

> ### flastmod

> The flastmod command prints the date a file was last modified. The attributes are the same as those for the include command (virtual and file). The date format is determined by the timefmt attribute in the config command.

> Example:

> <!--#flastmod file="bottle.gif"-->

> ### exec

> The exec command runs a shell command or CGI program.

> - The cmd attribute (UNIX only) runs a command using /bin/sh. You may include any special environment variables in the command.
> - The cgi attribute runs a CGI program and includes its output in the parsed file.

> Example:

> <!--#exec cgi="workit.pl"-->

> ### Environment Variables in Server-Side HTML Commands

> In addition to the normal set of environment variables used in CGI, you may include the following variables in your parsed commands:

> - DOCUMENT_NAME

> is the file name of the parsed file.

> - DOCUMENT_URI

> is the virtual path to the parsed file (for example, /shtml/test.shtml).

> - QUERY_STRING_UNESCAPED

> is the unescaped version of any search query the client sent with all shell-special characters escaped with the \ character.

> - DATE_LOCAL

> is the current date and local time.

> - DATE_GMT

> is the current date and time expressed in Greenwich Mean Time.

> - LAST_MODIFIED

> is the date the file was last modified.

> ##

> Embedding Servlets

> Sun Java System Application Server 7 supports the <SERVLET> tag as introduced by Java Web Server. This tag allows you to embed servlet output in an SHTML file. No configuration changes are necessary to enable this behavior. If SSI and servlets are both enabled, the <SERVLET> tag is enabled.

> The <SERVLET> tag syntax is slightly different from that of other SSI commands; it resembles the <APPLET> tag syntax:

> <servlet code=code>
> <param name=param1 value=v3>
> <param name=param2 value=v4>
> .
> .
> </servlet>

> The code parameter specifies the URI of the servlet, including the web application context root. This URI must match a url-pattern subelement of a servlet-mapping element in the J2EE deployment descriptor (web.xml).

> ##

> Time Formats

> The following table describes the format strings for dates and times used by server-parsed HTML.

> Table 7-1 Time Formats

> Symbol | Meaning
> --- | ---
> %a | Abbreviated weekday name (3 chars)
> %d | Day of month as decimal number (01-31)
> %S | Second as decimal number (00-59)
> %M | Minute as decimal number (00-59)
> %H | Hour in 24-hour format (00-23)
> %Y | Year with century, as decimal number, up to 2099
> %b | Abbreviated month name (3 chars)
> %h | Abbreviated month name (3 chars)
> %T | Time "HH:MM:SS"
> %X | Time "HH:MM:SS"
> %A | Full weekday name
> %B | Full month name
> %C | "%a %b %e %H:%M:%S %Y"
> %c | Date & time "%m/%d/%y %H:%M:%S"
> %D | Date "%m/%d/%y"
> %e | Day of month as decimal number (1-31) without leading zeros
> %I | Hour in 12-hour format (01-12)
> %j | Day of year as decimal number (001-366)
> %k | Hour in 24-hour format (0-23) without leading zeros
> %l | Hour in 12-hour format (1-12) without leading zeros
> %m | Month as decimal number (01-12)
> %n | line feed
> %p | A.M./P.M. indicator for 12-hour clock
> %R | Time "%H:%M"
> %r | Time "%I:%M:%S %p"
> %t | tab
> %U | Week of year as decimal number, with Sunday as first day of week (00-51)
> %w | Weekday as decimal number (0-6; Sunday is 0)
> %W | Week of year as decimal number, with Monday as first day of week (00-51)
> %x | Date "%m/%d/%y"
> %y | Year without century, as decimal number (00-99)
> %% | Percent sign

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.