2 * Sone - Sone.java - Copyright © 2010–2012 David Roden
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 package net.pterodactylus.sone.data;
20 import java.util.Collection;
21 import java.util.Comparator;
22 import java.util.List;
25 import net.pterodactylus.sone.core.Core;
26 import net.pterodactylus.sone.core.Options;
27 import net.pterodactylus.sone.freenet.wot.Identity;
28 import net.pterodactylus.sone.freenet.wot.OwnIdentity;
29 import net.pterodactylus.sone.template.SoneAccessor;
30 import net.pterodactylus.util.collection.filter.Filter;
31 import freenet.keys.FreenetURI;
34 * A Sone defines everything about a user: her profile, her status updates, her
35 * replies, her likes and dislikes, etc.
37 * Operations that modify the Sone need to synchronize on the Sone in question.
39 * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
41 public interface Sone extends Fingerprintable, Comparable<Sone> {
44 * Enumeration for the possible states of a {@link Sone}.
46 * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
48 public enum SoneStatus {
50 /** The Sone is unknown, i.e. not yet downloaded. */
53 /** The Sone is idle, i.e. not being downloaded or inserted. */
56 /** The Sone is currently being inserted. */
59 /** The Sone is currently being downloaded. */
64 * The possible values for the “show custom avatars” option.
66 * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
68 public static enum ShowCustomAvatars {
70 /** Never show custom avatars. */
73 /** Only show custom avatars of followed Sones. */
76 /** Only show custom avatars of Sones you manually trust. */
79 /** Only show custom avatars of automatically trusted Sones. */
82 /** Always show custom avatars. */
87 /** comparator that sorts Sones by their nice name. */
88 public static final Comparator<Sone> NICE_NAME_COMPARATOR = new Comparator<Sone>() {
91 public int compare(Sone leftSone, Sone rightSone) {
92 int diff = SoneAccessor.getNiceName(leftSone).compareToIgnoreCase(SoneAccessor.getNiceName(rightSone));
96 return leftSone.getId().compareToIgnoreCase(rightSone.getId());
102 * Comparator that sorts Sones by last activity (least recent active first).
104 public static final Comparator<Sone> LAST_ACTIVITY_COMPARATOR = new Comparator<Sone>() {
107 public int compare(Sone firstSone, Sone secondSone) {
108 return (int) Math.min(Integer.MAX_VALUE, Math.max(Integer.MIN_VALUE, secondSone.getTime() - firstSone.getTime()));
112 /** Comparator that sorts Sones by numbers of posts (descending). */
113 public static final Comparator<Sone> POST_COUNT_COMPARATOR = new Comparator<Sone>() {
119 public int compare(Sone leftSone, Sone rightSone) {
120 return (leftSone.getPosts().size() != rightSone.getPosts().size()) ? (rightSone.getPosts().size() - leftSone.getPosts().size()) : (rightSone.getReplies().size() - leftSone.getReplies().size());
124 /** Comparator that sorts Sones by number of images (descending). */
125 public static final Comparator<Sone> IMAGE_COUNT_COMPARATOR = new Comparator<Sone>() {
131 public int compare(Sone leftSone, Sone rightSone) {
132 return rightSone.getAllImages().size() - leftSone.getAllImages().size();
136 /** Filter to remove Sones that have not been downloaded. */
137 public static final Filter<Sone> EMPTY_SONE_FILTER = new Filter<Sone>() {
140 public boolean filterObject(Sone sone) {
141 return sone.getTime() != 0;
145 /** Filter that matches all {@link Core#getLocalSones() local Sones}. */
146 public static final Filter<Sone> LOCAL_SONE_FILTER = new Filter<Sone>() {
149 public boolean filterObject(Sone sone) {
150 return sone.getIdentity() instanceof OwnIdentity;
155 /** Filter that matches Sones that have at least one album. */
156 public static final Filter<Sone> HAS_ALBUM_FILTER = new Filter<Sone>() {
159 public boolean filterObject(Sone sone) {
160 return !sone.getAlbums().isEmpty();
169 * Returns the identity of this Sone.
171 * @return The identity of this Sone
173 public String getId();
176 * Returns the identity of this Sone.
178 * @return The identity of this Sone
180 public Identity getIdentity();
183 * Sets the identity of this Sone. The {@link Identity#getId() ID} of the
184 * identity has to match this Sone’s {@link #getId()}.
187 * The identity of this Sone
188 * @return This Sone (for method chaining)
189 * @throws IllegalArgumentException
190 * if the ID of the identity does not match this Sone’s ID
192 public Sone setIdentity(Identity identity) throws IllegalArgumentException;
195 * Returns whether this Sone is local.
197 * @return {@code true} if this Sone is local, {@code false} otherwise
199 public boolean isLocal();
202 * Returns the name of this Sone.
204 * @return The name of this Sone
206 public String getName();
209 * Returns the request URI of this Sone.
211 * @return The request URI of this Sone
213 public FreenetURI getRequestUri();
216 * Sets the request URI of this Sone.
219 * The request URI of this Sone
220 * @return This Sone (for method chaining)
222 public Sone setRequestUri(FreenetURI requestUri);
225 * Returns the insert URI of this Sone.
227 * @return The insert URI of this Sone
229 public FreenetURI getInsertUri();
232 * Sets the insert URI of this Sone.
235 * The insert URI of this Sone
236 * @return This Sone (for method chaining)
238 public Sone setInsertUri(FreenetURI insertUri);
241 * Returns the latest edition of this Sone.
243 * @return The latest edition of this Sone
245 public long getLatestEdition();
248 * Sets the latest edition of this Sone. If the given latest edition is not
249 * greater than the current latest edition, the latest edition of this Sone
252 * @param latestEdition
253 * The latest edition of this Sone
255 public void setLatestEdition(long latestEdition);
258 * Return the time of the last inserted update of this Sone.
260 * @return The time of the update (in milliseconds since Jan 1, 1970 UTC)
262 public long getTime();
265 * Sets the time of the last inserted update of this Sone.
268 * The time of the update (in milliseconds since Jan 1, 1970 UTC)
269 * @return This Sone (for method chaining)
271 public Sone setTime(long time);
274 * Returns the status of this Sone.
276 * @return The status of this Sone
278 public SoneStatus getStatus();
281 * Sets the new status of this Sone.
284 * The new status of this Sone
286 * @throws IllegalArgumentException
287 * if {@code status} is {@code null}
289 public Sone setStatus(SoneStatus status);
292 * Returns a copy of the profile. If you want to update values in the
293 * profile of this Sone, update the values in the returned {@link Profile}
294 * and use {@link #setProfile(Profile)} to change the profile in this Sone.
296 * @return A copy of the profile
298 public Profile getProfile();
301 * Sets the profile of this Sone. A copy of the given profile is stored so
302 * that subsequent modifications of the given profile are not reflected in
308 public void setProfile(Profile profile);
311 * Returns the client used by this Sone.
313 * @return The client used by this Sone, or {@code null}
315 public Client getClient();
318 * Sets the client used by this Sone.
321 * The client used by this Sone, or {@code null}
322 * @return This Sone (for method chaining)
324 public Sone setClient(Client client);
327 * Returns whether this Sone is known.
329 * @return {@code true} if this Sone is known, {@code false} otherwise
331 public boolean isKnown();
334 * Sets whether this Sone is known.
337 * {@code true} if this Sone is known, {@code false} otherwise
340 public Sone setKnown(boolean known);
343 * Returns all friend Sones of this Sone.
345 * @return The friend Sones of this Sone
347 public Collection<String> getFriends();
350 * Returns whether this Sone has the given Sone as a friend Sone.
352 * @param friendSoneId
353 * The ID of the Sone to check for
354 * @return {@code true} if this Sone has the given Sone as a friend,
355 * {@code false} otherwise
357 public boolean hasFriend(String friendSoneId);
360 * Adds the given Sone as a friend Sone.
363 * The friend Sone to add
364 * @return This Sone (for method chaining)
366 public Sone addFriend(String friendSone);
369 * Removes the given Sone as a friend Sone.
371 * @param friendSoneId
372 * The ID of the friend Sone to remove
373 * @return This Sone (for method chaining)
375 public Sone removeFriend(String friendSoneId);
378 * Returns the list of posts of this Sone, sorted by time, newest first.
380 * @return All posts of this Sone
382 public List<Post> getPosts();
385 * Sets all posts of this Sone at once.
388 * The new (and only) posts of this Sone
389 * @return This Sone (for method chaining)
391 public Sone setPosts(Collection<Post> posts);
394 * Adds the given post to this Sone. The post will not be added if its
395 * {@link Post#getSone() Sone} is not this Sone.
400 public void addPost(Post post);
403 * Removes the given post from this Sone.
408 public void removePost(Post post);
411 * Returns all replies this Sone made.
413 * @return All replies this Sone made
415 public Set<PostReply> getReplies();
418 * Sets all replies of this Sone at once.
421 * The new (and only) replies of this Sone
422 * @return This Sone (for method chaining)
424 public Sone setReplies(Collection<PostReply> replies);
427 * Adds a reply to this Sone. If the given reply was not made by this Sone,
428 * nothing is added to this Sone.
433 public void addReply(PostReply reply);
436 * Removes a reply from this Sone.
439 * The reply to remove
441 public void removeReply(PostReply reply);
444 * Returns the IDs of all liked posts.
446 * @return All liked posts’ IDs
448 public Set<String> getLikedPostIds();
451 * Sets the IDs of all liked posts.
453 * @param likedPostIds
454 * All liked posts’ IDs
455 * @return This Sone (for method chaining)
457 public Sone setLikePostIds(Set<String> likedPostIds);
460 * Checks whether the given post ID is liked by this Sone.
464 * @return {@code true} if this Sone likes the given post, {@code false}
467 public boolean isLikedPostId(String postId);
470 * Adds the given post ID to the list of posts this Sone likes.
474 * @return This Sone (for method chaining)
476 public Sone addLikedPostId(String postId);
479 * Removes the given post ID from the list of posts this Sone likes.
483 * @return This Sone (for method chaining)
485 public Sone removeLikedPostId(String postId);
488 * Returns the IDs of all liked replies.
490 * @return All liked replies’ IDs
492 public Set<String> getLikedReplyIds();
495 * Sets the IDs of all liked replies.
497 * @param likedReplyIds
498 * All liked replies’ IDs
499 * @return This Sone (for method chaining)
501 public Sone setLikeReplyIds(Set<String> likedReplyIds);
504 * Checks whether the given reply ID is liked by this Sone.
507 * The ID of the reply
508 * @return {@code true} if this Sone likes the given reply, {@code false}
511 public boolean isLikedReplyId(String replyId);
514 * Adds the given reply ID to the list of replies this Sone likes.
517 * The ID of the reply
518 * @return This Sone (for method chaining)
520 public Sone addLikedReplyId(String replyId);
523 * Removes the given post ID from the list of replies this Sone likes.
526 * The ID of the reply
527 * @return This Sone (for method chaining)
529 public Sone removeLikedReplyId(String replyId);
532 * Returns the albums of this Sone.
534 * @return The albums of this Sone
536 public List<Album> getAlbums();
539 * Returns a flattened list of all albums of this Sone. The resulting list
540 * contains parent albums before child albums so that the resulting list can
541 * be parsed in a single pass.
543 * @return The flattened albums
545 public List<Album> getAllAlbums();
548 * Returns all images of a Sone. Images of a album are inserted into this
549 * list before images of all child albums.
551 * @return The list of all images
553 public List<Image> getAllImages();
556 * Adds an album to this Sone.
561 public void addAlbum(Album album);
564 * Sets the albums of this Sone.
567 * The albums of this Sone
569 public void setAlbums(Collection<? extends Album> albums);
572 * Removes an album from this Sone.
575 * The album to remove
577 public void removeAlbum(Album album);
580 * Moves the given album up in this album’s albums. If the album is already
581 * the first album, nothing happens.
584 * The album to move up
585 * @return The album that the given album swapped the place with, or
586 * <code>null</code> if the album did not change its place
588 public Album moveAlbumUp(Album album);
591 * Moves the given album down in this album’s albums. If the album is
592 * already the last album, nothing happens.
595 * The album to move down
596 * @return The album that the given album swapped the place with, or
597 * <code>null</code> if the album did not change its place
599 public Album moveAlbumDown(Album album);
602 * Returns Sone-specific options.
604 * @return The options of this Sone
606 public Options getOptions();