@sitevision/api 1.0.19 → 1.1.0-alpha.1

package/server/UserIdentityUtil/index.d.ts

@@ -1,40 +1,72 @@
-import Node from '../../builtins/Node';
-
-export interface UserIdentityUtil {
-  /**
-   * Creates the corresponding sv:userIdentity Node for a specified sv:user Node.
-   * @param {Node} aUserNode - a user node that presumably do not have a corresponding user identity
-   * @returns {Node} the existing or created sv:userIdentity Node for aUserNode, or nullif aUserNode is null or isn't allowed to have user identity for current site (e.g. user is anonymized). 
-   */
-  getOrCreateUserIdentity(aUserNode: Node): Node;
-
-  /**
-   * Gets the corresponding sv:userIdentity Node for a specified sv:user Node.
-   * @param {Node} aUserNode - a user node
-   * @returns {Node} the corresponding sv:userIdentity Node for aUserNode, or nullif aUserNode is null or has no corresponding user identity for current site (e.g. user is anonymized). 
-   */
-  getUserIdentity(aUserNode: Node): Node;
-}
+import Node from "../../hidden/javax/jcr/Node";
 
 /**
- * Creates the corresponding sv:userIdentity Node for a specified sv:user Node.
- * @param {Node} aUserNode - a user node that presumably do not have a corresponding user identity
- * @returns {Node} the existing or created sv:userIdentity Node for aUserNode, or nullif aUserNode is null or isn't allowed to have user identity for current site (e.g. user is anonymized). 
+ * Creates the corresponding <code>sv:userIdentity</code> Node for a specified <code>sv:user</code> Node.
+ *
+ * <p>
+ *    <strong>Note!</strong> When Collaboration is activated for a site, user identities are automatically created
+ *    for each user when they authenticates themselves. This method is typically used for "infrequent" users during
+ *    the startup phase of using Collaboration.
+ * </p>
+ * <p>
+ *    <em>Note that neither anonymous users, the indexer or the extractor can have a user identity!</em>
+ * </p>
+ * @param aUserNode a user node that presumably do not have a corresponding user identity
+ * @return the existing or created sv:userIdentity Node for <code>aUserNode</code>, or <code>null</code> if <code>aUserNode</code> is <code>null</code> or isn't allowed to have user identity for current site (e.g. user is anonymized).
+ * @see #getUserIdentity(javax.jcr.Node)
  */
 export function getOrCreateUserIdentity(aUserNode: Node): Node;
 
 /**
- * Gets the corresponding sv:userIdentity Node for a specified sv:user Node.
- * @param {Node} aUserNode - a user node
- * @returns {Node} the corresponding sv:userIdentity Node for aUserNode, or nullif aUserNode is null or has no corresponding user identity for current site (e.g. user is anonymized). 
+ * Gets the corresponding <code>sv:userIdentity</code> Node for a specified <code>sv:user</code> Node.
+ *
+ * <p>
+ *    <em>Note that neither anonymous users, the indexer or the extractor user has a user identity!</em>
+ * </p>
+ * <p>
+ *    <em>Tip!</em> Use {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUserIdentity()} for getting
+ *    the user identity of current user.
+ * </p>
+ * @param aUserNode a user node
+ * @return the corresponding sv:userIdentity Node for <code>aUserNode</code>, or <code>null</code> if <code>aUserNode</code> is <code>null</code> or has no corresponding user identity for current site (e.g. user is anonymized).
  */
 export function getUserIdentity(aUserNode: Node): Node;
 
-declare namespace userIdentityUtil {
-  export {
-    getOrCreateUserIdentity,
-    userDataUtil,
-  };
+/**
+ * User identity utility interface.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link UserFactory#getUserIdentityUtil()}.
+ *    See {@link senselogic.sitevision.api.user.UserFactory} for how to obtain an instance of the <code>UserFactory</code> interface.
+ * </p>
+ *
+ * <p>
+ *    <em>Tip!</em> Use {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUserIdentity()} for getting
+ *    the user identity of current user.
+ * </p>Creates the corresponding <code>sv:userIdentity</code> Node for a specified <code>sv:user</code> Node.
+ *
+ * <p>
+ *    <strong>Note!</strong> When Collaboration is activated for a site, user identities are automatically created
+ *    for each user when they authenticates themselves. This method is typically used for "infrequent" users during
+ *    the startup phase of using Collaboration.
+ * </p>
+ * <p>
+ *    <em>Note that neither anonymous users, the indexer or the extractor can have a user identity!</em>
+ * </p>Gets the corresponding <code>sv:userIdentity</code> Node for a specified <code>sv:user</code> Node.
+ *
+ * <p>
+ *    <em>Note that neither anonymous users, the indexer or the extractor user has a user identity!</em>
+ * </p>
+ * <p>
+ *    <em>Tip!</em> Use {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUserIdentity()} for getting
+ *    the user identity of current user.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+declare namespace UserIdentityUtil {
+  export { getOrCreateUserIdentity, getUserIdentity };
 }
 
-export default userIdentityUtil;
+export default UserIdentityUtil;

package/server/UserUtil/index.d.ts

@@ -1,40 +1,81 @@
-import Node from '../../builtins/Node'
-
-export interface UserUtil { 
-  /**
-   * Checks if current user is member of a group.
-   * @param {Node} aGroup - a group node (sv:userGroup or sv:virtualGroup)
-   * @returns {boolean} true if current user is member of aGroup, false otherwise 
-   */
-  isMemberOfGroup(aGroup: Node): boolean;
-
-  /**
-   * Checks if a specific user is member of a group.
-   * @param {Node} aUser - a user node (sv:user, sv:simpleUser or sv:systemUser)
-   * @param {Node} aGroup - a group node (sv:userGroup or sv:virtualGroup)
-   * @returns {boolean} true if aUser is member of aGroup, false otherwise 
-   */
-  isMemberOfGroup(aUser: Node, aGroup: Node): boolean;
-}
+import Node from "../../hidden/javax/jcr/Node";
 
 /**
  * Checks if current user is member of a group.
- * @param {Node} aGroup - a group node (sv:userGroup or sv:virtualGroup)
- * @returns {boolean} true if current user is member of aGroup, false otherwise 
+ *
+ * <p>
+ *    This is a convenience for {@link #isMemberOfGroup(javax.jcr.Node, javax.jcr.Node)} using current user
+ *    (as of {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUser()}).
+ * </p>
+ * @param aGroup a group node (sv:userGroup or sv:virtualGroup)
+ * @return <code>true</code> if current user is member of <code>aGroup</code>, <code>false</code> otherwise
  */
 export function isMemberOfGroup(aGroup: Node): boolean;
 
 /**
  * Checks if a specific user is member of a group.
- * @param {Node} aUser - a user node (sv:user, sv:simpleUser or sv:systemUser)
- * @param {Node} aGroup - a group node (sv:userGroup or sv:virtualGroup)
- * @returns {boolean} true if aUser is member of aGroup, false otherwise 
+ *
+ * <p>
+ *    <em>Tip!</em> To check if a <code>sv:userIdentity</code> is member of a <code>sv:collaborationGroup</code>,
+ *    you would typically use {@link senselogic.sitevision.api.user.UserIdentityWrapper#isMemberOf(javax.jcr.Node)} or
+ *    {@link senselogic.sitevision.api.collaboration.CollaborationGroupWrapper#isMember(javax.jcr.Node)}.
+ * </p>
+ * @param aUser a user node (sv:user, sv:simpleUser or sv:systemUser)
+ * @param aGroup a group node (sv:userGroup or sv:virtualGroup)
+ * @return <code>true</code> if <code>aUser</code> is member of <code>aGroup</code>, <code>false</code> otherwise
  */
 export function isMemberOfGroup(aUser: Node, aGroup: Node): boolean;
 
-declare namespace userUtil {
-  export {
-    isMemberOfGroup,
-  };
+/**
+ * User utility interface.
+ *
+ * <p>
+ *    This interface primarily handles nodes with primary node type <code>sv:user</code>, but some methods can also handle
+ *    other user types (i.e. <code>sv:simpleUser</code> and/or <code>sv:systemUser</code>).
+ * </p>
+ *
+ * <p>
+ *    <em>Tip!</em> Some user-related functionality in other interfaces:
+ * </p>
+ * <ul>
+ *    <li>
+ *       Use {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUser()} if you should get current user.
+ *    </li>
+ *    <li>
+ *       Use {@link senselogic.sitevision.api.user.UserIdentityUtil#getUserIdentity(javax.jcr.Node)} if you should get
+ *       the <code>sv:userIdentity</code> of a user.
+ *    </li>
+ *    <li>
+ *       Use {@link senselogic.sitevision.api.security.DirectoryUtil} if you should lookup/search directory-bound users.
+ *    </li>
+ *    <li>
+ *       Use {@link senselogic.sitevision.api.security.PermissionUtil} if you should check permission(s) for a <code>sv:user</code>.
+ *    </li>
+ * </ul>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.user.UserFactory#getUserUtil()}.
+ *    See {@link senselogic.sitevision.api.user.UserFactory} for how to obtain an instance of the <code>UserFactory</code> interface.
+ * </p>Checks if current user is member of a group.
+ *
+ * <p>
+ *    This is a convenience for {@link #isMemberOfGroup(javax.jcr.Node, javax.jcr.Node)} using current user
+ *    (as of {@link senselogic.sitevision.api.context.PortletContextUtil#getCurrentUser()}).
+ * </p>Checks if a specific user is member of a group.
+ *
+ * <p>
+ *    <em>Tip!</em> To check if a <code>sv:userIdentity</code> is member of a <code>sv:collaborationGroup</code>,
+ *    you would typically use {@link senselogic.sitevision.api.user.UserIdentityWrapper#isMemberOf(javax.jcr.Node)} or
+ *    {@link senselogic.sitevision.api.collaboration.CollaborationGroupWrapper#isMember(javax.jcr.Node)}.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 4.0.1
+ * @see senselogic.sitevision.api.user.SystemUserUtil
+ * @see senselogic.sitevision.api.user.SimpleUserUtil
+ */
+declare namespace UserUtil {
+  export { isMemberOfGroup };
 }
-export default userUtil;
+
+export default UserUtil;