Package cdc.args

Class FormalArg<T>

  • Type Parameters:
    T - Type of the formal argument.
    Direct Known Subclasses:
    CompositeFormalArg, MapFormalArg
    public class FormalArg<T>
extends Object
    Class used to describe a formal argument.

    A formal argument has a name, a type and may be optional or mandatory.

    Author:
    Damien Carbonne

    • Constructor Detail

      • FormalArg

        public FormalArg​(String name,
                 Class<T> type,
                 Necessity necessity)
        Creates a formal argument.
        Parameters:
        name - The formal argument name.
        type - The formal argument type.
        necessity - The formal argument necessity.
        Throws:
        IllegalArgumentException - when name is invalid, or when type or necessity is null.

      • FormalArg

        public FormalArg​(String name,
                 Class<T> type)
        Creates a MANDATORY formal argument.
        Parameters:
        name - The formal argument name.
        type - The formal argument type.
        Throws:
        IllegalArgumentException - when name is invalid, or when type is null.

    • Method Detail

      • isValidName

        public static boolean isValidName​(String s)
        Returns true when a string can be used as a valid name.

        Rules are very relaxed: only null names are forbidden.
        Stronger rules should be applied.

        Parameters:
        s - The string
        Returns:
        True when s is a valid name.

      • checkName

        public static void checkName​(String name)
        Checks a name.
        Parameters:
        name - The name
        Throws:
        IllegalArgumentException - when name is invalid.

      • getName

        public final String getName()
        Returns:
        The formal argument name.

      • getType

        public final Class<T> getType()
        Returns:
        The formal argument type.

      • getDescription

        public final String getDescription()
        Returns:
        The formal argument description.

      • getWrappedType

        public final Class<T> getWrappedType()
        Returns:
        The formal argument wrapped type.

      • getNecessity

        public final Necessity getNecessity()
        Returns:
        The formal argument necessity.

      • isMandatory

        public final boolean isMandatory()
        Returns:
        true if this formal argument is mandatory.

      • isOptional

        public final boolean isOptional()
        Returns:
        true if this formal argument is optional.

      • isCompliantWith

        public final boolean isCompliantWith​(Object value)
        Returns whether a value is compliant with this formal argument.

        If value is null, then this formal argument must be optional.
        Otherwise, value must be assignable to wrappedType of the formal argument.

        Parameters:
        value - The value to check.
        Returns:
        Whether value is compliant with this formal argument.

      • matchesName

        public final boolean matchesName​(String other)
        Returns true if the name of this formal argument equals another name.
        Parameters:
        other - The other name.
        Returns:
        true if the name of this formal argument equals other.

      • hasWeakerType

        public final boolean hasWeakerType​(Class<?> other)
        Returns true if the (wrapped) type of this formal argument can be assigned by another type.
        Parameters:
        other - The other type.
        Returns:
        true if the (wrapped) type of this formal argument can be assigned by  other.

      • hasWeakerNecessity

        public final boolean hasWeakerNecessity​(Necessity other)
        Returns true if the necessity of this formal argument is weaker than (or equal to) another necessity.
        Parameters:
        other - The other necessity.
        Returns:
        true if the necessity of this formal argument is weaker than (or equal to) other.

      • isWeakerThan

        public final boolean isWeakerThan​(FormalArg<?> other)
        Returns true if this formal argument is weaker than another one.

        This is the case when any argument that is compliant with other is compliant with this formal argument.

        It must have:

        • The same name.
        • A weaker necessity.
        • A weaker (more general) type.
        Parameters:
        other - The other formal argument.
        Returns:
        true if this formal argument is weaker than other.

      • merge

        public static FormalArg<?> merge​(FormalArg<?> farg1,
                                 FormalArg<?> farg2,
                                 Necessity privileged)
        Merges 2 formal arguments.

        This is possible if one of them is null, or they have same name and compliant types.
        In that case, if necessity are different, the resulting necessity is MANDATORY.
        When types are compliant, the most specialized one is chosen.

        For example:

        • merge(null, null) = null
        • merge(null, w) = x
        • merge(x, null) = x
        • merge((name1, ...), (name2, ...)) throws IllegalArgumentException
        • merge((name, String.class, OPTIONAL), (name, Object, OPTIONAL)) = (name, String.class, OPTIONAL)
        • merge((name, String.class, OPTIONAL), (name, Object, MANDATORY)) = (name, String.class, MANDATORY)
        • merge((name, String.class, OPTIONAL), (name, Integer, OPTIONAL)) = throws IllegalArgumentException
        Parameters:
        farg1 - The first formal argument (possibly null).
        farg2 - The second formal argument (possibly null).
        privileged - The privileged necessity.
        Returns:
        The merge of farg1 and farg2.
        Throws:
        IllegalArgumentException - When merge is impossible (names conflict or types conflict).

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object