@sitevision/api 1.0.20 → 1.1.0-alpha.1

package/server/CollaborationGroupTemplateUtil/index.d.ts

@@ -1,52 +1,84 @@
-import List from '../../builtins/List';
-import Node from '../../builtins/Node';
+import Node from "../../hidden/javax/jcr/Node";
 
 /**
-* Gets the first found collaboration group template that matches a given name.
-* @returns {Node} a collaboration group template, or null if indeterminable (e.g. no accessible collaboration group template named aCollaborationGroupTemplateName could be found) 
-* @param {string} aCollaborationGroupTemplateName - name of the template
-*/
-export function getCollaborationGroupTemplateByName(aCollaborationGroupTemplateName: string): Node;
+ * Gets the default collaboration group template.
+ *
+ * <p>
+ *    The <em>default collaboration group template</em> is the template that are used by default to create new
+ *    collaboration groups (i.e. collaboration group pages).
+ * </p>
+ * <p>
+ *    <em>Permission note!</em> Current user must have {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ}
+ *    on default collaboration group template.
+ * </p>
+ * @return the default collaboration group template, or <code>null</code> if indeterminable
+ */
+export function getDefaultCollaborationGroupTemplate(): Node;
 
 /**
-* Gets all collaboration group templates.
-* @returns {List<Node>} all collaboration group templates, or empty list if there are no accessible collaboration group templates. 
-*/
-export function getCollaborationGroupTemplates(): List<Node>;
+ * Gets the first found collaboration group template that matches a given name.
+ *
+ * <p>
+ *    <em>Permission note!</em> Only collaboration group templates that current user has
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ} on will be considered.
+ * </p>
+ * @param aCollaborationGroupTemplateName name of the template
+ * @return a collaboration group template, or <code>null</code> if indeterminable (e.g. no accessible collaboration group template named <code>aCollaborationGroupTemplateName</code> could be found)
+ * @since Sitevision 4.1
+ */
+export function getCollaborationGroupTemplateByName(
+  aCollaborationGroupTemplateName: string
+): Node;
 
 /**
-* Gets the default collaboration group template.
-* @returns {Node} the default collaboration group template, or null if indeterminable 
-*/
-export function getDefaultCollaborationGroupTemplate(): Node;
-
-export interface ICollaborationGroupTemplateUtil {
-  /**
-  * Gets the first found collaboration group template that matches a given name.
-  * @returns {Node} a collaboration group template, or null if indeterminable (e.g. no accessible collaboration group template named aCollaborationGroupTemplateName could be found) 
-  * @param {string} aCollaborationGroupTemplateName - name of the template
-  */
-  getCollaborationGroupTemplateByName(aCollaborationGroupTemplateName: string): Node;
-
-  /**
-  * Gets all collaboration group templates.
-  * @returns {List<Node>} all collaboration group templates, or empty list if there are no accessible collaboration group templates. 
-  */
-  getCollaborationGroupTemplates(): List<Node>;
+ * Gets all collaboration group templates.
+ *
+ * <p>
+ *    <em>Permission note!</em> The list will only contain collaboration group templates that current user has
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ} on.
+ * </p>
+ * @return all collaboration group templates, or empty list if there are no accessible collaboration group templates.
+ * @since Sitevision 4.1
+ */
+export function getCollaborationGroupTemplates(): unknown[];
 
-  /**
-  * Gets the default collaboration group template.
-  * @returns {Node} the default collaboration group template, or null if indeterminable 
-  */
-  getCollaborationGroupTemplate(): Node;
-}
-
-declare namespace collaborationGroupTemplateUtil {
+/**
+ * Collaboration group template utility interface that handles nodes with primary node type <code>sv:collaborationGroupTemplate</code>.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link CollaborationFactory#getCollaborationGroupTemplateUtil()}.
+ *    See {@link CollaborationFactory} for how to obtain an instance of the <code>CollaborationFactory</code> interface.
+ * </p>Gets the default collaboration group template.
+ *
+ * <p>
+ *    The <em>default collaboration group template</em> is the template that are used by default to create new
+ *    collaboration groups (i.e. collaboration group pages).
+ * </p>
+ * <p>
+ *    <em>Permission note!</em> Current user must have {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ}
+ *    on default collaboration group template.
+ * </p>Gets the first found collaboration group template that matches a given name.
+ *
+ * <p>
+ *    <em>Permission note!</em> Only collaboration group templates that current user has
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ} on will be considered.
+ * </p>Gets all collaboration group templates.
+ *
+ * <p>
+ *    <em>Permission note!</em> The list will only contain collaboration group templates that current user has
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ} on.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6.4
+ * @see senselogic.sitevision.api.resource.TemplateUtil
+ */
+declare namespace CollaborationGroupTemplateUtil {
   export {
+    getDefaultCollaborationGroupTemplate,
     getCollaborationGroupTemplateByName,
     getCollaborationGroupTemplates,
-    getCollaborationGroupTemplate,
   };
 }
 
-export default collaborationGroupTemplateUtil;
+export default CollaborationGroupTemplateUtil;

package/server/CollaborationGroupUtil/index.d.ts

@@ -1,65 +1,138 @@
-import Node from '../../builtins/Node';
-import CollaborationGroupType from '../CollaborationGroupType';
+import Node from "../../hidden/javax/jcr/Node";
+import CollaborationGroupType from "../CollaborationGroupType";
 
 /**
-* Creates an open collaboration group.
-* @returns {Node} The created collaboration group (sv:collaborationGroup) 
-* @param {Node} aGroupTemplate - the collaboration group template (sv:collaborationGroupTemplate) to use when creating the collaboration group page of the collaboration group
-* @param {Node} aGroupFolder - the collaboration group folder (sv:collaborationGroupFolder) where the collaboration group page of the collaboration group should reside
-* @param {string} aGroupName - the name of the collaboration group
-*/
-export function createCollaborationGroup(aGroupTemplate: Node, aGroupFolder: Node, aGroupName: string): Node;
+ * Creates an open collaboration group.
+ *
+ * <p>
+ *    <em>
+ *       This is a legacy convenience method that delegates to {@link #createCollaborationGroup(Node, Node, String, CollaborationGroupType)}
+ *       using {@link CollaborationGroupType#OPEN} as group type.
+ *    </em>
+ * </p>
+ * @param aGroupTemplate the collaboration group template (sv:collaborationGroupTemplate) to use when creating the collaboration group page of the collaboration group
+ * @param aGroupFolder the collaboration group folder (sv:collaborationGroupFolder) where the collaboration group page of the collaboration group should reside
+ * @param aGroupName the name of the collaboration group
+ * @return The created collaboration group (sv:collaborationGroup)
+ * @throws java.lang.NullPointerException if <code>aGroupTemplate</code>, <code>aGroupFolder</code> or <code>aGroupName</code> is <code>null</code>
+ * @throws ConstraintViolationException if <code>aGroupTemplate</code> or <code>aGroupFolder</code> is of invalid type, if <code>aGroupName</code> is whitespace only, if <code>aGroupFolder</code> already contains a collaboration group named <code>aGroupName</code> (case ignored) or if current user is not authorized to create the collaboration group
+ * @throws RepositoryException if something else goes wrong
+ * @see #createCollaborationGroup(Node, Node, String, CollaborationGroupType)
+ */
+export function createCollaborationGroup(
+  aGroupTemplate: Node,
+  aGroupFolder: Node,
+  aGroupName: string
+): Node;
 
 /**
-* Creates a collaboration group.
-* @returns {Node} The created collaboration group (sv:collaborationGroup) 
-* @param {Node} aGroupTemplate - the collaboration group template (sv:collaborationGroupTemplate) to use when creating the collaboration group page of the collaboration group
-* @param {Node} aGroupFolder - the collaboration group folder (sv:collaborationGroupFolder) where the collaboration group page of the collaboration group should reside
-* @param {string} aGroupName - the name of the collaboration group
-* @param {CollaborationGroupType} aGroupType - the group type, note that CollaborationGroupType.CLOSED needs additional permission
-*/
-export function createCollaborationGroup(aGroupTemplate: Node, aGroupFolder: Node, aGroupName: string, aGroupType: CollaborationGroupType): Node;
+ * Creates a collaboration group.
+ *
+ * <p>
+ *    <strong>Permission note!</strong> Current user must have
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ} on <code>aGroupTemplate</code>
+ *    and {@link senselogic.sitevision.api.security.PermissionUtil.Permission#CREATE_COLLABORATION_GROUP} on <code>aGroupFolder</code>.
+ *    In order to create a {@link CollaborationGroupType#CLOSED} collaboration group, current user must also have
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#CREATE_CLOSED_COLLABORATION_GROUP} on <code>aGroupFolder</code>.
+ * </p>
+ * <p>
+ *    <strong>User note!</strong> Current user must have a user identity as it will be the administrator of the created
+ *    group. <em>Anonymous</em> users doesn't have a user identity, nor the <em>Indexer</em>, <em>Validator</em> or the <em>Extractor</em>.
+ *    In other words: {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUserIdentity()} must be non-<code>null</code>.
+ * </p>
+ *
+ * <p>
+ *    <em>Tip!</em> Use {@link CollaborationGroupTemplateUtil} to get a group template,
+ *    use {@link CollaborationGroupFolderUtil} to get the default group folder (and perhaps check if the collaboration folder already contains
+ *    a collaboration group with specified name). Use {@link CollaborationGroupWrapper} to update the group that is created.
+ * </p>
+ * @param aGroupTemplate the collaboration group template (sv:collaborationGroupTemplate) to use when creating the collaboration group page of the collaboration group
+ * @param aGroupFolder the collaboration group folder (sv:collaborationGroupFolder) where the collaboration group page of the collaboration group should reside
+ * @param aGroupName the name of the collaboration group
+ * @param aGroupType the group type, note that {@link CollaborationGroupType#CLOSED} needs additional permission
+ * @return The created collaboration group (sv:collaborationGroup)
+ * @throws java.lang.NullPointerException if <code>aGroupTemplate</code>, <code>aGroupFolder</code>, <code>aGroupName</code> or <code>aGroupType</code> is <code>null</code>
+ * @throws ConstraintViolationException if <code>aGroupTemplate</code> or <code>aGroupFolder</code> is of invalid type, if <code>aGroupName</code> is whitespace only, if <code>aGroupFolder</code> already contains a collaboration group named <code>aGroupName</code> (case ignored) or if current user is not authorized to create the collaboration group (see permission note above)
+ * @throws RepositoryException if something else goes wrong
+ * @since Sitevision 4.1
+ */
+export function createCollaborationGroup(
+  aGroupTemplate: Node,
+  aGroupFolder: Node,
+  aGroupName: string,
+  aGroupType: CollaborationGroupType
+): Node;
 
 /**
-* Removes a collaboration group.
-* @returns {boolean} true if aCollaborationGroup was removed, i.e. collaboration group page was moved to trashcan, false otherwise. 
-* @param {Node} aCollaborationGroup - a collaboration group to remove
-*/
+ * Removes a collaboration group.
+ *
+ * <p>
+ *    <em>Note!</em> When a collaboration group (<code>sv:collaborationGroup</code>) is removed,
+ *    its collaboration group page (<code>sv:collaborationGroupPage</code>) is moved to the trashcan.
+ * </p>
+ * <p>
+ *    <strong>Permission note!</strong> To remove a collaboration group current user must have
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#MANAGE_COLLABORATION_GROUP} on the collaboration group page.
+ * </p>
+ * @param aCollaborationGroup a collaboration group to remove
+ * @return <code>true</code> if <code>aCollaborationGroup</code> was removed, i.e. collaboration group page was moved to trashcan, <code>false</code> otherwise.
+ * @since Sitevision 4.5.3
+ */
 export function removeCollaborationGroup(aCollaborationGroup: Node): boolean;
 
-export interface ICollaborationGroupUtil {
-  /**
-  * Creates an open collaboration group.
-  * @returns {Node} The created collaboration group (sv:collaborationGroup) 
-  * @param {Node} aGroupTemplate - the collaboration group template (sv:collaborationGroupTemplate) to use when creating the collaboration group page of the collaboration group
-  * @param {Node} aGroupFolder - the collaboration group folder (sv:collaborationGroupFolder) where the collaboration group page of the collaboration group should reside
-  * @param {string} aGroupName - the name of the collaboration group
-  */
-  createCollaborationGroup(aGroupTemplate: Node, aGroupFolder: Node, aGroupName: string): Node;
-
-  /**
-  * Creates a collaboration group.
-  * @returns {Node} The created collaboration group (sv:collaborationGroup) 
-  * @param {Node} aGroupTemplate - the collaboration group template (sv:collaborationGroupTemplate) to use when creating the collaboration group page of the collaboration group
-  * @param {Node} aGroupFolder - the collaboration group folder (sv:collaborationGroupFolder) where the collaboration group page of the collaboration group should reside
-  * @param {string} aGroupName - the name of the collaboration group
-  * @param {CollaborationGroupType} aGroupType - the group type, note that CollaborationGroupType.CLOSED needs additional permission
-  */
-  createCollaborationGroup(aGroupTemplate: Node, aGroupFolder: Node, aGroupName: string, aGroupType: CollaborationGroupType): Node;
-
-  /**
-  * Removes a collaboration group.
-  * @returns {boolean} true if aCollaborationGroup was removed, i.e. collaboration group page was moved to trashcan, false otherwise. 
-  * @param {Node} aCollaborationGroup - a collaboration group to remove
-  */
-  removeCollaborationGroup(aCollaborationGroup: Node): boolean;
+/**
+ * Collaboration group utility interface.
+ *
+ * <p>
+ *    <em>Note!</em> This interface is used to <em>create</em> collaboration groups. You would typically use
+ *    {@link senselogic.sitevision.api.collaboration.CollaborationGroupWrapper} to <em>update</em> an existing
+ *    collaboration group.
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link CollaborationFactory#getCollaborationGroupUtil()}.
+ *    See {@link CollaborationFactory} for how to obtain an instance of the <code>CollaborationFactory</code> interface.
+ * </p>Creates an open collaboration group.
+ *
+ * <p>
+ *    <em>
+ *       This is a legacy convenience method that delegates to {@link #createCollaborationGroup(Node, Node, String, CollaborationGroupType)}
+ *       using {@link CollaborationGroupType#OPEN} as group type.
+ *    </em>
+ * </p>Creates a collaboration group.
+ *
+ * <p>
+ *    <strong>Permission note!</strong> Current user must have
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#READ} on <code>aGroupTemplate</code>
+ *    and {@link senselogic.sitevision.api.security.PermissionUtil.Permission#CREATE_COLLABORATION_GROUP} on <code>aGroupFolder</code>.
+ *    In order to create a {@link CollaborationGroupType#CLOSED} collaboration group, current user must also have
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#CREATE_CLOSED_COLLABORATION_GROUP} on <code>aGroupFolder</code>.
+ * </p>
+ * <p>
+ *    <strong>User note!</strong> Current user must have a user identity as it will be the administrator of the created
+ *    group. <em>Anonymous</em> users doesn't have a user identity, nor the <em>Indexer</em>, <em>Validator</em> or the <em>Extractor</em>.
+ *    In other words: {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUserIdentity()} must be non-<code>null</code>.
+ * </p>
+ *
+ * <p>
+ *    <em>Tip!</em> Use {@link CollaborationGroupTemplateUtil} to get a group template,
+ *    use {@link CollaborationGroupFolderUtil} to get the default group folder (and perhaps check if the collaboration folder already contains
+ *    a collaboration group with specified name). Use {@link CollaborationGroupWrapper} to update the group that is created.
+ * </p>Removes a collaboration group.
+ *
+ * <p>
+ *    <em>Note!</em> When a collaboration group (<code>sv:collaborationGroup</code>) is removed,
+ *    its collaboration group page (<code>sv:collaborationGroupPage</code>) is moved to the trashcan.
+ * </p>
+ * <p>
+ *    <strong>Permission note!</strong> To remove a collaboration group current user must have
+ *    {@link senselogic.sitevision.api.security.PermissionUtil.Permission#MANAGE_COLLABORATION_GROUP} on the collaboration group page.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6.4
+ */
+declare namespace CollaborationGroupUtil {
+  export { createCollaborationGroup, removeCollaborationGroup };
 }
 
-declare namespace collaborationGroupUtil {
-  export {
-    createCollaborationGroup,
-    createCollaborationGroup,
-    removeCollaborationGroup,
-  };
-}
-export default collaborationGroupUtil;
+export default CollaborationGroupUtil;