@sitevision/api 1.0.19 → 1.1.0-alpha.1

package/server/LogUtil/index.d.ts

@@ -1,113 +1,154 @@
-import Throwable from '../../builtins/Throwable';
-
-/**
-* Logs a debug message to the Sitevision server log.
-* @param {string} aMessage - a message.
-*/
-export function debug(aMessage: string): void;
-  
 /**
-* Logs a debug message to the Sitevision server log.
-* @param {string} aMessage - a message.
-* @param {Throwable} aThrowable - a throwable.
-*/
-export function debug(aMessage: string, aThrowable: Throwable): void;
+ * Checks if trace logging is enabled.
+ *
+ * <p>
+ *    Appropriate to check first if you are about to do extensive/expensive trace logging.
+ * </p>
+ * @return <code>true</code> if trace logging is enabled, <code>false</code> otherwise
+ * @since Sitevision 4.1
+ */
+export function isTraceEnabled(): boolean;
 
 /**
-* Logs an error message to the Sitevision server log.
-* @param {string} aMessage - a message.
-*/
-export function error(aMessage: string): void;
+ * Logs a trace message to the Sitevision server log.
+ * @param aMessage a message.
+ * @since Sitevision 4.1
+ */
+export function trace(aMessage: string): void;
 
 /**
-* Logs an error message to the Sitevision server log.
-* @param {string} aMessage - a message.
-* @param {Throwable} aThrowable - a throwable.
-*/
-export function error(aMessage: string, aThrowable: Throwable): void;
+ * Logs a trace message to the Sitevision server log.
+ * @param aMessage a message.
+ * @param aThrowable a throwable.
+ * @since Sitevision 4.1
+ */
+export function trace(aMessage: string, aThrowable: unknown): void;
 
 /**
-* Logs an info message to the Sitevision server log.
-* @param {string} aMessage - a message.
-*/
-export function info(aMessage: string): void;
+ * Checks if debug logging is enabled.
+ *
+ * <p>
+ *    Appropriate to check first if you are about to do extensive/expensive debug logging.
+ * </p>
+ * @return <code>true</code> if debug logging is enabled, <code>false</code> otherwise
+ * @since Sitevision 3.0
+ */
+export function isDebugEnabled(): boolean;
 
 /**
-* Logs an info message to the Sitevision server log.
-* @param {string} aMessage - a message.
-* @param {Throwable} aThrowable - a throwable.
-*/
-export function info(aMessage: string, aThrowable: Throwable): void;
+ * Logs a debug message to the Sitevision server log.
+ * @param aMessage a message.
+ */
+export function debug(aMessage: string): void;
 
 /**
-* Checks if debug logging is enabled.
-* @returns {boolean} true if debug logging is enabled, false otherwise 
-*/
-export function isDebugEnabled(): boolean;
+ * Logs a debug message to the Sitevision server log.
+ * @param aMessage a message.
+ * @param aThrowable a throwable.
+ */
+export function debug(aMessage: string, aThrowable: unknown): void;
 
 /**
-* Checks if error logging is enabled.
-* @returns {boolean} true if error logging is enabled, false otherwise 
-*/
-export function isErrorEnabled(): boolean;
+ * Checks if info logging is enabled.
+ *
+ * <p>
+ *    Appropriate to check first if you are about to do extensive/expensive info logging.
+ * </p>
+ * @return <code>true</code> if info logging is enabled, <code>false</code> otherwise
+ * @since Sitevision 4.1
+ */
+export function isInfoEnabled(): boolean;
 
 /**
-* Checks if info logging is enabled.
-* @returns {boolean} true if info logging is enabled, false otherwise 
-*/
-export function isInfoEnabled(): boolean;
+ * Logs an info message to the Sitevision server log.
+ * @param aMessage a message.
+ */
+export function info(aMessage: string): void;
 
 /**
-* Checks if trace logging is enabled.
-* @returns {boolean} true if trace logging is enabled, false otherwise 
-*/
-export function isTraceEnabled(): boolean;
+ * Logs an info message to the Sitevision server log.
+ * @param aMessage a message.
+ * @param aThrowable a throwable.
+ */
+export function info(aMessage: string, aThrowable: unknown): void;
 
 /**
-* Checks if warn logging is enabled.
-* @returns {boolean} true if warn logging is enabled, false otherwise 
-*/
+ * Checks if warn logging is enabled.
+ * @return <code>true</code> if warn logging is enabled, <code>false</code> otherwise
+ * @since Sitevision 4.1
+ */
 export function isWarnEnabled(): boolean;
 
 /**
-* Logs a trace message to the Sitevision server log.
-* @param {string} aMessage - a message.
-*/
-export function trace(aMessage: string): void;
+ * Logs a warn message to the Sitevision server log.
+ * @param aMessage a message.
+ */
+export function warn(aMessage: string): void;
 
 /**
-* Logs a trace message to the Sitevision server log.
-* @param {string} aMessage - a message.
-* @param {Throwable} aThrowable - a throwable.
-*/
-export function trace(aMessage: string, aThrowable: Throwable): void;
+ * Logs a warn message to the Sitevision server log.
+ * @param aMessage a message.
+ * @param aThrowable a throwable.
+ */
+export function warn(aMessage: string, aThrowable: unknown): void;
 
 /**
-* Logs a warn message to the Sitevision server log.
-* @param {string} aMessage - a message.
-*/
-export function warn(aMessage: string): void;
+ * Checks if error logging is enabled.
+ * @return <code>true</code> if error logging is enabled, <code>false</code> otherwise
+ * @since Sitevision 4.1
+ */
+export function isErrorEnabled(): boolean;
 
 /**
-* Logs a warn message to the Sitevision server log.
-* @param {string} aMessage - a message.
-* @param {Throwable} aThrowable - a throwable.
-*/
-export function warn(aMessage: string, aThrowable: Throwable): void;
+ * Logs an error message to the Sitevision server log.
+ * @param aMessage a message.
+ */
+export function error(aMessage: string): void;
 
-declare namespace logUtil {
+/**
+ * Logs an error message to the Sitevision server log.
+ * @param aMessage a message.
+ * @param aThrowable a throwable.
+ */
+export function error(aMessage: string, aThrowable: unknown): void;
+
+/**
+ * Logging utility class for simple logging to the Sitevision server log.
+ * <p>
+ *    If you implement a custom portlet you would typically use a logging framework, not this class.
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.Utils#getLogUtil()}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>Checks if trace logging is enabled.
+ *
+ * <p>
+ *    Appropriate to check first if you are about to do extensive/expensive trace logging.
+ * </p>Logs a trace message to the Sitevision server log.Logs a trace message to the Sitevision server log.Checks if debug logging is enabled.
+ *
+ * <p>
+ *    Appropriate to check first if you are about to do extensive/expensive debug logging.
+ * </p>Logs a debug message to the Sitevision server log.Logs a debug message to the Sitevision server log.Checks if info logging is enabled.
+ *
+ * <p>
+ *    Appropriate to check first if you are about to do extensive/expensive info logging.
+ * </p>Logs an info message to the Sitevision server log.Logs an info message to the Sitevision server log.Checks if warn logging is enabled.Logs a warn message to the Sitevision server log.Logs a warn message to the Sitevision server log.Checks if error logging is enabled.Logs an error message to the Sitevision server log.Logs an error message to the Sitevision server log.
+ * @author Magnus Lövgren
+ */
+declare namespace LogUtil {
   export {
-    debug,   
-    error,  
-    info,   
+    isTraceEnabled,
+    trace,
     isDebugEnabled,
-    isErrorEnabled,
+    debug,
     isInfoEnabled,
-    isTraceEnabled,
+    info,
     isWarnEnabled,
-    trace,   
-    warn,   
+    warn,
+    isErrorEnabled,
+    error,
   };
 }
 
-export default logUtil;
+export default LogUtil;

package/server/MailBuilder/index.d.ts

@@ -0,0 +1,238 @@
+import Mail from "../../hidden/senselogic/sitevision/api/mail/Mail";
+
+/**
+ * Sets the from address.
+ * @param aFromAddress the from address. A whitespace-only address will be ignored, default (null) will be set instead.
+ * @return this builder
+ */
+export function setFrom(aFromAddress: string): MailBuilder;
+
+/**
+ * Adds a reply-to address.
+ * @param aReplyToAddress a reply-to address. A null or whitespace-only address will be ignored.
+ * @return this builder
+ */
+export function addReplyTo(aReplyToAddress: string): MailBuilder;
+
+/**
+ * Removes all previously added reply-to addresses.
+ * @return this builder
+ */
+export function clearReplyTos(): MailBuilder;
+
+/**
+ * Sets the subject.
+ * @param aSubject a subject
+ * @return this builder
+ */
+export function setSubject(aSubject: string): MailBuilder;
+
+/**
+ * Sets the text message.
+ * @param aTextMessage a text message
+ * @return this builder
+ */
+export function setTextMessage(aTextMessage: string): MailBuilder;
+
+/**
+ * Sets the html message.
+ * @param aHtmlMessage a html message
+ * @return this builder
+ * @since Sitevision 4.3
+ */
+export function setHtmlMessage(aHtmlMessage: string): MailBuilder;
+
+/**
+ * Adds a recipient address (TO).
+ * @param aRecipientAddress a recipient address. A null or whitespace-only address will be ignored.
+ * @return this builder
+ */
+export function addRecipient(aRecipientAddress: string): MailBuilder;
+
+/**
+ * Removes all previously added recipient addresses (TO).
+ * @return this builder
+ */
+export function clearRecipients(): MailBuilder;
+
+/**
+ * Convenience method for removing all addresses for all recipient types (TO/CC/BCC).
+ * @return this builder
+ * @since Sitevision 3.6.3
+ * @see #clearRecipients()
+ * @see #clearCopyRecipients()
+ * @see #clearBlindCopyRecipients()
+ */
+export function clearAllRecipients(): MailBuilder;
+
+/**
+ * Adds a carbon copy recipient address (CC).
+ * @param aCopyRecipientAddress a carbon copy recipient address. A null or whitespace-only address will be ignored.
+ * @return this builder
+ * @since Sitevision 3.6.3
+ */
+export function addCopyRecipient(aCopyRecipientAddress: string): MailBuilder;
+
+/**
+ * Removes all previously added carbon copy recipient addresses (CC).
+ * @return this builder
+ * @since Sitevision 3.6.3
+ */
+export function clearCopyRecipients(): MailBuilder;
+
+/**
+ * Adds a blind carbon copy recipient address (BCC).
+ * @param aBlindCopyRecipientAddress a blind carbon copy recipient address. A null or whitespace-only address will be ignored.
+ * @return this builder
+ * @since Sitevision 3.6.3
+ */
+export function addBlindCopyRecipient(
+  aBlindCopyRecipientAddress: string
+): MailBuilder;
+
+/**
+ * Removes all previously added blind carbon copy recipient addresses (BCC).
+ * @return this builder
+ * @since Sitevision 3.6.3
+ */
+export function clearBlindCopyRecipients(): MailBuilder;
+
+/**
+ * Creates a Mail instance using current state of this builder.
+ * @return a mail that can be sent
+ * @throws IllegalStateException will be thrown if subject is null, if there are no recipients or if a recipient address is invalid, if the from address, a copy address, blind copy address or reply-to address is invalid.
+ */
+export function build(): Mail;
+
+/**
+ * Builder to create a Mail instances that can be sent.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.mail.MailUtil#getMailBuilder()}.
+ *    See {@link senselogic.sitevision.api.mail.MailUtil} for how to obtain an instance of the <code>MailUtil</code> interface.
+ * </p>
+ *
+ * <p>
+ *    MailBuilder has some <strong>mandatory attributes</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>subject</em> - The mail subject. Must be non-null.
+ *    </li>
+ *    <li>
+ *       <em>message</em> - The mail message. Can be a text message (text/plain), a html message (text/html), or both. Must be non-null.
+ *    </li>
+ *    <li>
+ *       <em>recipients</em> - The mail recipient (TO). At least one recipient must be added.
+ *    </li>
+ * </ul>
+ * <p>
+ *    MailBuilder also has some <strong>optional attributes</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>copyRecipients</em> - The carbon copy recipients (CC). Default is <code>null</code>.
+ *    </li>
+ *    <li>
+ *       <em>blindCopyRecipients</em> - The blind carbon copy recipients (BCC). Default is <code>null</code>.
+ *    </li>
+ *    <li>
+ *       <em>fromAddress</em> - The from address. Default is the address of the site responsible and the
+ *       address of the server responsible as fallback.
+ *    </li>
+ *    <li>
+ *       <em>replyTos</em> - The reply-to addresses. Default is <code>null</code>.
+ *    </li>
+ * </ul>
+ *
+ * <p>
+ *    <em>Note that there are three types of recipients (TO, CC, BCC). This builder will not detect or automatically handle duplicates
+ *    cross types. It is up to the mail builder user to ensure addresses aren't added as different types of recipients.</em>
+ * </p>
+ *
+ * <p>
+ *    Using the MailBuilder is pretty straightforward, if you remember that it is <strong>stateful</strong>. Conceptually you
+ *    would typically use it like this:
+ * </p>
+ * <ol>
+ *   <li>Get the MailBuilder</li>
+ *   <li>Set the subject</li>
+ *   <li>Set the text message</li>
+ *   <li>Add a recipient</li>
+ *   <li>Possibly add another recipient</li>
+ *   <li>Possibly set the from address</li>
+ *   <li>Possibly add a reply-to address</li>
+ *   <li>Possibly add another reply-to address</li>
+ *   <li>Do build (+ send)</li>
+ * </ol>
+ * <p>
+ *    When you have built a <code>Mail</code> instance, you can re-use the MailBuilder to build more instances. Something like:
+ * </p>
+ * <ol>
+ *   <li>Set a new subject</li>
+ *   <li>Set a new text message</li>
+ *   <li>Clear recipients</li>
+ *   <li>Add a new recipient</li>
+ *   <li>Do build (+ send)</li>
+ * </ol>
+ *
+ * <p>
+ *    <strong>Example of how this strategy could be implemented in Velocity:</strong><br>
+ *    (send one "personalized" mail to Magnus and one to Mikael)
+ * </p>
+ * <pre><code>
+ *   <em>## Get the mail util and the mail builder</em>
+ *   #set ($mailUtil = $sitevisionUtils.mailUtil)
+ *   #set ($mailBuilder = $mailUtil.mailBuilder)
+ *
+ *   <em>## Create a mail</em>
+ *   #set ($mail = $mailBuilder.setSubject('Hello buddy'
+ *                            ).setTextMessage('How are you Magnus?'
+ *                            ).addRecipient('magnus.lovgren@sitevision.se'
+ *                            ).build())
+ *   <em>## Send mail</em>
+ *   #if ($mail.send())
+ *      &lt;p&gt;Mail to Magnus successfully sent!&lt;/p&gt;
+ *   #else
+ *      &lt;p&gt;Mail to Magnus could &lt;strong&gt;not&lt;/strong&gt; be sent!&lt;/p&gt;
+ *   #end
+ *
+ *   <em>## Create another mail</em>
+ *   #set ($mail = $mailBuilder.setTextMessage('How are you Mikael?'
+ *                            ).clearRecipients().addRecipient('mikael.wikblom@sitevision.se'
+ *                            ).build())
+ *   <em>## Send mail</em>
+ *   #if ($mail.send())
+ *      &lt;p&gt;Mail to Mikael successfully sent!&lt;/p&gt;
+ *   #else
+ *      &lt;p&gt;Mail to Mikael could &lt;strong&gt;not&lt;/strong&gt; be sent!&lt;/p&gt;
+ *   #end
+ * </code></pre>
+ * <p>
+ *    <strong>Tip!</strong> The {@link senselogic.sitevision.api.base.Builder Builder interface documentation} contains
+ *    more information about Builders and how to work with them!
+ * </p>Sets the from address.Adds a reply-to address.Removes all previously added reply-to addresses.Sets the subject.Sets the text message.Sets the html message.Adds a recipient address (TO).Removes all previously added recipient addresses (TO).Convenience method for removing all addresses for all recipient types (TO/CC/BCC).Adds a carbon copy recipient address (CC).Removes all previously added carbon copy recipient addresses (CC).Adds a blind carbon copy recipient address (BCC).Removes all previously added blind carbon copy recipient addresses (BCC).Creates a Mail instance using current state of this builder.
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+declare namespace MailBuilder {
+  export {
+    setFrom,
+    addReplyTo,
+    clearReplyTos,
+    setSubject,
+    setTextMessage,
+    setHtmlMessage,
+    addRecipient,
+    clearRecipients,
+    clearAllRecipients,
+    addCopyRecipient,
+    clearCopyRecipients,
+    addBlindCopyRecipient,
+    clearBlindCopyRecipients,
+    build,
+  };
+}
+
+export default MailBuilder;

package/server/MailUtil/index.d.ts

@@ -0,0 +1,98 @@
+import MailBuilder from "../MailBuilder";
+
+/**
+ * Returns a mail builder for creating mails.
+ * @return a mail builder
+ */
+export function getMailBuilder(): MailBuilder;
+
+/**
+ * Checks if a mail address has a valid format.
+ * @param aMailAddress the address to check
+ * @return <code>true</code> if <code>aMailAddress</code> has a valid format and can be used to create a <code>javax.mail.internet.InternetAddress</code>, <code>false</code> otherwise.
+ */
+export function isValidAddress(aMailAddress: string): boolean;
+
+/**
+ * Gets the mail address of the site responsible.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>
+ * @return the mail address of the site responsible, or <code>null</code> if there are no address or if it's whitespace only
+ */
+export function getSiteResponsibleAddress(): string;
+
+/**
+ * Gets the from mail address of current site.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>
+ * @return the from mail address of current site, or <code>null</code> if there are no address or if it's whitespace only
+ */
+export function getSiteFromAddress(): string;
+
+/**
+ * Gets the mail address of the server responsible.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>
+ * @return the mail address of the server responsible, or <code>null</code> if there are no address or if it's whitespace only
+ */
+export function getServerResponsibleAddress(): string;
+
+/**
+ * Gets the server from mail address.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>
+ * @return the server from mail address, or <code>null</code> if there are no address or if it's whitespace only
+ */
+export function getServerFromAddress(): string;
+
+/**
+ * Mail utility interface.
+ *
+ * <p>
+ * An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.Utils#getMailUtil()}.
+ * See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>
+ *
+ * <p>
+ *    <em>Note!</em> To send one or more mails, you must use a {@link MailBuilder}.
+ *    Use the {@link #getMailBuilder()} method to get a builder instance.
+ * </p>Returns a mail builder for creating mails.Checks if a mail address has a valid format.Gets the mail address of the site responsible.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>Gets the from mail address of current site.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>Gets the mail address of the server responsible.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>Gets the server from mail address.
+ *
+ * <p>
+ *    <strong>Note!</strong> The returned address is <em>not</em> validated, i.e. it might be an invalid mail address.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+declare namespace MailUtil {
+  export {
+    getMailBuilder,
+    isValidAddress,
+    getSiteResponsibleAddress,
+    getSiteFromAddress,
+    getServerResponsibleAddress,
+    getServerFromAddress,
+  };
+}
+
+export default MailUtil;