Package net.kautler.command.api.parameter

Interface ParameterConverter<M,​R>

  • Type Parameters:
    M - the class of the messages this parameter converter processes
    R - the class of the result this parameter converter produces
    public interface ParameterConverter<M,​R>
    A converter that converts a String parameter determined from the given message type to the given result type.

    CDI Beans implementing this interface also need to be annotated with one or multiple ParameterType qualifiers that define the parameter type aliases for which the annotated parameter converter works. Without such qualifier the converter will simply never be used. It is an error to have multiple parameter converters with the same parameter type that can be applied to the same framework message type and this will produce an error latest when a parameter with that type is being converted. The only exception are the built-in parameter types. A user-supplied converter with the same parameter type as a built-in converter will be preferred, but it would still be an error to have multiple such overrides for the same type.

    • Method Detail

      • convert

        R convert​(String parameter,
          String type,
          CommandContext<? extends M> commandContext)
   throws Exception
        Converts the given parameter to the result type. null results are not permitted and will lead to exceptions at runtime.

        If the format of the parameter is invalid, for example some text for a number-parsing converter, an InvalidParameterFormatException will be thrown. The parameterName and parameterValue should not be set manually, they will automatically be set by the code calling the converter and will override any previously set values. The exception message should be written in a way so that it can be directly presented to the end user.

        If the value of the parameter is invalid though the format was correct, for example the id of an unknown user, an InvalidParameterValueException will be thrown. The parameterName and parameterValue should not be set manually, they will automatically be set by the code calling the converter and will override any previously set values. The exception message should be written in a way so that it can be directly presented to the end user.

        Any other Exception will be wrapped by the code calling the converter in a ParameterParseException with parameterName and parameterValue set unless the thrown exception already is of that type. If a ParameterParseException is thrown, the parameterName and parameterValue should not be set manually, they will automatically be set by the code calling the converter and will override any previously set values.

        Parameters:
        parameter - the parameter to convert
        type - the type of the parameter to convert
        commandContext - the command context, usually fully populated but not necessarily
        Returns:
        the converted parameter
        Throws:
        InvalidParameterFormatException - if the format of the parameter is invalid and could not be parsed
        InvalidParameterValueException - if the value of the parameter is invalid, e. g. the id of an unknown user
        Exception - if there goes anything wrong during parsing