com.pushtechnology.diffusion.client.features.control.clients.SecurityStoreFeature Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2023 DiffusionData Ltd., All Rights Reserved.
*
* Use is subject to license terms.
*
* NOTICE: All information contained herein is, and remains the
* property of Push Technology. The intellectual and technical
* concepts contained herein are proprietary to Push Technology and
* may be covered by U.S. and Foreign Patents, patents in process, and
* are protected by trade secret or copyright law.
*******************************************************************************/
package com.pushtechnology.diffusion.client.features.control.clients;
import java.util.Collection;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import com.pushtechnology.diffusion.client.callbacks.Callback;
import com.pushtechnology.diffusion.client.callbacks.ContextCallback;
import com.pushtechnology.diffusion.client.features.ClusterRoutingException;
import com.pushtechnology.diffusion.client.features.ScriptException;
import com.pushtechnology.diffusion.client.session.Feature;
import com.pushtechnology.diffusion.client.session.PermissionsException;
import com.pushtechnology.diffusion.client.session.SessionClosedException;
import com.pushtechnology.diffusion.client.types.ErrorReport;
/**
* The super interface for features that update security stores.
*
* @author DiffusionData Limited
* @since 5.3
*/
public interface SecurityStoreFeature extends Feature {
/**
* Send a command script to the server to update the security store.
*
* The script may be generated using a {@code ScriptBuilder} obtained from
* the feature.
*
* Each line of script is a command to update the store.
*
* The server attempts to execute each command in order against a copy of
* the store. If any command fails, none of the changes will be applied. If
* all commands succeed, the changes will be applied.
*
* If the server is configured for topic replication then the changes will
* be replicated to all members of the cluster.
*
* @param commandScript the script
*
* @return a CompletableFuture that completes when a response is received
* from the server.
*
*
* If the request was successful, the CompletableFuture will
* complete successfully. The result type is any rather than Void to
* provide forward compatibility with future iterations of this API
* that may provide a non-null result with a more specific result
* type.
*
*
* Otherwise, the CompletableFuture will complete exceptionally with
* a {@link CompletionException}. Common reasons for failure, listed
* by the exception reported as the
* {@link CompletionException#getCause() cause}, include:
*
*
*
* - {@link ScriptException} – if {@code commandScript} is
* invalid;
*
*
- {@link PermissionsException} – if the session does
* not have {@code MODIFY_SECURITY} permission;
*
*
- {@link ClusterRoutingException} – if the operation failed
* due to a transient cluster error;
*
*
- {@link SessionClosedException} – if the session is
* closed.
*
* @since 6.0
*/
CompletableFuture updateStore(String commandScript);
/**
* Send a command script to the server to update the security store.
*
* The script may be generated using a {@code ScriptBuilder} obtained from
* the feature.
*
* Each line of script is a command to update the store.
*
* The server attempts to execute each command in order against a copy of
* the store. If any command fails, none of the changes will be applied. If
* all commands succeed, the changes will be applied.
*
* @param commandScript the script
*
* @param callback the result of applying the script
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void updateStore(
String commandScript,
UpdateStoreCallback callback);
/**
* Send a command script to the server to update the security store, with a
* contextual callback.
*
* The script may be generated using a {@code ScriptBuilder} obtained from
* the feature.
*
* Each line of script is a command to update the store.
*
* The server attempts to execute each command in order against a copy of
* the store. If any command fails, none of the changes will be applied. If
* all commands succeed, the changes will be applied.
*
* @param commandScript the script
*
* @param context the context to pass to the callback. May be null.
*
* @param callback the result of applying the script
*
* @param the context type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
void updateStore(
String commandScript,
C context,
UpdateStoreContextCallback callback);
/**
* The callback interface for use with
* {@link SecurityStoreFeature#updateStore(String, UpdateStoreCallback)
* updateStore}.
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
interface UpdateStoreCallback extends Callback {
/**
* The script was applied successfully.
*/
void onSuccess();
/**
* The script was rejected. No changes were made to the security store.
*
* @param errors the detail of why the script was rejected
*/
void onRejected(Collection errors);
}
/**
* The contextual callback interface for use with
* {@link SecurityStoreFeature#updateStore(String, Object, UpdateStoreContextCallback)
* updateStore}.
*
* Attaches an arbitrary context object to callback notifications.
*
* @param the context type
*
* @deprecated since 6.7
*
* Methods that use callbacks are deprecated and will be removed
* in a future release. Use CompletableFuture variant instead.
*/
@Deprecated
interface UpdateStoreContextCallback extends ContextCallback {
/**
* The script was applied successfully.
*
* @param context the context object supplied when making the call
*/
void onSuccess(C context);
/**
* The script was rejected. No changes were made to the security store.
*
* @param context the context object supplied when making the call
*
* @param errors the detail of why the script was rejected
*/
void onRejected(C context, Collection errors);
}
}