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 * @return Title of media item
42 */
43 @Nullable
44 String getTitle();
45
46 /**
47 * @return Alternative text for media item
48 */
49 @Nullable
50 String getAltText();
51
52 /**
53 * @return Description for this media item
54 */
55 @Nullable
56 String getDescription();
57
58 /**
59 * Internal path pointing to media item, if it is stored in the JCR repository.
60 * @return Repository path or null if not stored in repository
61 */
62 @Nullable
63 String getPath();
64
65 /**
66 * @return Properties of media item
67 */
68 @NotNull
69 @JsonIgnore
70 ValueMap getProperties();
71
72 /**
73 * Get the default rendition without specifying and media args.
74 * @return {@link Rendition} instance or null if no rendition exists
75 */
76 @Nullable
77 @JsonIgnore
78 Rendition getDefaultRendition();
79
80 /**
81 * Get the first rendition that matches the given media args.
82 * @param mediaArgs Media args to filter specific media formats or extensions.
83 * @return {@link Rendition} for the first matching rendition or null if no match found.
84 */
85 @Nullable
86 Rendition getRendition(@NotNull MediaArgs mediaArgs);
87
88 /**
89 * Get the first image rendition that matches the given media args.
90 * @param mediaArgs Media args to filter specific media formats or extensions.
91 * @return {@link Rendition} for the first matching rendition or null if no match found.
92 */
93 @Nullable
94 Rendition getImageRendition(@NotNull MediaArgs mediaArgs);
95
96 /**
97 * Get the first download rendition that matches the given media args.
98 * @param mediaArgs Media args to filter specific media formats or extensions.
99 * @return {@link Rendition} for the first matching rendition or null if no match found.
100 */
101 @Nullable
102 Rendition getDownloadRendition(@NotNull MediaArgs mediaArgs);
103
104 /**
105 * Generate an URI template for the asset.
106 * The URI template ignores any resolving parameters like media formats and relates only to the original
107 * asset and the max. width/height of it's original rendition.
108 * @param type URI template type
109 * @return URI template
110 * @throws UnsupportedOperationException if the original rendition is not an image or it is a vector image.
111 */
112 @NotNull
113 UriTemplate getUriTemplate(@NotNull UriTemplateType type);
114
115 }