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”.
Each plugin with configurable settings should have a file
preferences.ini
in its root directory. This file has several purposes:
- It defines those settings, i.e. their name.
- It documents their meaning, explaining supported values.
- It establishes the default value for each setting.
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 org.csstudio.x.y/preferences.ini.
Note that Eclipse offers more ways to establish defaults, but they are discouraged for CSS because of disadvantages:
- Defaults hard-coded in calls to the preference service: These are difficult to find in the code.
- Preference Initializer extension point defined in plugin.xml: This again hides the preference tags and their default values in the code.
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
plugin_customization.ini
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,
consult the 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
org.csstudio.x.y.
Eclipse will look for a file
org.csstudio.x.y/plugin_customization.ini,
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
via the preferenceCustomization setting
in the product plugin.xml file.
For example, if preferenceCustomization
is set to platform:/config/plugin_customization.ini,
the customization file will need to be in
your_product/configuration/plugin_customization.ini,
i.e. within the directory tree of the final product.
In the compiled version of the product, plugins are
usually JAR files in a plugins sub-directory
of the installed product.
The customization file will then be found inside
plugins/org.csstudio.x.y_*.jar
where the * 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
plugin_customization.ini,
for example testnet.ini,
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
plugin_customization.ini,
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 Eclipse menu.
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 CSS menu)
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.
The CSS SecureStorage and 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:
INSTALL_LOCATION:This is the directory where CSS is installed, for example
/usr/local/css/CSS3.0.0. 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:
- System administrator installs CSS.
- System administrator starts CSS and enters the passwords once in the preference GUI.
- Users can now run CSS. CSS plugins have access to the password, but users cannot see the password.
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.
CONFIGURATION_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
.eclipsesub-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:
- System administrator installs CSS, maybe with some passwords build into the
product's
plugin_customization.ini. - User can run CSS. CSS plugins have access to the built-in password.
- User knows another password, enters that password in the preference GUI.
- For that user, CSS plugins now use the password that the user entered.
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.
- System administrator installs CSS, maybe with some passwords build into the
product's
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
The Eclipse 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
- org.eclipse.equinox.security.macosx
- org.eclipse.equinox.security.win32.x86
On other operating systems, Eclipse will fall back to a dialog box that queries the user for a
master password.
The plugin 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