Don’t hand in a SoneProvider to a class that is going to be the SoneProvider
[Sone.git] / src / main / java / net / pterodactylus / sone / data / Image.java
1 /*
2  * Sone - Image.java - Copyright © 2011–2016 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  * Container for image metadata.
22  *
23  * @author <a href="mailto:d.roden@xplosion.de">David Roden</a>
24  */
25 public interface Image extends Identified, Fingerprintable {
26
27         /**
28          * Returns the ID of this image.
29          *
30          * @return The ID of this image
31          */
32         String getId();
33
34         /**
35          * Returns the Sone this image belongs to.
36          *
37          * @return The Sone this image belongs to
38          */
39         Sone getSone();
40
41         /**
42          * Returns the album this image belongs to.
43          *
44          * @return The album this image belongs to
45          */
46         Album getAlbum();
47
48         /**
49          * Sets the album this image belongs to. The album of an image can only be
50          * set once, and it is usually called by {@link Album#addImage(Image)}.
51          *
52          * @param album
53          *            The album this image belongs to
54          * @return This image
55          */
56         Image setAlbum(Album album);
57
58         /**
59          * Returns the request key of this image.
60          *
61          * @return The request key of this image
62          */
63         String getKey();
64
65         /**
66          * Returns whether the image has already been inserted. An image is
67          * considered as having been inserted it its {@link #getKey() key} is not
68          * {@code null}.
69          *
70          * @return {@code true} if there is a key for this image, {@code false}
71          *         otherwise
72          */
73         boolean isInserted();
74
75         /**
76          * Returns the creation time of this image.
77          *
78          * @return The creation time of this image (in milliseconds since 1970, Jan
79          *         1, UTC)
80          */
81         long getCreationTime();
82
83         /**
84          * Returns the width of this image.
85          *
86          * @return The width of this image (in pixels)
87          */
88         int getWidth();
89
90         /**
91          * Returns the height of this image.
92          *
93          * @return The height of this image (in pixels)
94          */
95         int getHeight();
96
97         /**
98          * Returns the title of this image.
99          *
100          * @return The title of this image
101          */
102         String getTitle();
103
104         /**
105          * Returns the description of this image.
106          *
107          * @return The description of this image
108          */
109         String getDescription();
110
111         /**
112          * {@inheritDoc}
113          */
114         @Override
115         String getFingerprint();
116
117         Modifier modify() throws IllegalStateException;
118
119         interface Modifier {
120
121                 Modifier setSone(Sone sone);
122
123                 Modifier setCreationTime(long creationTime);
124
125                 Modifier setKey(String key);
126
127                 Modifier setTitle(String title);
128
129                 Modifier setDescription(String description);
130
131                 Modifier setWidth(int width);
132
133                 Modifier setHeight(int height);
134
135                 Image update() throws IllegalStateException;
136
137                 class ImageTitleMustNotBeEmpty extends IllegalStateException { }
138
139         }
140
141 }