email application

[shroffk]

• Service to create MimeMessages
• Send each mail request by submitting a job
• Preferences view to manage the host, username, password

ui components to create email entries which supports

• plain text
• html
• embedded images
• attachments

[kasemir]

In that list, preference for host, username, password is of course important, but preference UI isn't.
End users, for example beam line users, shouldn't have a need to configure it, in fact it should be impossible for them to accidentally change these settings.

[shroffk]

The email application uses the preferences api for reading the following preferences from the node:

User Preference Node: /org.phoebus.applications.email.EmailApp

#smtp host default localhost
mailhost
#smtp port default 25
mailport

username
password

If these preferences are not set via preference, then the default preferences are read from the properties file in the email application module
src/main/resources/email.properties

TODO: finalize the properties and preferences mapping and move this info to the help documentation.

[kasemir]

Yes, I found that code now.

Points to discuss:

I like the idea of having a properties file that lists the defaults and has comments to explain the settings.
If that file started with the node, it would contain all the information, no need to look for the node in the software:

# Preference Node: org.phoebus.applications.email.EmailApp

# smtp host
mailhost=localhost

For gettting the preferences, I suggest

Preferences prefs = Preferences.userNodeForPackage(this.getClass());

instead of

Preferences prefs = Preferences.userRoot().node(this.getClass().getName());

So you'd have "org.phoebus.applications.email" instead of "org.phoebus.applications.email.EmailApp".

Finally, we have no way to import settings of the type

org.phoebus.applications.email/mailhost=smtp.my_site.org

We can only import and export the XML format, which would be like

<preferences EXTERNAL_XML_VERSION="1.0">
  <root type="user">
    <map/>
    <node name="org">
      <map/>
      <node name="phoebus">
        <map/>
        <node name="applications">
          <map/>
          <node name="email">
            <map>
              <entry key="show_mailhost" value="smtp.my_site.org"/>

That's hard to type. It's somewhat OK, considering that only the site maintainer really needs to mess with it, if you can export, edit, import.
But for that we need to populate the preferences. If we just read, and when nothing found, parse the property file, the preferences remain empty and there's nothing in the export.
On http://phoebus-doc.readthedocs.io/en/latest/preferences.html#preferences-notes I thus describe the idea to always write when you read:

final Preferences prefs = Preferences.userNodeForPackage(SomeTopLevelClassOfMyModule.class);
String value = prefs.get("some_setting", "default_value");
prefs.put("some_setting", value);

Should we automate this?
Basically all that needs is this in FileSystemPreferences:

    public String get(String key, String def) {
        final String value = super.get(key, null);
        if (value == null)
        {
            super.put(key, def);
            return def;
        }
        return value;
    }

[shroffk]

Preferences prefs = Preferences.userNodeForPackage(this.getClass());
ok I agree...making the changes now

For the finally point:

importing and exporting xml format

This is fine since it is not somehting all users are gong to be dealing with.

If for any reason you are using the default value...either from a programmatic defined variable or from properties file then I don't think this should be written into preferences - not setting these values into the prefs should not have any impact, while keeping the preferences clean and not filled with lots of defaults. We should only put preferences when explicitly set by a user action or something.

[kasemir]

OK, so do we go with this:

1. Preferences use a package name, Preferences.userNodeForPackage(SomeTopLevelClassInYouApp.class);

2. Each app feature has a properties file that lists and explains the default preferences. Maybe call that "preferences.properties" so it's easy to spot? Should include the package name as a comment.

3. We do NOT write the preferences. So if you export preferences, that's mostly empty.

4. To set preferences, you for now need to locate the "preferences.properties" and construct the XML for import. The Launcher could support a settings import that reads a property file type of format with lines "package/setting=value" because that's MUCH easier to construct than the XML.

[shroffk]

Preferences use a package name, Preferences.userNodeForPackage(SomeTopLevelClassInYouApp.class);

yes

Each app feature has a properties file that lists and explains the default preferences. Maybe call that "preferences.properties" so it's easy to spot? Should include the package name as a comment.

yes

We do NOT write the preferences. So if you export preferences, that's mostly empty.

yes

To set preferences, you for now need to locate the "preferences.properties" and construct the XML for import. The Launcher could support a settings import that reads a property file type of format with lines "package/setting=value" because that's MUCH easier to construct than the XML.

yes

I like how much agreement is happening here.

[kasemir]

I've updated PVTable etc. to use *preferences.properties files.
#58 managed to get 1 of 2 travis runs to succeed, looks like the SF problem is recovering.

I think I'll add 2 more things:

1. A helper that you call with the *preferences.properties file name and the package name.
   It loads the properties, and has get(String) calls which use defaults from the prop file when reading prefs.

2. The manual build can look for all the *preferences.properties files in the sources and concat them into some appendix. So in there we'll then have a list of all the available settings with comments.