Table of Contents
Once you are able to start a CSS product, you need to configure it. For example, to run the archive engine, you need to specify where it should write data. Likewise, the CSS Data Browser needs to be configured to read the archived data from that location. These settings are site-specific, they cannot be included in the source code. The local CSS administrator should be able to configure these settings so that local end users of CSS can simply open the Data Browser without having to adjust the archive data source settings. Other settings might have useful defaults, but end users may still prefer to adjust them to their liking.
Eclipse has a preference system that allows each plugin to provide default settings. The builder of a product can then add site-specific settings, and finally the users are able to adjust them individually for their instance of CSS.
Note that the following is a technical view of preference settings: How they are originally defined and then adjusted on several levels. This is the information that CSS developers need. As an end user, you might want to read this from the back, jumping right away to the section called “End User Settings: Preference Pages”. As somebody who downloaded some generic version of CSS and wants to provide all the settings for your site, you would follow the section called “Command-line Adjustments: -pluginCustomization”.
For example, such a file can be:
# Example preferences.ini for plugin org.csstudio.demo # Enable the super feature. # Set to 'on', 'off' or 'automatic' which enables it whenever possible enable_super=automatic # URL of server where the super feature connects url=http://localhost/superdata
The Eclipse preference service for a plugin will automatically use such a file
as long as it has the correct name and is located in the plugins root directory.
So for a pluging called
org.csstudio.x.y, that file
must be called
Note that Eclipse offers more ways to establish defaults, but they are discouraged for CSS because of disadvantages:
Putting the defaults into
preferences.ini seems the best way to define
and at the same time document them.
When bundling plugins into a site-specific product, a file
in the plugin that defines that product is automatically used by Eclipse
to override settings from individual plugins.
# Example plugin_customization.ini # Override defaults of plugin org.csstudio.demo: # URL of our super feature server org.csstudio.demo/url=http://my.site.org/mysuperdata
Note that in comparison to an individual plugin's preference file,
all settings in this global preference file are prefixed with the
name of the affected plugin.
If you wonder about the names of preference settings supported by each plugin,
preferences.ini of the respective plugin.
The file has to be in the plugin that defines the product.
By default, it needs to be in the root directory of the product.
For example, assume you have a product X that is defined as
Eclipse will look for a file
i.e. a customization file in the root directory of the plugin
that defines the product, for settings to override values
from individual plugins.
Note, however, that the exact location can be adjusted
in the product
For example, if
is set to
the customization file will need to be in
i.e. within the directory tree of the final product.
In the compiled version of the product, plugins are
usually JAR files in a
of the installed product.
The customization file will then be found inside
* represents some version number and date.
End users will not open and modify that JAR file and the
plugin_customization.ini file inside the JAR.
This way, your product has the settings for your site “built-in”.
In principle, you could actually un-zip the JAR file, edit the customization file, and re-zip it. As a CSS maintainer for your site, you may occasionally be tempted to do this. The downside is that such changes are easily forgotten, and the next time you build a product, you would have to re-do the un-zip, edit, re-zip hack. A better approach to applying changes to the build-in settings of a product is described in the next section.
If a select installation at a site requires a few extra changes, for example
a test network installation needs settings that differ from your main campus
network, put those into a file with the same format as
and run the product with a command-line option
my_product -pluginCustomization /path/to/testnet.ini
While that customization file has the same format as
its name and location are arbitrary.
You can call it anything and place it anywhere,
as long as you provide the full path to it via the
-pluginCustomization command line option.
In fact you want to always provide the full name to the file, even if it is in what you consider the current directory, because the Java runtime that is started by the Eclipse RCP launcher could have a very different idea of its current directory.
If Eclipse does not find your -pluginCustomization file, it is simply ignored, there will be no error message! So if the settings that you think you put into a -pluginCustomization file are not having the desired effect, triple check that you indeed provided the full and correct path to the file.
Finally, the GUI code can offer Preference Pages via which the end user can change the settings.
The exact location of the menu entry for opening the Preference Pages can change.
Eclipse usually has a Preference entry in the
Window menu, except on Mac OS X
where it is placed in the
CSS provides a Preference entry in the
Edit menu regardless of the operating
system because that seems to be a common location for the preference settings in other programs.
(Older versions of CSS actually used the
Typically, these end-user settings are saved in the user's workspace, i.e. they persist for the current user but will not affect the settings of other users or even the site-wide defaults. Details depend on the preference store that is selected by the code that implements the preference page.
PasswordFieldEditor allow to keep preferences for passwords encrypted.
It is for example used to store passwords for accessing the relational database of the SNS alarm and archive system.
These encrypted preferences can be stored in either of two places:
This is the directory where CSS is installed, for example
Using the install location has the advantage that all users of CSS on that computer will
have the password available for use without actually knowing it.
The typical scenario is this:
The disadvantage is that if a user were to try to change any of the related preferences from the GUI, CSS will try to write the password and fail because ordinary users have no write permission in the install location.
The exact directory name of this location is determined
automatically based on where the user can write.
It can for example be in an
sub-directory of the user home directory.
Using the configuration location has the advantage that every user of CSS
can enter his or her own password. The password they entered usually
applies to their instance of CSS, but may also affect instances
started by other users.
The typical scenario is this:
The disadvantage of this approach it its unpredictability. The configuration location can default to the CSS installation location if that user has write permissions to that area of the file system. If such a user enters a password, it will be used by all instances of CSS on that computer. If a user with lesser file access privileges enters a password, it will only be written to a configuration location in that users home directory and not apply to other users.
The location for secure storage can be configured via this setting:
# Can be either "INSTALL_LOCATION" or "CONFIGURATION_LOCATION". # By default it is "CONFIGURATION_LOCATION". org.csstudio.auth/secure_storage_location=CONFIGURATION_LOCATION
SecurePreferencesFactory that is used
for the secure storage of passwords as described above requires a password provider.
This password is sued to encrypt and descrypt the preferences.
Eclipse provides implementations for Windows or OS X that can interface with OS-specific
key stores, including
On other operating systems, Eclipse will fall back to a dialog box that queries the user for a
org.csstudio.sns.passwordprovider provides a password without
requiring user input, which can be very convenient.
Since the password can be derived from reading the code, it is not 100% secure