Preference Settings
When you run Phoebus, you may find that it cannot connect to your control system because for example the EPICS Channel Access address list is not configured.
To locate available preferences, refer to the complete
Preferences Listing
or check the source code for files named *preferences.properties
,
for example in the core-pv
sources:
# ----------------------------------------
# Package org.phoebus.applications.pvtable
# ----------------------------------------
# Show a "Description" column that reads xxx.DESC?
show_description=true
# -------------------------
# Package org.phoebus.pv.ca
# -------------------------
# Channel Access address list
addr_list=
Create a file settings.ini
that lists the settings you want to change:
# Format:
#
# package_name/setting=value
org.phoebus.pv.ca/addr_list=127.0.0.1 my_ca_gateway.site.org:5066
The value
might be plain text, with details depending on the
preference setting, for example allowing an IP address for the addr_list
or a true
value for some boolean preference setting.
In addition, Java properties or environment variables can be used like this:
# Example of using a Java property 'gateway'.
# If it is set to 'my_ca_gateway.site.org:5066',
# this example would have the same end result as
# the previous example.
#
# If no Java property 'gateway' is found,
# an environment variable 'gateway' is checked.
org.phoebus.pv.ca/addr_list=127.0.0.1 $(gateway)
Start Phoebus like this to import the settings from your file:
phoebus.sh -settings <location>
Where <location> can be specified as either absolute path:
phoebus.sh -settings /path/to/settings.ini
Or as a file name only:
phoebus.sh -settings settings.ini
In this case the current directory is checked for presence of the file, then user’s home directory.
<location> may also point to a remote URL:
phoebus.sh -settings http://mysite.com/settings.ini
Loading from URL assumes remote service does not respond with a redirect. Moreover, if using https, the remote URL must be backed by a trusted certificate.
At runtime, you can view the currently effective preference settings
from the menu Help
, About
. The Details
pane includes a tab
that lists all preference settings in the same format that is used by the
settings.ini
file. You can copy settings that you need to change
from the display into your settings file.
Settings loaded via the -settings ..
command line option
only remain effective while the application is running.
It is therefore necessary to always run the application with the same
-settings ..
command line option to get the same results.
In practice, it is advisable to include the -settings ..
command line option
in a site-specific application start script or add them to a site-specific
product as detailed below.
This way, new users do not need to remember any command line settings
because they are applied in the launcher script or bundled into the product.
Conceptually, preference settings are meant to hold critical configuration parameters like the control system network configuration. They are configured by system administrators, and once they are properly adjusted for your site, there is usually no need to change them.
Most important, these are not settings that an end user would need to see and frequently adjust during ordinary use of the application. For such runtime settings, each application needs to offer user interface options like context menus or configuration dialogs.
When you package phoebus for distribution at your site, you can also place
a file settings.ini
in the installation location (see Locations).
At startup, Phoebus will automatically load the file settings.ini
from the installation location, eliminating the need for your users or a launcher script
to add the -settings ..
command line option.
Developer Notes
In your code, create a file with a name that ends in *preferences.properties
.
In that file, list the available settings, with explanatory comments:
# ---------------------------------------
# Package org.phoebus.applications.my_app
# ---------------------------------------
# Note that the above
#
# "# Package name.of.your.package"
#
# is important. It is used to format the online help,
# and users will need to know the package name to
# assemble their settings file.
# Explain what each setting means,
# what values are allowed etc.
my_setting=SomeValue
# Enable some feature, allowed values are true or false
my_other_setting=true
In your application code, you can most conveniently access them like this:
package org.phoebus.applications.my_app
import org.phoebus.framework.preferences.AnnotatedPreferences;
import org.phoebus.framework.preferences.Preference;
class MyAppSettings
{
@Preference public static String my_setting;
@Preference public static boolean my_other_setting;
static
{
AnnotatedPreferences.initialize(MyAppSettings.class, "/my_app_preferences.properties");
}
}
The AnnotatedPreferences
helper will read your *preferences.properties
,
apply updates from java.util.prefs.Preferences
that have been added via -settings ..
, and then set the values
of all static fields annotated with @Preference
.
It handles basic types like int
, long
, double
, boolean
, String
,
File
. It can also parse comma-separated items into int[]
or String[]
.
By default, it uses the name of the field as the name of the preference setting,
which can be overridden via @Preference(name="name_of_settings")
.
If more elaborate settings need to be handled, AnnotatedPreferences.initialize
returns a PreferencesReader
, or you could directly use that lower level API like this:
package org.phoebus.applications.my_app
import org.phoebus.framework.preferences.PreferencesReader;
# The class that you pass here determines the package name for your preferences
final PreferencesReader prefs = new PreferencesReader(getClass(), "/my_app_preferences.properties");
String pref1 = prefs.get("my_setting");
Boolean pref2 = prefs.getBoolean("my_other_setting");
// .. use getInt, getDouble as needed.
// For more complex settings, use `get()` to fetch the string
// and parse as desired.
The PreferencesReader
loads defaults from the property file,
then allows overrides via the java.util.prefs.Preferences
API
that is used when loading a settings.ini
in the installation location
and by the -settings ..
provided on the command line.