LinkArgs.java

  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.link;

  22. import java.util.HashMap;
  23. import java.util.Map;

  25. import io.wcm.handler.url.VanityMode;
  26. import org.apache.commons.lang3.ArrayUtils;
  27. import org.apache.commons.lang3.builder.EqualsBuilder;
  28. import org.apache.commons.lang3.builder.HashCodeBuilder;
  29. import org.apache.commons.lang3.builder.ToStringBuilder;
  30. import org.apache.sling.api.resource.ValueMap;
  31. import org.apache.sling.api.wrappers.ValueMapDecorator;
  32. import org.jetbrains.annotations.NotNull;
  33. import org.jetbrains.annotations.Nullable;
  34. import org.osgi.annotation.versioning.ProviderType;

  36. import io.wcm.handler.url.UrlHandler;
  37. import io.wcm.handler.url.UrlMode;
  38. import io.wcm.wcm.commons.util.ToStringStyle;

  40. /**
  41.  * Holds parameters to influence the link resolving process.
  42.  */
  43. @ProviderType
  44. public final class LinkArgs implements Cloneable {

  46.   private UrlMode urlMode;
  47.   private VanityMode vanityMode;
  48.   private boolean dummyLink;
  49.   private String dummyLinkUrl;
  50.   private String selectors;
  51.   private String extension;
  52.   private String suffix;
  53.   private String queryString;
  54.   private String fragment;
  55.   private String windowTarget;
  56.   private boolean disableSuffixSelector;
  57.   private ValueMap properties;
  58.   private String[] linkTargetUrlFallbackProperty;
  59.   private String[] linkTargetWindowTargetFallbackProperty;


  62.   /**
  63.    * @return URL mode for externalizing the URL
  64.    */
  65.   public @Nullable UrlMode getUrlMode() {
  66.     return this.urlMode;
  67.   }

  69.   /**
  70.    * @return Vanity mode for building the URL
  71.    */
  72.   public @Nullable VanityMode getVanityMode() {
  73.     return this.vanityMode;
  74.   }

  76.   /**
  77.    * @param value URL mode for externalizing the URL
  78.    * @return this
  79.    */
  80.   public @NotNull LinkArgs urlMode(@Nullable UrlMode value) {
  81.     this.urlMode = value;
  82.     return this;
  83.   }

  85.   /**
  86.    * @param value Vanity mode for building the URL
  87.    * @return this
  88.    */
  89.   public @NotNull LinkArgs vanityMode(@Nullable VanityMode value) {
  90.     this.vanityMode = value;
  91.     return this;
  92.   }

  94.   /**
  95.    * @return If set to true, link handler returns a dummy link in edit mode when link is invalid.
  96.    */
  97.   public boolean isDummyLink() {
  98.     return this.dummyLink;
  99.   }

  101.   /**
  102.    * @param value If set to true, link handler returns a dummy link in edit mode when link is invalid.
  103.    * @return this
  104.    */
  105.   public @NotNull LinkArgs dummyLink(boolean value) {
  106.     this.dummyLink = value;
  107.     return this;
  108.   }

  110.   /**
  111.    * @return Custom dummy link url. If null default dummy url is used.
  112.    */
  113.   public @Nullable String getDummyLinkUrl() {
  114.     return this.dummyLinkUrl;
  115.   }

  117.   /**
  118.    * @param value Custom dummy link url. If null default dummy url is used.
  119.    * @return this
  120.    */
  121.   public @NotNull LinkArgs dummyLinkUrl(@Nullable String value) {
  122.     this.dummyLinkUrl = value;
  123.     return this;
  124.   }

  126.   /**
  127.    * @return Selector string
  128.    */
  129.   public @Nullable String getSelectors() {
  130.     return this.selectors;
  131.   }

  133.   /**
  134.    * @param value Selector string
  135.    * @return this
  136.    */
  137.   public @NotNull LinkArgs selectors(@Nullable String value) {
  138.     this.selectors = value;
  139.     return this;
  140.   }

  142.   /**
  143.    * @return File extension
  144.    */
  145.   public @Nullable String getExtension() {
  146.     return this.extension;
  147.   }

  149.   /**
  150.    * @param value File extension
  151.    * @return this
  152.    */
  153.   public @NotNull LinkArgs extension(@Nullable String value) {
  154.     this.extension = value;
  155.     return this;
  156.   }

  158.   /**
  159.    * @return Suffix string
  160.    */
  161.   public @Nullable String getSuffix() {
  162.     return this.suffix;
  163.   }

  165.   /**
  166.    * @param value Suffix string
  167.    * @return this
  168.    */
  169.   public @NotNull LinkArgs suffix(@Nullable String value) {
  170.     this.suffix = value;
  171.     return this;
  172.   }

  174.   /**
  175.    * @return Query parameters string (properly url-encoded)
  176.    */
  177.   public @Nullable String getQueryString() {
  178.     return this.queryString;
  179.   }

  181.   /**
  182.    * @param value Query parameters string (properly url-encoded)
  183.    * @return this
  184.    */
  185.   public @NotNull LinkArgs queryString(@Nullable String value) {
  186.     this.queryString = value;
  187.     return this;
  188.   }

  190.   /**
  191.    * @return Fragment identifier
  192.    */
  193.   public @Nullable String getFragment() {
  194.     return this.fragment;
  195.   }

  197.   /**
  198.    * @param value Fragment identifier
  199.    * @return this
  200.    */
  201.   public @NotNull LinkArgs fragment(@Nullable String value) {
  202.     this.fragment = value;
  203.     return this;
  204.   }

  206.   /**
  207.    * @return Link window target
  208.    */
  209.   public @Nullable String getWindowTarget() {
  210.     return this.windowTarget;
  211.   }

  213.   /**
  214.    * @param value Link window target
  215.    * @return this
  216.    */
  217.   public @NotNull LinkArgs windowTarget(@Nullable String value) {
  218.     this.windowTarget = value;
  219.     return this;
  220.   }

  222.   /**
  223.    * Disable the automatic addition of an additional selector {@link UrlHandler#SELECTOR_SUFFIX}
  224.    * in case a suffix is present for building the URL. Although recommended as best practice, this can
  225.    * be omitted if you are sure your URLs are always either include a suffix or never do, so there is no risk
  226.    * for file name clashes in dispatcher cache.
  227.    * @return If set to true, no additional suffix selector is added
  228.    */
  229.   public boolean isDisableSuffixSelector() {
  230.     return this.disableSuffixSelector;
  231.   }

  233.   /**
  234.    * Disable the automatic addition of an additional selector {@link UrlHandler#SELECTOR_SUFFIX}
  235.    * in case a suffix is present for building the URL. Although recommended as best practice, this can
  236.    * be omitted if you are sure your URLs are always either include a suffix or never do, so there is no risk
  237.    * for file name clashes in dispatcher cache.
  238.    * @param value If set to true, no additional suffix selector is added
  239.    * @return this
  240.    */
  241.   public @NotNull LinkArgs disableSuffixSelector(boolean value) {
  242.     this.disableSuffixSelector = value;
  243.     return this;
  244.   }

  246.   /**
  247.    * Custom properties that my be used by application-specific markup builders or processors.
  248.    * @param map Property map. Is merged with properties already set.
  249.    * @return this
  250.    */
  251.   @SuppressWarnings({ "null", "unused" })
  252.   public @NotNull LinkArgs properties(@NotNull Map<String, Object> map) {
  253.     if (map == null) {
  254.       throw new IllegalArgumentException("Map argument must not be null.");
  255.     }
  256.     getProperties().putAll(map);
  257.     return this;
  258.   }

  260.   /**
  261.    * Custom properties that my be used by application-specific markup builders or processors.
  262.    * @param key Property key
  263.    * @param value Property value
  264.    * @return this
  265.    */
  266.   @SuppressWarnings({ "null", "unused" })
  267.   public @NotNull LinkArgs property(@NotNull String key, @Nullable Object value) {
  268.     if (key == null) {
  269.       throw new IllegalArgumentException("Key argument must not be null.");
  270.     }
  271.     getProperties().put(key, value);
  272.     return this;
  273.   }

  275.   /**
  276.    * Custom properties that my be used by application-specific markup builders or processors.
  277.    * @return Value map
  278.    */
  279.   public @NotNull ValueMap getProperties() {
  280.     if (this.properties == null) {
  281.       this.properties = new ValueMapDecorator(new HashMap<>());
  282.     }
  283.     return this.properties;
  284.   }


  287.   /**
  288.    * Defines a "fallback" property name that is used to load link target information from a single property
  289.    * instead of the link type + link type depending property name. This property is used for migration
  290.    * from components that do not support Link Handler. It is only used for reading, and never written back to.
  291.    * When opened and saved in the link dialog, the property is removed and instead the dedicated properties are used.
  292.    * @param propertyNames Property name(s)
  293.    * @return this
  294.    */
  295.   public @NotNull LinkArgs linkTargetUrlFallbackProperty(@NotNull String @Nullable... propertyNames) {
  296.     this.linkTargetUrlFallbackProperty = propertyNames;
  297.     return this;
  298.   }

  300.   /**
  301.    * @return Property name(s)
  302.    */
  303.   public @Nullable String[] getLinkTargetUrlFallbackProperty() {
  304.     return this.linkTargetUrlFallbackProperty;
  305.   }

  307.   /**
  308.    * Defines a "fallback" property name that is used to load the "windows target" information from
  309.    * instead of the the default property. This property is used for migration
  310.    * from components that do not support Link Handler. It is only used for reading, and never written back to.
  311.    * When opened and saved in the link dialog, the property is removed and instead the dedicated properties are used.
  312.    * @param propertyNames Property name(s)
  313.    * @return this
  314.    */
  315.   public @NotNull LinkArgs linkTargetWindowTargetFallbackProperty(@NotNull String @Nullable... propertyNames) {
  316.     this.linkTargetWindowTargetFallbackProperty = propertyNames;
  317.     return this;
  318.   }

  320.   /**
  321.    * @return Property name(s)
  322.    */
  323.   public @Nullable String[] getLinkTargetWindowTargetFallbackProperty() {
  324.     return this.linkTargetWindowTargetFallbackProperty;
  325.   }


  328.   @Override
  329.   public int hashCode() {
  330.     return HashCodeBuilder.reflectionHashCode(this);
  331.   }

  333.   @Override
  334.   public boolean equals(Object obj) {
  335.     return EqualsBuilder.reflectionEquals(this, obj);
  336.   }

  338.   @Override
  339.   public String toString() {
  340.     return ToStringBuilder.reflectionToString(this, ToStringStyle.SHORT_PREFIX_OMIT_NULL_STYLE);
  341.   }

  343.   /**
  344.    * Custom clone-method for {@link LinkArgs}
  345.    * @return the cloned {@link LinkArgs}
  346.    */
  347.   @Override
  348.   @SuppressWarnings({ "java:S2975", "java:S1182", "checkstyle:SuperCloneCheck" }) // ignore clone warnings
  349.   public LinkArgs clone() { //NOPMD
  350.     LinkArgs clone = new LinkArgs();

  352.     clone.urlMode = this.urlMode;
  353.     clone.dummyLink = this.dummyLink;
  354.     clone.dummyLinkUrl = this.dummyLinkUrl;
  355.     clone.selectors = this.selectors;
  356.     clone.extension = this.extension;
  357.     clone.suffix = this.suffix;
  358.     clone.queryString = this.queryString;
  359.     clone.fragment = this.fragment;
  360.     clone.windowTarget = this.windowTarget;
  361.     clone.disableSuffixSelector = this.disableSuffixSelector;
  362.     clone.linkTargetUrlFallbackProperty = ArrayUtils.clone(this.linkTargetUrlFallbackProperty);
  363.     clone.linkTargetWindowTargetFallbackProperty = ArrayUtils.clone(this.linkTargetWindowTargetFallbackProperty);
  364.     if (this.properties != null) {
  365.       clone.properties = new ValueMapDecorator(new HashMap<>(this.properties));
  366.     }

  368.     return clone;
  369.   }

  371. }
Created with JaCoCo 0.8.13.202504020838