OpenSubsystems

Business Components for Java Applications

Documentation

Configuration

Last modified

$Author: bastafidli $
$Date: 2006/08/31 06:34:08 $
$Revision: 1.8 $
$RCSfile: configuration.html,v $

Configuration

oss.config.file

Used by: Open Core
Specified in: java -D command line parameter | J2EE server specific setup

Specifies the name of the configuration file that contains the rest of the properties for the application and OpenSubsystems. This property should be specified on the java command line using -D command line parameter or using application server specific method if OpenSubsystems is running inside of J2EE application server. If a value for this property is specified, the system first tries to directly open the specified file therefore if the specified name contains full path to the file it will be opened. If this value is not specified the system will look for the default configuration file oss.properties. If the value doesn't contain full path to the file and the file is not located in the current directory, the system will try to load the file from the system classpath.

oss.config.dependent.file

Used by: Open Core
Specified in: oss.properties | file previously specified using oss.config.dependent.file property

Specifies the configuration file that a given configuration file depends on. If this property is found in the file being loaded, the dependent file is loaded first. Then the properties loaded from the dependent file are replaced with the properties, which were redefined in the current file.

java.util.logging.config.file

Used by: Open Core
Specified in: java -D command line parameter | J2EE server specific setup

Specifies the name of the configuration file that should be used to configure logging capabilites of application and OpenSubsystems. This property should be specified on the java command line using -D command line parameter or using application server specific method if OpenSubsystems is running inside of J2EE application server. If a value for this property is specified, the system first tries to directly open the specified file therefore if the specified name contains full path to the file it will be opened. If this value is not specified the system will look for the default configuration file osslog.properties. If the value doesn't contain full path to the file and the file is not located in the current directory, the system will try to load the file from the system classpath.

Database

oss.datasource.driver

Used by: Open Core
Specified in: oss.properties

Name of the default JDBC driver class used to connect to the database. For example for Oracle database this property can contain oracle.jdbc.driver.OracleDriver.

oss.datasource.url

Used by: Open Core
Specified in: oss.properties

URL of the default database to connect to. It has to match the configured driver. For example for Oracle database this property can contain jdbc:oracle:thin:@server:1521:database.

oss.datasource.user

Used by: Open Core
Specified in: oss.properties

Login name of the database user used to connect to the database. This database user doesn't have to exist for most of the supported databases. If the user doesn't exist the system will try to create it if the administration user and password is specified using oss.datasource.adminuser and oss.datasource.adminpassword

oss.datasource.password

Used by: Open Core
Specified in: oss.properties

Password for the database user specified by the oss.datasource.user property used to connect to the database.

oss.datasource.adminuser

Used by: Open Core
Specified in: oss.properties

Login name for the administration database user used to connect to the database. This user is used to connect to the database only in case the user specified by the oss.datasource.user property doesn't exist and needs to be created.

oss.datasource.adminpassword

Used by: Open Core
Specified in: oss.properties

Password for the database user specified by the oss.datasource.adminuser property used to connect to the database.

oss.datasource.admindatasource

Used by: Open Core
Specified in: oss.properties

Boolean flag specifying if a separate datasource should be used to obtain administration connection instead of just using the default data source with separate credentials. This have to be set to true when using J2EE capabilities in WebLogic 9.x.

realdriver

Used by: Open Core
Specified in: spy.properties

If P6Spy is used to monitor interaction with the database by specifying value com.p6spy.engine.spy.P6SpyDriver for the oss.datasource.driver property, specify in this property the real JDBC driver class name, which should the P6Spy use to connect to the database.

oss.dbschema.prefix

Used by: Open Core
Specified in: oss.properties

Specifies default prefix to use for database objects. E.g. if this property is set to BF_ the database table to track registered database schemas will be named BF_SCHEMA.

Connection pool

Following settings allow to configure behaviour of one or more connection pools for a registered datasource. These settings are defined at two different levels. Settings without a datasource name apply to all registered datasources unless they are redefined using a setting with the datasource name specified.

oss.datasource.pool[.datasourcename].initialsize

Used by: Open Core
Specified in: oss.properties

Initial size of the connection pool. How many connections are created in the pool when the pool is started.

Connection pool specific terminology:

  • DBCP: initialSize - if 0 - no initial connections created
  • XAPool: StandardXAPoolDataSource(iInitialPoolSize)
  • C3P0: initialPoolSize
  • Proxool: No support
oss.datasource.pool[.datasourcename].minsize

Used by: Open Core
Specified in: oss.properties

Minimal size of the connection pool. Number of connections in the pool should not fall under this threshold regardless if they are used or not. This is not the same as the initial/optimal size.

Connection pool specific terminology:

  • DBCP: minIdle - if 0 - pool can become empty
  • XAPool: StandardXAPoolDataSource.setMinSize
  • C3P0: minPoolSize
  • Proxool: minimum-connection-count
oss.datasource.pool[.datasourcename].maxsize

Used by: Open Core
Specified in: oss.properties

Maximal size of the connection pool. How many connections can be taken out of the pool or can exist in the pool idle.

Connection pool specific terminology:

  • DBCP: maxActive, maxIdle - if 0 - no limit
  • XAPool: StandardXAPoolDataSource.setMaxSize
  • C3P0: maxPoolSize
  • Proxool: maximum-connection-count
oss.datasource.pool[.datasourcename].cangrow

Used by: Open Core
Specified in: oss.properties

Can the connection pool grow above maximal size or should it block. This can be useful if we want to have soft max limit but still allow to satisfy request when load increases and then maybe in the future readjust the settings. If we do not allow growing, then the caller will be blocked until connection becomes available.

Connection pool specific terminology:

  • DBCP: GenericObjectPool(...whenExhaustedAction...)
  • XAPool: No support
  • C3P0: No support
  • Proxool: No support
oss.datasource.pool[.datasourcename].waitperiod

Used by: Open Core
Specified in: oss.properties

Setting that specifies if the pool should block when it reaches maximal size, how long can wait at most for a connection. Time is in miliseconds.

Connection pool specific terminology:

  • DBCP: maxWait - if -1 - wait indefinitely
  • XAPool: StandardXAPoolDataSource.setDeadLockMaxWait
  • C3P0: checkoutTimeout - if 0 - wait indefinitely
  • Proxool: No support
oss.datasource.pool[.datasourcename].retryperiod

Used by: Open Core
Specified in: oss.properties

Setting that specifies how long to wait until the pool tries to acquire another connection, if getting connection from the pool fails (e.g. in case of C3P0 even for some other reason than the pool is exhaused, such as temporary database outage). Time is in miliseconds.

Connection pool specific terminology:

  • DBCP: No support
  • XAPool: StandardXAPoolDataSource.setDeadLockRetryWait
  • C3P0: acquireRetryDelay
  • Proxool: No support
oss.datasource.pool[.datasourcename].retrycount

Used by: Open Core
Specified in: oss.properties

Setting that specifies how many times the pool tries to acquire another connection, if getting connection from the pool fails (e.g. in case of C3P0 even for some other reason than the pool is exhaused, such as temporary database outage).

Connection pool specific terminology:

  • DBCP: No support
  • XAPool: No support
  • C3P0: acquireRetryAttempts - if less or equal to 0 - try indefinitely
  • Proxool: No support
oss.datasource.pool[.datasourcename].validate.borrow

Used by: Open Core
Specified in: oss.properties

Should the pool validate connection immmediately before it is borrowed from the pool. This is quite expensive to do by default and often it is better to let pool check on idle connection if such option is available.

Connection pool specific terminology:

  • DBCP: testOnBorrow
  • XAPool: No support
  • C3P0: testConnectionOnCheckout
  • Proxool: test-before-use
oss.datasource.pool[.datasourcename].validate.return

Used by: Open Core
Specified in: oss.properties

Should the pool validate connection when it is returned to the pool.

Connection pool specific terminology:

  • DBCP: testOnReturn
  • XAPool: No support
  • C3P0: testConnectionOnCheckin
  • Proxool: test-after-use
oss.datasource.pool[.datasourcename].validate.idle

Used by: Open Core
Specified in: oss.properties

Should the pool validate connection when it is idle. This is the most efficient way of conection testing and if you do decide to test connections you may consider doing so while they are idle.

Connection pool specific terminology:

  • DBCP: testWhileIdle
  • XAPool: No support
  • C3P0: testConnectionOnCheckin
  • Proxool: Just set value for idlecheckperiod
oss.datasource.pool[.datasourcename].validate.level

Used by: Open Core
Specified in: oss.properties

How thoroughly to validate the objects in the pool. Since this is the only way provided by XAPool to configure connection testing, we provide this attribute, even though it has no meaning for other pools.

Connection pool specific terminology:

  • DBCP: No support
  • XAPool: StandardXAPoolDataSource.setCheckLevelObject
  • C3P0: No support
  • Proxool: No support

From XAPool JavaDoc:

  • 0 = no special checking
  • 1 = just a check on an object
  • 2 = test the object
  • 3 = just a check on an object (for all the objects)
  • 4 = test the object (for all the objects)
oss.datasource.pool[.datasourcename].idlecheckperiod

Used by: Open Core
Specified in: oss.properties

How often to validate idle connections. Validating idles connections is the most efficient way of validating connections since it doesn't affect requesting of returning of connections and therefore performance of the application. Time is in miliseconds (even though some pools expect it in seconds, it will be converted from milliseconds as needed). Alternative is to set idlechecksize if the connection pool supports it.

Connection pool specific terminology:

  • DBCP: timeBetweenEvictionRunsMillis - if less or equal to 0 - do not check
  • XAPool: No support
  • C3P0: idleConnectionTestPeriod - if less or equal to 0 - do not check
  • Proxool: house-keeping-sleep-time
oss.datasource.pool[.datasourcename].idlechecksize

Used by: Open Core
Specified in: oss.properties

How many of the idle connections to test during one test run. This is an alternative of idlecheckperiod.

Connection pool specific terminology:

  • DBCP: numTestsPerEvictionRun
  • XAPool: No support
  • C3P0: No support
  • Proxool: No support
oss.datasource.pool[.datasourcename].idleperiod

Used by: Open Core
Specified in: oss.properties

How long can connection sit in the pool before it is considered idle. Time is in miliseconds (even though some pools expect it in seconds, it will be converted from milliseconds as needed).

Connection pool specific terminology:

  • DBCP: minEvictableIdleTimeMillis
  • XAPool: No support
  • C3P0: maxIdleTime - 0 means connections will never expire
  • Proxool: No support
oss.datasource.pool[.datasourcename].transaction.isolation

Used by: Open Core
Specified in: oss.properties

Default transaction isolation level. Settings are commited, uncommited, repeatable, serializable.

Connection pool specific terminology:

  • DBCP: defaultTransactionIsolation
  • XAPool: StandardXADataSource.setTransactionIsolation
  • C3P0: No support
  • Proxool: No support
oss.datasource.pool[.datasourcename].pstmtcachesize

Used by: Open Core
Specified in: oss.properties

Should the connection pool cache prepared statements and if so how many.

Connection pool specific terminology:

  • DBCP: maxOpenPreparedStatements - if 0 - cache and do not impose any limit - if less than 0 - do no cache
  • XAPool: StandardXADataSource.setPreparedStmtCacheSize - if less or equal to 0 - do not cache
  • C3P0: maxStatements - if less or equal to 0 - do not cache
  • Proxool: No support

Transactions

oss.transaction.timeout

Used by: Open Core
Specified in: oss.properties

Transaction timeout in seconds, which should be set for a transaction when it is started. If this is set to 0, according to Java documentation the transaction manager restores the default value.

oss.transaction.monitor

Used by: Open Core
Specified in: oss.properties

Boolean flag, which specifies if the system should monitor transactions that is use a delegating class which intercepts and monitors calls to UserTransaction class. This is useful for troubleshooting and during development but can affect the system performance.

Server

oss.server.start.retrycount

Used by: Open Core
Specified in: oss.properties

Specifies how many times we should try to restart the server if it cannot be started at the port specified by oss.webserver.port property. If the port specified is the standard HTTP port 80, the server will try port 8080 and then other ports above it until an available port is found or until the specified value is reached. If the port specified is not port 80, the port number will be increased by 1 until an available port is found or until the specified value is reached. If the value is 0, the system will not attempt to restart the server if it cannot be started on the originally specified port.

oss.webserver.port

Used by: Open Core
Specified in: oss.properties

The port the embedded web server should start on. The oss.server.start.retrycount property specifies what to do if the web server cannot be started on the specified port.

oss.webserver.port.secure

Used by: Open Core
Specified in: oss.properties

The port the embedded web server should accepts SSL requests on.

oss.webserver.servebuffer.size

Used by: Open Core
Specified in: oss.properties

The size of the buffer used to serve files requested from the server.

oss.webserver.dispatcher.cached

Used by: Open Core
Specified in: oss.properties

Specifies if the web tier should cache the request dispatchers used to dispatch client requests to various web resources. Caching of the request dispatchers can improve performance, but not all web containers allows to do it.

File system

oss.file.path.temp

Used by: Open Core
Specified in: oss.properties

The directory that should be used to store generated and other temporary files and directories. This directory should be different from the regular operating system temporary directory since some of the subsystems may want to delete all content from this directory during restart.

oss.filecommit.retrycount

Used by: Open Core
Specified in: oss.properties

Specifies how many times to retry file commit or rollback operations performed using FileCommitUtils class in case of error before the commit or rollback of file manipulation operation is aborted.

Security

oss.messagedigest.algorithm

Used by: Open Core
Specified in: oss.properties

Algorithm to generate message digests for verifying passwords. The standard names of the algorithms are defined by Java Cryptography Architecture API Specification Reference

oss.messagedigest.provider

Used by: Open Core
Specified in: oss.properties

Algorithm implementation provider to use for an algorithm defined by property oss.messagedigest.algorithm.

oss.webserver.sessionhandshake.required

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

Boolean value specifying if the server must ensure that the client accepted the server session before it allows further communication. This improves the login process if one is needed since at the time of login the server already knows that the client supports and accepted its session tracking. If the session wasn't confirmed yet and a session handshake is required, it will be redirected to page specified using oss.webserver.sessionhandshake.url property.

oss.webserver.sessionhandshake.url

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

The URL of page to which the user will be redirected if session handshake is required and session wasn't confirmed at the time when the request is submitted to the server.

oss.webserver.login.required

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

Boolean value specifying if user has to be logged in in order to process his or her request sent to the server. If this setting is specified using init-param of a servlet only that servlet will (or will not) require user to be logged in to process the request. If user is not logged in and login is required, it will be redirected to page specified using oss.webserver.login.url property.

oss.webserver.login.url

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

The URL of login page to which the user will be redirected if login is required and user is not logged in at the time when request is submitted to the server.

oss.webserver.sessionvalidator.class

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

The name of a class implementing SessionValidator interface to verify validity of a session each time a request is submitted to the server.

oss.login.secure

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

Boolean value specifying if the login page should be displayed in a secure mode using SSL protocol.

oss.application.secure

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

Boolean value specifying if all pages of the application should be displayed in a secure mode using SSL protocol.

Application

oss.database.schema.[X]

Used by: Open Core
Specified in (priority order): oss.properties | context-param of web.xml

This configuration setting is used to name parameters such as oss.database.schema.0, oss.database.schema.1, which specify what database schemas the application consists of. The database schemas are initialized in the numeric order specified in the configuration setting name after all dependencies exposed by the individual database schemas are taken into account.

oss.webclient.module.[X]

Used by: Open Core
Specified in (priority order): oss.properties | context-param of web.xml

This configuration setting is used to name parameters such as oss.webclient.module.0, oss.webclient.module.1, which specify what web modules the application consists of. The web modules are initialized in the numeric order specified in the configuration setting name.

oss.listdata.asyncloader.pagesize

Used by: Open Patterns
Specified in: oss.properties

How many items to load at once when loading data asynchronously. If this is equal to ListOptions.PAGE_SIZE_ALL then all items will be loaded at once.

User interface

oss.webui.messagebox.page

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

Path to the template page used by the application to display messages to the user. You can specify the title, text of the message, optional recovery URL and exception.

oss.webui.messagebox.css

Used by: Open Core
Specified in (priority order): oss.properties | init-param of a servlet in web.xml | context-param of web.xml

Path to the style sheet file used by the application to display messages to the user.

oss.webui.helplabel.focus

Used by: Open Patterns
Specified in: oss.properties

Boolean flag controlling if user interface allows user to focus (for example by tabbing through controls on the screen) on labels that can be used to display context help.

oss.webui.list.check

Used by: Open Patterns
Specified in: oss.properties

Boolean flag controlling if scrollable tables has a checkbox in each line.

oss.webui.list.sortable

Used by: Open Patterns
Specified in: oss.properties

Boolean flag controlling if rows of a scrollable tables can be sorted by clicking on a column heading.

Tests

oss.loadtest.list.size

Used by: Open Patterns
Specified in: oss.properties

Integer value specifying the total number of items to use for list performance testing. This many randomly generated data items will be loaded into the database and then list operations and searches will be performed with this data set.

oss.loadtest.page.size

Used by: Open Patterns
Specified in: oss.properties

Integer value specifying the page size to use for list performance testing. When testing the list performance, only the specified number of items will be accessed at the same time.

oss.loadtest.loadtime

Used by: Open Patterns
Specified in: oss.properties

Integer value specifying the time threshold in milliseconds to still consider list operation performance acceptable. If any list operation exceeds this value then the performance will be considered too bad and the test will fail.