validateSystemSettings

This method allows your component to verify that any system settings it needs in order to operate are set correctly. For example, the Kettle component (org.pentaho.plugin.kettle.KettleComponent) checks it system settings to see if it is configured for a file-based or RBDMS-based repository. In another example, the email component (org.pentaho.plugin.email.EmailComponent) uses its system settings to connect to your email server.

System-wide settings for components should be stored in XML documents in the 'system' folder in the Pentaho solution root folder. System settings are ones that will be the same for every instance of your component and that won't change while the server or application is running (unless manually changed by an administrator).

In the system folder you will see subdirectories such as 'kettle', 'quartz', and 'smtp-email'. If your component needs system settings you can create a directory to store your settings in and place an XML file in the directory. The XML file can be named anything that you like. Within the XML document you can arrange the settings in any format that you like. The settings file for the email component provides a good example of a settings file. Within the root solution folder the path to the email settings file is 'system/smtp-email/email_config.xml'.

<email-smtp>

   <!-- The values within <properties> are passed directly to the JavaMail API.
   For a list of valid properties see
   http://java.sun.com/products/javamail/javadocs/index.html -->
   <properties>
      <!-- This is the address of your SMTP email server for sending email. e.g.
           smtp.pentaho.org -->
      <mail.smtp.host></mail.smtp.host>

      <!-- This is the port of your SMTP email server. Usually this is 25.
           For GMail this is 587 -->
      <mail.smtp.port>25</mail.smtp.port>

      <!-- The transport for accessing the email server. Usually this is smtp.
           For GMail this is smtps -->
      <mail.transport.protocol>smtp</mail.transport.protocol>

      <!-- Usually this is 'false'. For GMail it is 'true' -->
      <mail.smtp.starttls.enable>false</mail.smtp.starttls.enable>

      <!-- Set to true if the email server requires the sender to authenticate -->
      <mail.smtp.auth>true</mail.smtp.auth>

      <!-- This is true if the email server requires an SSL connection.
           Usually 'false'. For GMail this is 'true' -->
      <mail.smtp.ssl>false</mail.smtp.ssl>

      <!-- Output debug information from the JavaMail API -->
      <mail.debug>false</mail.debug>
   </properties>

   <!-- This is the default 'from' address that emails from the Pentaho BI Suite
        will appear to come from e.g. joe.pentaho@pentaho.org -->
   <mail.from.default>joe.pentaho@pentaho.org</mail.from.default>

   <!-- This is the user id used to connect to the email server for sending email
        It is only required if email-authenticate is set to true
        This is never sent or shown to anyone -->
   <mail.userid></mail.userid>

   <!-- This is the password used to connect to the email server for sending email
        It is only required if email-authenticate is set to true
        This is never sent or shown to anyone -->
   <mail.password></mail.password>

</email-smtp>

The email component accesses these settings by calling PentahoSystem.getSystemSetting(). For example:

String mailhost = PentahoSystem.getSystemSetting("smtp-email/email_config.xml",     "mail.smtp.host", null);

The getSystemSetting() method finds an entry in a system setting file and returns it to the component. The component does not need to know where the system settings files are located.