org.apache.beehive.netui.tags.databinding.invoke
Class AbstractCallMethod

Object
  extended by TagSupport
      extended by BodyTagSupport
          extended by AbstractClassicTag
              extended by AbstractCallMethod
All Implemented Interfaces:
Serializable, BodyTag, IterationTag, JspTag, Tag, INetuiTag
Direct Known Subclasses:
CallMethod

public abstract class AbstractCallMethod
extends AbstractClassicTag

An abstract base class for tags that are capable of reflectively invoking methods. Specializations of this tag provide method implementations that locate the object on which to invoke the method and that handle any return value from the invoked method.

The CallMethod tag can have child tags of type MethodParameter; these tags must be in the same order as the parameter list in the method signature of the method that will be invoked. To invoke an overloaded method, the MethodParameter.setType(String) property must be set to the String name of the type to pass to the method. If the type attribute values on nested MethodParameter tags do not match any method signature, an error will be reported in the page.

See Also:
Serialized Form

Nested Class Summary
protected  class AbstractCallMethod.ParamNode
          An internal struct that represents a parameter that will be passed to a reflective method invocation call.
 
Field Summary
 
Fields inherited from class AbstractClassicTag
DefaultNamingChain, NETUI_UNIQUE_CNT
 
Fields inherited from class BodyTagSupport
bodyContent
 
Fields inherited from class TagSupport
id, pageContext
 
Fields inherited from interface BodyTag
EVAL_BODY_BUFFERED, EVAL_BODY_TAG
 
Fields inherited from interface IterationTag
EVAL_BODY_AGAIN
 
Fields inherited from interface Tag
EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE
 
Constructor Summary
AbstractCallMethod()
           
 
Method Summary
 void addParameter(String type, Object parameter)
          Add a paramter that will be passed as an argument to the method that will be invoked.
protected  boolean allowNullInvocationTarget()
          When implemented to return true, this method allows a tag invoking a method to accept a null invocation target and simply return null.
 int doEndTag()
          Reflectively invokes the method specified by the method attribute, findMethod(Object, String, boolean).
 int doStartTag()
          Causes the body of this tag to be rendered; only MethodParameter tags are allowed to be contained inside of this tag.
protected  Method findMethod(Object target, String methodName, boolean verifyTypes)
          The default findMethod implementation is an uncached search of all of the methods available on the Class of the target
protected abstract  String getObjectName()
          Get the name of the object that is the target of the invocation.
protected  List getParameterNodes()
          Internal, read-only property used by subclasses to get the list of parameters to be used when reflectively invoking a method.
protected  void handleReturnValue(Object result)
          

A method that allows concrete classes to handle the result of the reflective invocation in an implementation specific way.

protected  void localRelease()
          Reset all of the fields of this tag.
protected abstract  Object resolveObject()
          

Resolve the object on which the method should be invoked.

 void setFailOnError(boolean failOnError)
          Sets whether or not to report exceptions to the page when errors occur invoking a method on an object.
 void setMethod(String method)
          Sets the name of a method to invoke on the target object.
 void setResultId(String resultId)
          Sets the identifier at which the result of invoking the method will stored.
 
Methods inherited from class AbstractClassicTag
applyNamingChain, getErrorsReport, getIdForTagId, getNamingChain, getNextId, getScriptReporter, getTagName, getUserLocale, hasErrors, qualifyAttribute, registerTagError, registerTagError, reportAndExit, reportErrors, rewriteName, setNonEmptyValueAttribute, setRequiredValueAttribute, write
 
Methods inherited from class BodyTagSupport
doAfterBody, doInitBody, getBodyContent, getPreviousOut, release, setBodyContent
 
Methods inherited from class TagSupport
findAncestorWithClass, getId, getParent, getValue, getValues, removeValue, setId, setPageContext, setParent, setValue
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface Tag
getParent, setPageContext, setParent
 

Constructor Detail

AbstractCallMethod

public AbstractCallMethod()
Method Detail

setResultId

public void setResultId(String resultId)
Sets the identifier at which the result of invoking the method will stored.

Parameters:
resultId - a String that names an attribute in the PageContext's attribute map where any resulting object will be stored.

setFailOnError

public void setFailOnError(boolean failOnError)
Sets whether or not to report exceptions to the page when errors occur invoking a method on an object.

Parameters:
failOnError - a boolean that defines whether or not exceptions should be thrown when invocation fails.

setMethod

public void setMethod(String method)
Sets the name of a method to invoke on the target object.

Parameters:
method - the name of the method to invoke

addParameter

public void addParameter(String type,
                         Object parameter)
Add a paramter that will be passed as an argument to the method that will be invoked. This method is implemented to allow the the MethodParameter tags to register their parameters. This object is passed in the position that it appeared in the set of child MethodParameter tags.

Parameters:
type - a String of the type or class name of this parameter
parameter - an object that should be passed as an argument to the invoked method
See Also:
MethodParameter

doStartTag

public int doStartTag()
               throws JspException
Causes the body of this tag to be rendered; only MethodParameter tags are allowed to be contained inside of this tag. The body content is never rendered.

Specified by:
doStartTag in interface Tag
Overrides:
doStartTag in class BodyTagSupport
Returns:
EVAL_BODY_BUFFERED
Throws:
JspException
See Also:
MethodParameter

doEndTag

public int doEndTag()
             throws JspException
Reflectively invokes the method specified by the method attribute, findMethod(Object, String, boolean). The arguments passed to the method are taken from any nested MethodParameter tags. When the parameters which are added by the MethodParameter tags are String types, an attempt is made to convert each of these parameters into the type expected by the method. This conversion is done using the TypeUtils.convertToObject(java.lang.String, java.lang.Class) method. If a String can not be converted do the type expected by the method, an exception is thrown and the error is reported in the tag. Any return value that results from invoking the given method is passed to the subclass implementation of the method handleReturnValue(java.lang.Object).

Specified by:
doEndTag in interface Tag
Overrides:
doEndTag in class BodyTagSupport
Returns:
EVAL_PAGE to continue evaluating the page
Throws:
JspException - if there are errors. All exceptions that may be thrown in the process of reflectively invoking the method and performing type conversion are reported as @see javax.servlet.jsp.JspException.
See Also:
findMethod(Object, String, boolean), handleReturnValue(java.lang.Object), MethodParameter, ObjectNotFoundException, TypeUtils.convertToObject(java.lang.String, java.lang.Class), String

localRelease

protected void localRelease()
Reset all of the fields of this tag.

Overrides:
localRelease in class AbstractClassicTag

resolveObject

protected abstract Object resolveObject()
                                 throws ObjectNotFoundException,
                                        JspException

Resolve the object on which the method should be invoked. If there are errors resolving this object, this method will throw an ObjectNotFoundException.

If the object is not found but no exception occurred, this method should return null.

Returns:
the object on which to reflectively invoke the method.
Throws:
ObjectNotFoundException - if an exception occurred attempting to resolve an object
JspException

getObjectName

protected abstract String getObjectName()
Get the name of the object that is the target of the invocation. This is a generic method for this tag that enables more specific error reporting.

Returns:
a name for the object on which the method will be invoked.

allowNullInvocationTarget

protected boolean allowNullInvocationTarget()
When implemented to return true, this method allows a tag invoking a method to accept a null invocation target and simply return null. The default implementation returns false.

Returns:
true if the object on which to invoke the method can be null; false otherwise.

handleReturnValue

protected void handleReturnValue(Object result)

A method that allows concrete classes to handle the result of the reflective invocation in an implementation specific way.

The default beahavior is to set the return value resulting from invoking the method in the PageContext attribute map of the current JSP page. The result is set as an attribute if the result is not null and the setResultId(java.lang.String) String is not null. If the value returned from calling a method is null and the setResultId(java.lang.String) is non-null, the JspContext.removeAttribute(java.lang.String) is called to remove the attribute from the attribute map.

Parameters:
result - the object that was returned by calling the method on the object

getParameterNodes

protected List getParameterNodes()
Internal, read-only property used by subclasses to get the list of parameters to be used when reflectively invoking a method. If the method takes no parameters, this list will be of size zero.

Returns:
the list of parameters

findMethod

protected Method findMethod(Object target,
                            String methodName,
                            boolean verifyTypes)
The default findMethod implementation is an uncached search of all of the methods available on the Class of the target

Parameters:
target - the object from which to find the method
methodName - the name of the method to find
verifyTypes - a boolean that if true will match the type names in addition to the String method name
Returns:
a Method object matching the methodName and types, if verifyTypes is true. null otherwise.