@sitevision/api 2023.2.1 → 2023.2.2-beta.2

package/server/LinkTargetBuilder/index.d.ts

@@ -1,64 +1,65 @@
 import type { Node } from "../../types/javax/jcr/Node";
+import type { String } from "../../types/java/lang/String";
 
 import type { LinkTarget } from "../../types/senselogic/sitevision/api/webresource/LinkTarget";
 import type { Builder } from "../../types/senselogic/sitevision/api/base/Builder";
 
 /**
  * Builder to create link target instances that can be used to create and update a Link page
- * via {@link senselogic.sitevision.api.webresource.LinkPageUtil}.
+ *  via {@link senselogic.sitevision.api.webresource.LinkPageUtil}.
  *
- * <p>
- *    LinkTargetBuilder has one <strong>mandatory attribute</strong>:
- * </p>
- * <ul>
- *    <li>
- *       <em>target</em> - The target. Must be non-null.
- *    </li>
- * </ul>
- * <p>
- *    LinkTargetBuilder also has some <strong>optional attributes</strong>:
- * </p>
- * <ul>
- *    <li>
- *       <em>description</em> - The description. Default is <code>null</code>.
- *    </li>
- *    <li>
- *       <em>open in new window</em> - Whether or not the target should be opened in new window. Default is <code>false</code>.
- *    </li>
- * </ul>
+ *  <p>
+ *     LinkTargetBuilder has one <strong>mandatory attribute</strong>:
+ *  </p>
+ *  <ul>
+ *     <li>
+ *        <em>target</em> - The target. Must be non-null.
+ *     </li>
+ *  </ul>
+ *  <p>
+ *     LinkTargetBuilder also has some <strong>optional attributes</strong>:
+ *  </p>
+ *  <ul>
+ *     <li>
+ *        <em>description</em> - The description. Default is <code>null</code>.
+ *     </li>
+ *     <li>
+ *        <em>open in new window</em> - Whether or not the target should be opened in new window. Default is <code>false</code>.
+ *     </li>
+ *  </ul>
  *
- * <p>
- *    Using the LinkTargetBuilder 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 LinkTargetBuilder</li>
- *   <li>Set the target</li>
- *   <li>Possibly set a description</li>
- *   <li>Possibly set open in new window</li>
- *   <li>Do build</li>
- * </ol>
- * <p>
- *    When you have built a <code>LinkTarget</code> instance, you can re-use the LinkTargetBuilder to build more instances. Something like:
- * </p>
- * <ol>
- *   <li>Set a new target</li>
- *   <li>Possibly set a description</li>
- *   <li>Possibly set open in new window</li>
- *   <li>Do build</li>
- * </ol>
+ *  <p>
+ *     Using the LinkTargetBuilder 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 LinkTargetBuilder</li>
+ *    <li>Set the target</li>
+ *    <li>Possibly set a description</li>
+ *    <li>Possibly set open in new window</li>
+ *    <li>Do build</li>
+ *  </ol>
+ *  <p>
+ *     When you have built a <code>LinkTarget</code> instance, you can re-use the LinkTargetBuilder to build more instances. Something like:
+ *  </p>
+ *  <ol>
+ *    <li>Set a new target</li>
+ *    <li>Possibly set a description</li>
+ *    <li>Possibly set open in new window</li>
+ *    <li>Do build</li>
+ *  </ol>
  *
- * <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>
+ *  <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>
  *
- * <p>
- *    An instance of the Sitevision class implementing this interface can be obtained via
- *    {@link senselogic.sitevision.api.webresource.WebResourceFactory#getLinkTargetBuilder()}.
- *    See {@link senselogic.sitevision.api.webresource.WebResourceFactory} for how to obtain an instance of the
- *    <code>WebResourceFactory</code> interface.
- * </p>
+ *  <p>
+ *     An instance of the Sitevision class implementing this interface can be obtained via
+ *     {@link senselogic.sitevision.api.webresource.WebResourceFactory#getLinkTargetBuilder()}.
+ *     See {@link senselogic.sitevision.api.webresource.WebResourceFactory} for how to obtain an instance of the
+ *     <code>WebResourceFactory</code> interface.
+ *  </p>
  * @author Magnus Lövgren
  * @since Sitevision 4.2
  * @see senselogic.sitevision.api.webresource.LinkPageUtil
@@ -78,7 +79,7 @@ export interface LinkTargetBuilder extends Builder {
    * @return this builder
    * @throws IllegalArgumentException if <code>aURL</code> is <code>null</code> or whitespace only
    */
-  setExternalTarget(aURL: string): LinkTargetBuilder;
+  setExternalTarget(aURL: String | string): LinkTargetBuilder;
 
   /**
    * Sets the target.
@@ -87,7 +88,7 @@ export interface LinkTargetBuilder extends Builder {
    * @throws IllegalArgumentException if <code>aMailAddress</code> is <code>null</code>, whitespace only or an invalid mail address.
    * @see senselogic.sitevision.api.mail.MailUtil#isValidAddress(String)
    */
-  setMailTarget(aMailAddress: string): LinkTargetBuilder;
+  setMailTarget(aMailAddress: String | string): LinkTargetBuilder;
 
   /**
    * Sets the target.
@@ -95,14 +96,14 @@ export interface LinkTargetBuilder extends Builder {
    * @return this builder
    * @throws IllegalArgumentException if <code>aPhoneNumber</code> is <code>null</code>, whitespace only or an invalid phone number.
    */
-  setPhoneTarget(aPhoneNumber: string): LinkTargetBuilder;
+  setPhoneTarget(aPhoneNumber: String | string): LinkTargetBuilder;
 
   /**
    * Sets the description.
    * @param aDescription the description
    * @return this builder
    */
-  setDescription(aDescription: string): LinkTargetBuilder;
+  setDescription(aDescription: String | string): LinkTargetBuilder;
 
   /**
    * Sets open in new window.
@@ -114,12 +115,12 @@ export interface LinkTargetBuilder extends Builder {
   /**
    * Creates a LinkTarget instance using current state of this builder.
    *
-   * <p>
-   *    <em>
-   *       Note! The 'open in new window' state is ignored when creating a LinkTarget with
-   *       a mail or telephone target (these target types can never be opened in a new window).
-   *    </em>
-   * </p>
+   *  <p>
+   *     <em>
+   *        Note! The 'open in new window' state is ignored when creating a LinkTarget with
+   *        a mail or telephone target (these target types can never be opened in a new window).
+   *     </em>
+   *  </p>
    * @return a link target
    * @throws IllegalStateException if there are no link target.
    */

package/server/LinkValueBuilder/index.d.ts

@@ -1,3 +1,4 @@
+import type { String } from "../../types/java/lang/String";
 import type { Node } from "../../types/javax/jcr/Node";
 
 import type { LinkValue } from "../../types/senselogic/sitevision/api/metadata/value/LinkValue";
@@ -6,62 +7,62 @@ import type { Builder } from "../../types/senselogic/sitevision/api/base/Builder
 /**
  * Builder to create LinkValue instances that can be used to set link metadata.
  *
- * <p>
- *    LinkValueBuilder has one <strong>mandatory attribute</strong>:
- * </p>
- * <ul>
- *    <li>
- *       <em>target</em> - The link target. Must be non-null.
- *    </li>
- * </ul>
- * <p>
- *    LinkValueBuilder also has some <strong>optional attributes</strong>:
- * </p>
- * <ul>
- *    <li>
- *       <em>name</em> - The link name. Default is <code>null</code>.
- *    </li>
- *    <li>
- *       <em>description</em> - The Link description. Default is <code>null</code>.
- *    </li>
- *    <li>
- *       <em>open in new window</em> - Whether or not the link should be opened in new window. Default is <code>false</code>.
- *    </li>
- * </ul>
+ *  <p>
+ *     LinkValueBuilder has one <strong>mandatory attribute</strong>:
+ *  </p>
+ *  <ul>
+ *     <li>
+ *        <em>target</em> - The link target. Must be non-null.
+ *     </li>
+ *  </ul>
+ *  <p>
+ *     LinkValueBuilder also has some <strong>optional attributes</strong>:
+ *  </p>
+ *  <ul>
+ *     <li>
+ *        <em>name</em> - The link name. Default is <code>null</code>.
+ *     </li>
+ *     <li>
+ *        <em>description</em> - The Link description. Default is <code>null</code>.
+ *     </li>
+ *     <li>
+ *        <em>open in new window</em> - Whether or not the link should be opened in new window. Default is <code>false</code>.
+ *     </li>
+ *  </ul>
  *
- * <p>
- *    Using the LinkValueBuilder 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 LinkValueBuilder</li>
- *   <li>Set the target</li>
- *   <li>Possibly set a name</li>
- *   <li>Possibly set a description</li>
- *   <li>Possibly set open in new window</li>
- *   <li>Do build</li>
- * </ol>
- * <p>
- *    When you have built a <code>LinkValue</code> instance, you can re-use the LinkValueBuilder to build more instances. Something like:
- * </p>
- * <ol>
- *   <li>Set a new target</li>
- *   <li>Possibly set a name</li>
- *   <li>Possibly set a description</li>
- *   <li>Possibly set open in new window</li>
- *   <li>Do build</li>
- * </ol>
+ *  <p>
+ *     Using the LinkValueBuilder 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 LinkValueBuilder</li>
+ *    <li>Set the target</li>
+ *    <li>Possibly set a name</li>
+ *    <li>Possibly set a description</li>
+ *    <li>Possibly set open in new window</li>
+ *    <li>Do build</li>
+ *  </ol>
+ *  <p>
+ *     When you have built a <code>LinkValue</code> instance, you can re-use the LinkValueBuilder to build more instances. Something like:
+ *  </p>
+ *  <ol>
+ *    <li>Set a new target</li>
+ *    <li>Possibly set a name</li>
+ *    <li>Possibly set a description</li>
+ *    <li>Possibly set open in new window</li>
+ *    <li>Do build</li>
+ *  </ol>
  *
- * <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>
+ *  <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>
  *
- * <p>
- *    An instance of the Sitevision class implementing this interface can be obtained via
- *    {@link senselogic.sitevision.api.metadata.MetadataUtil#getLinkValueBuilder()}.
- *    See {@link senselogic.sitevision.api.metadata.MetadataUtil} for how to obtain an instance of the <code>MetadataUtil</code> interface.
- * </p>
+ *  <p>
+ *     An instance of the Sitevision class implementing this interface can be obtained via
+ *     {@link senselogic.sitevision.api.metadata.MetadataUtil#getLinkValueBuilder()}.
+ *     See {@link senselogic.sitevision.api.metadata.MetadataUtil} for how to obtain an instance of the <code>MetadataUtil</code> interface.
+ *  </p>
  * @author Magnus Lövgren
  * @since Sitevision 3.6
  */
@@ -72,7 +73,7 @@ export interface LinkValueBuilder extends Builder {
    * @return this builder
    * @throws IllegalArgumentException if <code>anURL</code> is <code>null</code> or whitespace only
    */
-  setExternalTarget(anURL: string): LinkValueBuilder;
+  setExternalTarget(anURL: String | string): LinkValueBuilder;
 
   /**
    * Sets the target.
@@ -81,7 +82,7 @@ export interface LinkValueBuilder extends Builder {
    * @throws IllegalArgumentException if <code>aMailAddress</code> is <code>null</code>, whitespace only or an invalid mail address.
    * @see senselogic.sitevision.api.mail.MailUtil#isValidAddress(String)
    */
-  setMailTarget(aMailAddress: string): LinkValueBuilder;
+  setMailTarget(aMailAddress: String | string): LinkValueBuilder;
 
   /**
    * Sets the target.
@@ -90,7 +91,7 @@ export interface LinkValueBuilder extends Builder {
    * @throws IllegalArgumentException if <code>aPhoneNumber</code> is <code>null</code>, whitespace only or an invalid phone number.
    * @since Sitevision 4.2.1
    */
-  setPhoneTarget(aPhoneNumber: string): LinkValueBuilder;
+  setPhoneTarget(aPhoneNumber: String | string): LinkValueBuilder;
 
   /**
    * Sets the target.
@@ -105,14 +106,14 @@ export interface LinkValueBuilder extends Builder {
    * @param aName the link name
    * @return this builder
    */
-  setName(aName: string): LinkValueBuilder;
+  setName(aName: String | string): LinkValueBuilder;
 
   /**
    * Sets the link description.
    * @param aDescription the link description
    * @return this builder
    */
-  setDescription(aDescription: string): LinkValueBuilder;
+  setDescription(aDescription: String | string): LinkValueBuilder;
 
   /**
    * Sets open in new window.

package/server/ListWrapper/index.d.ts

@@ -1,88 +1,94 @@
+import type { Object } from "../../types/java/lang/Object";
+
+import type { Iterator } from "../../types/java/util/Iterator";
+import type { Comparator } from "../../types/java/util/Comparator";
+import type { List } from "../../types/java/util/List";
+import type { Iterable } from "../../types/java/lang/Iterable";
 import type { Wrapper } from "../../types/senselogic/sitevision/api/base/Wrapper";
 
 /**
  * An convenience <code>java.util.List</code> wrapper that delegates method calls to the wrapped list.
  *
- * <p>
- *    This is a convenience wrapper that bypasses potential problems with the <code>add</code> method of a <code>java.util.List</code>.
- *    The <code>List.add</code> method accepts <code>null</code> values and returns a <code>boolean</code>.
- *    When working with Velocity, this boolean gets part of the output if not suppressed via a <code>#set</code>, <code>#if</code>,
- *    <code>#elseif</code> or via {@link senselogic.sitevision.api.script.ScriptUtil#swallow(Object)})
- * </p>
- *
- * <p>
- *    An example with the add problem of a java.util.List:<br>This Velocity code:
- * </p>
- * <pre><code>
- *    #set ($myList = $instanceCreatorUtil.list)
- *    $myList.add("Magnus Lövgren") <em>## Returns true</em>
- *    $myList.add("Mikael Wikblom") <em>## Returns true</em>
- *
- *    $someObject.someMethod($myList)</code></pre>will result in the following Velocity output
- *    (the <code>add</code> method of <code>List</code> returns a <code>boolean</code>):<pre><code>
- *    true true</code></pre>
- * <p>
- *    If a non-void method is invoked and the return value isn't handled, it will be part of the Velocity output.
- *    Using an <code>ListWrapper</code> will prevent that:
- * </p>
- * <pre><code>
- *    #set ($myList = $instanceCreatorUtil.listWrapper)
- *    myList.add("Magnus Lövgren") <em>## Silent</em>
- *    myList.add("Mikael Wikblom") <em>## Silent</em>
+ *  <p>
+ *     This is a convenience wrapper that bypasses potential problems with the <code>add</code> method of a <code>java.util.List</code>.
+ *     The <code>List.add</code> method accepts <code>null</code> values and returns a <code>boolean</code>.
+ *     When working with Velocity, this boolean gets part of the output if not suppressed via a <code>#set</code>, <code>#if</code>,
+ *     <code>#elseif</code> or via {@link senselogic.sitevision.api.script.ScriptUtil#swallow(Object)})
+ *  </p>
  *
- *    $someObject.someMethod($myList.unwrap()) <em>## Get wrapped List</em>
- * </code></pre>
+ *  <p>
+ *     An example with the add problem of a java.util.List:<br>This Velocity code:
+ *  </p>
+ *  <pre><code>
+ *     #set ($myList = $instanceCreatorUtil.list)
+ *     $myList.add("Magnus Lövgren") <em>## Returns true</em>
+ *     $myList.add("Mikael Wikblom") <em>## Returns true</em>
  *
+ *     $someObject.someMethod($myList)</code></pre>will result in the following Velocity output
+ *     (the <code>add</code> method of <code>List</code> returns a <code>boolean</code>):<pre><code>
+ *     true true</code></pre>
  *  <p>
- *     <strong>Important Velocity #foreach note!</strong><br>
- *     Iterating a <code>ListWrapper</code> via the Velocity <code>#foreach</code> loop is not possible in all Velocity versions
- *     (proper <code>Iterable</code> support not present). To ensure proper <code>#foreach</code> iteration in all Velocity versions,
- *     you should use one of the following alternative ways:
+ *     If a non-void method is invoked and the return value isn't handled, it will be part of the Velocity output.
+ *     Using an <code>ListWrapper</code> will prevent that:
  *  </p>
  *  <pre><code>
  *     #set ($myList = $instanceCreatorUtil.listWrapper)
- *     ...
+ *     myList.add("Magnus Lövgren") <em>## Silent</em>
+ *     myList.add("Mikael Wikblom") <em>## Silent</em>
+ *
+ *     $someObject.someMethod($myList.unwrap()) <em>## Get wrapped List</em>
+ *  </code></pre>
  *
- *     <em>## ALTERNATIVE A - unwrap, i.e. do actual iteration on the wrapped list itself</em>
- *     #foreach ($item in $myList.<strong>unwrap()</strong>)
- *        ...
- *     #end
+ *   <p>
+ *      <strong>Important Velocity #foreach note!</strong><br>
+ *      Iterating a <code>ListWrapper</code> via the Velocity <code>#foreach</code> loop is not possible in all Velocity versions
+ *      (proper <code>Iterable</code> support not present). To ensure proper <code>#foreach</code> iteration in all Velocity versions,
+ *      you should use one of the following alternative ways:
+ *   </p>
+ *   <pre><code>
+ *      #set ($myList = $instanceCreatorUtil.listWrapper)
+ *      ...
  *
- *     <em>## ALTERNATIVE B - explicitly hand over the Iterator</em>
- *     #foreach ($item in $myList.<strong>iterator()</strong>)
- *        ...
- *     #end
+ *      <em>## ALTERNATIVE A - unwrap, i.e. do actual iteration on the wrapped list itself</em>
+ *      #foreach ($item in $myList.<strong>unwrap()</strong>)
+ *         ...
+ *      #end
  *
- *     <em>## ALTERNATIVE C - extract as array</em>
- *     #foreach ($item in $myList.<strong>toArray()</strong>)
- *        ...
- *     #end</code></pre>
- * <p>
- *     For best performance, you should choose alternative A or B over C.
- * </p>
+ *      <em>## ALTERNATIVE B - explicitly hand over the Iterator</em>
+ *      #foreach ($item in $myList.<strong>iterator()</strong>)
+ *         ...
+ *      #end
  *
- * <p>
- *    An instance of the Sitevision class implementing this interface can be obtained via {@link InstanceCreatorUtil#getListWrapper()}.
- *    See {@link InstanceCreatorUtil} for how to obtain an instance of the <code>InstanceCreatorUtil</code> interface.
- * </p>
+ *      <em>## ALTERNATIVE C - extract as array</em>
+ *      #foreach ($item in $myList.<strong>toArray()</strong>)
+ *         ...
+ *      #end</code></pre>
+ *  <p>
+ *      For best performance, you should choose alternative A or B over C.
+ *  </p>
+ *
+ *  <p>
+ *     An instance of the Sitevision class implementing this interface can be obtained via {@link InstanceCreatorUtil#getListWrapper()}.
+ *     See {@link InstanceCreatorUtil} for how to obtain an instance of the <code>InstanceCreatorUtil</code> interface.
+ *  </p>
  * @author Magnus Lövgren
  * @since Sitevision 3.5
  */
-export interface ListWrapper extends Wrapper {
+export interface ListWrapper extends Iterable, Wrapper {
   /**
    * Appends the specified element (if non-null) to the end of the wrapped list.
    *
-   * <p>
-   *    <strong>Important!</strong> Null values in lists are inherently bad. This method will <strong>not</strong>
-   *    delegate any <code>null</code> to the wrapped list.
-   *    If you <em>must</em> add a <code>null</code> value, you can explicitly do it to the wrapped list, i.e:
-   * </p>
-   * <pre><code>
-   *    #set ($myList = $instanceCreatorUtil.listWrapper)
-   *    ...
-   *    $myList.add($anObject.aMethod())          <em>## Will only delegate non-nulls to the wrapped list</em>
-   *    $myList.unwrap().add($anObject.aMethod()) <em>## Will add any value directly to the wrapped list</em>
-   * </code></pre>
+   *  <p>
+   *     <strong>Important!</strong> Null values in lists are inherently bad. This method will <strong>not</strong>
+   *     delegate any <code>null</code> to the wrapped list.
+   *     If you <em>must</em> add a <code>null</code> value, you can explicitly do it to the wrapped list, i.e:
+   *  </p>
+   *  <pre><code>
+   *     #set ($myList = $instanceCreatorUtil.listWrapper)
+   *     ...
+   *     $myList.add($anObject.aMethod())          <em>## Will only delegate non-nulls to the wrapped list</em>
+   *     $myList.unwrap().add($anObject.aMethod()) <em>## Will add any value directly to the wrapped list</em>
+   *  </code></pre>
    * @param anObject the element to be appended to the wrapped list, <code>null</code> will be ignored.
    */
   add(anObject: unknown): void;
@@ -118,7 +124,7 @@ export interface ListWrapper extends Wrapper {
    * Returns an iterator for the wrapped list.
    * @return an Iterator.
    */
-  iterator(): unknown;
+  iterator(): Iterator;
 
   /**
    * The size (number of elements) of the wrapped list.
@@ -137,13 +143,13 @@ export interface ListWrapper extends Wrapper {
    * @param aComparator the comparator to use when sorting
    * @since Sitevision 4.0
    */
-  sort(aComparator: unknown): void;
+  sort(aComparator: Comparator): void;
 
   /**
    * Returns the wrapped List.
    * @return the List wrapped by this ListWrapper
    */
-  unwrap(): unknown;
+  unwrap(): List;
 }
 
 declare namespace ListWrapper {}