Servlet Parameter Reference

 

ViewsFlash is a J2EE web application. Some of its functionality is controlled by servlet parameters. These can be provided as init-param entries in its web.xml file, or in a viewsflash.properties file where they take the form name=value. The viewsflash.properties file is located at the location specified in web.xml, which is by default set to /etc/cogix/viewsflash.properties:

<init-param>
  <param-name>propertiesfile</param-name>
  <param-value>/etc/cogix/viewsflash.properties</param-value>
</init-param>

Servlet parameters can also be specified in the web.xml file, like this: <init-param>
  <param-name>name</param-name>
  <param-value>value</param-value>
</init-param>
When deploying ViewsFlash in a distributed configuration, it is preferable to put all parameters in web.xml.

To modify web.xml, unpack the ViewsFlash.war file, modify web.xml, and repack the ViewsFlash.war file. The "jar" Java utility can be used for this purpose.

This section is divided into Commonly Used and Rarely Used sections. It's safe to avoid the latter section unless there's some unusual trouble that cannot be fixed by modifying the commonly used parameters.

Commonly used parameters

Required See Installation
data Directory where to store ViewsFlash files
license Licensing Key. Without one, ViewsFlash will expire after 30 days, and each screen will include an "Evaluation Copy" message. Note that ViewsFlash 5 requires new license keys; older license keys will not work. Contact Cogix for a new key.
When running with a database using a data source See Installation and Using a database
database One of these: Oracle, Oracle9, Oracle10, Oracle11, DB2, MSSQL, MySQL
datasource The name of a JNDI data source.
When using application security See Application security
appsecurity Usually appsecurity=user
administrators A comma-separated list of user IDs and roles; the roles are prefixed by an @ sign. If the logged in user ID matches any of those on the list, or if the logged in user is in any of the roles, they are granted the rights to access all portions of the ViewsFlash application.
Example: peter.ustinov,rhonda.fleming,@viewsflashusers

Rarely used parameters

When running without a database  
backupdir Directory where ViewsFlash stores *.bak files. For best performance, put it on the same drive as ViewsFlash, or turn this option off in the Administration page. Default is the data directory.
logpath A directory for recording ViewsFlash logs. Default is the data directory.
txtpath A directory for recording .txt files that capture votes or surveys, one entry per line. Default is the data directory.
votedir A directory for storing temporary information during multi-page voting. Highly recommended under heavy loads. Default is the data directory.
logrequests Set to 1 to log every http request to the ViewsFlash log. Set to 2 to also log every database access. Useful for debugging, but log can get very large. Default is 0.
strictinit If set to 1, all servlet parameters are checked for correct spelling. If any are misspelled, the servlet will refuse to run with an UnavailableException. Default is 0. When using this, if you want to disable other servlet parameters, prefix them with a ~ and strictinit will regard them as valid, but will ignore them.
confirmwrite If set to 1, whenever an .html file is written to the file system (such as a poll fragment), ViewsFlash will make sure the write succeeded.
 
Other application security techniques
admintimeoutminutes Passwords will need to be reentered after the given minutes. This guards against people who walk away from their computers while using ViewsFlash. Default is 60.
adminport Port for administrative functions; should be behind a firewall for maximum protection. Default is no protection - any administration request can come on any port.
apiport Port for inter-application communication. When used, the Web Services API commands are only available on this port, which should be behind a firewall for maximum protection. By default, this port is set to a non-existant port.
apiattribute Attribute for inter-application communication. Web Services API commands issued in JSP pages with a RequestDispatcher must set this attribute in the HttpRequest to a Long value with the current time. Requests that are missing this attribute will be denied. JSP pages provided by Cogix, such as i18n.jsp, expect this parameter to be set to:
apiatttribute=com.cogix.vwf.api
By default, this parameter is not set, and using the Web Services API from JSP pages is disabled. See How to use the Web Services API.
securesurveyport For questionnaires that specify use SSL, if a port other than the default 443 is desired, use this parameter
normalsurveyport To use a port other than 80 for questionnaire URLs, use this parameter
adminpw When not using Container Security, this parameter provides password to restrict access to the administrative functions. Each place can also have its own password.
extravulnerabilitychecks When set to true, application page forms include an additional security token to validate that each form submitted is unique. Note that when using this parameter users cannot use the technique of opening up two application windows to work on different parts of the application at the same time.
 
Web Application parameters
webappname When installed as a web application, normally ViewsFlash can guess its web application name automatically. If it does not, use this parameter to set it. /ViewsFlash is the normal name, except in WebSphere Portal.
appwebroot Normally, ViewsFlash will automatically find the "document root" by discovering the location that corresponds to the URI "/". If this fails, set this parameter to that location.
usedefaultcharacterencoding A few application servers (like Dynamo 7) interpret charset when receiving requests. If a questionnaire's Language page does not work, set this parameter to true to prevent ViewsFlash from decoding request parameters and form submissions.
Setup page parameters can be enterd as servlet parameters rather than entering them through the Setup page.
admin.name ViewsFlash Administrator name
admn.emailto His or her email address for receiving ViewsFlash emails
admin.emailfrom His or her from email address to identify the messages
admin.emailreplyto His or her reply-to address for receiving replies
admin.smtp.host Host name for the smtp server that handles outgoing email
admin.smtp.username If the smtp server requires authentication, provide the username
admin.smtp.password and the password
mail. In addition, any parameters that start with "mail." will be used to initialize the JavaMail session for the smtp server. Example: mail.smpt.auth can be used when the mail server requires authentication.
admin.viewsflashapplicationurl The URL for the ViewsFlash application. Specify only if the default value is incorrect. Example: http://www.yourcomany.com/ViewsFlash.
admin.viewsflashservleturl The URL for the ViewsFlash servlet. Specify only if the default value is incorrect. This can be useful when the ViewsFlash application runs behind a proxy server that translates URLs to internal URLs and the public servlet URL needs to be different. This option requires the showadminservleturl=true servlet parameter.
admin.viewsflashsecureservleturl The URL for the secure ViewsFlash servlet. Specify only if the default value is incorrect. This option requires the showadminservleturl=true servlet parameter.
showadminservleturl Set this parameter to true to make additional fields in the Administration visible and editable. Use this option when the ViewsFlash URLs are incorrect. Normally, quesionnaire URLs are the same as the application URL. When this parameter is used, questionnaire URLs are generated from the settings in the Administration page instead. When using a reverse proxy server, this option allows for the ViewsFlash application to work at a different URL and port. When the entire server runs only on https, use this parameter and configure the application Setup page URLs to use https.
usingsslproxy Setting this parameter to true prevents the generation of certain HTTP headers that interfere with downloading files and reports in IE6.
admin.pollroot When not using a database, the directory where HTML files should be written. Specify only if the default value is incorrect. Example: /opt/virtual/yourcompany/ViewsFlash
admin.usersendemail Allows sending email. Default true. Set to false to disable.
admin.emailerroralerts Notify administrator of error conditions by email. Default true. Set to false to disable.
admin.cookiedomain Cookie domain for ViewsFlash cookies.
Environmental parameters
servletserver Allows ViewsFlash to be named something other than /servlet/viewsflash. For example, if set to /cgi-bin/Polling, then you can use http://mycompany.com/cgi-bin/Polling/viewsflash.
servletpath If the application server does not support getServletPath(), or if you are using 'servletserver' above, set this parameter to "viewsflash". (Very rare).
servletrequestinputstream ViewsFlash versions before 3.0 parsed the servlet input stream, rather than using getParameterNames(). Set this parameter to "1" to revert to parsing the servlet input stream instead.
realpath If the application server does not support ServletContext.getRealPath("/") in the HttpServlet.init() method, set this parameter to the equivalent of the hosting web server's root directory. Omit the trailing / or \.
referer If the application server does not set the usual REFERER header, use this parameter to specify the name of the header that serves this purpose. (Very rare).
hostipaddress Use this parameter to tell ViewsFlash its IP address. ViewsFlash normally determines the IP address of its machine by using getLocalHost(). Sometimes this returns 127.0.0.1, which is not useful. This is also useful when the machine has more than one IP address.
Database parameters
dbstores Use dbstores=all to store questionnaire definitions, logs and other data on the database. Omiting this parameter will write the ViewsFlash logs to the file system, either in the data directory as viewsflash.log, or to the directory specified in the logpath parameter.
notificationinterval In a distributed database configuration, each instance checks for new events at this interval, in milliseconds. Default is 5,000. If not running in a distributed database configuration, you can set this value quite large (1000000 - one million) to reduce the load on the database a little bit.
instanceid In a distributed database configuration, this parameter is used to identify each instance. If omitted, a random number is assigned. These instance ID's are used in the application logs to identify the instance that is writing to the log. You can assign a number on your own to make the log easier to read; note that if you do, it must be unique for each instance. Failure to make instanceid unique can result in inconsistent instances; for example, one instance could think that a poll is open, while another one doesn't.
storeflushtime Number of milliseconds before saving a poll's tallied results to database. Default is 000 (no delay).
purge Number of days after which unused .vote records, which are created when a questionnaire is partially filled out but not completed, are removed from the vwfobjects table. Default value is 0, which disables purging.
noreports Set to true to disable reports on this server. A separate server without this setting will create reports in the background.
refreshresultstime In a distributed database configuration, this parameter indicates how often to retrieve the current live results from the database. The default value is 3,000 milliseconds. A very small value will increase system load significantly.
dbmaxvarchar The largest size of a VARCHAR type allowed. Default is 2000. If setting dbcharwidthmultiplier greater than 1, we recommend changing this to 4000.
dbcharwidthmultiplier The maximum number of characters required to express one Unicode character. If the database will only store ISO-8859-1 characters, this value is 1 (the default). If the database must store other kinds of characters, we recommend setting this parameter to 3 to support the UTF8 character set and setting dbmaxvarchar (above) to 4000.
dbtablenameprefix If present, this string will be prepended to the name of every table used by ViewsFlash.
For example, COGIX. will use tables such as COGIX.VWFOBJECTS. Note that the trailing period must be entered explicitly.
dbcreatetablespacestatement If present, this string must contain a CREATE TABLESPACE statement that is exectuted before executing a questionnaire's CREATE TABLE statement.
It can contain the string %1, which is replaced by a 7 digit random number.
Examples: dbcreatetablespacestatement=CREATE TABLESPACE A%1 in MYPARTITION USING...(and other parameters, all on one line) will produce CREATE TABLESPACE A12345 IN MYPARTITION USING ...
Do not use this parameter if using the same partition for all data tables; precreate the table space manually.
In either case, use dbtablenamesuffix as described below to assign the table to a tablespace.
dbtablenamesuffix If present, this clause will be inserted after the CREATE TABLE statement used to create a questionnaire's own table. Examples:
dbtablenamesuffix=IN VFD.A%1 will produce CREATE TABLE xxxx (...) IN VFD.A12345
dbtablenamesuffix=IN MYTABLESPACE will produce CREATE TABLE xxxx (...) IN MYTABLESPACE
database Name of the Java class to use for database storage. Example: Oracle, Oracle9, Oracle10, MSSQL, MySQL, DB2.
The actual class name is created by prepending "com.cogix.vwf" if not present, and appending "NamedDataSource" if the name does not include "DataSource". So, Oracle becomes com.cogix.vwf.OracleNamedDataSource.
databaseextension

Name of the Java class to use for writing responses to a single, normalized table. Example is OracleDatabaseExtension.

By default, this parameter is assumed to be XXXDataBaseExtension, where XXX is Oracle, MSSQL, etc.
Using databaseextension= (without an argument) will disable the Normalized Database functionality.
Note that the actual class name is com.cogix.vwf.XXXDataBaseExtension, but com.cogix.vwf can safely be omitted.

normalizedtype

Some normalized database drivers use this parameter to specify what type to use for storing the data element, which is normally set to VARCHAR.

Saving data parameters
save.text Set to false to prohibit saving questionnaire data in the file system
save.table Set to false to prohibit saving questionnaire data in its own database table. Use this when the database user should not be granted the right to create, alter and drop tables.
save.normalized Set to false to prohibit saving questionnaire data in the common, normalized table VWFDATA.
upload.maxsize Specifies the maximum size of an uploaded document. The default value is 10,000,000.
upload.strictfilename Specifies what characters are allowed in uploaded files. The default value is 1, which allows only letters, numbers, space, underscore and dash. A value of 0 makes does not allow file names that contain spaces. A value of 2 allows most characters, including Unicode, but still prevents these characters: \/:*"<>|~&?*
uploadtimeout Specifies how long an upload form remains active, in minutes. The default is 5.
upload.directory Points to a directory where the ViewsFlash application server has been granted file creation, directory creation, and read, write and delete access rights. In a single-server deployment, any directory can be used. In a clustered deployment, this directory must reside on a shared volume, so that attachments gathered from all servers are stored in the same directory and can be accessed by all nodes in the cluster. If this parameter is omitted, a subdirectory of the data directory is used.
Database error recovery parameters
dbretryinterval After a database failure, wait this number of milliseconds before retrying. Default is 30,000 milliseconds.
dbretries After a database failure, retry this number of times. Each retry generates an error log entry and an administrator e-mail. Defaults is 100.
dbignorevendorcodes

The dbignorevendorcodes parameter suppresses database retries for the specified database vendor error codes. Enter this parameter as a list of integers, separated by commas, omitting leading zeroes. For example, dbignorevendorcodes=1401 will disable retries for Oracle error code ORA-01401, caused by attempting to store a non-numeric value in a numeric field.

dbignoresqlstatecodes The dbignoresqlstatecodes parameter suppresses database retries for the specified 5 character standard XOpen SQLState codes. Enter this parameter as a list of 5 character SQLState codes, separated by commas, including leading zeroes. For example, dbignoresqlstatecodes=23000
will disable retries for XOpen SQLState code 23000 (Integrity constraint violation), a more generic form of ORA-01401.
Java Extensibility more info
publishnotifierextension Name of the Java class to invoke after a publishing change. Example is com.cogix.vwf.PublishNotifierExtension
votenotifierextension Name of the Java class to invoke after a valid vote is cast. Example is com.cogix.vwf.VoteNotifierExtension
requestnotifierextension

Name of the Java class to invoke after a request is scanned. Example is com.cogix.vwf.atgRequestNotifier

This requires servlet API 2.2. If application fails to boot with a NoSuchMethod exception, try disabling this parameter to nothing with:
requestnotifierextension=

webcasteventextension Name of the Java class to invoke when a webcast poll or survey event happens. Example is com.cogix.vwf.WebCastEventExtension.
Miscellaneous
errorinterval Controls the interval, in seconds, used to calculate whether a repetitive log entry should be suppressed.
writehtmltodisk When using a database, setting this option to 1 enables options in the place Settings page that allow writing HTML to disk.
webcast Setting this option to 1 enables the Webcast features.
datareviewapi=true Enables the data review and modification API.
appcharset=UTF-8 Defines the application's default character set. Useful when the native locale is not English. For example, GB2312 is useful in mainland China.
appcharset=UTF-8 is the default
dbdatabaseconnectionclass Deprecated: use database instead
dbservername Deprecated: use datasource instead
polladjustment Set to true to enable the legacy Options/Bulk Vote, Remove Entries, and Set Rank polling functions which are disabled by default as of ViewsFlash 6.
Staging parameters
exportby,exportusersecurity,
exportdir,importby,importdir
See Staging

Next: Production