com.adobe.cq.social.scoring.api.ScoringService Maven / Gradle / Ivy

/**************************************************************************
 *
 * ADOBE CONFIDENTIAL
 * __________________
 *
 *  Copyright 2012 Adobe Systems Incorporated
 *  All Rights Reserved.
 *
 * NOTICE:  All information contained herein is, and remains
 * the property of Adobe Systems Incorporated and its suppliers,
 * if any.  The intellectual and technical concepts contained
 * herein are proprietary to Adobe Systems Incorporated and its
 * suppliers and are protected by trade secret or copyright law.
 * Dissemination of this information or reproduction of this material
 * is strictly forbidden unless prior written permission is obtained
 * from Adobe Systems Incorporated.
 **************************************************************************/
package com.adobe.cq.social.scoring.api;

import java.util.List;

import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
import javax.jcr.RepositoryException;

import com.adobe.cq.social.srp.SocialResourceProvider;
import org.apache.sling.api.resource.PersistenceException;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;

import com.adobe.cq.social.srp.SearchSortField;

/**
 * Scoring service exposes operations like getPoints needed by components.
 */
public interface ScoringService {

    /**
     * Retrieves score specified by scoreName for user.
     * @param resourceResolver - resolver used to read the resources
     * @param userId - the user's userid
     * @param componentResource - the resource where the scoring rule was applied
     * @param scoreRuleResource - resource of score to be retrieved
     * @return score of the user
     * @throws RepositoryException thrown if unable to retrieve the score
     */
    long getScore(@Nonnull ResourceResolver resourceResolver, @Nonnull String userId,
        @Nonnull Resource componentResource, @Nonnull Resource scoreRuleResource) throws RepositoryException;

    /**
     * Get the top scores for a scoring rule at a location
     * @param resolver - resolver used to search and read resources
     * @param componentResource - the resource where the scoring rule is
     * @param scoreRuleResource - resource of scoring rule
     * @param offset - offset of list
     * @param size - number of items to return
     * @param sortFields - set to null or empty List for the default of sorting by scores and then by userid in
     *            descending order
     * @return a list of UserScore objects in the order specified
     * @throws RepositoryException thrown if unable to retrieve scores
     */
    List getTopScores(@Nonnull ResourceResolver resolver, @Nonnull Resource componentResource,
        @Nonnull Resource scoreRuleResource, int offset, int size, List sortFields)
        throws RepositoryException;

    /**
     * Get to number of scores for a scoring rule at a location
     * @param resolver - resolver used to search and read resources
     * @param componentResource - the resource where the scoring rule is
     * @param scoreRuleResource - resource of scoring rule
     * @return the number of scores
     * @throws RepositoryException thrown if unable to retrieve scores
     */
    long getTotalNumberOfScores(@Nonnull ResourceResolver resolver, final Resource componentResource,
        final Resource scoreRuleResource) throws RepositoryException;

    /**
     * Saves score specified by scoreName for user.
     * @param resourceResolver - resolver of the user whose score needs to be retrieved
     * @param userId - the user's userid
     * @param componentResource - the resource where the scoring rule was applied
     * @param scoreRuleResource - name of score to be retrieved
     * @param scoreValue - score value, in the form of an increment, to save
     * @throws RepositoryException thrown if unable to save the score
     * @throws PersistenceException thrown if unable to save the score
     */
    void saveScore(@Nonnull ResourceResolver resourceResolver, @Nonnull String userId,
        @Nonnull Resource componentResource, @Nonnull Resource scoreRuleResource, long scoreValue)
        throws RepositoryException, PersistenceException;

    /**
     * Returns the path of a score resource.
     * @param resourceResolver - resolver of the user whose score needs to be retrieved
     * @param userId - the user's userid
     * @param componentResource - the resource where the scoring rule was applied
     * @param scoreRuleResource - name of score to be retrieved
     * @return the path of score resource
     * @throws RepositoryException if unable to calculate the score path
     */
    @CheckForNull
    String getScoreResourcePath(@Nonnull final ResourceResolver resourceResolver, final String userId,
        @Nonnull final Resource componentResource, @Nonnull final Resource scoreRuleResource)
        throws RepositoryException;
}