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

   1 /*
   2  * Sone - PostBuilder.java - Copyright © 2013 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 /**
  21  * Builder for {@link Post} objects.
  22  * <p>
  23  * A {@link Post} consists of the following elements:
  24  * <ul>
  25  * <li>an ID,</li>
  26  * <li>a {@link Sone sender},</li>
  27  * <li>an optional {@link Sone recipient},</li>
  28  * <li>a time,</li>
  29  * <li>and a text.</li>
  30  * </ul>
  31  * Except for the recipient, all this elements have to be configured on this
  32  * builder. For the ID you have the possibility to configure either a random ID
  33  * (which should be used for new posts) or a custom ID you specify (for creating
  34  * an existing post). For the time you can use the current time (again, for
  35  * creating new posts) or the given time (for loading posts). It is an error to
  36  * specify both ways for either the ID or the time.
  37  *
  38  * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  39  */
  40 public interface PostBuilder {
  41
  42         /**
  43          * Copies all attributes of the given post to this post builder.
  44          *
  45          * @param post
  46          *            The post whose attributes to copy into this builder
  47          * @return This builder
  48          * @throws NullPointerException
  49          *             if {@code post} is {@code null}
  50          */
  51         public PostBuilder copyPost(Post post) throws NullPointerException;
  52
  53         /**
  54          * Configures this builder to use the given Sone as sender of the new post.
  55          *
  56          * @param senderId
  57          *            The ID of the sender of the post
  58          * @return This post builder
  59          */
  60         public PostBuilder from(String senderId);
  61
  62         /**
  63          * Configures this builder to use a random ID for the new post. If this
  64          * method is used, {@link #withId(String)} must not be used.
  65          *
  66          * @return This post builder
  67          */
  68         public PostBuilder randomId();
  69
  70         /**
  71          * Configures this builder to use the given ID as ID for the new post. If
  72          * this method is used, {@link #randomId()} must not be used.
  73          *
  74          * @param id
  75          *            The ID to use for the post
  76          * @return This post builder
  77          */
  78         public PostBuilder withId(String id);
  79
  80         /**
  81          * Configures this builder to use the current time when creating the post.
  82          * If this method is used, {@link #withTime(long)} must not be used.
  83          *
  84          * @return This post builder
  85          */
  86         public PostBuilder currentTime();
  87
  88         /**
  89          * Configures the builder to use the given time as time for the new post. If
  90          * this method is used, {@link #currentTime()} must not be used.
  91          *
  92          * @param time
  93          *            The time to use for the post
  94          * @return This post builder
  95          */
  96         public PostBuilder withTime(long time);
  97
  98         /**
  99          * Configures the builder to use the given text for the new post.
 100          *
 101          * @param text
 102          *            The text to use for the post
 103          * @return This post builder
 104          */
 105         public PostBuilder withText(String text);
 106
 107         /**
 108          * Configures the builder to use the given {@link Sone} as recipient for the
 109          * post.
 110          *
 111          * @param recipientId
 112          *            The ID of the recipient of the post
 113          * @return This post builder
 114          */
 115         public PostBuilder to(String recipientId);
 116
 117         /**
 118          * Verifies this builder’s configuration and creates a new post.
 119          * <p>
 120          * The following conditions must be met in order for this builder to be
 121          * configured correctly:
 122          * <ul>
 123          * <li>Exactly one of {@link #randomId()} or {@link #withId(String)} must
 124          * have been called.</li>
 125          * <li>The {@link #from(String) sender} must not be {@code null}.</li>
 126          * <li>Exactly one of {@link #currentTime()} or {@link #withTime(long)} must
 127          * have been called.</li>
 128          * <li>The {@link #withText(String) text} must not be {@code null} and must
 129          * contain something other than whitespace.</li>
 130          * <li>The {@link #to(String) recipient} must either not have been set, or
 131          * it must have been set to a {@link Sone} other than {@link #from(String)
 132          * the sender}.</li>
 133          * </ul>
 134          *
 135          * @return A new post
 136          * @throws IllegalStateException
 137          *             if this builder’s configuration is not valid
 138          */
 139         public Post build() throws IllegalStateException;
 140
 141 }