/*
 * Copyright 2015 Google Inc.
 *
 * 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 jsinterop.annotations;

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

/**
 * JsType is used to describe the JavaScript API of an object, either one that already exists from
 * the external JavaScript environment, or one that will be accessible from the external JavaScript
 * environment.
 *
 * <p>Marking an object with JsType is similar to marking each public member of the class with
 * {@link JsProperty}/{@link JsMethod}/{@link JsConstructor} respectively. In order for this to work
 * correctly the JavaScript name needs to be unique for each member. Some unobvious ways to cause
 * name collisions are:
 *
 * <ul>
 * <li>having method or constructor overloads
 * <li>using the same name for a method and a field
 * <li>shadowing a field from parent
 * </ul>
 *
 * <p>Name collisions must be avoided by providing custom names (e.g. {@link JsProperty#name}) or by
 * ignoring members using {@link JsIgnore}.
 *
 * <p>If the JsType is marked as "native" via {@link #isNative}, then the type is considered a stub
 * for an existing class that is available in native JavaScript. Unlike non-native JsTypes, all
 * members are considered {@link JsProperty}/{@link JsMethod}/{@link JsConstructor} unless they are
 * explicitly marked with {@link JsOverlay}.
 *
 * <p> For native interfaces with no particular JavaScript type associated with them (e.g.
 * structural types) it is recommeded to use {@code namespace = JsPackage.GLOBAL} and
 * {@code name = '?'}.
 *
 * <p><b>Instanceof and Castability:</b>
 *
 * <p>If the JsType is native, the generated code will try to mimic Javascript semantics.
 *
 * <p>All non-native JsTypes will follow regular Java semantics in terms of castability.
 *
 * <ul>
 * <li>For concrete native JsTypes, cast checks and instanceof checks will be delegated to the
 *     native JavaScript instanceof operator.
 * <li>For interface native JsTypes, instanceof is forbidden and casts to them always succeed.
 * </ul>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface JsType {

  /**
   * Customizes the name of the type in generated JavaScript. If not provided, the simple Java name
   * will be used.
   */
  String name() default "<auto>";

  /**
   * Customizes the namespace of the type in generated JavaScript.
   */
  String namespace() default "<auto>";

  /**
   * Set to {@code true}, this JsType is a native JavaScript type.
   */
  boolean isNative() default false;
}