Make the API less verbose

[chiaradiamarcelo]

as the messages grow in parameters, it's a little bit cumbersome and verbose to define them all explicitly.

For example,

RemoteMetadataReaderException(ExaError.messageBuilder("E-VS-COM-JDBC-31")
        .message("Unsupported data type(s) {{dataTypes}} in column(s) in query: {{unsupportedColumns}}.")
        .unquotedParameter("dataTypes", dataTypes)  
        .unquotedParameter("unsupportedColumns", unsupportedColumns)
        .mitigation("Please remove those columns from your query:\n{{query}}")
        .unquotedParameter("query", query).toString());

It would be nicer to define the interface similar to slf4j logger, so the previous example would become

RemoteMetadataReaderException(ExaError.messageBuilder("E-VS-COM-JDBC-31")
        .message("Unsupported data type(s) {} in column(s) in query: {}.", dataTypes, unsupportedColumns)
        .mitigation("Please remove those columns from your query:\n{}", query).toString());

[jakobbraun]

By that, we loose the ability to add a description to parameters:

unquotedParameter("dataTypes", dataTypes, "List of available datatypes") 

We wanted to have this for the error catalog.

[chiaradiamarcelo]

By that, we loose the ability to add a description to parameters:

unquotedParameter("dataTypes", dataTypes, "List of available datatypes") 

We wanted to have this for the error catalog.

True. This would be a shortcut in cases we don't need to define a description

[jakobbraun]

Ok, but I don't like that by that we introduce two types of placeholders (named and without name). That makes the API harder to understand.

[jakobbraun]

But I also see that it would be more compact.

[jakobbraun]

another issue: We decided to make the quotedParameter as default. For that reason, it's parameter and unquotedParameter. The suggested API would suggest users to use unquoted parameters and maybe they would even start to quote themselves.

[chiaradiamarcelo]

another issue: We decided to make the quotedParameter as default. For that reason, it's parameter and unquotedParameter. The suggested API would suggest users to use unquoted parameters and maybe they would even start to quote themselves.

Yeah We can talk later if we want to add some change in the API and how.

[chiaradiamarcelo]

Some discussed alternatives are:

• use the {} place holder for unquoted parameters, and another one for quoted, or vice versa, eg, {q}, {\q}, \{}, [], etc
• add the description, if any, inside the place holder, as follows:

.message("This is a message with parameter {'parameter description'}", parameter)

[redcatbear]

The main question is if we really need an extra parameter description or not.
We are talking about a situation where the fill-in-text is completely available. If that text is written properly, the description is redundant.

I like this the last variant Marcello suggested, but would get rid of the single quotes and slightly modify the way to indicate a quoted parameter:

ExaError.messageBuilder("W-FOO-BAR-1")
    .message("Remaining space on device {device name|q} is less than {warning threshold}%. Only {remaining space} MiB left.",
            deviceName, warningThreshold, remainingSpace)
    // ...

This would be a shorthand version of saying:

ExaError.messageBuilder("W-FOO-BAR-1")
    .message("Remaining space on device {{device name}} is less than {{warning threshold}}%. Only {{remaining space}} MiB left.")
    .quotedParameter("device name", deviceName, "device name")
    .unquotedParameter("warning threshold", warningThreshold, "warning threshold")
    .unquotedParameter("remaining space", remainingSpace, "remaining space")
    // ...

[jakobbraun]

generally sounds good, but in the last meeting we wanted to have the quoted as default. For that reason it's parameter and unquotedParameter (not quotedParameter).
I would like to keep this API as it is for backward compatibility.
To be consequent I would also suggest to use |uq for the new API to mark unquoted parameters.

[redcatbear]

I see, I missed the parameter naming.

Yes, we should keep the verbose API too. The other method is then just a short-hand version that internally uses the verbose API.

[redcatbear]

@chiaradiamarcelo: Since you originally suggested this change, please also implement it. @jakobbraun should review it.