Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.wicket.markup.html.image; import java.util.ArrayList; import java.util.Arrays; import java.util.List; import org.apache.wicket.Component; import org.apache.wicket.IRequestListener; import org.apache.wicket.core.request.handler.IPartialPageRequestHandler; import org.apache.wicket.markup.ComponentTag; import org.apache.wicket.markup.MarkupStream; import org.apache.wicket.markup.html.WebComponent; import org.apache.wicket.markup.html.image.resource.LocalizedImageResource; import org.apache.wicket.model.IModel; import org.apache.wicket.model.Model; import org.apache.wicket.request.mapper.parameter.PageParameters; import org.apache.wicket.request.resource.IResource; import org.apache.wicket.request.resource.ResourceReference; /** * An Image component displays localizable image resources. * <p> * For details of how Images load, generate and manage images, see {@link LocalizedImageResource}. * * The first ResourceReference / ImageResource is used for the src attribute within the img tag, all * following are applied to the srcset. If setXValues(String... values) is used the values are set * behind the srcset elements in the order they are given to the setXValues(String... valus) method. * The separated values in the sizes attribute are set with setSizes(String... sizes) * * @see NonCachingImage * * @author Jonathan Locke * @author Tobias Soloschenko */ public class Image extends WebComponent implements IRequestListener { private static final long serialVersionUID = 1L; /** * To be used for the crossOrigin attribute * * @see {@link #setCrossOrigin(Cors)} */ public enum Cors { /** * no authentication required */ ANONYMOUS("anonymous"), /** * user credentials required */ USE_CREDENTIALS("user-credentials"), /** * no cross origin */ NO_CORS(""); private final String realName; private Cors(String realName) { this.realName = realName; } /** * Gets the real name for the cors option * * @return the real name */ public String getRealName() { return realName; } } /** The image resource this image component references (src attribute) */ private final LocalizedImageResource localizedImageResource = new LocalizedImageResource(this); /** The extra image resources this image component references (srcset attribute) */ private final List<LocalizedImageResource> localizedImageResources = new ArrayList<>(); /** The x values to be used within the srcset */ private List<String> xValues = null; /** The sizes of the responsive images */ private List<String> sizes = null; /** * Cross origin settings */ private Cors crossOrigin = null; /** * This constructor can be used if you override {@link #getImageResourceReference()} or * {@link #getImageResource()} * * @param id */ protected Image(final String id) { super(id); } /** * Constructs an image from an image resourcereference. That resource reference will bind its * resource to the current SharedResources. * * If you are using non sticky session clustering and the resource reference is pointing to a * Resource that isn't guaranteed to be on every server, for example a dynamic image or * resources that aren't added with a IInitializer at application startup. Then if only that * resource is requested from another server, without the rendering of the page, the image won't * be there and will result in a broken link. * * @param id * See Component * @param resourceReference * The shared image resource used in the src attribute * @param resourceReferences * The shared image resources used in the srcset attribute */ public Image(final String id, final ResourceReference resourceReference, final ResourceReference... resourceReferences) { this(id, resourceReference, null, resourceReferences); } /** * Constructs an image from an image resourcereference. That resource reference will bind its * resource to the current SharedResources. * * If you are using non sticky session clustering and the resource reference is pointing to a * Resource that isn't guaranteed to be on every server, for example a dynamic image or * resources that aren't added with a IInitializer at application startup. Then if only that * resource is requested from another server, without the rendering of the page, the image won't * be there and will result in a broken link. * * @param id * See Component * @param resourceReference * The shared image resource used in the src attribute * @param resourceParameters * The resource parameters * @param resourceReferences * The shared image resources used in the srcset attribute */ public Image(final String id, final ResourceReference resourceReference, PageParameters resourceParameters, final ResourceReference... resourceReferences) { super(id); setImageResourceReference(resourceReference, resourceParameters); setImageResourceReferences(resourceParameters, resourceReferences); } /** * Constructs an image directly from an image resource. * * This one doesn't have the 'non sticky session clustering' problem that the ResourceReference * constructor has. But this will result in a non 'stable' url and the url will have request * parameters. * * @param id * See Component * * @param imageResource * The image resource used in the src attribute * @param imageResources * The image resource used in the srcset attribute */ public Image(final String id, final IResource imageResource, final IResource... imageResources) { super(id); setImageResource(imageResource); setImageResources(imageResources); } /** * @see org.apache.wicket.Component#Component(String, IModel) */ public Image(final String id, final IModel<?> model) { super(id, model); } /** * @param id * See Component * @param string * Name of image * @see org.apache.wicket.Component#Component(String, IModel) */ public Image(final String id, final String string) { this(id, new Model<>(string)); } @Override public boolean rendersPage() { return false; } /** * @see org.apache.wicket.IResourceListener#onResourceRequested() */ @Override public void onRequest() { localizedImageResource.onResourceRequested(null); for (LocalizedImageResource localizedImageResource : localizedImageResources) { localizedImageResource.onResourceRequested(null); } } /** * @param imageResource * The new ImageResource to set. */ public void setImageResource(final IResource imageResource) { if (imageResource != null) { localizedImageResource.setResource(imageResource); } } /** * * @param imageResources * the new ImageResource to set. */ public void setImageResources(final IResource... imageResources) { localizedImageResources.clear(); for (IResource imageResource : imageResources) { LocalizedImageResource localizedImageResource = new LocalizedImageResource(this); localizedImageResource.setResource(imageResource); localizedImageResources.add(localizedImageResource); } } /** * @param resourceReference * The shared ImageResource to set. */ public void setImageResourceReference(final ResourceReference resourceReference) { setImageResourceReference(resourceReference, null); } /** * @param resourceReference * The resource reference to set. * @param parameters * the parameters to be applied to the localized image resource */ public void setImageResourceReference(final ResourceReference resourceReference, final PageParameters parameters) { if (localizedImageResource != null) { if (parameters != null) { localizedImageResource.setResourceReference(resourceReference, parameters); } else { localizedImageResource.setResourceReference(resourceReference); } } } /** * @param parameters * Set the resource parameters for the resource. * @param resourceReferences * The resource references to set. */ public void setImageResourceReferences(final PageParameters parameters, final ResourceReference... resourceReferences) { localizedImageResources.clear(); for (ResourceReference resourceReference : resourceReferences) { LocalizedImageResource localizedImageResource = new LocalizedImageResource(this); if (parameters != null) { localizedImageResource.setResourceReference(resourceReference, parameters); } else { localizedImageResource.setResourceReference(resourceReference); } localizedImageResources.add(localizedImageResource); } } /** * @param values * the x values to be used in the srcset */ public void setXValues(String... values) { if (xValues == null) { xValues = new ArrayList<>(); } else { xValues.clear(); } xValues.addAll(Arrays.asList(values)); } /** * Removes all x values from the image src set */ public void removeXValues() { if (xValues != null) { xValues.clear(); } } /** * @param sizes * the sizes to be used in the size */ public void setSizes(String... sizes) { if (this.sizes == null) { this.sizes = new ArrayList<>(); } else { this.sizes.clear(); } this.sizes.addAll(Arrays.asList(sizes)); } /** * Removes all sizes values. The corresponding attribute will not be rendered anymore. */ public void removeSizes() { if (sizes != null) { sizes.clear(); } } /** * @see org.apache.wicket.Component#setDefaultModel(org.apache.wicket.model.IModel) */ @Override public Component setDefaultModel(IModel<?> model) { // Null out the image resource, so we reload it (otherwise we'll be // stuck with the old model. for (LocalizedImageResource localizedImageResource : localizedImageResources) { localizedImageResource.setResourceReference(null); localizedImageResource.setResource(null); } localizedImageResource.setResourceReference(null); localizedImageResource.setResource(null); return super.setDefaultModel(model); } /** * @return Resource returned from subclass */ protected IResource getImageResource() { return localizedImageResource.getResource(); } /** * @return ResourceReference returned from subclass */ protected ResourceReference getImageResourceReference() { return localizedImageResource.getResourceReference(); } /** * @see org.apache.wicket.Component#initModel() */ @Override protected IModel<?> initModel() { // Images don't support Compound models. They either have a simple // model, explicitly set, or they use their tag's src or value // attribute to determine the image. return null; } /** * @see org.apache.wicket.Component#onComponentTag(ComponentTag) */ @Override protected void onComponentTag(final ComponentTag tag) { super.onComponentTag(tag); if ("source".equals(tag.getName())) { buildSrcSetAttribute(tag); tag.remove("src"); } else { checkComponentTag(tag, "img"); String srcAttribute = buildSrcAttribute(tag); buildSrcSetAttribute(tag); tag.put("src", srcAttribute); } buildSizesAttribute(tag); Cors crossOrigin = getCrossOrigin(); if (crossOrigin != null && Cors.NO_CORS != crossOrigin) { tag.put("crossOrigin", crossOrigin.getRealName()); } } /** * Builds the srcset attribute if multiple localizedImageResources are found as varargs * * @param tag * the component tag */ protected void buildSrcSetAttribute(final ComponentTag tag) { int srcSetPosition = 0; for (LocalizedImageResource localizedImageResource : localizedImageResources) { localizedImageResource.setSrcAttribute(tag); if (shouldAddAntiCacheParameter()) { addAntiCacheParameter(tag); } String srcset = tag.getAttribute("srcset"); String xValue = ""; // If there are xValues set process them in the applied order to the srcset attribute. if (xValues != null) { xValue = xValues.size() > srcSetPosition && xValues.get(srcSetPosition) != null ? " " + xValues.get(srcSetPosition) : ""; } tag.put("srcset", (srcset != null ? srcset + ", " : "") + tag.getAttribute("src") + xValue); srcSetPosition++; } } /** * Builds the src attribute * * @param tag * the component tag * @return the value of the src attribute */ protected String buildSrcAttribute(final ComponentTag tag) { final IResource resource = getImageResource(); if (resource != null) { localizedImageResource.setResource(resource); } final ResourceReference resourceReference = getImageResourceReference(); if (resourceReference != null) { localizedImageResource.setResourceReference(resourceReference); } localizedImageResource.setSrcAttribute(tag); if (shouldAddAntiCacheParameter()) { addAntiCacheParameter(tag); } return tag.getAttribute("src"); } /** * builds the sizes attribute of the img tag * * @param tag * the component tag */ protected void buildSizesAttribute(final ComponentTag tag) { // if no sizes have been set then don't build the attribute if (sizes == null) { return; } String sizes = ""; for (String size : this.sizes) { sizes += size + ","; } int lastIndexOf = sizes.lastIndexOf(","); if (lastIndexOf != -1) { sizes = sizes.substring(0, lastIndexOf); } if (!"".equals(sizes)) { tag.put("sizes", sizes); } } /** * Adding an image to {@link org.apache.wicket.ajax.AjaxRequestTarget} most of the times mean * that the image has changes and must be re-rendered. * <p> * With this method the user may change this default behavior for some of her images. * </p> * * @return {@code true} to add the anti cache request parameter, {@code false} - otherwise */ protected boolean shouldAddAntiCacheParameter() { return getRequestCycle().find(IPartialPageRequestHandler.class).isPresent(); } /** * Adds random noise to the url every request to prevent the browser from caching the image. * * @param tag */ protected void addAntiCacheParameter(final ComponentTag tag) { String url = tag.getAttributes().getString("src"); url = url + (url.contains("?") ? "&" : "?"); url = url + "antiCache=" + System.currentTimeMillis(); tag.put("src", url); } /** * @see org.apache.wicket.Component#getStatelessHint() */ @Override protected boolean getStatelessHint() { boolean stateless = (getImageResource() == null || getImageResource() == localizedImageResource.getResource()) && localizedImageResource.isStateless(); boolean statelessList = false; for (LocalizedImageResource localizedImageResource : localizedImageResources) { if (localizedImageResource.isStateless()) { statelessList = true; } } return stateless || statelessList; } /** * @see org.apache.wicket.Component#onComponentTagBody(MarkupStream, ComponentTag) */ @Override public void onComponentTagBody(final MarkupStream markupStream, final ComponentTag openTag) { } @Override public boolean canCallListener() { if (isVisibleInHierarchy()) { // when the image data is requested we do not care if this component // is enabled in // hierarchy or not, only that it is visible return true; } else { return super.canCallListener(); } } /** * Gets the cross origin settings * * @see {@link #setCrossOrigin(Cors)} * * @return the cross origins settings */ public Cors getCrossOrigin() { return crossOrigin; } /** * Sets the cross origin settings<br> * <br> * * <b>ANONYMOUS</b>: Cross-origin CORS requests for the element will not have the credentials * flag set.<br> * <br> * <b>USE_CREDENTIALS</b>: Cross-origin CORS requests for the element will have the credentials * flag set.<br> * <br> * <b>NO_CORS</b>: The empty string is also a valid keyword, and maps to the Anonymous state. * The attribute's invalid value default is the Anonymous state. The missing value default, used * when the attribute is omitted, is the No CORS state * * @param crossOrigin * the cross origins settings to set */ public void setCrossOrigin(Cors crossOrigin) { this.crossOrigin = crossOrigin; } }