/*
 * Copyright 2003-2007 the original author or authors.
 *
 * 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 groovy.lang;

import org.codehaus.groovy.ast.ClassNode;

import java.util.List;

/**
 * A MetaClass within Groovy defines the behaviour of any given Groovy or Java class. The MetaClass
 * interface defines two parts. The client API, which is defined via the extend MetaObjectProtocol interface
 * and the contract with the Groovy runtime system.
 *
 * In general the compiler and Groovy runtime engine interact with methods on this class whilst MetaClass
 * clients interact with the method defined by the MetaObjectProtocol interface
 *
 *
 * @see MetaClassImpl
 * @see groovy.lang.MetaObjectProtocol
 * 
 * @author John Wilson
 * @author Graeme Rocher
 */
public interface MetaClass extends MetaObjectProtocol {


    /**
     * <p>Invokes a method on the given receiver for the specified arguments. The sender is the class that invoked the method on the object.
     * The MetaClass will attempt to establish the method to invoke based on the name and arguments provided.
     *
     * <p>The isCallToSuper and fromInsideClass help the Groovy runtime perform optimisations on the call to go directly
     * to the super class if necessary
     *
     * @param sender The java.lang.Class instance that invoked the method
     * @param receiver The object which the method was invoked on
     * @param methodName The name of the method
     * @param arguments The arguments to the method
     * @param isCallToSuper Whether the method is a call to a super class method
     * @param fromInsideClass Whether the call was invoked from the inside or the outside of the class
     *
     * @return The return value of the method
     */
     Object invokeMethod(Class sender, Object receiver, String methodName, Object[] arguments, boolean isCallToSuper, boolean fromInsideClass);


    /**
     * <p>Retrieves a property on the given receiver for the specified arguments. The sender is the class that is requesting the property from the object.
     * The MetaClass will attempt to establish the method to invoke based on the name and arguments provided.
     *
     * <p>The isCallToSuper and fromInsideClass help the Groovy runtime perform optimisations on the call to go directly
     * to the super class if necessary
     *
     * @param sender The java.lang.Class instance that requested the property
     * @param receiver The Object which the property is being retrieved from
     * @param property The name of the property
     * @param isCallToSuper Whether the call is to a super class property
     * @param fromInsideClass ??
     *
     * @return The properties value
     */
     Object getProperty(Class sender, Object receiver, String property, boolean isCallToSuper, boolean fromInsideClass);

    /**
     * <p>Retrieves a property on the given receiver for the specified arguments. The sender is the class that is requesting the property from the object.
     * The MetaClass will attempt to establish the method to invoke based on the name and arguments provided.
     *
     * <p>The isCallToSuper and fromInsideClass help the Groovy runtime perform optimisations on the call to go directly
     * to the super class if necessary
     *
     * @param sender The java.lang.Class instance that is mutating the property
     * @param receiver The Object which the property is being set on
     * @param property The name of the property
     * @param value The new value of the property to set
     * @param isCallToSuper Whether the call is to a super class property
     * @param fromInsideClass ??
     *
     */
     void setProperty(Class sender, Object receiver, String property, Object value, boolean isCallToSuper, boolean fromInsideClass);

    /**
     *
     * <p>Attempts to invoke the methodMissing method otherwise throws a MissingMethodException
     *
     * @see groovy.lang.MissingMethodException
     *
     * @param instance The instance to invoke methodMissing on
     * @param methodName The name of the method
     * @param arguments The arguments to the method
     * @return The results of methodMissing or throws MissingMethodException
     */
     Object invokeMissingMethod(Object instance, String methodName, Object[] arguments);

    /**
     * Invokes the propertyMissing method otherwise throws a MissingPropertyException
     *
     * @param instance The instance of the class
     * @param propertyName The name of the property
     * @param optionalValue The value of the property which could be null in the case of a getter
     * @param isGetter Whether the missing property event was the result of a getter or a setter
     * 
     * @return The result of the propertyMissing method or throws MissingPropertyException
     */
     Object invokeMissingProperty(Object instance, String propertyName, Object optionalValue, boolean isGetter);


    /**
     * Retrieves the value of an attribute (field). This method is to support the Groovy runtime and not for general client API usage.
     *
     * @param sender The class of the object that requested the attribute
     * @param receiver The instance
     * @param messageName The name of the attribute
     * @param useSuper Whether to look-up on the super class or not
     * @return The attribute value
     */
     Object getAttribute(Class sender, Object receiver, String messageName, boolean useSuper);

    /**
     * Sets the value of an attribute (field). This method is to support the Groovy runtime and not for general client API usage.
     *
     * @param sender The class of the object that requested the attribute
     * @param receiver The instance
     * @param messageName The name of the attribute
     * @param messageValue The value of the attribute
     * @param useSuper Whether to look-up on the super class or not
     * @param fromInsideClass Whether the call happened from the inside or the outside of a class
     */
     void setAttribute(Class sender, Object receiver, String messageName, Object messageValue, boolean useSuper, boolean fromInsideClass);
    

    /**
     * complete the initlialisation process. After this method
     * is called no methods should be added to the meta class.
     * Invocation of methods or access to fields/proeprties is
     * forbidden unless this method is called. This method 
     * should contain any initialisation code, taking a longer
     * time to complete. An example is the creation of the 
     * Reflector. It is suggested to synchronize this 
     * method.
     */
     void initialize();


    /**
     * Retrives a list of MetaProperty instances that the MetaClass has
     *
     * @see MetaProperty
     *
     * @return A list of MetaProperty instances
     */
     List getProperties();

    /**
     * Retrieves a list of MetaMethods held by the class
     *
     * @return A list of MetaMethods
     *
     */
     List getMethods();
     
     /**
      * Obtains a reference to the original AST for the MetaClass if it is available at runtime
      *
      * @return The original AST or null if it cannot be returned
      */
     ClassNode getClassNode();
     
     
     /**
      * Retrieves a list of MetaMethod instances held by this class
      * @return A list of MetaMethod instances
      */
     List getMetaMethods();
    

     /**
      *
      * Internal method to support Groovy runtime. Not for client usage.
      *
      * @param numberOfConstructors The number of constructors
      * @param arguments The arguments
      *
      * @return selected index
      */
     int selectConstructorAndTransformArguments(int numberOfConstructors, Object[] arguments);

    /**
     * Selects a method by name and argument classes. This method
     * does not search for an exact match, it searches for a compatible
     * method. For this the method selection mechanism is used as provided
     * bye the implementation of this MetaClass. pickMethod may or may
     * not used during the method selection process when invoking a method
     * thereis no warranty for that.
     *
     * @return a matching MetaMethod or null
     * @throws GroovyRuntimeException if there is more than one matching method
     * @param methodName the name of the method to pick
     * @param arguments the method arguments
     */
     MetaMethod pickMethod(String methodName, Class[] arguments);
}