001/*
002 * (C) Copyright 2011 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Thomas Roger <troger@nuxeo.com>
016 */
017
018package org.nuxeo.ecm.activity;
019
020import java.io.Serializable;
021import java.util.Collection;
022import java.util.Locale;
023import java.util.Map;
024
025/**
026 * Service storing and querying activities.
027 * <p>
028 * It also uses contributed {@link ActivityStreamFilter}s to store and filter activities for specific use cases.
029 *
030 * @author <a href="mailto:troger@nuxeo.com">Thomas Roger</a>
031 * @since 5.5
032 */
033public interface ActivityStreamService {
034
035    /**
036     * To be used as {@code filterId}
037     */
038    String ALL_ACTIVITIES = "allActivities";
039
040    Activity getActivity(Serializable activityId);
041
042    ActivitiesList getActivities(Collection<Serializable> activityIds);
043
044    /**
045     * Add and store a new {@code Activity}.
046     */
047    Activity addActivity(Activity activity);
048
049    /**
050     * Remove the given {@code activities}.
051     */
052    void removeActivities(Collection<Activity> activities);
053
054    /**
055     * Returns the list of activities filtered by the given parameters using the {@code ActivityStreamFilter} referenced
056     * by {@code filterId}.
057     *
058     * @param filterId the id of the {@code ActivityStreamFilter} to use.
059     * @param parameters this query parameters.
060     * @param offset the offset (starting at 0) into the list of activities.
061     * @param limit the maximum number of activities to retrieve, or 0 for all of them.
062     * @throws NuxeoException if there is no {@code ActivityStreamFilter} matching the given {@code filterId}.
063     */
064    ActivitiesList query(String filterId, Map<String, Serializable> parameters, long offset, long limit);
065
066    /**
067     * Returns the list of activities filtered by the given parameters using the {@code ActivityStreamFilter} referenced
068     * by {@code filterId}.
069     *
070     * @param filterId the id of the {@code ActivityStreamFilter} to use.
071     * @param parameters this query parameters.
072     * @throws NuxeoException if there is no {@code ActivityStreamFilter} matching the given {@code filterId}.
073     */
074    ActivitiesList query(String filterId, Map<String, Serializable> parameters);
075
076    /**
077     * Computes an {@link ActivityMessage} from the given {@code activity} and {@code locale}.
078     */
079    ActivityMessage toActivityMessage(Activity activity, Locale locale);
080
081    /**
082     * Computes an {@link ActivityMessage} from the given {@code activity}, {@code locale} and use .
083     */
084    ActivityMessage toActivityMessage(Activity activity, Locale locale, String activityLinkBuilderName);
085
086    /**
087     * Computes an {@link ActivityReplyMessage} from the given {@code activityReply} and {@code locale}.
088     *
089     * @since 5.6
090     */
091    ActivityReplyMessage toActivityReplyMessage(ActivityReply activityReply, Locale locale);
092
093    /**
094     * Computes an {@link ActivityReplyMessage} from the given {@code activityReply} and {@code locale}.
095     *
096     * @since 5.6
097     */
098    ActivityReplyMessage toActivityReplyMessage(ActivityReply activityReply, Locale locale,
099            String activityLinkBuilderName);
100
101    /**
102     * Returns the {@link ActivityStream} with the given {@code name}, {@code null} if it does not exist.
103     */
104    ActivityStream getActivityStream(String name);
105
106    /**
107     * Returns the {@link ActivityLinkBuilder} with the given {@code name}.
108     * <p>
109     * If {@code name} is {@code null}, or if the {@link ActivityLinkBuilder} does not exist, fallback on the default
110     * one if any.
111     */
112    ActivityLinkBuilder getActivityLinkBuilder(String name);
113
114    /**
115     * Add an {@link ActivityReply} to the {@link Activity} referenced by the {@code activityId}.
116     *
117     * @return the updated {@code activityReply}
118     * @since 5.6
119     */
120    ActivityReply addActivityReply(Serializable activityId, ActivityReply activityReply);
121
122    /**
123     * Remove an {@link ActivityReply} from the {@link Activity} referenced by the {@code activityId}.
124     *
125     * @return the removed {@link ActivityReply} if any, {@code null} otherwise
126     * @since 5.6
127     */
128    ActivityReply removeActivityReply(Serializable activityId, String activityReplyId);
129
130}