Adding additional documentation and optional parameters

redback-configuration/src/main/java/org/apache/archiva/redback/configuration/UserConfigurationKeys.java

@@ -169,4 +169,14 @@ public interface UserConfigurationKeys
     String REST_CSRF_ENABLED = "rest.csrffilter.enabled";
 
     String REST_CSRF_DISABLE_TOKEN_VALIDATION = "rest.csrffilter.disableTokenValidation";
+
+    /**
+     * Encoding used for reading mail templates / Default is UTF-8
+     */
+    String MAIL_TEMPLATE_ENCODING = "mail.template.encoding";
+
+    /**
+     * The locale to use for sending mails and finding mail templates
+     */
+    String MAIL_DEFAULT_LOCALE = "mail.locale";
 }

redback-integrations/redback-common-integrations/src/main/java/org/apache/archiva/redback/integration/mail/FreemarkerMailGenerator.java

@@ -36,6 +36,29 @@ import java.util.Locale;
 import java.util.Map;
 
 /**
+ * Mail generator that uses freemarker templates.
+ *
+ * This implementation sets the following model values that can be used in templates:
+ * <ul>
+ *     <li>applicationUrl</li>
+ *     <li>urlPath</li>
+ *     <li>authKey</li>
+ *     <li>accountId</li>
+ *     <li>requestedOn</li>
+ *     <li>expiresOn</li>
+ * </ul>
+ *
+ * The additional template data is added for interpolation, if not <code>null</code>.
+ *
+ * This implementation is location enabled. That means, it will try to find templates in the following order:
+ * <ul>
+ *     <li><i>templateName</i>_<i>language</i>_<i>country</i>.ftl</li>
+ *     <li><i>templateName</i>_<i>language</i>.ftl</li>
+ *     <li><i>templateName</i>.ftl</li>
+ * </ul>
+ *
+ * The default encoding used for reading the template is UTF-8
+ *
  * @author Martin Stockhammer <martin_s@apache.org>
  */
 @Service( "mailGenerator#freemarker" )
@@ -54,32 +77,67 @@ public class FreemarkerMailGenerator implements MailGenerator
 
     private String encoding;
 
-    private String getEncoding() {
+    private String getEncoding( )
-        if (this.encoding==null) {
+    {
-            this.encoding = config.getString( "mail.encoding", DEFAULT_ENCODING );
+        if ( this.encoding == null )
+        {
+            this.encoding = config.getString( UserConfigurationKeys.MAIL_TEMPLATE_ENCODING, DEFAULT_ENCODING );
         }
         return this.encoding;
     }
 
-    @Override
+    private Locale getMailLocale() {
-    public String generateMail( String templateName, AuthenticationKey authkey, String baseUrl )
+        String localeString = config.getString( UserConfigurationKeys.MAIL_DEFAULT_LOCALE );
-    {
+        if (localeString == null || "".equals(localeString)) {
-        Map<String, String> context = createModel( authkey, baseUrl );
+            return Locale.getDefault( );
+        } else {
+            return Locale.forLanguageTag( localeString );
+        }
+    }
 
+    /**
+     *
+     * @param templateName the template name without extension
+     * @param locale the locale used to find the template file
+     * @param authkey the authentication key
+     * @param baseUrl the base url
+     * @param templateData additional template data, may be <code>null</code>
+     * @return the string generated from the template
+     */
+    @Override
+    public String generateMail( String templateName, Locale locale, AuthenticationKey authkey, String baseUrl,
+                                Map<String, Object> templateData )
+    {
+        Map<String, Object> context = createModel( authkey, baseUrl, templateData );
         StringBuffer content = new StringBuffer( );
-        try{
+        try
+        {
             content.append( FreeMarkerTemplateUtils.processTemplateIntoString(
-                freemarkerConfiguration.getTemplate(templateName+".ftl"),context));
+                freemarkerConfiguration.getTemplate( templateName + ".ftl", locale, getEncoding( ) ), context ) );
             return content.toString( );
-        }catch(Exception e){
+        }
-            System.out.println("Exception occured while processing fmtemplate:"+e.getMessage());
+        catch ( Exception e )
+        {
+            log.error( "Could not parse the mail template {}: {}", templateName, e.getMessage( ), e );
         }
         return "";
     }
 
-    private Map<String, String> createModel( AuthenticationKey authkey, String appUrl )
+    @Override
+    public String generateMail( String templateName, AuthenticationKey authenticationKey, String baseUrl )
     {
-        Map<String, String> context = new HashMap<>( );
+        return generateMail( templateName, getMailLocale(), authenticationKey, baseUrl );
+    }
+
+    @Override
+    public String generateMail( String templateName, Locale locale, AuthenticationKey authenticationKey, String baseUrl )
+    {
+        return generateMail( templateName, locale, authenticationKey, baseUrl, null );
+    }
+
+    private Map<String, Object> createModel( AuthenticationKey authkey, String appUrl, Map<String, Object> templateData )
+    {
+        Map<String, Object> context = new HashMap<>( );
         context.put( "applicationUrl", config.getString( UserConfigurationKeys.APPLICATION_URL, appUrl ) );
 
         String feedback = config.getString( UserConfigurationKeys.EMAIL_FEEDBACK_PATH );
@@ -114,6 +172,15 @@ public class FreemarkerMailGenerator implements MailGenerator
         {
             context.put( "expiresOn", "(does not expire)" );
         }
+
+        if (templateData!=null)
+        {
+            for ( Map.Entry<String, Object> entry : templateData.entrySet( ) )
+            {
+                context.put( entry.getKey( ), entry.getValue( ) );
+            }
+        }
+
         return context;
     }
 

redback-integrations/redback-common-integrations/src/main/java/org/apache/archiva/redback/integration/mail/MailGenerator.java

@@ -21,6 +21,9 @@ package org.apache.archiva.redback.integration.mail;
 
 import org.apache.archiva.redback.keys.AuthenticationKey;
 
+import java.util.Locale;
+import java.util.Map;
+
 /**
  * Mail generator component.
  *
@@ -29,5 +32,45 @@ import org.apache.archiva.redback.keys.AuthenticationKey;
  */
 public interface MailGenerator
 {
+
+
+    /**
+     * Generates a mail string from a template. How the template will be located depends on the underlying
+     * implementation.
+     * It uses a default locale.
+     *
+     * @param templateName the template name without extension
+     * @param authkey the authentication key of the current user
+     * @param baseUrl  the base url
+     * @return A string for the mail body generated from the template
+     */
     String generateMail( String templateName, AuthenticationKey authkey, String baseUrl );
+
+    /**
+     * Generates a mail string from a template. The given locale is used for retrieving the template.
+     * How the template will be located depends on the underlying implementation.
+     *
+     * @param templateName the template name without extension
+     * @param locale the locale used to find the template file
+     * @param authenticationKey the authentication key of the current user
+     * @param baseUrl the base url
+     * @return a string for the mail body generated from the template
+     */
+    String generateMail( String templateName, Locale locale, AuthenticationKey authenticationKey, String baseUrl );
+
+    /**
+     * Generates a mail string from a template. The given locale is used for retrieving the template.
+     * How the template will be located depends on the underlying implementation.
+     * The templateData is used as model data that is interpolated from the template.
+     *
+     * @param templateName the template name without extension
+     * @param locale the locale used to find the template file
+     * @param authenticationKey the authentication key of the current user
+     * @param baseUrl the base url
+     * @param templateData additional data used for interpolation in the template
+     * @return a string for the mail body generated from the template
+     */
+    String generateMail( String templateName, Locale locale, AuthenticationKey authenticationKey, String baseUrl,
+                         Map<String, Object> templateData );
+
 }