How to use the Preferences Manager
Document #: ??
Authors: Louis Salvail (CWI)
Status: Draft Version. 1, SEMPER internal
To be done
- Improve exceptions handling,
- Allow selective Access Control for group operations.
- Integrate Profiles data management with interactive negotiations
The Preferences Block
works with 4 main classes:
- Configuration class is
responsible for the management of user configuration. In order to be
initialised, this class must be able to retrieve a configuration file
stored in the target files system.
It is possible to initialise with the default configuration file
or any other configuration file by specifying the path and the name
for that file.
- Preferences class :
is the front end for accessing user preferences.
This class must be initialised after Configuration initialisation
before being used. During initialisation, user preferences are retrieved
from the Archive via a default record. If the default file has not been
retrieved the manager is not initialised.
The Preferences Manager includes methods to construct preferences environment.
A preferences environment contains a set of preferences
groups. Operations on groups are:
group of preferences are defined in that class.
If there is no user preferences in the Archive, a new environment can be
built from scratch. Once this is done, the new environment can be saved
in the default record (or another one) and initialisation can now be performed.
- adding (addGroup),
- removing (delGroup) and
- getting (getGroup) a particular
This Preferences Class is responsible for:
- launching interactive edition (editGroup) is also
- storing (save) and
- retrieving (load) from the Archive Manager a previously
defined preferences environment.
- update() and cancel()
allow to record and cancel changes made by the user during
- PreGroup class
defines a set of preferences fields logically
put together. A group has an internal name by which further
references are made (this is a string). It is by the groupName
that references to that group are made through the Preferences
class. In addition, a label is attached to each group and used to
display the name of the group to the user (like the menu items in
the Test program). Methods
allow to add and
get a field for the current group. In addition,
It will also be possible to
- delField() method removes
a field of the current group.
- update() and cancel() methods
are used by the Preferences class to update or cancel user's
changes during interactive edition. These two methods should not
be used directly from the outside.
- save (savePrefGroup()) and
- load (loadPrefGroup()) a group
- showme(frame) add to the frame the components of the
group in the same order by which the fields have been added. This
is important for formatting reasons.
- PrefField class is an
abstract data class providing the methods
needed to define a preferences field. Each user-pereferences field
items is a subclass of that data class. Each field has a name by which
further references (through PrefGroup object) are made. A PrefField object
has a value which is
An important point is the appearance of a field.
A PrefField object always provide a
- get by the getValue() method and
- set by the setValue() method.
A PrefFrame object is placed into a frame by setting a set of
These values are used to display the current component according to
the previous one. The order by which the fields are added is important for
Methods cancel(), isModified(), applyModification() are used to manage
interactive edition of each field in the same way than explain
The method isOK(), return true if the new value of a field is allowed.
The Preferences manager does not record the user's changes if one field
of a group is not Ok.
- showme() method ables to put the
component in a PrefFrame .
Other classes are needed to help the three others:
- PrefFrame is a frame allowing to put each
field appearance. This frame
has a GridBagConstraints layout to allow flexible display. The PrefFrame
intercept an update of the values selected by the user after interactive
edition and a cancel of these modifications. The add(comp, csts) method
is used to add a new compoenent comp with the constraints csts to the
- The other classes:
are all subclasses of PrefField.
They define different field with different appearance. The most interesting
at that point is the PrefFieldNegotiable class which allows to define
fields to represent priority lists. The field looks like 2 lists of items,
the first one contains a list of unused items while the other is
the priority list itself. By selecting one element from the unused list
and one from the priority list the user indicate that the selected unused
item will be added in the priority list at the selected position. If no
poisition is selected in the priority list, the new item is added
in last position. It is also possible to select an item in the priority list
and put it back in the unused list. This class needs classes
to work properly.
PrList is the definition of the priority list and UnList is the
definition of the Unused list.
The two others are the buttons appearing in that component.
is the Panel used to put the different components for Negotiable Field.
How to create a Negotiation Field (other fields are similar)?
String it = new String;
it = new String( "item 1" );
it = new String( "item 2" );
it = new String( "item 3" );
it = new String( "item 4" );
it = new String( "item 5" );
it = new String( "item 6" );
PrefFieldNegotiable neg1 = new PrefFieldNegotiable( new String("neg1"),
Here cs is the constraints for the position of that field in the group. They
are GridBagConstraints from the stantard awt package. If you are not concern
with these constraints, you always have access to a constructor with no
constraints. In that case defaults are used. Every field is then put one
below the previous one. From the previous exemple:
- PrefFieldNegotiable neg1 = new PrefFieldNegotiable( new String("neg1"),
How to create a Group?
groupe1 = new PrefGroup(new String("G1"), new String("Group 1"));
groupe2 = new PrefGroup(new String("G2"),new String("Group 2"));
This two lines create two groups . To put a field in a group just call the
method put() provides by the PrefGroup class. To add neg1 in the group
groupe1 just perform:
You just have to continue like that until all fields are added in the group.
For more details on how to create groups see the PrefTestC.java file in the
How to create a Preferences environment?
To create a preferences envirnment, you just have to add group
in the Preferences class. If groupe1 and groupe2 have already been defined,
you can add them by doing:
How to get the values?
To get the values for a particular field, you must first retrieve
the group which contains the field you are looking for:
group = Preferences.getGroup("G1");
Now group contains the group having the name "G1". Now you can get the
the field with name "neg1" by doing:
field = group.get("neg1");
The field value is then obtain by calling:
val = field.getVal();
In that case, since that field is PrefFieldNegotiable field type the value
returned byt getVal is a vector. Thus, val.size() is the size for that vector
and val[i] contains the i^th string items in priority selected by the user.
In the same way, the value for a field can be changed.
Also available is the Test package.
Date: August, 1996 .