/*
 * Copyright 2003-2006 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 */

package sun.reflect.generics.factory;

import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.lang.reflect.TypeVariable;
import java.lang.reflect.WildcardType;
import sun.reflect.generics.tree.FieldTypeSignature;

/**
 * A factory interface for reflective objects representing generic types.
 * Implementors (such as core reflection or JDI, or possibly javadoc
 * will manufacture instances of (potentially) different classes
 * in response to invocations of the methods described here.
 * <p> The intent is that reflective systems use these factories to
 * produce generic type information on demand.
 * Certain components of such reflective systems can be independent
 * of a specific implementation by using this interface. For example,
 * repositories of generic type information are initialized with a
 * factory conforming to this interface, and use it to generate the
 * tpe information they are required to provide. As a result, such
 * repository code can be shared across different reflective systems.
 */
public interface GenericsFactory {
    /**
     * Returns a new type variable declaration. Note that <tt>name</tt>
     * may be empty (but not <tt>null</tt>). If <tt>bounds</tt> is
     * empty, a bound of <tt>java.lang.Object</tt> is used.
     * @param name The name of the type variable
     * @param bounds An array of abstract syntax trees representing
     * the upper bound(s) on the type variable being declared
     * @return a new type variable declaration
     * @throws NullPointerException - if any of the actual parameters
     * or any of the elements of <tt>bounds</tt> are <tt>null</tt>.
     */
    TypeVariable<?> makeTypeVariable(String name,
                                     FieldTypeSignature[] bounds);
    /**
     * Return an instance of the <tt>ParameterizedType</tt> interface
     * that corresponds to a generic type instantiation of the
     * generic declaration <tt>declaration</tt> with actual type arguments
     * <tt>typeArgs</tt>.
     * If <tt>owner</tt> is <tt>null</tt>, the declaring class of
     * <tt>declaration</tt> is used as the owner of this parameterized
     * type.
     * <p> This method throws a MalformedParameterizedTypeException
     * under the following circumstances:
     * If the type declaration does not represent a generic declaration
     * (i.e., it is not an instance of <tt>GenericDeclaration</tt>).
     * If the number of actual type arguments (i.e., the size of the
     * array <tt>typeArgs</tt>) does not correspond to the number of
     * formal type arguments.
     * If any of the actual type arguments is not an instance of the
     * bounds on the corresponding formal.
     * @param declaration - the generic type declaration that is to be
     * instantiated
     * @param typeArgs - the list of actual type arguments
     * @return - a parameterized type representing the instantiation
     * of the declaration with the actual type arguments
     * @throws MalformedParameterizedTypeException - if the instantiation
     * is invalid
     * @throws NullPointerException - if any of <tt>declaration</tt>
     * , <tt>typeArgs</tt>
     * or any of the elements of <tt>typeArgs</tt> are <tt>null</tt>
     */
    ParameterizedType makeParameterizedType(Type declaration,
                                            Type[] typeArgs,
                                            Type owner);

    /**
     * Returns the type variable with name <tt>name</tt>, if such
     * a type variable is declared in the
     * scope used to create this factory.
     * Returns <tt>null</tt> otherwise.
     * @param name - the name of the type variable to search for
     * @return - the type variable with name <tt>name</tt>, or <tt>null</tt>
     * @throws  NullPointerException - if any of actual parameters are
     * <tt>null</tt>
     */
    TypeVariable<?> findTypeVariable(String name);

    /**
     * Returns a new wildcard type variable. If
     * <tt>ubs</tt> is empty, a bound of <tt>java.lang.Object</tt> is used.
     * @param ubs An array of abstract syntax trees representing
     * the upper bound(s) on the type variable being declared
     * @param lbs An array of abstract syntax trees representing
     * the lower bound(s) on the type variable being declared
     * @return a new wildcard type variable
     * @throws NullPointerException - if any of the actual parameters
     * or any of the elements of <tt>ubs</tt> or <tt>lbs</tt>are
     * <tt>null</tt>
     */
    WildcardType makeWildcard(FieldTypeSignature[] ubs,
                              FieldTypeSignature[] lbs);

    Type makeNamedType(String name);

    /**
     * Returns a (possibly generic) array type.
     * If the component type is a parameterized type, it must
     * only have unbounded wildcard arguemnts, otherwise
     * a MalformedParameterizedTypeException is thrown.
     * @param componentType - the component type of the array
     * @return a (possibly generic) array type.
     * @throws MalformedParameterizedTypeException if <tt>componentType</tt>
     * is a parameterized type with non-wildcard type arguments
     * @throws NullPointerException - if any of the actual parameters
     * are <tt>null</tt>
     */
    Type makeArrayType(Type componentType);

    /**
     * Returns the reflective representation of type <tt>byte</tt>.
     * @return the reflective representation of type <tt>byte</tt>.
     */
    Type makeByte();

    /**
     * Returns the reflective representation of type <tt>boolean</tt>.
     * @return the reflective representation of type <tt>boolean</tt>.
     */
    Type makeBool();

    /**
     * Returns the reflective representation of type <tt>short</tt>.
     * @return the reflective representation of type <tt>short</tt>.
     */
    Type makeShort();

    /**
     * Returns the reflective representation of type <tt>char</tt>.
     * @return the reflective representation of type <tt>char</tt>.
     */
    Type makeChar();

    /**
     * Returns the reflective representation of type <tt>int</tt>.
     * @return the reflective representation of type <tt>int</tt>.
     */
    Type makeInt();

    /**
     * Returns the reflective representation of type <tt>long</tt>.
     * @return the reflective representation of type <tt>long</tt>.
     */
    Type makeLong();

    /**
     * Returns the reflective representation of type <tt>float</tt>.
     * @return the reflective representation of type <tt>float</tt>.
     */
    Type makeFloat();

    /**
     * Returns the reflective representation of type <tt>double</tt>.
     * @return the reflective representation of type <tt>double</tt>.
     */
    Type makeDouble();

    /**
     * Returns the reflective representation of <tt>void</tt>.
     * @return the reflective representation of <tt>void</tt>.
     */
    Type makeVoid();
}