groovy-core/src/main/groovy/lang/MetaObjectProtocol.java - groovy - Git at Google

 /*
  * 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 java.util.List;

 /**
  * <p>An interface that defines the API usable by clients of Groovy's Meta Object Protocol (MOP). These methods are
  * implemented by the reference implementation of the @link groovy.lang.MetaClass interface.</p>
  *
  * @see MetaClassImpl
  *
  * @author John Wilson
  * @author Graeme Rocher
  */
 public interface MetaObjectProtocol {

     /**
      * Obtain a list of all meta properties available on this meta class
      *
      * @see groovy.lang.MetaBeanProperty
      * @return A list of MetaBeanProperty instances
      */
     List getProperties();
     /**
      * Obtain a list of all the meta methods available on this meta class
      *
      * @see groovy.lang.MetaMethod
      * @return A list of MetaMethod instances
      */
     List getMethods();

     /**
      * <p>Returns true if the implementing MetaClass responds a method with the given name and arguments types
      *
      * <p>Note that this method will only return true for realised methods and does not take into account
      * objects or classes that implement invokeMethod or methodMissing
      *
      * <p>This method is "safe" and will always return a boolean and never throw an exception
      *
      * @param obj The object to inspect
      * @param name The name of the method
      * @param argTypes The argument types
      * @return A List of MetaMethods which is empty if non exist
      */
     List respondsTo(Object obj,String name, Object[] argTypes);

     /**
      * <p>Returns true if the implementing MetaClass responds a method with the given name regardless of
      * arguments. In other words this method will return for foo() and foo(String)
      *
      * <p>Note that this method will only return true for realised methods and does not take into account
      * objects or classes that implement invokeMethod or methodMissing
      *
      * <p>This method is "safe" and will always return a boolean and never throw an exception
      *
      * @param obj The object to inspect
      * @param name The name of the method
      * @return A List of MetaMethods which is empty if non exist
      */
     List respondsTo(Object obj,String name);

     /**
      * <p>Returns true of the implementing MetaClass has a property of the given name
      *
      * <p>Note that this method will only return true for realised properties and does not take into
      * account implementation of getProperty or propertyMissing
      *
      * @param obj The object to inspect
      * @param name The name of the property
      * @return The MetaProperty or null if it doesn't exist
      */
     MetaProperty hasProperty(Object obj, String name);

     /**
      * Returns a MetaProperty for the given name or null if it doesn't exist
      *
      * @param name The name of the MetaProperty
      * @return A MetaProperty or null
      */
     MetaProperty getMetaProperty(String name);

     /**
      * Retreives a static MetaMethod for the given name and argument values, using the types of the arguments
      * to establish the chosen MetaMethod
      *
      * @param name The name of the MetaMethod
      * @param args The argument types
      * @return A MetaMethod or null if it doesn't exist
      */
     MetaMethod getStaticMetaMethod(String name, Object[] args);


     /**
      * Retrieves an instance MetaMethod for the given name and argument values, using the types of the
      * argument values to establish the chosen MetaMethod
      *
      * @param name The name of the MetaMethod
      * @param args The argument types
      * @return A MetaMethod or null if it doesn't exist
      */
     MetaMethod getMetaMethod(String name, Object[] args);

     /**
      * Retrieves that Java Class that the attached Meta behaviours apply to
      *
      * @return The java.lang.Class instance
      */
     Class getTheClass();

     /**
      * Invokes a constructor for the given arguments. The MetaClass will attempt to pick the best argument which
      * matches the types of the objects passed within the arguments array
      *
      * @param arguments The arguments to the constructor
      * @return An instance of the java.lang.Class that this MetaObjectProtocol object applies to
      */
     Object invokeConstructor(Object[] arguments);

     /**
      * <p>Invokes a method on the given Object with the given name and arguments. The MetaClass will attempt to pick
      * the best method for the given name and arguments. If a method cannot be invoked a MissingMethodException will be
      * thrown.</p>
      *
      *
      * @see groovy.lang.MissingMethodException
      *
      * @param object The instance which the method is invoked on
      * @param methodName The name of the method
      * @param arguments The arguments to the method
      * @return The return value of the method which is null if the return type is void
      */
     Object invokeMethod(Object object, String methodName, Object[] arguments);

     /**
      * <p>Invokes a method on the given object, with the given name and single argument.</p>
      *
      * @see #invokeMethod(Object, String, Object[])
      *
      * @param object The Object to invoke the method on
      * @param methodName The name of the method
      * @param arguments The argument to the method
      * @return The return value of the method which is null if the return type is void
      */
      Object invokeMethod(Object object, String methodName, Object arguments);

     /**
      * <p>Invokes a static method on the given Object with the given name and arguments.</p>
      *
      * <p> The Object can either be an instance of the class that this
      * MetaObjectProtocol instance applies to or the java.lang.Class instance itself. If a method cannot be invoked
      * a MissingMethodException is will be thrown</p>
      *
      * @see groovy.lang.MissingMethodException
      *
      * @param object An instance of the class returned by the getTheClass() method or the class itself
      * @param methodName The name of the method
      * @param arguments The arguments to the method
      * @return The return value of the method which is null if the return type is void
      */
     Object invokeStaticMethod(Object object, String methodName, Object[] arguments);

     /**
      * <p>Retrieves a property of an instance of the class returned by the getTheClass() method. </p>
      *
      * <p>What this means is largely down to the MetaClass implementation, however the default case would result
      * in an attempt to invoke a JavaBean getter, or if no such getter exists a public field of the instance.</p>
      *
      * @see MetaClassImpl
      *
      * @param object An instance of the class returned by the getTheClass() method
      * @param property The name of the property to retrieve the value for
      * @return The properties value
      */
     Object getProperty(Object object, String property);

     /**
      * <p>Sets a property of an instance of the class returned by the getTheClass() method.</p>
      *
      * <p>What this means is largely down to the MetaClass implementation, however the default case would result
      * in an attempt to invoke a JavaBean setter, or if no such setter exists to set a public field of the instance.</p>
      *
      * @see MetaClassImpl
      *
      * @param object An instance of the class returned by the getTheClass() method
      * @param property The name of the property to set
      * @param newValue The new value of the property
      */
     void setProperty(Object object, String property, Object newValue);

     /**
      * <p>Retrieves an attribute of an instance of the class returned by the getTheClass() method. </p>
      *
      * <p>What this means is largely down to the MetaClass implementation, however the default case would result
      * in attempt to read a field of the instance.</p>
      *
      * @see MetaClassImpl
      *
      * @param object An instance of the class returned by the getTheClass() method
      * @param attribute The name of the attribute to retrieve the value for
      * @return The attribute value
      */
     Object getAttribute(Object object, String attribute);

     /**
      * <p>Sets an attribute of an instance of the class returned by the getTheClass() method.</p>
      *
      * <p>What this means is largely down to the MetaClass implementation, however the default case would result
      * in an attempt to set a field of the instance.</p>
      *
      * @see MetaClassImpl
      *
      * @param object An instance of the class returned by the getTheClass() method
      * @param attribute The name of the attribute to set
      * @param newValue The new value of the attribute
      */
     void setAttribute(Object object, String attribute, Object newValue);
 }
	/*
	* 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 java.util.List;

	/**
	* <p>An interface that defines the API usable by clients of Groovy's Meta Object Protocol (MOP). These methods are
	* implemented by the reference implementation of the @link groovy.lang.MetaClass interface.</p>
	*
	* @see MetaClassImpl
	*
	* @author John Wilson
	* @author Graeme Rocher
	*/
	public interface MetaObjectProtocol {

	/**
	* Obtain a list of all meta properties available on this meta class
	*
	* @see groovy.lang.MetaBeanProperty
	* @return A list of MetaBeanProperty instances
	*/
	List getProperties();
	/**
	* Obtain a list of all the meta methods available on this meta class
	*
	* @see groovy.lang.MetaMethod
	* @return A list of MetaMethod instances
	*/
	List getMethods();

	/**
	* <p>Returns true if the implementing MetaClass responds a method with the given name and arguments types
	*
	* <p>Note that this method will only return true for realised methods and does not take into account
	* objects or classes that implement invokeMethod or methodMissing
	*
	* <p>This method is "safe" and will always return a boolean and never throw an exception
	*
	* @param obj The object to inspect
	* @param name The name of the method
	* @param argTypes The argument types
	* @return A List of MetaMethods which is empty if non exist
	*/
	List respondsTo(Object obj,String name, Object[] argTypes);

	/**
	* <p>Returns true if the implementing MetaClass responds a method with the given name regardless of
	* arguments. In other words this method will return for foo() and foo(String)
	*
	* <p>Note that this method will only return true for realised methods and does not take into account
	* objects or classes that implement invokeMethod or methodMissing
	*
	* <p>This method is "safe" and will always return a boolean and never throw an exception
	*
	* @param obj The object to inspect
	* @param name The name of the method
	* @return A List of MetaMethods which is empty if non exist
	*/
	List respondsTo(Object obj,String name);

	/**
	* <p>Returns true of the implementing MetaClass has a property of the given name
	*
	* <p>Note that this method will only return true for realised properties and does not take into
	* account implementation of getProperty or propertyMissing
	*
	* @param obj The object to inspect
	* @param name The name of the property
	* @return The MetaProperty or null if it doesn't exist
	*/
	MetaProperty hasProperty(Object obj, String name);

	/**
	* Returns a MetaProperty for the given name or null if it doesn't exist
	*
	* @param name The name of the MetaProperty
	* @return A MetaProperty or null
	*/
	MetaProperty getMetaProperty(String name);

	/**
	* Retreives a static MetaMethod for the given name and argument values, using the types of the arguments
	* to establish the chosen MetaMethod
	*
	* @param name The name of the MetaMethod
	* @param args The argument types
	* @return A MetaMethod or null if it doesn't exist
	*/
	MetaMethod getStaticMetaMethod(String name, Object[] args);


	/**
	* Retrieves an instance MetaMethod for the given name and argument values, using the types of the
	* argument values to establish the chosen MetaMethod
	*
	* @param name The name of the MetaMethod
	* @param args The argument types
	* @return A MetaMethod or null if it doesn't exist
	*/
	MetaMethod getMetaMethod(String name, Object[] args);

	/**
	* Retrieves that Java Class that the attached Meta behaviours apply to
	*
	* @return The java.lang.Class instance
	*/
	Class getTheClass();

	/**
	* Invokes a constructor for the given arguments. The MetaClass will attempt to pick the best argument which
	* matches the types of the objects passed within the arguments array
	*
	* @param arguments The arguments to the constructor
	* @return An instance of the java.lang.Class that this MetaObjectProtocol object applies to
	*/
	Object invokeConstructor(Object[] arguments);

	/**
	* <p>Invokes a method on the given Object with the given name and arguments. The MetaClass will attempt to pick
	* the best method for the given name and arguments. If a method cannot be invoked a MissingMethodException will be
	* thrown.</p>
	*
	*
	* @see groovy.lang.MissingMethodException
	*
	* @param object The instance which the method is invoked on
	* @param methodName The name of the method
	* @param arguments The arguments to the method
	* @return The return value of the method which is null if the return type is void
	*/
	Object invokeMethod(Object object, String methodName, Object[] arguments);

	/**
	* <p>Invokes a method on the given object, with the given name and single argument.</p>
	*
	* @see #invokeMethod(Object, String, Object[])
	*
	* @param object The Object to invoke the method on
	* @param methodName The name of the method
	* @param arguments The argument to the method
	* @return The return value of the method which is null if the return type is void
	*/
	Object invokeMethod(Object object, String methodName, Object arguments);

	/**
	* <p>Invokes a static method on the given Object with the given name and arguments.</p>
	*
	* <p> The Object can either be an instance of the class that this
	* MetaObjectProtocol instance applies to or the java.lang.Class instance itself. If a method cannot be invoked
	* a MissingMethodException is will be thrown</p>
	*
	* @see groovy.lang.MissingMethodException
	*
	* @param object An instance of the class returned by the getTheClass() method or the class itself
	* @param methodName The name of the method
	* @param arguments The arguments to the method
	* @return The return value of the method which is null if the return type is void
	*/
	Object invokeStaticMethod(Object object, String methodName, Object[] arguments);

	/**
	* <p>Retrieves a property of an instance of the class returned by the getTheClass() method. </p>
	*
	* <p>What this means is largely down to the MetaClass implementation, however the default case would result
	* in an attempt to invoke a JavaBean getter, or if no such getter exists a public field of the instance.</p>
	*
	* @see MetaClassImpl
	*
	* @param object An instance of the class returned by the getTheClass() method
	* @param property The name of the property to retrieve the value for
	* @return The properties value
	*/
	Object getProperty(Object object, String property);

	/**
	* <p>Sets a property of an instance of the class returned by the getTheClass() method.</p>
	*
	* <p>What this means is largely down to the MetaClass implementation, however the default case would result
	* in an attempt to invoke a JavaBean setter, or if no such setter exists to set a public field of the instance.</p>
	*
	* @see MetaClassImpl
	*
	* @param object An instance of the class returned by the getTheClass() method
	* @param property The name of the property to set
	* @param newValue The new value of the property
	*/
	void setProperty(Object object, String property, Object newValue);

	/**
	* <p>Retrieves an attribute of an instance of the class returned by the getTheClass() method. </p>
	*
	* <p>What this means is largely down to the MetaClass implementation, however the default case would result
	* in attempt to read a field of the instance.</p>
	*
	* @see MetaClassImpl
	*
	* @param object An instance of the class returned by the getTheClass() method
	* @param attribute The name of the attribute to retrieve the value for
	* @return The attribute value
	*/
	Object getAttribute(Object object, String attribute);

	/**
	* <p>Sets an attribute of an instance of the class returned by the getTheClass() method.</p>
	*
	* <p>What this means is largely down to the MetaClass implementation, however the default case would result
	* in an attempt to set a field of the instance.</p>
	*
	* @see MetaClassImpl
	*
	* @param object An instance of the class returned by the getTheClass() method
	* @param attribute The name of the attribute to set
	* @param newValue The new value of the attribute
	*/
	void setAttribute(Object object, String attribute, Object newValue);
	}