How to use the Preferences Manager

Document #: ??
Authors: Louis Salvail (CWI)
Editor: (none)
Reviewer: (none)
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

General Remarks

• 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:
  • adding (addGroup),
  • removing (delGroup) and
  • getting (getGroup) a particular
  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. In addition, method for
  • launching interactive edition (editGroup) is also provided.
  This Preferences Class is responsible for:
  • storing (save) and
  • retrieving (load) from the Archive Manager a previously defined preferences environment.
  Methods
  • update() and cancel() allow to record and cancel changes made by the user during interactive edition.

  ---

• 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
  • put() and
  • get()
  allow to add and get a field for the current group. In addition,
  • 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.
  It will also be possible to
  • save (savePrefGroup()) and
  • load (loadPrefGroup()) a group
  from Archive. The method
  • 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
  • get by the getValue() method and
  • set by the setValue() method.
  An important point is the appearance of a field. A PrefField object always provide a
  • showme() method ables to put the component in a PrefFrame .
  A PrefFrame object is placed into a frame by setting a set of GridBagConstraints values. 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 that reason. Methods cancel(), isModified(), applyModification() are used to manage interactive edition of each field in the same way than explain before . 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.

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 frame.
• The other classes:
  • PrefFieldLabel ,
  • PrefFieldString ,
  • PrefFieldChoice ,
  • PrefFieldNegotiable ,
  • PrefFieldCheckBox
  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
  • PrList ,
  • UnList ,
  • MoveButton and
  • RemoveButton
  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. NegotiablePanel 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[6];
  it[0] = new String( "item 1" );
  it[1] = new String( "item 2" );
  it[2] = new String( "item 3" );
  it[3] = new String( "item 4" );
  it[4] = new String( "item 5" );
  it[5] = new String( "item 6" );
  PrefFieldNegotiable neg1 = new PrefFieldNegotiable( new String("neg1"), it, 4, cs);

  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"), it, 4);

  ---

  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:
  groupe1.put(neg1);
  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 Test directory.

  ---

  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:

  Preferences.addGroup(groupe1);
  Preferences.addGroup(groupe2);

  ---

  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 .