Class ParameterAccessor


  • public class ParameterAccessor
    extends Object
    Access parameters without confusion on their numbers. Depending on the representation of a method (IMethod, MethodReference) parameters are placed at a different position. Functions furthermore may have an implicit this-pointer which alters the positions again. Accessing parameters of these functions by their numbers only is error prone and leads to confusion. This class tries to leverage parameter-access. You can use this class using now numbers at all. However if you choose to use numbers this class has yet another numbering convention (jupeee): 1 is the first parameter appearing in the Selector, no matter if the Method has an implicit this. It is not zero as Java initializes new integer-arrays with zero. If you want to alter the values of the incoming parameters you may also want to use the ParameterManager which tracks the changes.
    Since:
    2013-10-19
    • Constructor Detail

      • ParameterAccessor

        public ParameterAccessor​(MethodReference mRef,
                                 IClassHierarchy cha)
        Reads the parameters of a MethodReference CAUTION:. Do _not_ use ParameterAceesor(IMethod.getReference()), but ParameterAceesor(IMehod)! Using this Constructor influences the SSA-Values returned later. The cha is needed to determine whether mRef is static. If this is already known one should prefer the faster #ParameterAccessor(ParameterAccessor, boolean).
        Parameters:
        mRef - The method to read the parameters from.
      • ParameterAccessor

        public ParameterAccessor​(MethodReference mRef,
                                 boolean hasImplicitThis)
        Reads the parameters of a MethodReference CAUTION:. Do _not_ use ParameterAceesor(IMethod.getReference()), but ParameterAceesor(IMehod)! This constructor is faster than {@link #ParameterAccessor(MethodReference, IClassHierarchy}.
        Parameters:
        mRef - The method to read the parameters from.
      • ParameterAccessor

        public ParameterAccessor​(IMethod method)
        Read the parameters from an IMethod. Using this Constructor influences the SSA-Values returned later.
        Parameters:
        method - The method to read the parameters from.
    • Method Detail

      • getParameter

        public ParameterAccessor.Parameter getParameter​(int no)
        Make an Parameter Object using a Descriptor-based numbering (starting with 1). Number 1 is the first parameter in the methods Selector. No matter if the function has an implicit this pointer. If the Function has an implicit this-pointer you can access it using getThis().
        Parameters:
        no - the number in the Selector
        Returns:
        new Parameter-Object for no
        Throws:
        IllegalArgumentExceptions - if the parameter is zero
        ArrayIndexOutOfBoundsException - if no is not within bounds [1 to numberOfParameters]
      • getParameterNo

        public int getParameterNo​(int no)
        Return the SSA-Value to access a parameter using a Descriptor-based numbering (starting with 1). Number 1 is the first parameter in the methods Selector. No matter if the function has an implicit this pointer. If the Function has an implicit this-pointer you can acess it using getThisNo().
        Parameters:
        no - the number in the Selector
        Returns:
        the offseted number for accessing the parameter
        Throws:
        IllegalArgumentException - if the parameter is zero
        ArrayIndexOutOfBoundsException - if no is not within bounds [1 to numberOfParameters]
      • getParameterNo

        public int getParameterNo​(ParameterAccessor.Parameter param)
        Same as Parameter.getNumber().
        Returns:
        SSA-Value to access the parameters contents.
      • all

        public List<ParameterAccessor.Parameter> all()
        This list _excludes_ the implicit this-pointer (if any). If you want the implicit this-pointer use getThis().
        Returns:
        All parameters appearing in the Selector.
      • getThis

        public ParameterAccessor.Parameter getThis()
        Return the implicit this-pointer (or throw). This obviously only works on non-static methods. You probably want to check if the method has such an implicit this using hasImplicitThis() as this method will throw if there is none. If you only want the number use the more lightweight getThisNo().
        Returns:
        Object containing all Information on the parameter.
        Throws:
        IllegalStateException - if the function has no implicit this
      • getThisNo

        public int getThisNo()
        Return the SSA-Value of the implicit this-pointer (or throw). This obviously only works on non-static methods. You probably want to check if the method has such an implicit this using hasImplicitThis() as this method will throw if there is none.
        Returns:
        Number of the this.
        Throws:
        IllegalStateException - if the function has no implicit this.
      • hasImplicitThis

        public boolean hasImplicitThis()
        If the method has an implicit this parameter.
      • makeReturn

        public ParameterAccessor.Parameter makeReturn​(int ssa)
        Create a "Parameter" containing the Return-Type w/o Type-checking. This should be of rather theoretical use.
        Throws:
        IllegalStateException - if used on a void-Function
      • firstInSelector

        public int firstInSelector()
        The SSA-Value to acces the parameter appearing first in the Descriptor with.
        Throws:
        IllegalArgumentException - if the method has no parameters in its Descriptor.
      • getParameterType

        public TypeReference getParameterType​(int no)
        Prefer: getParameter(int no) or all(). Get the type of the parameter (not this) using a fixed numbering. Number 1 is the first parameter in the methods Selector. No matter if the function has an implicit this pointer. Use all() if you want to get all parameter-types.
        Parameters:
        no - the number in the Selector
        Returns:
        the type of the parameter
      • firstExtends

        public ParameterAccessor.Parameter firstExtends​(TypeName tName,
                                                        IClassHierarchy cha)
        First parameter in the selector that is a subclass of tName (slow). TypeNames have to be lloked up first, do prefer the variant with the TypeReference if one is available.
        Returns:
        first parameter found or null if there is none
        Throws:
        IllegalArgumentException - if searching for void or null
      • getFirstAfter

        public int getFirstAfter()
        The first SSA-Number after the parameters. This is useful for making synthetic methods.
      • forInvokeStatic

        public int[] forInvokeStatic​(List<? extends SSAValue> args)
        Generate the params-param for an InvokeIstruction w/o type checking.
        Parameters:
        args - list to build the arguments from - without implicit this
      • forInvokeStatic

        public int[] forInvokeStatic​(List<? extends SSAValue> args,
                                     ParameterAccessor target,
                                     IClassHierarchy cha)
        Generate the params-param for an InvokeIstruction with type checking.
        Parameters:
        args - list to build the arguments from - without implicit this
        target - the method to be called - for type checking only
        cha - if types don't match exactly needed for the assignability check (may be null if that check is not wanted)
        Throws:
        IllegalArgumentException - if you call this method on a target that needs an implicit this
        IllegalArgumentException - if args length does not match the targets param-length
        IllegalArgumentException - if a parameter is unassignable
      • forInvokeVirtual

        public int[] forInvokeVirtual​(int self,
                                      List<? extends SSAValue> args)
        Generate the params-param for an InvokeIstruction w/o type checking.
        Parameters:
        self - the this-pointer to use
        args - the rest of the arguments. Be shure it does not start with a this pointer. This is _not_ checked so you can use a this-pointer as an argument. However a warning is issued.
        Throws:
        IllegalArgumentException - if the value of self is to small in the current method
      • forInvokeVirtual

        public int[] forInvokeVirtual​(int self,
                                      List<? extends SSAValue> args,
                                      ParameterAccessor target,
                                      IClassHierarchy cha)
        Generate the params-param for an InvokeIstruction with type checking.
        Parameters:
        self - the this-pointer to use
        args - list to build the arguments from - without implicit this
        target - the method to be called - for type checking only
        cha - if types don't match exactly needed for the assignability check (may be null if that check is not wanted)
        Throws:
        IllegalArgumentException - if you call this method on a target that needs an implicit this
        IllegalArgumentException - if args length does not match the targets param-length
        IllegalArgumentException - if a parameter is unassignable
      • connectThrough

        public List<SSAValue> connectThrough​(ParameterAccessor callee,
                                             Set<? extends SSAValue> overrides,
                                             Set<? extends SSAValue> defaults,
                                             IClassHierarchy cha,
                                             IInstantiator instantiator,
                                             Object... instantiatorArgs)
        Connects though parameters from the calling function (overridable) - CAUTION:. This functions makes is decisions based on Type-Referes only so if a TypeReference occurs multiple times in the caller or callee it may make surprising connections. The List of Parameters is generated based on the overrides, than parameters in 'this' are searched, finally we'll fall back to defaults. A "perfect match" is searched. If a parameter was not assigned yet these three sources are considdered again but cha.isAssignableFrom is used. If the parameter was still not found a value of 'null' is used. This funktion is useful when generating wrapper-functions.
        Parameters:
        callee - The function to generate the parameter-list for
        overrides - If a parameter occurs here, it is preferred over the ones present in this
        defaults - If a parameter is not present in this or the overrides, defaults are searched. If the parameter is not present there null is assigned.
        cha - Optional class hierarchy for testing assignability
        Returns:
        the parameter-list for the call of toMethod
      • forMethod

        public MethodReference forMethod()
        The method this accessor reads the parameters from.
      • forInvokeStatic

        public int[] forInvokeStatic​(List<? extends ParameterAccessor.Parameter> args,
                                     MethodReference target,
                                     IClassHierarchy cha)
        Shorthand for forInvokeStatic(final List args, final ParameterAccessor target, final IClassHierarchy cha). Generates a new ParameterAccessor for target and hands the call through.
      • forInvokeVirtual

        public int[] forInvokeVirtual​(int self,
                                      List<? extends ParameterAccessor.Parameter> args,
                                      MethodReference target,
                                      IClassHierarchy cha)
        Shorthand for forInvokeVirtual(final int self, final List args, final ParameterAccessor target, final IClassHierarchy cha). Generates a new ParameterAccessor for target and hands the call through.
      • hasReturn

        public boolean hasReturn()
        If the method returns a value eg is non-void.
      • connectThrough

        public List<SSAValue> connectThrough​(ParameterAccessor callee,
                                             Set<? extends SSAValue> overrides,
                                             Set<? extends SSAValue> defaults,
                                             IClassHierarchy cha)
        Assign parameters to a call based on their type. this variant of connectThrough cannot create new instances if needed.
        Parameters:
        callee - The function to generate the parameter-list for
        overrides - If a parameter occurs here, it is preferred over the ones present in this
        defaults - If a parameter is not present in this or the overrides, defaults are searched. If the parameter is not present there null is assigned.
        cha - Optional class hierarchy for testing assignability
        Returns:
        the parameter-list for the call of toMethod
      • getReturnType

        public TypeReference getReturnType()
        Handed through to the IMethod / MethodReference
      • getNumberOfParameters

        public int getNumberOfParameters()
        Number of parameters _excluding_ implicit this
      • dump

        public String dump()
        Extensive output for debugging purposes.