/*
    * Copyright 2013 smartics, Kronseder & Reiner GmbH
    *
    * Licensed 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 de.smartics.resteasy.hypermedia.renderer;
  
  import java.net.URI;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.List;
  import java.util.Map;
  
  import javax.ws.rs.core.Link;
  import javax.ws.rs.core.UriBuilder;
  
  import org.apache.commons.lang3.StringUtils;
  
  import de.smartics.util.lang.Arg;
  
  /**
   * Provides information on a single link.
   */
  public abstract class LinkDescriptor extends Link
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    // --- members --------------------------------------------------------------
  
    /**
     * The additional link metadata about the link.
     */
    protected final LinkMetadata metadata;
  
    /**
     * The path parameters to apply to the template link.
     */
    protected final Map<String, String> params;
  
    /**
     * The list of tokens that specify the relationship between the document
     * containing the hyperlink and the destination indicated by the hyperlink.
     *
     * @see <a href="http://dev.w3.org/html5/markup/a.html#a.attrs.rel">rel</a>
     */
    protected final List<String> rels;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Default constructor.
     *
     * @param metadata the additional link metadata about the link.
     * @param params the value for params.
     * @param rels the relations of this link.
     */
    protected LinkDescriptor(final LinkMetadata metadata,
        final Map<String, String> params, final List<String> rels)
    {
      this.metadata = metadata;
      this.params = params;
      this.rels = rels;
    }
  
    // ****************************** Inner Classes *****************************
  
    // ********************************* Methods ********************************
  
    // --- init -----------------------------------------------------------------
  
    /**
     * Splits the whitespace separated relation link attribute into its parts.
     *
     * @param rel the whitespace separated relation link attribute.
     * @return the individual parts.
     */
    protected static final List<String> splitRel(final String rel)
    {
      if (StringUtils.isBlank(rel))
      {
        return new ArrayList<String>();
      }
  
      final List<String> rels = Arrays.asList(rel.split("\\s+"));
      return rels;
   }
 
   // --- get&set --------------------------------------------------------------
 
   @Override
   public URI getUri()
   {
     final UriBuilder builder = getUriBuilder();
 
     if (builder == null)
     {
       return null;
     }
 
     final URI uri;
     if (!params.isEmpty())
     {
       uri = builder.build(params);
     }
     else
     {
       uri = builder.build();
     }
     return uri;
   }
 
   @Override
   public UriBuilder getUriBuilder()
   {
     final String href = getHref();
 
     if (href == null)
     {
       return null;
     }
 
     return UriBuilder.fromPath(href);
   }
 
   /**
    * Returns the URI to the resource the link points to.
    *
    * @return the URI to the resource the link points to.
    */
   public abstract String getHref();
 
   /**
    * Sets the URI to the resource the link points to.
    *
    * @param href the URI to the resource the link points to.
    */
   public abstract void setHref(String href);
 
   /**
    * Returns the content that describes the language of the resource pointed to
    * by the link. When used together with the rel="alternate", it implies a
    * translated version of the entry. Link elements MAY have an hreflang
    * attribute, whose value MUST be a language tag [RFC3066].
    *
    * @return the content that describes the language of the resource pointed to
    *         by the link.
    */
   public abstract String getHrefLang();
 
   /**
    * Sets the content that describes the language of the resource pointed to by
    * the link. When used together with the rel="alternate", it implies a
    * translated version of the entry. Link elements MAY have an hreflang
    * attribute, whose value MUST be a language tag [RFC3066].
    *
    * @param hrefLang the content that describes the language of the resource
    *          pointed to by the link.
    */
   public abstract void setHrefLang(String hrefLang);
 
   /**
    * Returns the media type of the resource the link points to.
    *
    * @return the media type of the resource the link points to.
    */
   @Override
   public abstract String getType();
 
   /**
    * Sets the media type of the resource the link points to.
    *
    * @param type the media type of the resource the link points to.
    */
   public abstract void setType(String type);
 
   /**
    * Returns the advisory length of the linked content in octets; it is a hint
    * about the content length of the representation returned when the IRI in the
    * href attribute is mapped to a URI and dereferenced. Note that the length
    * attribute does not override the actual content length of the representation
    * as reported by the underlying protocol. Link elements MAY have a length
    * attribute.
    *
    * @return the advisory length of the linked content in octets.
    */
   public abstract String getLength();
 
   /**
    * Sets the advisory length of the linked content in octets; it is a hint
    * about the content length of the representation returned when the IRI in the
    * href attribute is mapped to a URI and dereferenced. Note that the length
    * attribute does not override the actual content length of the representation
    * as reported by the underlying protocol. Link elements MAY have a length
    * attribute.
    *
    * @param length the advisory length of the linked content in octets.
    */
   public abstract void setLength(String length);
 
   /**
    * Returns the relations of this link.
    *
    * @return the relations of this link.
    */
   @Override
   public List<String> getRels()
   {
     return rels;
   }
 
   /**
    * Adds the list of relations.
    *
    * @param rels the relations to add.
    * @throws NullPointerException if {@code rels} is <code>null</code>.
    */
   public void addRels(final String... rels) throws NullPointerException
   {
     for (final String rel : rels)
     {
       this.rels.add(rel);
     }
   }
 
   /**
    * Adds the list of relations.
    *
    * @param rels the relations to add.
    * @throws NullPointerException if {@code rels} is <code>null</code>.
    */
   public void addRels(final List<String> rels) throws NullPointerException
   {
     for (final String rel : rels)
     {
       this.rels.add(rel);
     }
   }
 
   /**
    * Returns the relation attribute of the link. The relations are separated by
    * whitespaces.
    *
    * @return the whitespace separated relations of the link.
    */
   @Override
   public String getRel()
   {
     final StringBuilder buffer = new StringBuilder(128);
     for (final String rel : this.rels)
     {
       buffer.append(rel).append(' ');
     }
     return StringUtils.removeEnd(buffer.toString(), " ");
   }
 
   /**
    * Returns the path parameters to apply to the template link.
    *
    * @return the path parameters.
    */
   @Override
   public Map<String, String> getParams()
   {
     return params;
   }
 
   /**
    * Adds the given parameter to the map of parameters.
    *
    * @param name the name of the parameter to add.
    * @param value the value to the parameter to add.
    * @throws NullPointerException if {@code name} or {@code value} is
    *           <code>null</code>.
    * @throws IllegalArgumentException if {@code name} is blank}.
    */
   public void putParam(final String name, final String value)
     throws NullPointerException, IllegalArgumentException
   {
     params.put(Arg.checkNotBlank("name", name),
         Arg.checkNotBlank("value", value));
   }
 
   /**
    * Returns the key label or list of key labels with which to associate the
    * element; each key label represents a keyboard shortcut which UAs can use to
    * activate the element or give focus to the element.
    * <p>
    * An ordered set of unique space-separated tokens, each of which must be
    * exactly one Unicode code point in length.
    * </p>
    *
    * @return the key label or list of key labels with which to associate the
    *         element.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public final String getAccessKey()
   {
     return metadata.getAccessKey();
   }
 
   /**
    * Sets the key label or list of key labels with which to associate the
    * element; each key label represents a keyboard shortcut which UAs can use to
    * activate the element or give focus to the element.
    * <p>
    * An ordered set of unique space-separated tokens, each of which must be
    * exactly one Unicode code point in length.
    * </p>
    *
    * @param accessKey the key label or list of key labels with which to
    *          associate the element.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public final void setAccessKey(final String accessKey)
   {
     metadata.setAccessKey(accessKey);
   }
 
   /**
    * Returns the tab index.
    * <p>
    * Specifies whether the element represents an element that is is focusable
    * (that is, an element which is part of the sequence of focusable elements in
    * the document), and the relative order of the element in the sequence of
    * focusable elements in the document.
    * </p>
    *
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    * @return the tab index.
    */
   public final Integer getTabIndex()
   {
     return metadata.getTabIndex();
   }
 
   /**
    * Sets the tab index.
    * <p>
    * Specifies whether the element represents an element that is is focusable
    * (that is, an element which is part of the sequence of focusable elements in
    * the document), and the relative order of the element in the sequence of
    * focusable elements in the document.
    * </p>
    *
    * @param tabIndex the tab index.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public final void setTabIndex(final Integer tabIndex)
   {
     metadata.setTabIndex(tabIndex);
   }
 
   /**
    * Sets the advisory information associated with the element.
    *
    * @param title the advisory information associated with the element.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public final void setTitle(final String title)
   {
     metadata.setTitle(title);
   }
 
   /**
    * Returns the element’s text directionality.
    *
    * @return the element’s text directionality.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public final String getDir()
   {
     return metadata.getDir();
   }
 
   /**
    * Sets the element’s text directionality.
    *
    * @param dir the element’s text directionality.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public final void setDir(final String dir)
   {
     metadata.setDir(dir);
   }
 
   /**
    * Returns the hidden flag to specify that the element represents an element
    * that is not yet, or is no longer, relevant.
    *
    * @return the hidden flag to specify that the element represents an element
    *         that is not yet, or is no longer, relevant.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public final Boolean isHidden()
   {
     return metadata.isHidden();
   }
 
   /**
    * Sets the hidden flag to specify that the element represents an element that
    * is not yet, or is no longer, relevant.
    *
    * @param hidden the hidden flag to specify that the element represents an
    *          element that is not yet, or is no longer, relevant.
    * @see <a href="http://dev.w3.org/html5/markup/global-attributes.html">global
    *      attributes</a>
    */
   public void setHidden(final Boolean hidden)
   {
     metadata.setHidden(hidden);
   }
 
   /**
    * Returns the standard label to be rendered as the visible part of the link.
    *
    * @return the standard label to be rendered as the visible part of the link.
    */
   public String getLabel()
   {
     return metadata.getLabel();
   }
 
   /**
    * Sets the standard label to be rendered as the visible part of the link.
    *
    * @param label the standard label to be rendered as the visible part of the
    *          link.
    */
   public final void setLabel(final String label)
   {
     metadata.setLabel(label);
   }
 
   /**
    * Returns the short version of the label to be rendered in confined space.
    *
    * @return the short version of the label to be rendered in confined space.
    */
   public final String getShortLabel()
   {
     return metadata.getShortLabel();
   }
 
   /**
    * Sets the short version of the label to be rendered in confined space.
    *
    * @param shortLabel the short version of the label to be rendered in confined
    *          space.
    */
   public final void setShortLabel(final String shortLabel)
   {
     metadata.setShortLabel(shortLabel);
   }
 
   /**
    * Returns the detailed help information on the link.
    *
    * @return the detailed help information on the link.
    */
   public final String getHelp()
   {
     return metadata.getHelp();
   }
 
   /**
    * Sets the detailed help information on the link.
    *
    * @param help the detailed help information on the link.
    */
   public final void setHelp(final String help)
   {
     metadata.setHelp(help);
   }
 
   /**
    * Returns the CSS class information to the link.
    *
    * @return the CSS class information to the link.
    */
   public final String getCssClass()
   {
     return metadata.getCssClass();
   }
 
   /**
    * Sets the CSS class information to the link.
    *
    * @param cssClass the CSS class information to the link.
    */
   public final void setCssClass(final String cssClass)
   {
     metadata.setCssClass(cssClass);
   }
 
   /**
    * Returns the identifier of the link.
    *
    * @return the identifier of the link.
    */
   public String getId()
   {
     return metadata.getId();
   }
 
   /**
    * Sets the identifier of the link.
    *
    * @param id the identifier of the link.
    */
   public void setId(final String id)
   {
     metadata.setId(id);
   }
 
   /**
    * Returns the advisory information associated with the element.
    *
    * @return the advisory information associated with the element.
    */
   @Override
   public String getTitle()
   {
     return metadata.getTitle();
   }
 
   /**
    * Returns the name or keyword giving a browsing context for UAs to use when
    * following the hyperlink.
    *
    * @return the name or keyword giving a browsing context for UAs to use when
    *         following the hyperlink.
    */
   public String getTarget()
   {
     return metadata.getTarget();
   }
 
   /**
    * Sets the name or keyword giving a browsing context for UAs to use when
    * following the hyperlink.
    *
    * @param target the name or keyword giving a browsing context for UAs to use
    *          when following the hyperlink.
    */
   public void setTarget(final String target)
   {
     metadata.setTarget(target);
   }
 
   /**
    * Returns the media for which the destination of the hyperlink was designed.
    * <p>
    * Values are according to <a
    * href="http://www.w3.org/TR/2009/CR-css3-mediaqueries-20090915/">Media
    * Queries</a>.
    * </p>
    *
    * @return the media for which the destination of the hyperlink was designed.
    */
   public String getMedia()
   {
     return metadata.getMedia();
   }
 
   /**
    * Sets the media for which the destination of the hyperlink was designed.
    * <p>
    * Values are according to <a
    * href="http://www.w3.org/TR/2009/CR-css3-mediaqueries-20090915/">Media
    * Queries</a>.
    * </p>
    *
    * @param media the media for which the destination of the hyperlink was
    *          designed.
    */
   public void setMedia(final String media)
   {
     metadata.setMedia(media);
   }
 
   /**
    * Returns the identifier of a menu with which to associate the element as a
    * context menu.
    *
    * @return the identifier of a menu with which to associate the element as a
    *         context menu.
    */
   public String getContextMenu()
   {
     return metadata.getContextMenu();
   }
 
   /**
    * Sets the identifier of a menu with which to associate the element as a
    * context menu.
    *
    * @param contextMenu the identifier of a menu with which to associate the
    *          element as a context menu.
    */
   public void setContextMenu(final String contextMenu)
   {
     metadata.setContextMenu(contextMenu);
   }
 
   // --- business -------------------------------------------------------------
 
   // --- object basics --------------------------------------------------------
 
   @Override
   public String toString()
   {
     final StringBuilder buffer = new StringBuilder(64);
 
     buffer.append('<').append(getHref()).append('>');
     append(buffer, "title", getTitle());
     append(buffer, "rel", getRel());
     append(buffer, "type", getType());
     append(buffer, "hreflang", getHrefLang());
     append(buffer, "length", getLength());
 
     return buffer.toString();
   }
 
   private void append(final StringBuilder buffer, final String name,
       final String value)
   {
     if (StringUtils.isNotBlank(value))
     {
       buffer.append("; ").append(name).append("=\"").append(value).append('"');
     }
   }
 }