View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements. See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership. The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License. You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied. See the License for the
16   * specific language governing permissions and limitations under the License.
17   */
18  package org.apache.shindig.social.opensocial.spi;
19  
20  import org.apache.shindig.auth.SecurityToken;
21  import org.apache.shindig.social.opensocial.model.Person;
22  import org.apache.shindig.social.sample.spi.JsonDbOpensocialService;
23  
24  import com.google.inject.ImplementedBy;
25  
26  import java.util.Set;
27  import java.util.concurrent.Future;
28  
29  @ImplementedBy(JsonDbOpensocialService.class)
30  
31  public interface PersonService {
32  
33    /***
34     * When used will sort people by the container's definition of top friends. Note that both the
35     * sort order and the filter are required to deliver a topFriends response. The PersonService
36     * implementation should take this into account when delivering a topFriends response.
37     */
38    public static String TOP_FRIENDS_SORT = "topFriends";
39    /***
40     * Retrieves only the user's top friends. The meaning of top and how many top is is defined by the
41     * PersonService implementation.
42     */
43    public static String TOP_FRIENDS_FILTER = "topFriends";
44    /***
45     * Retrieves all friends with any data for this application.
46     * TODO: how is this application defined
47     */
48    public static String HAS_APP_FILTER = "hasApp";
49    /***
50     * Retrieves all friends. (ie no filter)
51     */
52    public static String ALL_FILTER = "all";
53    /***
54     * Will filter the people requested by checking if they are friends with the given idSpec. The
55     * filter value will be set to the userId of the target friend.
56     */
57    public static String IS_WITH_FRIENDS_FILTER = "isFriendsWith";
58  
59    public enum SortOrder {
60      ascending, descending
61    }
62  
63    public enum FilterOperation {
64      contains, equals, startsWith, present
65    }
66  
67    /***
68     * Returns a list of people that correspond to the passed in person ids.
69     *
70     * @param userIds A set of users
71     * @param groupId The group
72     * @param collectionOptions How to filter, sort and paginate the collection being fetched
73     * @param fields The profile details to fetch. Empty set implies all
74     * @param token The gadget token @return a list of people.
75     */
76    Future<RestfulCollection<Person>> getPeople(Set<UserId> userIds, GroupId groupId,
77        CollectionOptions collectionOptions, Set<String> fields, SecurityToken token)
78        throws SocialSpiException;
79  
80    /***
81     * Returns a person that corresponds to the passed in person id.
82     *
83     * @param id The id of the person to fetch.
84     * @param fields The fields to fetch.
85     * @param token The gadget token
86     * @return a list of people.
87     */
88    Future<Person> getPerson(UserId id, Set<String> fields, SecurityToken token)
89        throws SocialSpiException;
90  }