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 org.apache.sling.api.adapter.Adaptable;
23 import org.apache.sling.api.resource.ValueMap;
24 import org.jetbrains.annotations.NotNull;
25 import org.jetbrains.annotations.Nullable;
26 import org.osgi.annotation.versioning.ProviderType;
27
28 import com.fasterxml.jackson.annotation.JsonIgnore;
29 import com.fasterxml.jackson.annotation.JsonInclude;
30 import com.fasterxml.jackson.annotation.JsonInclude.Include;
31
32 /**
33 * Represents a media item that is referenced via a {@link MediaRequest} and resolved via {@link MediaHandler}.
34 * It cannot be rendered directly, but contains references to renditions depending on {@link MediaArgs}.
35 */
36 @ProviderType
37 @JsonInclude(Include.NON_NULL)
38 public interface Asset extends Adaptable {
39
40 /**
41 * Get title of media item.
42 * @return Title of media item
43 */
44 @Nullable
45 String getTitle();
46
47 /**
48 * Get alternative text for media item.
49 * @return Alternative text for media item
50 */
51 @Nullable
52 String getAltText();
53
54 /**
55 * Get description for this media item.
56 * @return Description for this media item
57 */
58 @Nullable
59 String getDescription();
60
61 /**
62 * Internal path pointing to media item, if it is stored in the JCR repository.
63 * @return Repository path or null if not stored in repository
64 */
65 @Nullable
66 String getPath();
67
68 /**
69 * Get properties of media item.
70 * @return Properties of media item
71 */
72 @NotNull
73 @JsonIgnore
74 ValueMap getProperties();
75
76 /**
77 * Get the default rendition without specifying and media args.
78 * @return {@link Rendition} instance or null if no rendition exists
79 */
80 @Nullable
81 @JsonIgnore
82 Rendition getDefaultRendition();
83
84 /**
85 * Get the first rendition that matches the given media args.
86 * @param mediaArgs Media args to filter specific media formats or extensions.
87 * @return {@link Rendition} for the first matching rendition or null if no match found.
88 */
89 @Nullable
90 Rendition getRendition(@NotNull MediaArgs mediaArgs);
91
92 /**
93 * Get the first image rendition that matches the given media args.
94 * @param mediaArgs Media args to filter specific media formats or extensions.
95 * @return {@link Rendition} for the first matching rendition or null if no match found.
96 */
97 @Nullable
98 Rendition getImageRendition(@NotNull MediaArgs mediaArgs);
99
100 /**
101 * Get the first download rendition that matches the given media args.
102 * @param mediaArgs Media args to filter specific media formats or extensions.
103 * @return {@link Rendition} for the first matching rendition or null if no match found.
104 */
105 @Nullable
106 Rendition getDownloadRendition(@NotNull MediaArgs mediaArgs);
107
108 /**
109 * Generate an URI template for the asset.
110 * The URI template ignores any resolving parameters like media formats and relates only to the original
111 * asset and the max. width/height of it's original rendition.
112 * @param type URI template type
113 * @return URI template
114 * @throws UnsupportedOperationException if the original rendition is not an image or it is a vector image.
115 */
116 @NotNull
117 UriTemplate getUriTemplate(@NotNull UriTemplateType type);
118
119 }