/*
 * Copyright 2000-2016 Vaadin Ltd.
 *
 * 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 com.vaadin.annotations;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import com.vaadin.server.ClientConnector;

/**
 * If this annotation is present on a {@link ClientConnector} class, the
 * framework ensures the referenced HTML imports are loaded before the init
 * method for the corresponding client-side connector is invoked.
 * <p>
 * Note that not all browsers yet support HTML imports. If a polyfill is needed
 * to load HTML imports, it must be loaded before HTML Imports can be loaded.
 * There is no automatic loading of any polyfill.
 * <p>
 * <ul>
 * <li>Relative URLs are interpreted as relative to the {@code VAADIN} folder,
 * i.e. {@literal bower_components/paper-slider/paper-slider.html} is equal to
 * {@literal vaadin://bower_components/paper-slider/paper-slider.html}.
 * <li>Absolute URLs including protocol and host are used as is on the
 * client-side.
 * </ul>
 * Note that it is a good idea to use relative URLs and place all HTML imports
 * in the same folder. Polymer elements rely on importing dependencies using
 * relative paths {@literal ../../other-element/other-element.html}, which will
 * not work if they are installed in different locations.
 * <p>
 * HTML imports are added to the page after any {@code @JavaScript} dependencies
 * added at the same time.
 * <p>
 * Example:
 * <code>@HtmlImport("bower_components/paper-slider/paper-slider.html")</code>
 * on the class com.example.MyConnector would load the file
 * http://host.com/VAADIN/bower_components/paper-slider/paper-slider.html before
 * the {@code init()} method of the client side connector is invoked.
 *
 * @author Vaadin Ltd
 * @since 8.0.0
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Repeatable(InternalContainerAnnotationForHtml.class)
public @interface HtmlImport {

    /**
     * HTML file URL(s) to load before using the annotated
     * {@link ClientConnector} in the browser.
     *
     * @return html file URL(s) to load
     */
    String[] value();
}

@@ -1385,211 +1385,144 @@
 are 
-interpreted as relative to the %7B@code VAADIN%7D folder,%0A * i.e. %7B@literal bower_components/paper-slider/paper-slider.html%7D is equal to%0A * %7B@literal vaadin://bower_components/paper-slider/paper-slider.html%7D
+mapped to APP/PUBLISHED/%5Burl%5D which are by default%0A * served from the classpath relative to the class where the annotation is%0A * defined
 .%0A *
@@ -1657,70 +1657,119 @@
 use 
-relative URLs and place all HTML imports%0A * in the same folder
+URLs starting with %7B@literal vaadin://%7D%0A * and place all HTML imports inside %7B@literal VAADIN/bower_components%7D
 . Po
@@ -1773,16 +1773,19 @@
  Polymer
+%0A *
  element
@@ -1822,19 +1822,16 @@
 es using
-%0A *
  relativ
@@ -1837,16 +1837,19 @@
 ve paths
+%0A *
  %7B@liter
@@ -1902,19 +1902,16 @@
 ich will
-%0A *
  not wor
@@ -1914,16 +1914,19 @@
  work if
+%0A *
  they ar

Update @HtmlImport javadoc to match implementation (#8331)