001/*
002 * (C) Copyright 2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Thomas Roger <troger@nuxeo.com>
018 */
019
020package org.nuxeo.ecm.activity;
021
022import java.io.Serializable;
023import java.util.Collection;
024import java.util.Locale;
025import java.util.Map;
026
027/**
028 * Service storing and querying activities.
029 * <p>
030 * It also uses contributed {@link ActivityStreamFilter}s to store and filter activities for specific use cases.
031 *
032 * @author <a href="mailto:troger@nuxeo.com">Thomas Roger</a>
033 * @since 5.5
034 */
035public interface ActivityStreamService {
036
037    /**
038     * To be used as {@code filterId}
039     */
040    String ALL_ACTIVITIES = "allActivities";
041
042    Activity getActivity(Serializable activityId);
043
044    ActivitiesList getActivities(Collection<Serializable> activityIds);
045
046    /**
047     * Add and store a new {@code Activity}.
048     */
049    Activity addActivity(Activity activity);
050
051    /**
052     * Remove the given {@code activities}.
053     */
054    void removeActivities(Collection<Activity> activities);
055
056    /**
057     * Returns the list of activities filtered by the given parameters using the {@code ActivityStreamFilter} referenced
058     * by {@code filterId}.
059     *
060     * @param filterId the id of the {@code ActivityStreamFilter} to use.
061     * @param parameters this query parameters.
062     * @param offset the offset (starting at 0) into the list of activities.
063     * @param limit the maximum number of activities to retrieve, or 0 for all of them.
064     * @throws NuxeoException if there is no {@code ActivityStreamFilter} matching the given {@code filterId}.
065     */
066    ActivitiesList query(String filterId, Map<String, Serializable> parameters, long offset, long limit);
067
068    /**
069     * Returns the list of activities filtered by the given parameters using the {@code ActivityStreamFilter} referenced
070     * by {@code filterId}.
071     *
072     * @param filterId the id of the {@code ActivityStreamFilter} to use.
073     * @param parameters this query parameters.
074     * @throws NuxeoException if there is no {@code ActivityStreamFilter} matching the given {@code filterId}.
075     */
076    ActivitiesList query(String filterId, Map<String, Serializable> parameters);
077
078    /**
079     * Computes an {@link ActivityMessage} from the given {@code activity} and {@code locale}.
080     */
081    ActivityMessage toActivityMessage(Activity activity, Locale locale);
082
083    /**
084     * Computes an {@link ActivityMessage} from the given {@code activity}, {@code locale} and use .
085     */
086    ActivityMessage toActivityMessage(Activity activity, Locale locale, String activityLinkBuilderName);
087
088    /**
089     * Computes an {@link ActivityReplyMessage} from the given {@code activityReply} and {@code locale}.
090     *
091     * @since 5.6
092     */
093    ActivityReplyMessage toActivityReplyMessage(ActivityReply activityReply, Locale locale);
094
095    /**
096     * Computes an {@link ActivityReplyMessage} from the given {@code activityReply} and {@code locale}.
097     *
098     * @since 5.6
099     */
100    ActivityReplyMessage toActivityReplyMessage(ActivityReply activityReply, Locale locale,
101            String activityLinkBuilderName);
102
103    /**
104     * Returns the {@link ActivityStream} with the given {@code name}, {@code null} if it does not exist.
105     */
106    ActivityStream getActivityStream(String name);
107
108    /**
109     * Returns the {@link ActivityLinkBuilder} with the given {@code name}.
110     * <p>
111     * If {@code name} is {@code null}, or if the {@link ActivityLinkBuilder} does not exist, fallback on the default
112     * one if any.
113     */
114    ActivityLinkBuilder getActivityLinkBuilder(String name);
115
116    /**
117     * Add an {@link ActivityReply} to the {@link Activity} referenced by the {@code activityId}.
118     *
119     * @return the updated {@code activityReply}
120     * @since 5.6
121     */
122    ActivityReply addActivityReply(Serializable activityId, ActivityReply activityReply);
123
124    /**
125     * Remove an {@link ActivityReply} from the {@link Activity} referenced by the {@code activityId}.
126     *
127     * @return the removed {@link ActivityReply} if any, {@code null} otherwise
128     * @since 5.6
129     */
130    ActivityReply removeActivityReply(Serializable activityId, String activityReplyId);
131
132}