🎨 Replace NEWEST_FIRST comparator with Kotlin version
[Sone.git] / src / main / java / net / pterodactylus / sone / data / Album.java
1 /*
2  * Sone - Album.java - Copyright Â© 2011–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 java.util.List;
21
22 /**
23  * Container for images that can also contain nested {@link Album}s.
24  */
25 public interface Album extends Identified, Fingerprintable {
26
27         /**
28          * Returns the ID of this album.
29          *
30          * @return The ID of this album
31          */
32         String getId();
33
34         /**
35          * Returns the Sone this album belongs to.
36          *
37          * @return The Sone this album belongs to
38          */
39         Sone getSone();
40
41         /**
42          * Returns the nested albums.
43          *
44          * @return The nested albums
45          */
46         List<Album> getAlbums();
47
48         /**
49          * Adds an album to this album.
50          *
51          * @param album
52          *              The album to add
53          */
54         void addAlbum(Album album);
55
56         /**
57          * Removes an album from this album.
58          *
59          * @param album
60          *              The album to remove
61          */
62         void removeAlbum(Album album);
63
64         /**
65          * Moves the given album up in this album’s albums. If the album is already the
66          * first album, nothing happens.
67          *
68          * @param album
69          *              The album to move up
70          * @return The album that the given album swapped the place with, or
71          *         <code>null</code> if the album did not change its place
72          */
73         Album moveAlbumUp(Album album);
74
75         /**
76          * Moves the given album down in this album’s albums. If the album is already
77          * the last album, nothing happens.
78          *
79          * @param album
80          *              The album to move down
81          * @return The album that the given album swapped the place with, or
82          *         <code>null</code> if the album did not change its place
83          */
84         Album moveAlbumDown(Album album);
85
86         /**
87          * Returns the images in this album.
88          *
89          * @return The images in this album
90          */
91         List<Image> getImages();
92
93         /**
94          * Adds the given image to this album.
95          *
96          * @param image
97          *              The image to add
98          */
99         void addImage(Image image);
100
101         /**
102          * Removes the given image from this album.
103          *
104          * @param image
105          *              The image to remove
106          */
107         void removeImage(Image image);
108
109         /**
110          * Moves the given image up in this album’s images. If the image is already the
111          * first image, nothing happens.
112          *
113          * @param image
114          *              The image to move up
115          * @return The image that the given image swapped the place with, or
116          *         <code>null</code> if the image did not change its place
117          */
118         Image moveImageUp(Image image);
119
120         /**
121          * Moves the given image down in this album’s images. If the image is already
122          * the last image, nothing happens.
123          *
124          * @param image
125          *              The image to move down
126          * @return The image that the given image swapped the place with, or
127          *         <code>null</code> if the image did not change its place
128          */
129         Image moveImageDown(Image image);
130
131         /**
132          * Returns whether this album contains any other albums or images.
133          *
134          * @return {@code true} if this album is empty, {@code false} otherwise
135          */
136         boolean isEmpty();
137
138         /**
139          * Returns whether this album is an identitiy’s root album.
140          *
141          * @return {@code true} if this album is an identity’s root album, {@code
142          *         false} otherwise
143          */
144         boolean isRoot();
145
146         /**
147          * Returns the parent album of this album.
148          *
149          * @return The parent album of this album, or {@code null} if this album does
150          *         not have a parent
151          */
152         Album getParent();
153
154         /**
155          * Sets the parent album of this album.
156          *
157          * @param parent
158          *              The new parent album of this album
159          * @return This album
160          */
161         Album setParent(Album parent);
162
163         /**
164          * Removes the parent album of this album.
165          *
166          * @return This album
167          */
168         Album removeParent();
169
170         /**
171          * Returns the title of this album.
172          *
173          * @return The title of this album
174          */
175         String getTitle();
176
177         /**
178          * Returns the description of this album.
179          *
180          * @return The description of this album
181          */
182         String getDescription();
183
184         /**
185          * Returns a modifier for this album.
186          *
187          * @return A modifier for this album
188          * @throws IllegalStateException
189          *              if this album can not be modified
190          */
191         Modifier modify() throws IllegalStateException;
192
193         /**
194          * Allows modifying an album. Modifications are only performed once {@link
195          * #update()} has succesfully returned a new album with the modifications
196          * made.
197          */
198         interface Modifier {
199
200                 Modifier setTitle(String title);
201
202                 Modifier setDescription(String description);
203
204                 Album update() throws IllegalStateException;
205
206                 class AlbumTitleMustNotBeEmpty extends IllegalStateException { }
207
208         }
209
210 }