@sitevision/api 1.1.0-alpha.2 → 2.0.0-alpha.0

package/hidden/senselogic/sitevision/api/log/LogUtil/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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>
+ * @author Magnus Lövgren
+ */
+
+interface LogUtil {
+  /**
+   * 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
+   */
+  isTraceEnabled(): boolean;
+
+  /**
+   * Logs a trace message to the Sitevision server log.
+   * @param aMessage a message.
+   * @since Sitevision 4.1
+   */
+  trace(aMessage: java.lang.String): void;
+
+  /**
+   * Logs a trace message to the Sitevision server log.
+   * @param aMessage a message.
+   * @param aThrowable a throwable.
+   * @since Sitevision 4.1
+   */
+  trace(aMessage: java.lang.String, aThrowable: java.lang.Throwable): 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
+   */
+  isDebugEnabled(): boolean;
+
+  /**
+   * Logs a debug message to the Sitevision server log.
+   * @param aMessage a message.
+   */
+  debug(aMessage: java.lang.String): void;
+
+  /**
+   * Logs a debug message to the Sitevision server log.
+   * @param aMessage a message.
+   * @param aThrowable a throwable.
+   */
+  debug(aMessage: java.lang.String, aThrowable: java.lang.Throwable): void;
+
+  /**
+   * 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
+   */
+  isInfoEnabled(): boolean;
+
+  /**
+   * Logs an info message to the Sitevision server log.
+   * @param aMessage a message.
+   */
+  info(aMessage: java.lang.String): void;
+
+  /**
+   * Logs an info message to the Sitevision server log.
+   * @param aMessage a message.
+   * @param aThrowable a throwable.
+   */
+  info(aMessage: java.lang.String, aThrowable: java.lang.Throwable): void;
+
+  /**
+   * Checks if warn logging is enabled.
+   * @return <code>true</code> if warn logging is enabled, <code>false</code> otherwise
+   * @since Sitevision 4.1
+   */
+  isWarnEnabled(): boolean;
+
+  /**
+   * Logs a warn message to the Sitevision server log.
+   * @param aMessage a message.
+   */
+  warn(aMessage: java.lang.String): void;
+
+  /**
+   * Logs a warn message to the Sitevision server log.
+   * @param aMessage a message.
+   * @param aThrowable a throwable.
+   */
+  warn(aMessage: java.lang.String, aThrowable: java.lang.Throwable): void;
+
+  /**
+   * Checks if error logging is enabled.
+   * @return <code>true</code> if error logging is enabled, <code>false</code> otherwise
+   * @since Sitevision 4.1
+   */
+  isErrorEnabled(): boolean;
+
+  /**
+   * Logs an error message to the Sitevision server log.
+   * @param aMessage a message.
+   */
+  error(aMessage: java.lang.String): void;
+
+  /**
+   * Logs an error message to the Sitevision server log.
+   * @param aMessage a message.
+   * @param aThrowable a throwable.
+   */
+  error(aMessage: java.lang.String, aThrowable: java.lang.Throwable): void;
+}

package/hidden/senselogic/sitevision/api/mail/Mail/index.d.ts

@@ -4,10 +4,7 @@
  * <p>
  *    An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.mail.MailBuilder#build()}.
  *    See {@link senselogic.sitevision.api.mail.MailBuilder} for how to obtain an instance of the <code>MailBuilder</code> interface.
- * </p>Sends this mail synchronously.Sends this mail asynchronously.
- *
- * No information is returned to as if the mail was really sent as far as the actual mail server (whose configuration is specified on the
- * Sitevision server node). The mail might be queued, quarantined or silently ignored by the mail server.
+ * </p>
  * @author Magnus Lövgren
  * @since Sitevision 3.6
  * @see senselogic.sitevision.api.mail.MailBuilder

package/hidden/senselogic/sitevision/api/mail/Mail/index.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {
+  send: function send() {},
+  sendAsync: function sendAsync() {}
+};
+exports["default"] = _default;

package/hidden/senselogic/sitevision/api/mail/MailBuilder/index.d.ts

@@ -0,0 +1,221 @@
+import Mail from "../Mail";
+import Builder from "../../base/Builder";
+
+/**
+ * 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>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+
+interface MailBuilder {
+  /**
+   * 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
+   */
+  setFrom(aFromAddress: java.lang.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
+   */
+  addReplyTo(aReplyToAddress: java.lang.String): MailBuilder;
+
+  /**
+   * Removes all previously added reply-to addresses.
+   * @return this builder
+   */
+  clearReplyTos(): MailBuilder;
+
+  /**
+   * Sets the subject.
+   * @param aSubject a subject
+   * @return this builder
+   */
+  setSubject(aSubject: java.lang.String): MailBuilder;
+
+  /**
+   * Sets the text message.
+   * @param aTextMessage a text message
+   * @return this builder
+   */
+  setTextMessage(aTextMessage: java.lang.String): MailBuilder;
+
+  /**
+   * Sets the html message.
+   * @param aHtmlMessage a html message
+   * @return this builder
+   * @since Sitevision 4.3
+   */
+  setHtmlMessage(aHtmlMessage: java.lang.String): MailBuilder;
+
+  /**
+   * Adds a recipient address (TO).
+   * @param aRecipientAddress a recipient address. A null or whitespace-only address will be ignored.
+   * @return this builder
+   */
+  addRecipient(aRecipientAddress: java.lang.String): MailBuilder;
+
+  /**
+   * Removes all previously added recipient addresses (TO).
+   * @return this builder
+   */
+  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()
+   */
+  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
+   */
+  addCopyRecipient(aCopyRecipientAddress: java.lang.String): MailBuilder;
+
+  /**
+   * Removes all previously added carbon copy recipient addresses (CC).
+   * @return this builder
+   * @since Sitevision 3.6.3
+   */
+  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
+   */
+  addBlindCopyRecipient(
+    aBlindCopyRecipientAddress: java.lang.String
+  ): MailBuilder;
+
+  /**
+   * Removes all previously added blind carbon copy recipient addresses (BCC).
+   * @return this builder
+   * @since Sitevision 3.6.3
+   */
+  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.
+   */
+  build(): Mail;
+}

package/hidden/senselogic/sitevision/api/mail/MailUtil/index.d.ts

@@ -0,0 +1,72 @@
+import MailBuilder from "../MailBuilder";
+
+/**
+ * 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>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+
+interface MailUtil {
+  /**
+   * Returns a mail builder for creating mails.
+   * @return a mail builder
+   */
+  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.
+   */
+  isValidAddress(aMailAddress: java.lang.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
+   */
+  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
+   */
+  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
+   */
+  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
+   */
+  getServerFromAddress(): string;
+}

package/hidden/senselogic/sitevision/api/message/MessageTextLinker/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Message text rendering interface that detects and creates links in plain message texts.Creates links found in plain message text.
+ * Message text rendering interface that detects and creates links in plain message texts.
  * @author Magnus Lövgren
  * @since Sitevision 3.0.2
  */

package/hidden/senselogic/sitevision/api/message/MessageTextLinker/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _default = {
+  autoLink: function autoLink() {}
+};
+exports["default"] = _default;

package/hidden/senselogic/sitevision/api/metadata/MetadataDefinitionUtil/index.d.ts

@@ -0,0 +1,109 @@
+import Node from "../../../../../javax/jcr/Node";
+
+/**
+ * Utility interface for getting metadata definitions.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.Utils#getMetadataDefinitionUtil()}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>
+ *
+ * <p>
+ *    <strong>Velocity example:</strong> This code gets all properties and nodes for a metadata definition named 'aMetadataName'.
+ * </p>
+ *
+ * <pre><code>
+ *   #set ($page = ...)
+ *
+ *   #set ($definitionUtil = $sitevisionUtils.metadataDefinitionUtil)
+ *   #set($definition = $definitionUtil.getDefinition($page, 'aMetadataName'))
+ *
+ *   #set($nodes = $definition.getNodes())
+ *   #foreach($node in $nodes)
+ *      $node
+ *   #end
+ *
+ *   #set($properties = $definition.getProperties())
+ *   #foreach($property in $properties)
+ *      $property
+ *   #end
+ * </code></pre>
+ * @author Daniel Pyykkö
+ * @since Sitevision 2.6.2_04
+ */
+
+interface MetadataDefinitionUtil {
+  /**
+   * Gets a metadata definition as a {@code Node} from a {@code Node}.
+   * @param aNode the {@code Node} that has a metadata definition
+   * @param aDefinitionName the name of the metadata definition
+   * @return the value for {@code aDefinitionName} as a {@code Node}. If no definition exists or it is not a {@code Node}, {@code null} is returned.
+   */
+  getDefinition(aNode: Node, aDefinitionName: java.lang.String): Node;
+
+  /**
+   * Gets a metadata definition as a {@code Node} from a {@code Node} with a fallback value if the definition does not exist.
+   * @param aNode the {@code Node} that has a metadata definition
+   * @param aDefinitionName the name of the metadata definition
+   * @param aDefaultValue fallback value if no definition exists
+   * @return the value for {@code aDefinitionName} as a {@code Node}. If no definition exists or it is not a {@code Node}, {@code aDefaultValue} is returned.
+   */
+  getDefinition(
+    aNode: Node,
+    aDefinitionName: java.lang.String,
+    aDefaultValue: Node
+  ): Node;
+
+  /**
+   * Gets all metadata definitions available for the current user on a {@code Node}
+   * @param aNode the {@code Node} that has a metadata definition
+   * @return a list of definitions on {@code aNode}, or empty list
+   * @since Sitevision 4.2.3
+   */
+  getDefinitions(aNode: Node): unknown[];
+
+  /**
+   * Add an alternative to a definition
+   * @param aNode the {@code Node} where the metadata definition is located
+   * @param aDefinitionName the name of the metadata definition. May not be <code>null</code> or whitespace only
+   * @param aAlternativeName the name of the alternative (case in-sensitive). May not be <code>null</code> or whitespace only
+   * @throws RepositoryException if {@code aNode} is invalid, if {@code aNode} does not have a metadata definition named {@code aDefinitionName}, if it already contains an alternative named {@code aAlternativeName}, or if something else goes wrong
+   * @since Sitevision 4.2.3
+   */
+  addAlternative(
+    aNode: Node,
+    aDefinitionName: java.lang.String,
+    aAlternativeName: java.lang.String
+  ): void;
+
+  /**
+   * Rename an alternative for a definition
+   * @param aNode the {@code Node} where the metadata definition is located
+   * @param aDefinitionName the name of the metadata definition. May not be <code>null</code> or whitespace only
+   * @param aAlternativeName the name of the alternative (case in-sensitive). May not be <code>null</code> or whitespace only
+   * @param aNewAlternativeName the new name of the alternative. May not be <code>null</code> or whitespace only
+   * @throws RepositoryException if {@code aNode} is invalid, if {@code aNode} does not have a metadata definition named {@code aDefinitionName}, if it does not contain an alternative named {@code aAlternativeName}, if it already contains an alternative named {@code aNewAlternativeName}, or if something else goes wrong
+   * @since Sitevision 8.1
+   */
+  renameAlternative(
+    aNode: Node,
+    aDefinitionName: java.lang.String,
+    aAlternativeName: java.lang.String,
+    aNewAlternativeName: java.lang.String
+  ): void;
+
+  /**
+   * Remove an alternative from a definition
+   * @param aNode the {@code Node} where the metadata definition is located
+   * @param aDefinitionName the name of the metadata definition. May not be <code>null</code> or whitespace only
+   * @param aAlternativeName the name of the alternative (case in-sensitive). May not be <code>null</code> or whitespace only
+   * @throws RepositoryException if {@code aNode} is invalid, if {@code aNode} does not have a metadata definition named {@code aDefinitionName}, if it does not contain an alternative named {@code aAlternativeName}, or if something else goes wrong
+   * @since Sitevision 8.1
+   */
+  removeAlternative(
+    aNode: Node,
+    aDefinitionName: java.lang.String,
+    aAlternativeName: java.lang.String
+  ): void;
+}