com.adobe.cq.social.srp.internal.SocialDataService 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.srp.internal;

import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;

import javax.annotation.Nonnull;

import aQute.bnd.annotation.ProviderType;

import com.adobe.cq.social.srp.APICommand;
import com.adobe.cq.social.srp.APIResult;
import com.adobe.cq.social.srp.FacetRangeField;
import com.adobe.cq.social.srp.FacetSearchResult;
import com.adobe.cq.social.srp.SearchSortField;
import com.adobe.cq.social.srp.SocialResourceSearchResult;
import com.adobe.cq.social.srp.config.SocialResourceConfiguration;

/**
 * An interface defining low-level access to Adobe Cloud Storage.
 */
@ProviderType
public interface SocialDataService {

    /**
     * Used in browseDocuments to indicate whether and which count of children is desired.
     */
    enum Counts {
        /**
         * Request count of the matching documents which are visible.
         */
        VISIBLE_ONLY,
        /**
         * Request count of all the matching documents.
         */
        ALL,
        /**
         * Do not request a count.
         */
        NONE
    };

    /**
     * Used in browseDocuments to return the page of documents found and the count of all matching documents.
     */
    interface BrowseDocumentsResult {
        /**
         * Return the count of all matching documents.
         * @return the count of all matching documents.
         */
        long getCount();

        /**
         * Return the requested page of documents.
         * @return the requested page of documents
         */
        List> getDocuments();

        /**
         * Return the requested documents related to the children listed.
         * @return the results of fetching the documents related to the children.
         */
        Map getRelatedDocuments();

        /**
         * Return the requested attachments from the children listed.
         * @return the results of fetching the attachments for the children.
         */
        Map getAttachments();

        /**
         * Return the requested child counts by resource type.
         * @return the results of fetching the counts of each base type.
         */
        Map> getBaseTypeCounts();
    }

    /**
     * Read a document.
     * @param key the key
     * @return the document
     * @throws IOException on failure
     */
    Map readDocument(String key) throws IOException;

    /**
     * Read a list of documents.
     * @param keys the keys
     * @return a map where each key is associated with the corresponding document, or else the error associated with
     *         trying to retrieve it
     * @throws IOException on failure to parse
     */
    Map readDocuments(List keys) throws IOException;

    List batchCommit(List commands) throws IOException;

    /**
     * Look for documents close to the provided query.
     * @param query The string to match
     * @param statusFilter the status of the documents to match
     * @param resourceTypeFilter the resource type(s) to match
     * @param componentFilter the component to match
     * @param mltField the field in the document to match
     * @param maxResults the most results to return
     * @param minTermFreq the number of times a term has to be in the query to be used
     * @param minDocFreq the number of docs a term has to be in for the term to be used.
     * @return the matching list of documents
     * @throws IOException on failure
     */
    List> getMLTResults(String query, String statusFilter, String resourceTypeFilter,
        String componentFilter, List mltField, int maxResults, int minTermFreq, int minDocFreq)
        throws IOException;

    /**
     * Search.
     * @param componentFilter the component to filter on
     * @param luceneQuery the lucene query
     * @param sortFields sort fields
     * @param offset starting offset
     * @param limit max to return
     * @return list of matching docs
     * @throws IOException on failure
     */
    SocialResourceSearchResult> find(final String componentFilter, final String luceneQuery,
        List sortFields, final int offset, final int limit) throws IOException;

    /**
     * Search.
     * @param component the component to filter on
     * @param solrQueryString the lucene query
     * @param sortFields sort fields
     * @param offset starting offset
     * @param limit max to return
     * @param signals contains query params(userlanguage, browserlanguge etc)
     * @return list of matching docs
     * @throws IOException on failure
     */
    SocialResourceSearchResult> find(final String component, final String solrQueryString,
        final List sortFields, final int offset, final int limit, final Map signals)
        throws IOException;

    /**
     * Search collections Faceted search
     * @param fieldNames Fields for which we want facet counts
     * @param resourceTypeFilter Resource filter
     * @param componentFilter Component filter
     * @param count Maximum number of results
     * @param visibleOnly whether to filter by visibility
     * @param rangeFields List of range fields
     * @param includeChildren boolean flag
     * @return map containing names and counts
     * @throws IOException IOException
     */
    FacetSearchResult findFacets(final List fieldNames, final List rangeFields,
        final String resourceTypeFilter, final String componentFilter, final int count, final boolean visibleOnly,
        final boolean includeChildren) throws IOException;

    /**
     * Do a combined faceted search and filtered search, returning both the facets and an actual page of results
     * @param inPath a list of the parent paths to be searched
     * @param fieldNames the fields being used for faceted searches by value
     * @param facetRanges the fields and intervals being used for faceted searches by range
     * @param scoredQueryString a search string for which solr calculates degree of match (the "q" parameter)
     * @param maxFacetCount the limit of facet results to return, or 0 for no limit
     * @param sortFields fields to sort by, with their directions, in the returned results
     * @param offset page offset
     * @param pageSize page size
     * @param notInPath List of paths
     * @return The returned data structure is basically a list of the raw results that also holds results for the
     *         facets
     * @throws IOException IOException
     */
    SocialResourceSearchResult> findFacets(final List inPath,
        final List notInPath, final List fieldNames, final List facetRanges,
        final String scoredQueryString, final int maxFacetCount, final List sortFields,
        final int offset, final int pageSize) throws IOException;

    /**
     * Browse the documents associated with the given key.
     * @param keyName the name of the index to query on
     * @param keyValue the value in the index
     * @param baseType the base type of the documents to list (can be empty or null)
     * @param maxResults the max number of result to return. If all results should be returned, send maxResults < 0
     * @param page the 0-based page of results to return. Only used if maxResults > 0
     * @param orderBy a list of field name and booleans to dictate the order of the results. For the boolean false is
     *            descending order and true is to sort in ascending order.
     * @param visibleOnly whether to (true) return only visible documents, or (false) all documents
     * @param counts whether to count matching documents and whether to count all documents or just the visible
     *            documents.
     * @return the list of matching documents and if requested a count of the matching documents (either all or just
     *         the visible ones)
     * @throws IOException on failure
     */
    BrowseDocumentsResult browseDocuments(String keyName, String keyValue, String baseType, int maxResults, int page,
        List> orderBy, boolean visibleOnly, @Nonnull Counts counts) throws IOException;

    /**
     * Browse the documents associated with the given key.
     * @param keyName the name of the index to query on
     * @param keyValue the value in the index
     * @param baseType the base type of the documents to list (can be empty or null)
     * @param maxResults the max number of result to return. If all results should be returned, send maxResults < 0
     * @param page the 0-based page of results to return. Only used if maxResults > 0
     * @param orderBy a list of field name and booleans to dictate the order of the results. For the boolean false is
     *            descending order and true is to sort in ascending order.
     * @param visibleOnly whether to (true) return only visible documents, or (false) all documents
     * @return the list of matching docs.
     * @throws IOException on failure
     */
    List> browseDocuments(String keyName, String keyValue, String baseType, int maxResults,
        int page, List> orderBy, boolean visibleOnly) throws IOException;

    /**
     * Get the index position of a reply amongst replies of a comment
     * @param keyName the name of the index to query on
     * @param keyValue the value in the index
     * @param commentToCheck  the comment whose index need to be found
     * @param baseType the base type of the documents to list (can be empty or null)
     * @param visibleOnly whether to (true) return only visible documents, or (false) all documents
     * @return the index of comment to check.
     */
    int getCommentIndex(String keyName, String keyValue, String commentToCheck, String baseType, boolean visibleOnly);

    /**
     * Add an attachment.
     * @param key the key
     * @param attachment the attachment data
     * @throws IOException on failure
     */
    void addAttachment(String key, Map attachment) throws IOException;

    /**
     * Read an attachment.
     * @param key the key
     * @return the attachment data
     * @throws IOException on failure
     */
    Map readAttachment(String key) throws IOException;

    /**
     * Count the visible, or all the documents associated with the given key.
     * @param keyValue the value in the index
     * @param childType the value of the base_type to filter by, or null if no base type filtering should be done
     * @param visibleOnly if true, the count of only the visible (not hidden, spam ..) docs is returned
     * @return The number of matching docs and the number of visible matching docs.
     * @throws IOException on failure
     */
    long countChildren(String keyValue, String childType, boolean visibleOnly) throws IOException;

    /**
     * Count the visible, or all the documents associated with the given keys.
     * @param keyValues the path of each parent id to get a child count for
     * @param childType the value of the base_type to filter by, or null if no base type filtering should be done
     * @param visibleOnly if true, the count of only the visible (not hidden, spam ..) docs is returned
     * @return The number of matching docs and the number of visible matching docs.
     * @throws IOException on failure
     */
    Map countChildren(List keyValues, String childType, boolean visibleOnly) throws IOException;

    /**
     * Close the service.
     */
    void close();

    /**
     * Delete an attachment.
     * @param key the key to be deleted.
     * @throws IOException on failure
     */
    void deleteAttachment(String key) throws IOException;

    /**
     * Set the configuration to use.
     * @param configuration the configuration.
     */
    void setConfiguration(final SocialResourceConfiguration configuration);

    /**
     * @return true if configuration was set
     */
    boolean isConfigured();

    /**
     * Do a faceted search.
     * @param queryToAs the query to use
     * @param facetFields the facet fields to use
     * @param pivotFields the pivot fields to use
     * @param numRows the number of results to return
     * @param mincount the min number of docs matching the facet to include the result
     * @param isPivot true iff this is a pivot search
     * @return the results.
     * @throws IOException on failure
     */
    FacetResults facetedSearch(String queryToAs, List facetFields, List pivotFields, String numRows,
        String mincount, boolean isPivot) throws IOException;

    /**
     * Do a regular search.
     * @param queryToAs the query
     * @return the matching documents
     * @throws IOException on failure
     */
    List> nonFacetedSearch(String queryToAs) throws IOException;

    /**
     * Get the attachment data as an InputStream and not just the meta data of the attachment
     * @param path path the to attachment resource
     * @return the attachment as an InputStream
     * @throws IOException on error
     */
    InputStream getAttachmentInputStream(String path) throws IOException;

    /**
     * Return the placeholder for dataservice client EG: 'ASRP|MSRP'
     * @return String
     */
    String getDSClient();
}