| web.xml <context-param>s | ||
|---|---|---|
 | Server Administration |  |
| web.xml <context-param>s | ||
|---|---|---|
| | Server Administration | |
Mr. XML Publisher provides many web.xml <context-param> elements that represent key-value pairs used for controlling its behavior. Their values must adhere to pre-set rules specific to each.
Command arrays, <context-param> elements whose names begin with "COMMAND", are discussed in COMMAND Arrays , and <context-param> elements whose names begin with "PULL_XXX_ON_STARTUP", where "XXX" is the name of the data puller, are discussed in PULL_XXX_ON_STARTUP.
Mr. XML Publisher <context-param>s related to general server management are those that affect the servicing of all requests. They cannot be turned on or off for specific formats or individual users.
Table 1 lists general server management <context-param>s. Details for each are in the following sections.
| <context-param> | Type and Default |
|---|---|
| log4j-init-file | Type — Text string, a path relative to the context path of the Mr. XML Publisher ServletContext. Default — None; however, it is virtually a requirement that this value be set to "/WEB-INF/log4j.properties". |
| PERFORMANCE_TIMING | Type — true/false Default — false |
| ENVIRONMENT | Type — Delimited text string consisting of name=value pairs. The delimiter must be "!!!!". Default — none |
| ATTEMPT_INHERIT_ENVIRONMENT | Type — true/false Default — false |
| tempDirUnix | Type — Text string, a fully-qualified path. Default — /tmp/ |
| tempDirWindows | Type — Text string, a fully-qualified path. Default — C:\TEMP\ |
| DEFAULT_SIZE_THRESHOLD | Type — integer Default — 33554432. Number of bytes. |
| MAX_CONCURRENT_REQUESTS | Type — integer Default — 16. Unless your server has at least 16 CPU cores, you should adjust this number downward. |
| MAX_ALLOWED_PROCESS_TIME | Type — integer Default — 120. Time in seconds. |
Table 1. General Server Management <context-param>'s
Mr. XML Publisher uses the Apache Software Foundation's log4j logging software to log most application-generated messages[12] (http://logging.apache.org/log4j/1.2/index.html). In the log4j-init-file <context-param>, you must specify a location and name for the log4j properties file, typically named "log4j.properties." The log4j.properties file instructs log4j as to what log level to use ("info", "warn", "error", or "debug") and all other log4j details. For more details concerning logging in Mr. XML Publisher, see Logging.
If the PERFORMANCE_TIMING <context-param> is set to "true", log entries are produced for performance timing and sent to wherever your web container is configured to send messages sent to System.out. Performance timing log entries include various measurements for the time taken to service each formatting request, including times taken to complete each required data pull. Performance timing log entries are sent to System.out instead of the log4j log file so as to eliminate the log4j overhead and produce more accurate results. Performance timing statistics do not include the time taken for the server to receive a user's upload. However, performance timing statistics do include the time taken on the server to completely finish streaming a user's download. Because of unpredictable networks it is unlikely to represent an exact measurement of what the user experiences.
The ENVIRONMENT <context-param>'s value contains the default
ENVIRONMENT variable name-value pairs passed to external subprocesses
whenever the ATTEMPT_INHERIT_ENVIRONMENT <context-param> is set to
"false". Each name-value pair is a member of the delimited text string
in the ENVIRONMENT <context-param>'s <param-value> element.
The delimiter must be "!!!!". If the ATTEMPT_INHERIT_ENVIRONMENT
<context-param> is set to "true", the value of this
<context-param> is ignored and external subprocesses are run by
default in the ENVIRONMENT inherited from the owner of the web
container process. In Linux/Unix, consider running individual commands
using the env command.
Example 24 shows an ENVIRONMENT <context-param> element as might be used in Windows.
The ATTEMPT_INHERIT_ENVIRONMENT <context-param>'s value
determines whether external subprocesses are run in the ENVIRONMENT
inherited from the owner of the web container process. If "true", the
value of the ENVIRONMENT <context-param> in Mr. XML Publisher's
web.xml file is ignored. If the ATTEMPT_INHERIT_ENVIRONMENT
<context-param>'s value is "false", external subprocesses are run
using the value of the ENVIRONMENT <context-param>. Thus, if you
set this value to "false", you must either make sure that the
ENVIRONMENT <context-param>'s <param-value> is properly set,
or use env commands to precisely
control the ENVIRONMENT.
The tempDirUnix <context-param>'s value represents the full path to a temporary directory on Linux/Unix. Uploaded projects are unpacked and processed into individual temporary directories created within this directory. Optionally, this directory might be located on a RAM disk.
The tempDirWindows <context-param>'s value represents the full path to a temporary directory on Windows. Uploaded projects are unpacked and processed into individual temporary directories created within this directory. Optionally, this directory might be located on a RAM disk.
The DEFAULT_SIZE_THRESHOLD <context-param>'s value represents an uploaded project's file size limit (measured in bytes) beyond which projects are written to disk before unpacking. This is not the same as the MAX_UPLOAD_FILE_SIZE <context-param>, which limits the size of project uploads. The DEFAULT_SIZE_THRESHOLD <context-param>'s value just determines whether to write the uploaded project to disk before unpacking it. Whenever possible, Mr. XML Publisher processes an upload in memory. However, depending on how much memory your system has, prior to unpacking you might want to write a project to disk. The default value is reasonable for most systems.
The MAX_CONCURRENT_REQUESTS <context-param>'s value represents a limit to the maximum number of allowed concurrent requests.[13] Typically, some of the commands in each format's command array are demanding, heavy-weight processes. Even if the operating system splits these processes into multiple threads, if you allow more concurrent requests than your server has CPU cores, your server could badly bog down. Formatting XML is resource intensive, comparable to source code compilation. The default value, 16, may be too high. Set it to a number less than or equal to the number of CPU cores in your server. Hyperthreading counts as 1/2 CPU.
The MAX_ALLOWED_PROCESS_TIME <context-param>'s value represents an execution time limit for any single individual command in a command array. It does not represent the time allowed to fully service a request. It represents an execution time limit beyond which an individual command will be killed and the servicing of its request aborted, thus preventing runaway processes. If your server is formatting large projects, the default, 120 seconds, may be too low. This will likely be the case when producing large PDF files (greater than 200 pages), or formatting any XML projects that use large graphic files or many graphics. However, a reasonable value depends on many factors, including your server's CPU speed, available memory, memory speed, bus speeds, and whether you are using a RAM disk, etc. Limiting process time also helps tighten security by preventing exploits that rely on overloading a server's processing capabilities.
Table 2 lists <context-param>s related to security and file checks. Details for each are in the sections that follow.
| <context-param> | Type and Default |
|---|---|
| SET_PERMISSIONS | Type — true/false Default — false |
| UNIX_CHOWN_COMMAND | Type — Text string, Linux/Unix command to set file ownership after unpacking a project. Default — none |
| WINDOWS_CACLS_COMMAND | Type — Text string, Windows command to set file ownership after unpacking a project. Default — echo y| C:\WINNT\system32\CACLS.exe
|
| WINDOWS_CACLS_PERMS | Type — Text string, switches and options to be used with the WINDOWS_CACLS_COMMAND <context-param>. Default — /T /G everyone:R
|
| PERFORM_MIME_TYPE_CHECKS | Type — true/false Default — None. An explicit value is required. |
| PERFORM_FILE_EXTENSION_CHECKS | Type — true/false Default — None. An explicit value is required. |
| ALLOW_UNKNOWN_MIME_TYPES | Type — true/false Default — false |
| ALLOWED_FILE_EXTENSIONS | Type — Text string, a comma-delimited string containing allowed filename extensions. Default — None. If the PERFORM_FILE_EXTENSION_CHECKS <context-param> is set to true, an explicit value is required, but not otherwise. |
| ALLOWED_MIME_TYPES | Type — Text string, a comma-delimited string containing allowed mime-types. Default — None. If the PERFORM_MIME_TYPE_CHECKS <context-param> is set to true, an explicit value is required, but not otherwise. |
| SKIP_FILE_CHECKS | Type — true/false Default — false |
| RETAIN_UPLOADED_PROJECT_FILES | Type — true/false Default — false |
| RETAIN_UPLOADED_PROJECT_FILES_FOR_USER | Type — Text string, a comma-delimited string containing names of users for whom uploaded projects are not deleted after request servicing. Default — None; however, this <context-param> must exist in the web.xml file even if its value is empty. Do not remove it. |
| MAX_UPLOAD_FILE_SIZE | Type — integer Default — 1048576000. Number of bytes. |
Table 2. Security and File Check <context-param>'s
If "true," on Linux/Unix systems, the SET_PERMISSIONS <context-param> causes the command in the UNIX_CHOWN_COMMAND <context-param> to be run on the directory containing the unpacked project. On Windows, it causes the command in the WINDOWS_CACLS_COMMAND <context-param> to be run on the directory containing the unpacked project, using the options specified in the WINDOWS_CACLS_PERMS <context-param>. In all cases, whether Linux/Unix or Windows, all unpacked files are initially set to read only (444 on Linux/Unix).
Except perhaps when testing, the value of the SET_PERMISSIONS <context-param> should always be "true". If "false", unpacked project files will be owned by the owner of the web container process and set read only. It's safest to take complete control by explicitly setting the ownership.
The value of the UNIX_CHOWN_COMMAND <context-param> represents a command in Linux/Unix used to set ownership of the files in an unpacked project, something like:
chown -hPR username:groupnameUse this <context-param> to automatically change the ownership of all project files after unpacking; however, keep in mind that the command will be limited by the permissions of the user who owns the web container process.
The value of the WINDOWS_CACLS_COMMAND <context-param> should be the text of a Windows command used to set ownership and file permissions on unpacked project files, something like:
echo y| C:\WINNT\system32\CACLS.exeIt should contain the exact path and executable. However, notice that it does not include the necessary switches and options. The switches and options are set in the WINDOWS_CACLS_PERMS <context-param>.
The value of the WINDOWS_CACLS_COMMAND <context-param> is
combined with the value of the value of the WINDOWS_CACLS_PERMS
<context-param> before being run. The two are split so that you
are not limited to just the
cacls.exe command. For example,
although not recommended because it is much slower, you could run
the xcacls.vbs script.
The WINDOWS_CACLS_PERMS <context-param> value represents the switches and options passed to the command specified in the WINDOWS_CACLS_COMMAND <context-param>. You would probably use something like:
/T /G everyone:R
Values for the WINDOWS_CACLS_PERMS and WINDOWS_CACLS_COMMAND
<context-param>s together specify the entire command string used
to assign permissions to unpacked project files in Windows. On a Windows
machine, type help cacls at a
command prompt for details on the
cacls command.
If the PERFORM_MIME_TYPE_CHECKS <context-param> value is "true", mime-type checks are performed on unpacked project files prior to writing them to disk. If a file's mime-type is not listed in the ALLOWED_MIME_TYPES <context-param>, servicing the request is aborted and the user is sent to an error page. If "false", no mime-type checks are performed and all mime-types are allowed. Unless off-line for configuration and testing, you should always use a value of "true".
If the PERFORM_FILE_EXTENSION_CHECKS <context-param> value is "true", filename extension checks are performed on unpacked project files prior to writing them to disk. If any file is found to be using a filename extension that is not listed in the ALLOWED_FILE_EXTENSIONS <context-param>, servicing of the request is aborted and the user is sent to an error page. If "false", no filename extension checks are performed and all filename extensions are allowed. Unless off-line for configuration and testing, you should always use a value of "true".
If the ALLOW_UNKNOWN_MIME_TYPES <context-param> value is "true", files whose mime-type cannot be determined are allowed. If "false", files whose mime-type cannot be determined are disallowed. Mime-types explicitly allowed are listed in the ALLOWED_MIME_TYPES <context-param>. If a file's mime-type can be positively determined, and the file's mime-type is not listed in the ALLOWED_MIME_TYPES <context-param>, the file is disallowed regardless of the value in this <context-param>.
Mr. XML Publisher uses the Java Mime Magic library to determine mime-types, and there are cases in which the mime-type for some files cannot be determined. For example, it cannot determine some varieties of the TIFF graphic file format and categorizes then as "unknown." Security is weakened a bit if you set this value to "true", but not by much. The Java Mime Magic library can detect most mime-types you want to exclude for security reasons, specifically executable files.
The ALLOWED_FILE_EXTENSIONS <context-param> value contains a comma-delimited string of allowed filename extensions for files in uploaded projects. Do not use spaces between commas and entries and do not use a dot character (".") as part of an entry. If the PERFORM_FILE_EXTENSION_CHECKS <context-param> is "true", only files with filename extensions matching those in this string are allowed. If the PERFORM_FILE_EXTENSION_CHECKS <context-param> is "false", this string is irrelevant. To allow files with no extension, use a "," as the first character in the <param-value> with no space between it and the next entry.
This context-param helps implement a quick check for prohibited files that a user might accidentally include in an uploaded project. It will not check if the file is misnamed with a deceptive file extension in an attempt to hide its mime-type. To catch deceptively named files whose mime-type is prohibited, you must rely on the ALLOWED_MIME_TYPES context-param.
The ALLOWED_MIME_TYPES <context-param> value contains a comma-delimited string of allowed mime-types for files in uploaded projects. Do not use spaces between commas and entries. If the PERFORM_MIME_TYPE_CHECKS <context-param> is "true", only files with a mime-type matching one of those in this string are allowed. If PERFORM_MIME_TYPE_CHECKS is "false", this string is irrelevant. To allow all mime-types, set PERFORM_MIME_TYPE_CHECKS to "false".
The list of allowed mime-types is a "white list," all other mime types are disallowed ("blacklisted"). Filename extensions are ignored when determining the mime-type. Use the list of allowed mime types to enforce documentation and security policies. For example, you might deliberately not include mime-types for disallowed graphics formats.
To help enforce security, exclude all executable mime-types. For example, on Windows you would not include any of the following:
application/octet-stream
application/x-msdownload
application/exe
application/x-exe
application/dos-exe
vms/exe
application/x-winexe
application/msdos-windows
application/x-msdos-program
If the SKIP_FILE_CHECKS <context-param> value is "true", checks are skipped for both filename extensions and mime types. If the SKIP_FILE_CHECKS <context-param> is "false", unpacked files are checked for mime-types and filename extensions according to the PERFORM_MIME_TYPE_CHECKS and PERFORM_FILE_EXTENSION_CHECKS <context-param> values. Unless you have taken the server off-line for configuration and testing, you should always use a value of "false".
If the RETAIN_UPLOADED_PROJECT_FILES <context-param> value is "true", unpacked project files are retained for all users (not deleted after servicing the request). If "false", unpacked project files are retained only for those specific users listed in the RETAIN_UPLOADED_PROJECT_FILES_FOR_USER <context-param>. Use this <context-param> for testing. For troubleshooting errors related to a specific user, use the RETAIN_UPLOADED_PROJECT_FILES_FOR_USER <context-param>.
The RETAIN_UPLOADED_PROJECT_FILES_FOR_USER <context-param> value contains a delimited string of usernames for whom unpacked project files will not be deleted after request servicing. The delimiter is "!!!!". Use this <context-param> for troubleshooting and testing specific to individual users. If the RETAIN_UPLOADED_PROJECT_FILES <context-param> is set to "true", this <context-param> is ignored and unpacked project files are retained for all users.
The MAX_UPLOAD_FILE_SIZE <context-param> value contains an integer representing, in bytes, the maximum size limit allowed for uploaded zipped projects. The default is 1048576000 (~1GB), but it's an arbitrary limit that in most cases administrators are expected to override.
A user might accidentally try to upload a very large file. From a security perspective, vulnerabilities can result. Prevent that from happening by setting this value to something reasonable for your site.
Mr. XML Publisher provides several <context-param>s used to control internal object caching. Caching internal objects costs very little in terms of resource consumption and provides significant benefit. The size for each cacheable object is less than 15KB.
Table 3 lists the <context-param>s used to control internal object caching. Details for each are provided in the sections that follow.
| <context-param> | Type and Default |
|---|---|
| NumTransformerObjs | Type — integer Default — MAX_CONCURRENT_REQUESTS <context-param> value |
| NumMagicObjs | Type — integer Default — MAX_CONCURRENT_REQUESTS <context-param> value |
| NumUnZipperObjs | Type — integer Default — MAX_CONCURRENT_REQUESTS <context-param> value |
| NumUnTGZipperObjs | Type — integer Default — MAX_CONCURRENT_REQUESTS <context-param> value |
| PREPARE_JDBC_PULLERS | Type — true/false Default — false |
| PREPARE_ORACLE_PULLERS | Type — true/false Default — false |
| PREPARE_XMLDB_PULLERS | Type — true/false Default — false |
| PREPARE_SEDNA_PULLERS | Type — true/false Default — false |
| PREPARE_TGL_PULLERS | Type — true/false Default — false |
| PREPARE_MKL_PULLERS | Type — true/false Default — false |
| PREPARE_TAMINO_PULLERS | Type — true/false Default — false |
| PREPARE_XHIVE_PULLERS | Type — true/false Default — false |
| PREPARE_XSTREAMDB_PULLERS | Type — true/false Default — false |
Table 3. Object Caching <context-param>'s
Transformer objects are instances of a custom class Mr. XML Publisher uses to coordinate server-side activities related to XML transformations. They are small "plain old Java objects" (POJOs) used internally and are especially good candidates for caching. Set this number at or slightly above the value used by MAX_CONCURRENT_REQUESTS. Or, set it at the number of CPU cores available on the server.
Mr. XML Publisher uses the Java Mime Magic Library (http://www.sourceforge.net/db-xsl-cfg/) when checking mime-types. The NumMagicObjs <context-param> represents the number of these objects to cache. Set this number at the value used for MAX_CONCURRENT_REQUESTS. Or, set it at the number of CPU cores available on the server.
UnZipper objects are instances of a custom class Mr. XML Publisher uses to unpack uploaded zipped projects. They are small POJOs used internally and are especially good candidates for caching. Set the NumUnZipperObjs <context-param> value at the value used by MAX_CONCURRENT_REQUESTS. Or, set it at the number of CPU cores available on the server.
The NumUnTGZipperObjs <context-param> value is relevant only if you are using a Mr. XML Publisher installation customized to accept uploads compressed as tar+gzip archives. In that case, the NumUnTGZipperObjs <context-param> works just like the NumUnZipperObjs <context-param> but for untarring and ungzipping uploaded projects. Set the NumUnTGZipperObjs <context-param> value at or slightly above the value used by MAX_CONCURRENT_REQUESTS. Or, set it at the number of CPU cores available on the server.
The PREPARE_JDBC_PULLERS <context-param> enables or disables caching of JDBC puller objects. If "true", they are cached in a number equal to the MAX_CONCURRENT_REQUESTS <context-param> value.[15] A value of "false" disables internal DBCP connection pooling for JDBC pullers; however, if your Mr. XML Publisher's web.xml file contains any PULL_JDBC_ON_STARTUP[…] <context-param>s, a "false" value is ignored and JDBC puller objects are automatically prepared and cached.
The PREPARE_ORACLE_PULLERS <context-param> enables or disables caching of Oracle puller objects. If "true", they are cached in a number equal to the MAX_CONCURRENT_REQUESTS <context-param> value. A value of "false" disables internal DBCP connection pooling for Oracle data pullers; however, if your Mr. XML Publisher's web.xml file contains any PULL_ORACLE_ON_STARTUP[…] <context-param>s, a "false" value is ignored and Oracle puller objects are automatically prepared and cached.
The PREPARE_XMLDB_PULLERS <context-param> value controls whether XMLDB puller objects are prepared and cached.[16] If "true", they are cached in a number equal to the value of the MAX_CONCURRENT_REQUESTS <context-param> value. A "false" value is ignored and XMLDB puller objects are cached anyway when using any PULL_XMLDB_ON_STARTUP[…] <context-param>s.
The PREPARE_SEDNA_PULLERS <context-param> value controls whether Sedna puller objects are prepared and cached. If "true", they are cached in a number equal to the value of the MAX_CONCURRENT_REQUESTS <context-param>. A "false" value is ignored and Sedna puller objects are cached anyway when using any PULL_SEDNA_ON_STARTUP[…] <context-param>s.
The PREPARE_TGL_PULLERS <context-param> value controls whether TigerLogic puller objects are prepared and cached. If "true", they are cached in a number equal to the value of the MAX_CONCURRENT_REQUESTS <context-param>. A "false" value is ignored and TigerLogic puller objects are cached anyway when using any PULL_TGL_ON_STARTUP[…] <context-param>s.
The PREPARE_MKL_PULLERS <context-param> value controls whether MarkLogic puller objects are prepared and cached. If "true", they are cached in a number equal to the value of the MAX_CONCURRENT_REQUESTS <context-param>. A "false" value is ignored and MarkLogic puller objects are cached anyway when using any PULL_MKL_ON_STARTUP[…] <context-param>s.
The PREPARE_TAMINO_PULLERS <context-param> value controls whether Tamino puller objects are cached and prepared. If "true", they are cached in a number equal to the value of the MAX_CONCURRENT_REQUESTS <context-param>. A "false" value is ignored and Tamino puller objects are cached anyway when using any PULL_TAMINO_ON_STARTUP[…] <context-param>s.
The PREPARE_XHIVE_PULLERS <context-param> value controls whether XHive puller objects are prepared and cached. If "true", they are cached in a number equal to the value of the MAX_CONCURRENT_REQUESTS <context-param>. A "false" value is ignored and XHive puller objects are cached anyway when using any PULL_XHIVE_ON_STARTUP[…] <context-param>s.
The PREPARE_XSTREAMDB_PULLERS <context-param> value controls whether XStreamDB puller objects are prepared and cached. If "true", they are cached in a number equal to the value of the MAX_CONCURRENT_REQUESTS <context-param>. A "false" value is ignored and XStreamDB puller objects are cached anyway when using any PULL_XSTREAMDB_ON_STARTUP[…] <context-param>s.
Mr. XML Publisher provides several <context-param>s used to manage pulling XML from data stores. They allow you to set reasonable limits for things like file size, timeouts, etc., and they allow you to enable/disable some optional connection pooling features.
Depending on your data store, you may need to configure connection pooling in its management facilities. For example, that's the case with the eXist native XML database. With other data stores, there's nothing you need to do at all. Connection pooling is automatic in both the data store and in Mr. XML Publisher. For example, that's the case with MarkLogic Server. Unfortunately, with some data stores, connection pooling is simply not available. Check the documentation for your data store. If connection pooling is available, you probably want to use it.
If enabled in Mr. XML Publisher through the appropriate web.xml <context-param>s, connection pooling for JDBC and Oracle occurs internally with no additional intervention necessary on your part. Specifically, you need not configure connection pooling in your web container. Mr. XML Publisher uses the Apache Software Foundation's commons-dbcp package to provide connection pooling for JDBC and Oracle (DBCP, http://commons.apache.org/dbcp/). Mr. XML Publisher does not use any modified code from Apache's commons-dbcp package. Rather, it uses advanced features from the commons-dbcp package to augment the JDBC and Oracle data pullers, adding new connections to the pools as they are used and timing out old connections that fail periodic validity tests. For data stores other than JDBC and Oracle, if connection pooling is available, Mr. XML Publisher automatically uses it and there is nothing you need to configure in Mr. XML Publisher.
Table 4 lists the <context-param>s used to manage pulling XML from data stores and pooling connections. Details for each are provided in the sections that follow.
| <context-param> | Type and Default |
|---|---|
| SINGLE_PULL_MAX_LENGTH |
Type — integer Default — 1048576000. Number of bytes. |
| MAX_PULLS_PER_REQUEST |
Type — integer Default — 12 |
| DISABLE_XINCLUDE_RESOLVER |
Type — true/false Default — false |
| DEFAULT_QUERY_TIMEOUT |
Type — integer Default — 30. Time in seconds. |
| PULL_XXX_ON_STARTUP |
Type — Text, a delimited string whose entries adhere to the rules for pulling data as described in XML from a Data Store. Default — none |
| DISABLE_INTERNAL_ORACLE_POOLING |
Type — true/false Default — true |
| DISABLE_INTERNAL_JDBC_POOLING |
Type — true/false Default — true |
Table 4. XML Data Pulls and Connection Pooling <context-param>'s
The SINGLE_PULL_MAX_LENGTH <context-param> value represents
a limit to the maximum size allowed for any single data pull. It is a
limit to the value returned by
String.length() where the pulled
data is the String object before being written to disk. If Mr. XML
Publisher detects that a returned result set is over this limit, it
aborts servicing for the entire request and sends the user to an
error page.
The MAX_PULLS_PER_REQUEST <context-param> value represents a limit to the maximum number of data pulls allowed per formatting request. It is a limit to the cumulative total of data pulls within the request, regardless of any order or mix in which data is pulled from various data stores.
Setting the DISABLE_XINCLUDE_RESOLVER <context-param> value to "true" disables all data pullers. If "false", Mr. XML Publisher always attempts to pull data according to the instructions it takes from an uploaded project's IncludeMap.xml file. Simply setting a PREPARE_XXX_PULLERS <context-param> value to "false" will not prevent data pulls.
The setting in this param is global. It is either "true" or "false" for all users and all data pullers. However, it does not apply to any PULL_XXX_ON_STARTUP[…] <context-param>s. Thus, you can prevent users from pulling data while still using the data pullers upon server startup.
The DEFAULT_QUERY_TIMEOUT <context-param> value represents the maximum number of seconds Mr. XML Publisher waits before timing out an attempted data pull. If a timeout occurs, the data pull is aborted along with servicing for the entire request. The user is then transferred to an error page explaining what happened.
PULL_XXX_ON_STARTUP <context-param> elements are used to pull XML or XSL from a data store upon loading of the Mr. XML Publisher servlet context. Often this is useful when otherwise needing to repeatedly pull the same data. For example, if you store server-side XSL in a data store, you can write XSL files to disk just once, upon loading of the Mr. XML Publisher servlet context. Thus, the XSL file is the most recent version and need not be pulled again until updated, at which time you simply reload the Mr. XML Publisher servlet context.
There is no actual <context-param> named "PULL_XXX_ON_STARTUP." It is used here to refer to the following <context-param>s whose names begin with "PULL_XXX_ON_STARTUP", where "XXX" is the name of a specific data puller and "[…]" may be anything:
PULL_JDBC_ON_STARTUP[…]
PULL_XMLDB_ON_STARTUP[…]
PULL_TGL_ON_STARTUP[…]
PULL_ORACLE_ON_STARTUP[…]
PULL_MKL_ON_STARTUP[…]
PULL_XHIVE_ON_STARTUP[…]
PULL_TAMINO_ON_STARTUP[…]
PULL_SEDNA_ON_STARTUP[…]
PULL_XSTREAMDB_ON_STARTUP[…]
In your Mr. XML Publisher web.xml file, you can create your own names for the above example <context-param>s by adding whatever you like in place of the "[…]" part. Thus, you can perform multiple data pulls upon startup and keep them organized. For example:
PULL_JDBC_ON_STARTUP_PDF
PULL_JDBC_ON_STARTUP_MAN_PAGES
PULL_ORACLE_ON_STARTUP_HTML
PULL_ORACLE_ON_STARTUP_JAVA_HELP
PULL_XMLDB_ON_STARTUP_ECLIPSE_HELP
Notice that each begins with the string, "PULL_XXX_ON_STARTUP", where "XXX" is the name of a specific data puller.
PULL_XXX_ON_STARTUP[…] <context-param> values are delimited strings, using "!!!!" (four exclamation marks) as the delimiter. Each delimited member represents a required parameter to be passed to the data puller.
![[Caution]](graphics/caution.png) | Caution |
|---|---|
Parameters passed to a data puller in an PULL_XXX_ON_STARTUP[…] <context-param> do not necessarily correspond exactly with the data puller's related elements in an IncludeMap.xml file. Nonetheless, the values for those parameters must comply with the data store's rules for connection strings, query strings, syntax, etc. For details on the rules of an IncludeMap.xml file, see IncludeMap.xml. |
For each type of puller, if a PULL_XXX_ON_STARTUP[…] <context-param> exists, including any that have null values, the value for that puller's PREPARE_XXX_PULLERS <context-param> is ignored and objects for that puller are prepared and cached. Additionally, all PULL_XXX_ON_STARTUP[…] <context-param>s work independently of the setting in the DISABLE_XINCLUDE_RESOLVER <context-param>.
Example PULL_XXX_ON_STARTUP[…] <context-param>s are provided in the following sections.
| Caution |
|---|---|
If you are using TigerLogic, you know about the required ampersand needed to separate special parameters passed as part of the URI. In a PULL_TGL_ON_STARTUP[…] <context-param>, you must code the ampersand ("&") as a character entity ("&") in the delimited string member containing the URI. |
The DISABLE_INTERNAL_ORACLE_POOLING <context-param> value determines whether internal DBCP connection pooling is disabled for connections to Oracle data stores. To disable internal DBCP connection pooling for Oracle, set this value to "true". To enable internal DBCP connection pooling for Oracle, not only must you set this value to "false", you must also set the PREPARE_ORACLE_PULLERS <context-param> value to "true". If an Oracle puller is not prepared and cached in advance, it will be instantiated with connection pooling disabled.
The DISABLE_INTERNAL_JDBC_POOLING <context-param> value determines whether internal DBCP connection pooling is used for connections to JDBC data stores.[17] To enable internal DBCP connection pooling for JDBC connections, not only must you set this value to "false", you must also set the PREPARE_JDBC_PULLERS <context-param> value to "true". If a JDBC puller is not prepared and cached in advance, it will be instantiated with connection pooling disabled and the DISABLE_INTERNAL_JDBC_POOLING <context-param> value will be ignored.
[12] Messages related to performance timing and server-side XML parsing do not use log4j and are sent to System.out.
[13] Individual users are limited to one formatting request at a time.
[14] Files created from data pulls are written to disk read-only, owned by the user who owns the web container process. You cannot change the ownership or permissions on them, and no mime-type or file extension checks are done prior to creating the file.
[15] JDBC data sources are IBM DB2, Microsoft SQL Server, Sun mySQL, and Sybase. Although Oracle is also a JDBC data source, Mr. XML Publisher provides a distinctly separate data puller for Oracle.
[16] XMLDB data sources include eXist and Xindice.
[17] JDBC data stores are IBM DB2, Microsoft SQL Server, Sun mySQL, and Sybase. Although Oracle is also a JDBC-compliant data store, Mr. XML Publisher provides a distinctly separate data puller for Oracle.
| |  | |
| ENVIRONMENTs |  | XML from a Data Store |
