Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate bad subscription options and add replacements #462

Merged
merged 5 commits into from
Oct 7, 2024
Merged

Deprecate bad subscription options and add replacements #462

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e4d4260
Add:
LukasBrand Oct 2, 2024
4f3693b
Update documentation
LukasBrand Oct 2, 2024
2d063b0
Apply review comments
LukasBrand Oct 7, 2024
0770409
Merge branch 'master' into feature/deprecate-bad-subscribe-options
LukasBrand Oct 7, 2024
399fe1f
Fixed tests to use new logs
LukasBrand Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/_includes/options/subscribe-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
| Option | Long Version | Explanation | Default |
|--------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
| `-t` | `--topic` | The MQTT topic the client will subscribe to. | |
| `-q` | `--qos` | Define the quality of service level. If only one QoS is specified it will be used for all topics.<br> You can define a specific QoS level for every topic. The corresponding QoS levels will be matched in order to the given topics. | `0` |
| `-of` | `--outputToFile` | Append the received publish messages to a file. Creates the file if it does not exist. | |
| `-b64` | `--base64` | Whether the received publish messages will be base64 encoded. | `false` |
| `-J` | `--jsonOutput` | Print the received publishes in pretty JSON format. | `false` |
| `-T` | `--showTopics` | Prepend the specific topic name to the received publish. | `false` |
| `-up` | `--userProperty` | A user property of the subscribe message. | |
| Option | Long Version | Explanation | Default |
|--------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
| `-t` | `--topic` | The MQTT topic the client will subscribe to. | |
| `-q` | `--qos` | Define the quality of service level. If only one QoS is specified it will be used for all topics.<br> You can define a specific QoS level for every topic. The corresponding QoS levels will be matched in order to the given topics. | `0` |
| | `--output-to-file` | Append the received publish messages to a file. Creates the file if it does not exist. | |
| | `--base64` | Whether the received publish messages will be base64 encoded. | `false` |
| `-J` | `--json-output` | Print the received publishes in pretty JSON format. | `false` |
| `-T` | `--show-topics` | Prepend the specific topic name to the received publish. | `false` |
| | `--user-property` | A user property of the subscribe message. | |
7 changes: 6 additions & 1 deletion src/main/java/com/hivemq/cli/commands/cli/SubscribeCommand.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@
import picocli.CommandLine;

import javax.inject.Inject;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.Callable;

Expand All @@ -41,6 +43,7 @@
public class SubscribeCommand implements Callable<Integer> {

private static final int IDLE_TIME = 5000;
private final @NotNull List<String> deprecationWarnings = new ArrayList<>();
private final @NotNull MqttClientExecutor mqttClientExecutor;
private @Nullable MqttClient subscribeClient;

Expand All @@ -64,7 +67,7 @@ private void printToSTDOUT(final boolean printToSTDOUT) {
private final @NotNull ConnectOptions connectOptions = new ConnectOptions();

@CommandLine.Mixin
private final @NotNull SubscribeOptions subscribeOptions = new SubscribeOptions();
private final @NotNull SubscribeOptions subscribeOptions = new SubscribeOptions(deprecationWarnings);

@CommandLine.Mixin
private final @NotNull DebugOptions debugOptions = new DebugOptions();
Expand All @@ -90,6 +93,8 @@ public SubscribeCommand(final @NotNull MqttClientExecutor mqttClientExecutor) {

Logger.trace("Command {}", this);

LoggerUtils.logDeprecatedOptions(deprecationWarnings);

connectOptions.setDefaultOptions();
connectOptions.logUnusedOptions();
subscribeOptions.setDefaultOptions();
Expand Down
166 changes: 150 additions & 16 deletions src/main/java/com/hivemq/cli/commands/options/SubscribeOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,17 @@
import java.io.File;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;

public class SubscribeOptions {

@SuppressWarnings({"NotNullFieldNotInitialized", "unused"})
@CommandLine.Spec
private @NotNull CommandLine.Model.CommandSpec spec;

private final @NotNull List<String> deprecationWarnings;

@SuppressWarnings({"NotNullFieldNotInitialized", "unused"}) //will be initialized via required
@CommandLine.Option(names = {"-t", "--topic"}, required = true, description = "The topics to subscribe to")
private @NotNull String @NotNull [] topics;
Expand All @@ -48,37 +55,164 @@ public class SubscribeOptions {
description = "Quality of service for the corresponding topics (default for all: 2)")
private @NotNull MqttQos @NotNull [] qos;

private @NotNull Mqtt5UserProperty @Nullable [] userProperties = null;
private boolean userPropertiesFromOption = false;
private boolean userPropertiesFromLegacyOption = false;

@SuppressWarnings("unused")
@CommandLine.Option(names = {"-up", "--userProperty"},
@CommandLine.Option(names = {"--user-property"},
converter = Mqtt5UserPropertyConverter.class,
description = "A user property of the subscribe message")
private @Nullable Mqtt5UserProperty @Nullable [] userProperties;
private void userProperties(final @NotNull Mqtt5UserProperty @NotNull [] userProperties) {
if (userPropertiesFromLegacyOption) {
LukasBrand marked this conversation as resolved.
Show resolved Hide resolved
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the user properties legacy options \"-up\" or \"--userProperty\" and the current \"--user-property\" is used. Please only use \"--user-property\" as the legacy options will be removed in a future version.");
}
userPropertiesFromOption = true;
this.userProperties = userProperties;
}

@SuppressWarnings("unused")
@CommandLine.Option(names = {"-of", "--outputToFile"},
@Deprecated(since = "4.34.0", forRemoval = true)
@CommandLine.Option(names = {"-up", "--userProperty"},
hidden = true,
converter = Mqtt5UserPropertyConverter.class,
description = "Options \"-up\" and \"--userProperty\" are legacy, please use \"--user-property\". They will be removed in a future version.")
private void userPropertiesLegacy(final @NotNull Mqtt5UserProperty @NotNull [] userPropertiesLegacy) {
//only show message once as this method is executed multiple times
if (!userPropertiesFromLegacyOption) {
deprecationWarnings.add(
"Options \"-up\" and \"--userProperty\" are legacy, please use \"--user-property\". They will be removed in a future version.");
LukasBrand marked this conversation as resolved.
Show resolved Hide resolved
}

if (userPropertiesFromOption) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the user properties legacy options \"-up\" or \"--userProperty\" and the current \"--user-property\" is used. Please only use \"--user-property\" as the legacy options will be removed in a future version.");
}
userPropertiesFromLegacyOption = true;
userProperties = userPropertiesLegacy;
}

private @Nullable File outputFile = null;

@SuppressWarnings("unused")
@CommandLine.Option(names = {"--output-to-file"},
description = "A file to which the received publish messages will be written")
private @Nullable File outputFile;
private void outputFile(final @NotNull File outputFile) {
if (this.outputFile != null) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the output file legacy options \"-of\" or \"--outputToFile\" and the current \"--output-to-file\" is used. Please only use \"--output-to-file\" as the legacy options will be removed in a future version.");
}
this.outputFile = outputFile;
}

@SuppressWarnings("unused")
@Deprecated(since = "4.34.0", forRemoval = true)
@CommandLine.Option(names = {"-of", "--outputToFile"},
hidden = true,
description = "Options \"-of\" and \"--outputToFile\" are legacy, please use \"--output-to-file\". They will be removed in a future version")
private void outputFileLegacy(final @NotNull File outputFileLegacy) {
deprecationWarnings.add(
"Options \"-of\" and \"--outputToFile\" are legacy, please use \"--output-to-file\". They will be removed in a future version.");

if (this.outputFile != null) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the output file legacy options \"-of\" or \"--outputToFile\" and the current \"--output-to-file\" is used. Please only use \"--output-to-file\" as the legacy options will be removed in a future version.");
}
this.outputFile = outputFileLegacy;
}

private boolean isPayloadEncodeToBase64 = false;
LukasBrand marked this conversation as resolved.
Show resolved Hide resolved

@SuppressWarnings("unused")
@CommandLine.Option(names = {"-b64", "--base64"},
@CommandLine.Option(names = {"--base64"},
description = "Specify the encoding of the received messages as Base64 (default: false)")
private boolean base64;
private void isMessageBase64Encoded(final boolean base64) {
if (isPayloadEncodeToBase64) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the base64 legacy options \"-b64\" and the current \"--base64\" is used. Please only use \"--base64\" as the legacy options will be removed in a future version.");
}
isPayloadEncodeToBase64 = base64;
}

@SuppressWarnings("unused")
@Deprecated(since = "4.34.0", forRemoval = true)
@CommandLine.Option(names = {"-b64"},
hidden = true,
description = "Option \"-b64\" is legacy, please use \"--base64\". It will be removed in a future version")
LukasBrand marked this conversation as resolved.
Show resolved Hide resolved
private void isMessageBase64EncodedLegacy(final boolean base64Legacy) {
deprecationWarnings.add(
"Option \"-b64\" is legacy, please use \"--base64\". It will be removed in a future version.");

if (isPayloadEncodeToBase64) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the base64 legacy options \"-b64\" and the current \"--base64\" is used. Please only use \"--base64\" as the legacy options will be removed in a future version.");
}
isPayloadEncodeToBase64 = base64Legacy;
}

private boolean jsonOutput = false;

@SuppressWarnings("unused")
@CommandLine.Option(names = {"-J", "--jsonOutput"},
defaultValue = "false",
@CommandLine.Option(names = {"-J", "--json-output"},
description = "Print the received publishes in pretty JSON format")
private boolean jsonOutput;
private void jsonOutput(final boolean jsonOutput) {
if (this.jsonOutput) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the json output legacy options \"--jsonOutput\" and the current \"-J\" or \"--json-output\" is used. Please only use \"-J\" or \"--json-output\" as the legacy options will be removed in a future version.");
}
this.jsonOutput = jsonOutput;
}

@SuppressWarnings("unused")
@Deprecated(since = "4.34.0", forRemoval = true)
@CommandLine.Option(names = {"--jsonOutput"},
hidden = true,
description = "Option \"--jsonOutput\" is legacy, please use \"--json-output\". It will be removed in a future version")
private void jsonOutputLegacy(final boolean jsonOutputLegacy) {
deprecationWarnings.add(
"Option \"--jsonOutput\" is legacy, please use \"--json-output\". It will be removed in a future version.");

if (jsonOutput) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the json output legacy options \"--jsonOutput\" and the current \"-J\" or \"--json-output\" is used. Please only use \"-J\" or \"--json-output\" as the legacy options will be removed in a future version.");
}
jsonOutput = true;
}

private boolean showTopics = false;

@SuppressWarnings("unused")
@CommandLine.Option(names = {"-T", "--showTopics"},
defaultValue = "false",
@CommandLine.Option(names = {"-T", "--show-topics"},
description = "Prepend the specific topic name to the received publish")
private boolean showTopics;
private void showTopics(final boolean showTopics) {
if (this.showTopics) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the show topics legacy options \"--showTopics\" and the current \"-T\" or \"--show-topics\" is used. Please only use \"-T\" or \"--show-topics\" as the legacy options will be removed in a future version.");
}
this.showTopics = showTopics;
}

@SuppressWarnings("unused")
@Deprecated(since = "4.34.0", forRemoval = true)
@CommandLine.Option(names = {"--showTopics"},
hidden = true,
description = "Option \"--showTopics\" is legacy, please use \"-T\" or \"--show-topics\". It will be removed in a future version")
private void showTopicsLegacy(final boolean showTopicsLegacy) {
deprecationWarnings.add(
"Option \"--showTopics\" is legacy, please use \"-T\" or \"--show-topics\". It will be removed in a future version.");

if (this.showTopics) {
throw new CommandLine.ParameterException(spec.commandLine(),
"A mix of the show topics legacy options \"--showTopics\" and the current \"-T\" or \"--show-topics\" is used. Please only use \"-T\" or \"--show-topics\" as the legacy options will be removed in a future version.");
}
showTopics = true;
}

private boolean printToSTDOUT = false;

public SubscribeOptions() {
public SubscribeOptions(final @NotNull List<String> deprecationWarnings) {
this.deprecationWarnings = deprecationWarnings;
setDefaultOptions();
}

Expand All @@ -98,8 +232,8 @@ public boolean isPrintToSTDOUT() {
return printToSTDOUT;
}

public boolean isBase64() {
return base64;
public boolean isPayloadEncodeToBase64() {
return isPayloadEncodeToBase64;
}

public boolean isJsonOutput() {
Expand Down Expand Up @@ -181,7 +315,7 @@ public void setDefaultOptions() {
", printToSTDOUT=" +
printToSTDOUT +
", base64=" +
base64 +
isPayloadEncodeToBase64 +
", jsonOutput=" +
jsonOutput +
", showTopics=" +
Expand Down
8 changes: 7 additions & 1 deletion src/main/java/com/hivemq/cli/commands/shell/ContextSubscribeCommand.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@
import picocli.CommandLine;

import javax.inject.Inject;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.Scanner;
import java.util.concurrent.Callable;
Expand All @@ -40,6 +42,8 @@ public class ContextSubscribeCommand extends ShellContextCommand implements Call

private static final int IDLE_TIME = 1000;

private final @NotNull List<String> deprecationWarnings = new ArrayList<>();

@SuppressWarnings("unused")
@CommandLine.Option(names = {"-s", "--stay"},
defaultValue = "false",
Expand All @@ -55,7 +59,7 @@ private void printToSTDOUT(final boolean printToSTDOUT) {
}

@CommandLine.Mixin
private final @NotNull SubscribeOptions subscribeOptions = new SubscribeOptions();
private final @NotNull SubscribeOptions subscribeOptions = new SubscribeOptions(deprecationWarnings);

@Inject
public ContextSubscribeCommand(final @NotNull MqttClientExecutor mqttClientExecutor) {
Expand All @@ -66,6 +70,8 @@ public ContextSubscribeCommand(final @NotNull MqttClientExecutor mqttClientExecu
public @NotNull Integer call() {
Logger.trace("Command {}", this);

LoggerUtils.logDeprecatedOptions(deprecationWarnings);

if (contextClient == null) {
Logger.error("The client to subscribe with does not exist");
return 1;
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/com/hivemq/cli/mqtt/SubscribeMqtt3PublishCallback.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ public class SubscribeMqtt3PublishCallback implements Consumer<Mqtt3Publish> {
SubscribeMqtt3PublishCallback(final @NotNull SubscribeOptions subscribeOptions, final @NotNull Mqtt3Client client) {
printToStdout = subscribeOptions.isPrintToSTDOUT();
outputFile = subscribeOptions.getOutputFile();
isBase64 = subscribeOptions.isBase64();
isBase64 = subscribeOptions.isPayloadEncodeToBase64();
isJsonOutput = subscribeOptions.isJsonOutput();
showTopics = subscribeOptions.isShowTopics();
this.client = client;
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/com/hivemq/cli/mqtt/SubscribeMqtt5PublishCallback.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ public class SubscribeMqtt5PublishCallback implements Consumer<Mqtt5Publish> {
SubscribeMqtt5PublishCallback(final @NotNull SubscribeOptions subscribeOptions, final @NotNull Mqtt5Client client) {
printToStdout = subscribeOptions.isPrintToSTDOUT();
outputFile = subscribeOptions.getOutputFile();
isBase64 = subscribeOptions.isBase64();
isBase64 = subscribeOptions.isPayloadEncodeToBase64();
isJsonOutput = subscribeOptions.isJsonOutput();
showTopics = subscribeOptions.isShowTopics();
this.client = client;
Expand Down
Loading
Loading