1 /*
2 * #%L
3 * wcm.io
4 * %%
5 * Copyright (C) 2014 wcm.io
6 * %%
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 * #L%
19 */
20 package io.wcm.handler.media;
21
22 import java.util.Date;
23
24 import org.apache.sling.api.adapter.Adaptable;
25 import org.apache.sling.api.resource.ValueMap;
26 import org.jetbrains.annotations.NotNull;
27 import org.jetbrains.annotations.Nullable;
28 import org.osgi.annotation.versioning.ProviderType;
29
30 import com.fasterxml.jackson.annotation.JsonIgnore;
31 import com.fasterxml.jackson.annotation.JsonInclude;
32 import com.fasterxml.jackson.annotation.JsonInclude.Include;
33 import com.fasterxml.jackson.annotation.JsonUnwrapped;
34
35 import io.wcm.handler.media.format.MediaFormat;
36 import io.wcm.handler.media.format.Ratio;
37 import io.wcm.wcm.commons.caching.ModificationDateProvider;
38
39 /**
40 * Represents a rendition contained in a {@link Asset} which can be rendered.
41 * A rendition can be pointing to a binary file stored in the repository, or a virtual rendition that is
42 * rendered on the fly if required.
43 */
44 @ProviderType
45 @JsonInclude(Include.NON_NULL)
46 public interface Rendition extends Adaptable, ModificationDateProvider {
47
48 /**
49 * Get externalized URL pointing to the rendition.
50 * @return Rendition URL
51 */
52 @Nullable
53 String getUrl();
54
55 /**
56 * Returns the internal path of the rendition if stored within the JCR repository. If the rendition is a virtual
57 * rendition the path points to the binary from which the virtual rendition is derived from.
58 * @return Repository path
59 */
60 @Nullable
61 String getPath();
62
63 /**
64 * @return File name of the renditions source binary
65 */
66 @Nullable
67 String getFileName();
68
69 /**
70 * @return File extension of the renditions source binary
71 */
72 @Nullable
73 String getFileExtension();
74
75 /**
76 * @return File size of the rendition in bytes (or -1 if it is unknown).
77 */
78 long getFileSize();
79
80 /**
81 * @return Mime type of the renditions source binary.
82 */
83 @Nullable
84 String getMimeType();
85
86 /**
87 * @return Media format that matches with the resolved rendition. Null if no media format was specified for resolving.
88 */
89 @Nullable
90 @JsonUnwrapped
91 MediaFormat getMediaFormat();
92
93 /**
94 * @return Properties of rendition
95 */
96 @NotNull
97 @JsonIgnore
98 ValueMap getProperties();
99
100 /**
101 * @return true if the rendition is an image format supported by the media handler.
102 */
103 @JsonIgnore
104 boolean isImage();
105
106 /**
107 * @return true if the rendition is a web image file that can be displayed in a browser.
108 */
109 @JsonIgnore
110 boolean isBrowserImage();
111
112 /**
113 * @return true if the rendition is a vector image that can be displayed in a browser.
114 */
115 @JsonIgnore
116 boolean isVectorImage();
117
118 /**
119 * @return true if the rendition is not and image nor a flash movie.
120 */
121 @JsonIgnore
122 boolean isDownload();
123
124 /**
125 * Gets the width of this rendition. If it is a virtual rendition the virtual height is returned.
126 * @return Height in pixels. Returns 0 if no height information is available.
127 */
128 long getWidth();
129
130 /**
131 * Gets the height of this rendition. If it is a virtual rendition the virtual height is returned.
132 * @return Height in pixels. Returns 0 if no height information is available.
133 */
134 long getHeight();
135
136 /**
137 * Gets the ratio of the image (width / height).
138 * @return Ratio. Returns 0 if no width or height information is available.
139 */
140 default double getRatio() {
141 long width = getWidth();
142 long height = getHeight();
143 if (width > 0 && height > 0) {
144 return Ratio.get(width, height);
145 }
146 return 0d;
147 }
148
149 /**
150 * @return The date of the last modification
151 */
152 @Override
153 @Nullable
154 @JsonIgnore
155 Date getModificationDate();
156
157 /**
158 * @return true if this rendition is returned as "fallback" not fully fulfilling the media request.
159 * Example: An explicit cropping was given, but it could not be fulfilled. If in this case another
160 * rendition is returned that fulfills all other media format restrictions, this flag is set to true.
161 */
162 boolean isFallback();
163
164 /**
165 * Generate an URI template for the rendition.
166 * The URI template ignores the actual resolution of this rendition and allows to scale the rendition
167 * to any size within the maximum range of width/height, keeping the aspect ratio and respecting
168 * both the original image and probably configured cropping parameters.
169 * @param type URI template type. It is not supported to use {@link UriTemplateType#CROP_CENTER}.
170 * @return URI template
171 * @throws IllegalArgumentException if {@link UriTemplateType#CROP_CENTER} is used
172 * @throws UnsupportedOperationException if the original rendition is not an image or it is a vector image.
173 */
174 @NotNull
175 UriTemplate getUriTemplate(@NotNull UriTemplateType type);
176
177 }