Callback.java
/*
** Module : Callback.java
** Abstract : encapsulates a callback
**
** Copyright (c) 2004-2020, Golden Code Development Corporation.
**
** -#- -I- --Date-- --JPRM-- ----------------------------------Description-----------------------------------
** 001 GES 20041116 @18653 First version implementing a bean-like interface. Only designed to contain some
** data, there is no processing being done.
** 002 GES 20070320 @32496 Added some documentation.
** 003 EVL 20160224 Javadoc fixes to make compatible with Oracle Java 8 for Solaris 10.
** 004 GES 20200626 Added toString();
*/
/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program 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 Affero General Public License for more details.
**
** You may find a copy of the GNU Affero GPL version 3 at the following
** location: https://www.gnu.org/licenses/agpl-3.0.en.html
**
** Additional terms under GNU Affero GPL version 3 section 7:
**
** Under Section 7 of the GNU Affero GPL version 3, the following additional
** terms apply to the works covered under the License. These additional terms
** are non-permissive additional terms allowed under Section 7 of the GNU
** Affero GPL version 3 and may not be removed by you.
**
** 0. Attribution Requirement.
**
** You must preserve all legal notices or author attributions in the covered
** work or Appropriate Legal Notices displayed by works containing the covered
** work. You may not remove from the covered work any author or developer
** credit already included within the covered work.
**
** 1. No License To Use Trademarks.
**
** This license does not grant any license or rights to use the trademarks
** Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
** of Golden Code Development Corporation. You are not authorized to use the
** name Golden Code, FWD, or the names of any author or contributor, for
** publicity purposes without written authorization.
**
** 2. No Misrepresentation of Affiliation.
**
** You may not represent yourself as Golden Code Development Corporation or FWD.
**
** You may not represent yourself for publicity purposes as associated with
** Golden Code Development Corporation, FWD, or any author or contributor to
** the covered work, without written authorization.
**
** 3. No Misrepresentation of Source or Origin.
**
** You may not represent the covered work as solely your work. All modified
** versions of the covered work must be marked in a reasonable way to make it
** clear that the modified work is not originating from Golden Code Development
** Corporation or FWD. All modified versions must contain the notices of
** attribution required in this license.
*/
package com.goldencode.p2j.uast;
import java.lang.reflect.*;
/**
* Encapsulates the data necessary to make a static or instance method call
* through the services provided by <code>java.lang.reflect</code>.
* <p>
* Accessors are provided to store and retrieve data but otherwise this
* data is not modified an any way.
* <p>
* The current design provides the ability to define a static method call
* or a call to a specific instance which must be specified in advance. There
* is no support for the dynamic instantiation of this class. In other
* words, if an instance method call is needed, the caller must construct
* the <code>Callback</code> object with the target instance object or
* the {@link #setTargetInstance} method must be called after construction or
* before the instance reference is needed. Since the <code>Callback</code>
* object itself does not handle the invocation, but rather only stores the
* data needed to do such an invocation, one may also obtain the instance
* reference via some other means.
* <p>
* There is no direct storage of parameter or return type information. This
* is the responsibility of the caller in the case where the class and
* method names are used instead of a <code>java.lang.reflect.Method</code>
* object. Since the <code>Method</code> object does store this information,
* if this value is not <code>null</code>, the parameter and return type
* information can be indirectly accessed.
*
* @author GES
*/
public class Callback
{
/**
* Stores the reference to the instance of the target object on which to
* invoke the method. This may be <code>null</code> in the case where a
* static method call is required.
*/
private Object targetInstance;
/**
* Stores the fully qualified class name of the target class object.
* This may be <code>null</code> if this <code>Callback</code> instance
* was constructed with a <code>java.lang.reflect.Method</code> object.
*/
private String className;
/**
* Stores the method name to invoke on the target class. This may be
* <code>null</code> if this <code>Callback</code> instance was
* constructed with a <code>java.lang.reflect.Method</code> object.
*/
private String methodName;
/**
* Stores the <code>java.lang.reflect.Method</code> which can be used
* to invoke the target method in the correct class. This may be
* <code>null</code> if this <code>Callback</code> instance was
* constructed with the class and method name strings, however usually a
* <code>Method</code> reference would be cached here when it is first
* dynamically found.
*/
private Method method;
/**
* Constructs a <code>Callback</code> instance using Strings representing
* the class and method names for the target.
*
* @param instance
* Object reference to the target object if the method call is
* non-static. This should be <code>null</code> for a static
* method call.
* @param className
* Fully qualified (including package) name of the target class.
* @param methodName
* Name of the method to call. This should be <code>null</code> to
* specify a constructor.
*/
public Callback(Object instance, String className, String methodName)
{
targetInstance = instance;
this.className = className;
this.methodName = methodName;
}
/**
* Constructs a <code>Callback</code> instance using an instance of
* <code>java.lang.reflect.Method</code>.
*
* @param instance
* Object reference to the target object if the method call is
* non-static. This should be <code>null</code> for a static
* method call.
* @param method
* Uniquely represents the method to be called using the
* Reflection features of Java.
*/
public Callback(Object instance, Method method)
{
targetInstance = instance;
this.method = method;
className = method.getDeclaringClass().getName();
methodName = method.getName();
}
/**
* Returns the reference to the target object.
*
* @return The instance on which the callback should be invoked or
* <code>null</code> if the method call is static.
*/
public Object getTargetInstance()
{
return targetInstance;
}
/**
* Sets the reference to the target object on which to invoke the
* associated method. Should be set to <code>null</code> if the method
* call is static.
*
* @param instance
* The target object on which to invoke the associated method or
* <code>null</code> if the method call is static.
*/
public void setTargetInstance(Object instance)
{
targetInstance = instance;
}
/**
* Returns the class name of the target object.
*
* @return The class name.
*/
public String getClassName()
{
return className;
}
/**
* Sets the class name of the target object.
*
* @param className
* The class name.
*/
public void setClassName(String className)
{
this.className = className;
}
/**
* Returns the method name to be called in the target object.
*
* @return The method name. <code>null</code> or empty string represent
* a constructor.
*/
public String getMethodName()
{
return methodName;
}
/**
* Sets the method name to be called in the target object.
*
* @param methodName
* The method name. <code>null</code> or empty string represent
* a constructor.
*/
public void setMethodName(String methodName)
{
this.methodName = methodName;
}
/**
* Returns the <code>java.lang.reflect.Method</code> which can be used to
* invoke the associated method. May be <code>null</code> if the
* <code>Callback</code> is only constructed using strings.
*
* @return Method object.
*/
public Method getMethod()
{
return method;
}
/**
* Sets the <code>java.lang.reflect.Method</code> which can be used to
* invoke the associated method. May be <code>null</code> if the
* <code>Callback</code> is only constructed using strings.
*
* @param method
* Method object.
*/
public void setMethod(Method method)
{
this.method = method;
}
/**
* Render the instance as text.
*
* @return A descriptive text string representing the state of the object.
*/
public String toString()
{
return String.format("CALLBACK (class %s; method name %s; instance %s; method %s)",
className,
methodName,
targetInstance,
method);
}
}