src/main/java/net/pterodactylus/sone/data/Sone.java

   1 /*
   2  * Sone - Sone.java - Copyright © 2010–2020 David Roden
   3  *
   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.
   8  *
   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.
  13  *
  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/>.
  16  */
  17
  18 package net.pterodactylus.sone.data;
  19
  20 import static com.google.common.collect.FluentIterable.from;
  21 import static java.util.Arrays.asList;
  22 import static net.pterodactylus.sone.data.Album.FLATTENER;
  23 import static net.pterodactylus.sone.data.Album.IMAGES;
  24
  25 import java.util.Collection;
  26 import java.util.Collections;
  27 import java.util.Comparator;
  28 import java.util.List;
  29 import java.util.Set;
  30
  31 import javax.annotation.Nonnull;
  32 import javax.annotation.Nullable;
  33
  34 import net.pterodactylus.sone.freenet.wot.Identity;
  35
  36 import freenet.keys.FreenetURI;
  37
  38 import com.google.common.base.Function;
  39 import com.google.common.primitives.Ints;
  40
  41 /**
  42  * A Sone defines everything about a user: her profile, her status updates, her
  43  * replies, her likes and dislikes, etc.
  44  */
  45 public interface Sone extends Identified, Fingerprintable, Comparable<Sone> {
  46
  47         /**
  48          * Enumeration for the possible states of a {@link Sone}.
  49          */
  50         public enum SoneStatus {
  51
  52                 /** The Sone is unknown, i.e. not yet downloaded. */
  53                 unknown,
  54
  55                 /** The Sone is idle, i.e. not being downloaded or inserted. */
  56                 idle,
  57
  58                 /** The Sone is currently being inserted. */
  59                 inserting,
  60
  61                 /** The Sone is currently being downloaded. */
  62                 downloading,
  63         }
  64
  65         /** Comparator that sorts Sones by number of images (descending). */
  66         public static final Comparator<Sone> IMAGE_COUNT_COMPARATOR = new Comparator<Sone>() {
  67
  68                 /**
  69                  * {@inheritDoc}
  70                  */
  71                 @Override
  72                 public int compare(Sone leftSone, Sone rightSone) {
  73                         int rightSoneImageCount = from(asList(rightSone.getRootAlbum())).transformAndConcat(FLATTENER).transformAndConcat(IMAGES).size();
  74                         int leftSoneImageCount = from(asList(leftSone.getRootAlbum())).transformAndConcat(FLATTENER).transformAndConcat(IMAGES).size();
  75                         /* sort descending. */
  76                         return Ints.compare(rightSoneImageCount, leftSoneImageCount);
  77                 }
  78         };
  79
  80         public static final Function<Sone, List<Album>> toAllAlbums = new Function<Sone, List<Album>>() {
  81                 @Override
  82                 public List<Album> apply(@Nullable Sone sone) {
  83                         return (sone == null) ? Collections.<Album>emptyList() : FLATTENER.apply(
  84                                         sone.getRootAlbum());
  85                 }
  86         };
  87
  88         public static final Function<Sone, List<Image>> toAllImages = new Function<Sone, List<Image>>() {
  89                 @Override
  90                 public List<Image> apply(@Nullable Sone sone) {
  91                         return (sone == null) ? Collections.<Image>emptyList() :
  92                                         from(FLATTENER.apply(sone.getRootAlbum()))
  93                                                         .transformAndConcat(IMAGES).toList();
  94                 }
  95         };
  96
  97         /**
  98          * Returns the identity of this Sone.
  99          *
 100          * @return The identity of this Sone
 101          */
 102         @Nonnull
 103         Identity getIdentity();
 104
 105         /**
 106          * Returns the name of this Sone.
 107          *
 108          * @return The name of this Sone
 109          */
 110         @Nonnull
 111         String getName();
 112
 113         /**
 114          * Returns whether this Sone is a local Sone.
 115          *
 116          * @return {@code true} if this Sone is a local Sone, {@code false} otherwise
 117          */
 118         boolean isLocal();
 119
 120         /**
 121          * Returns the request URI of this Sone.
 122          *
 123          * @return The request URI of this Sone
 124          */
 125         @Nonnull
 126         FreenetURI getRequestUri();
 127
 128         /**
 129          * Returns the latest edition of this Sone.
 130          *
 131          * @return The latest edition of this Sone
 132          */
 133         long getLatestEdition();
 134
 135         /**
 136          * Sets the latest edition of this Sone. If the given latest edition is not
 137          * greater than the current latest edition, the latest edition of this Sone is
 138          * not changed.
 139          *
 140          * @param latestEdition
 141          *              The latest edition of this Sone
 142          */
 143         void setLatestEdition(long latestEdition);
 144
 145         /**
 146          * Return the time of the last inserted update of this Sone.
 147          *
 148          * @return The time of the update (in milliseconds since Jan 1, 1970 UTC)
 149          */
 150         long getTime();
 151
 152         /**
 153          * Sets the time of the last inserted update of this Sone.
 154          *
 155          * @param time
 156          *              The time of the update (in milliseconds since Jan 1, 1970 UTC)
 157          * @return This Sone (for method chaining)
 158          */
 159         @Nonnull
 160         Sone setTime(long time);
 161
 162         /**
 163          * Returns the status of this Sone.
 164          *
 165          * @return The status of this Sone
 166          */
 167         @Nonnull
 168         SoneStatus getStatus();
 169
 170         /**
 171          * Sets the new status of this Sone.
 172          *
 173          * @param status
 174          *              The new status of this Sone
 175          * @return This Sone
 176          * @throws IllegalArgumentException
 177          *              if {@code status} is {@code null}
 178          */
 179         @Nonnull
 180         Sone setStatus(@Nonnull SoneStatus status);
 181
 182         /**
 183          * Returns a copy of the profile. If you want to update values in the profile
 184          * of this Sone, update the values in the returned {@link Profile} and use
 185          * {@link #setProfile(Profile)} to change the profile in this Sone.
 186          *
 187          * @return A copy of the profile
 188          */
 189         @Nonnull
 190         Profile getProfile();
 191
 192         /**
 193          * Sets the profile of this Sone. A copy of the given profile is stored so that
 194          * subsequent modifications of the given profile are not reflected in this
 195          * Sone!
 196          *
 197          * @param profile
 198          *              The profile to set
 199          */
 200         void setProfile(@Nonnull Profile profile);
 201
 202         /**
 203          * Returns the client used by this Sone.
 204          *
 205          * @return The client used by this Sone, or {@code null}
 206          */
 207         @Nullable
 208         Client getClient();
 209
 210         /**
 211          * Sets the client used by this Sone.
 212          *
 213          * @param client
 214          *              The client used by this Sone, or {@code null}
 215          * @return This Sone (for method chaining)
 216          */
 217         @Nonnull
 218         Sone setClient(@Nullable Client client);
 219
 220         /**
 221          * Returns whether this Sone is known.
 222          *
 223          * @return {@code true} if this Sone is known, {@code false} otherwise
 224          */
 225         boolean isKnown();
 226
 227         /**
 228          * Sets whether this Sone is known.
 229          *
 230          * @param known
 231          *              {@code true} if this Sone is known, {@code false} otherwise
 232          * @return This Sone
 233          */
 234         @Nonnull
 235         Sone setKnown(boolean known);
 236
 237         /**
 238          * Returns all friend Sones of this Sone.
 239          *
 240          * @return The friend Sones of this Sone
 241          */
 242         @Nonnull
 243         Collection<String> getFriends();
 244
 245         /**
 246          * Returns whether this Sone has the given Sone as a friend Sone.
 247          *
 248          * @param friendSoneId
 249          *              The ID of the Sone to check for
 250          * @return {@code true} if this Sone has the given Sone as a friend, {@code
 251          *         false} otherwise
 252          */
 253         boolean hasFriend(@Nonnull String friendSoneId);
 254
 255         /**
 256          * Returns the list of posts of this Sone, sorted by time, newest first.
 257          *
 258          * @return All posts of this Sone
 259          */
 260         @Nonnull
 261         List<Post> getPosts();
 262
 263         /**
 264          * Sets all posts of this Sone at once.
 265          *
 266          * @param posts
 267          *              The new (and only) posts of this Sone
 268          * @return This Sone (for method chaining)
 269          */
 270         @Nonnull
 271         Sone setPosts(@Nonnull Collection<Post> posts);
 272
 273         /**
 274          * Adds the given post to this Sone. The post will not be added if its {@link
 275          * Post#getSone() Sone} is not this Sone.
 276          *
 277          * @param post
 278          *              The post to add
 279          */
 280         void addPost(@Nonnull Post post);
 281
 282         /**
 283          * Removes the given post from this Sone.
 284          *
 285          * @param post
 286          *              The post to remove
 287          */
 288         void removePost(@Nonnull Post post);
 289
 290         /**
 291          * Returns all replies this Sone made.
 292          *
 293          * @return All replies this Sone made
 294          */
 295         @Nonnull
 296         Set<PostReply> getReplies();
 297
 298         /**
 299          * Sets all replies of this Sone at once.
 300          *
 301          * @param replies
 302          *              The new (and only) replies of this Sone
 303          * @return This Sone (for method chaining)
 304          */
 305         @Nonnull
 306         Sone setReplies(@Nonnull Collection<PostReply> replies);
 307
 308         /**
 309          * Adds a reply to this Sone. If the given reply was not made by this Sone,
 310          * nothing is added to this Sone.
 311          *
 312          * @param reply
 313          *              The reply to add
 314          */
 315         void addReply(@Nonnull PostReply reply);
 316
 317         /**
 318          * Removes a reply from this Sone.
 319          *
 320          * @param reply
 321          *              The reply to remove
 322          */
 323         void removeReply(@Nonnull PostReply reply);
 324
 325         /**
 326          * Returns the IDs of all liked posts.
 327          *
 328          * @return All liked posts’ IDs
 329          */
 330         @Nonnull
 331         Set<String> getLikedPostIds();
 332
 333         /**
 334          * Sets the IDs of all liked posts.
 335          *
 336          * @param likedPostIds
 337          *              All liked posts’ IDs
 338          * @return This Sone (for method chaining)
 339          */
 340         @Nonnull
 341         Sone setLikePostIds(@Nonnull Set<String> likedPostIds);
 342
 343         /**
 344          * Checks whether the given post ID is liked by this Sone.
 345          *
 346          * @param postId
 347          *              The ID of the post
 348          * @return {@code true} if this Sone likes the given post, {@code false}
 349          *         otherwise
 350          */
 351         boolean isLikedPostId(@Nonnull String postId);
 352
 353         /**
 354          * Adds the given post ID to the list of posts this Sone likes.
 355          *
 356          * @param postId
 357          *              The ID of the post
 358          * @return This Sone (for method chaining)
 359          */
 360         @Nonnull
 361         Sone addLikedPostId(@Nonnull String postId);
 362
 363         /**
 364          * Removes the given post ID from the list of posts this Sone likes.
 365          *
 366          * @param postId
 367          *              The ID of the post
 368          */
 369         void removeLikedPostId(@Nonnull String postId);
 370
 371         /**
 372          * Returns the IDs of all liked replies.
 373          *
 374          * @return All liked replies’ IDs
 375          */
 376         @Nonnull
 377         Set<String> getLikedReplyIds();
 378
 379         /**
 380          * Sets the IDs of all liked replies.
 381          *
 382          * @param likedReplyIds
 383          *              All liked replies’ IDs
 384          * @return This Sone (for method chaining)
 385          */
 386         @Nonnull
 387         Sone setLikeReplyIds(@Nonnull Set<String> likedReplyIds);
 388
 389         /**
 390          * Checks whether the given reply ID is liked by this Sone.
 391          *
 392          * @param replyId
 393          *              The ID of the reply
 394          * @return {@code true} if this Sone likes the given reply, {@code false}
 395          *         otherwise
 396          */
 397         boolean isLikedReplyId(@Nonnull String replyId);
 398
 399         /**
 400          * Adds the given reply ID to the list of replies this Sone likes.
 401          *
 402          * @param replyId
 403          *              The ID of the reply
 404          * @return This Sone (for method chaining)
 405          */
 406         @Nonnull
 407         Sone addLikedReplyId(@Nonnull String replyId);
 408
 409         /**
 410          * Removes the given post ID from the list of replies this Sone likes.
 411          *
 412          * @param replyId
 413          *              The ID of the reply
 414          */
 415         void removeLikedReplyId(@Nonnull String replyId);
 416
 417         /**
 418          * Returns the root album that contains all visible albums of this Sone.
 419          *
 420          * @return The root album of this Sone
 421          */
 422         @Nonnull
 423         Album getRootAlbum();
 424
 425         /**
 426          * Returns Sone-specific options.
 427          *
 428          * @return The options of this Sone
 429          */
 430         @Nonnull
 431         SoneOptions getOptions();
 432
 433         /**
 434          * Sets the options of this Sone.
 435          *
 436          * @param options
 437          *              The options of this Sone
 438          */
 439         /* TODO - remove this method again, maybe add an option provider */
 440         void setOptions(@Nonnull SoneOptions options);
 441
 442 }