THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
Code Block |
---|
{
"apiKey": 52,
"type": "request",
"name": "UpdateFeaturesRequest",
"validVersions": "0",
"flexibleVersions": "0+",
"fields": [
{ "name": "timeoutMs", "type": "int32", "versions": "0+", "default": "60000",
"about": "How long to wait in milliseconds before timing out the request." },
{ "name": "FeatureUpdates", "type": "[]FeatureUpdateKey", "versions": "0+",
"about": "The list of updates to finalized features.", "fields": [
{"name": "Feature", "type": "string", "versions": "0+", "mapKey": true,
"about": "The name of the finalized feature to be updated."},
{"name": "MaxVersionLevel", "type": "int16", "versions": "0+",
"about": "The new maximum version level for the finalized feature. A value >= 1 is valid. A value < 1, is special, and can be used to request the deletion of the finalized feature."},
{"name": "AllowDowngrade", "type": "bool", "versions": "0+",
"about": "When set to true, the finalized feature version level is allowed to be downgraded/deleted. The downgraded request will fail if the new maximum version level is a value that's not lower than the existing maximum finalized version level."}
]}
]
} |
...
Code Block |
---|
{
"apiKey": 18,
"type": "response", "name": "ApiVersionsResponse",
"validVersions": "0-3",
"flexibleVersions": "3+",
"fields": [
{ "name": "ErrorCode", "type": "int16", "versions": "0+",
"about": "The top-level error code." },
{ "name": "ApiKeys", "type": "[]ApiVersionsResponseKey", "versions": "0+",
"about": "The APIs supported by the broker.", "fields": [
{ "name": "ApiKey", "type": "int16", "versions": "0+", "mapKey": true,
"about": "The API index." },
{ "name": "MinVersion", "type": "int16", "versions": "0+",
"about": "The minimum supported version, inclusive." },
{ "name": "MaxVersion", "type": "int16", "versions": "0+",
"about": "The maximum supported version, inclusive." }]
},
{ "name": "ThrottleTimeMs", "type": "int32", "versions": "1+", "ignorable": true,
"about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
// ----- START: PROPOSED ADDITIONAL METADATA -----
{ "name": "SupportedFeatures", "type": "[]FeatureKey",
"versions": "3+", "tag": 10000, "taggedVersions": "3+",
"about": "Features supported by the broker.",
"fields": [
{ "name": "Name", "type": "string", "versions": "3+",
"about": "The name of the feature." },
{ "name": "MinVersion", "type": "int16", "versions": "3+",
"about": "The minimum supported version for the feature." },
{ "name": "MaxVersion", "type": "int16", "versions": "3+",
"about": "The maximum supported version for the feature." }
]
},
{"name": "FinalizedFeaturesEpoch", "type": "int64", "versions": "3+",
"tag": 10001, "taggedVersions": "3+", "default": "-1", "ignorable": true,
"about": "The monotonically increasing epoch for the features information."},
{ "name": "FinalizedFeatures", "type": "[]FinalizedFeatureKey",
"versions": "3+", "tag": 10002, "taggedVersions": "3+",
"about": "List of cluster-wide finalized features.",
"fields": [
{"name": "Name", "type": "string", "versions": "3+",
"about": "The name of the feature."},
{"name": "MaxVersionLevel", "type": "int16", "versions": "3+",
"about": "The cluster-wide finalized max version level for the feature."},
{"name": "MinVersionLevel", "type": "int16", "versions": "3+",
"about": "The cluster-wide finalized min version level for the feature."}
]
}
// ----- END: PROPOSED ADDITIONAL METADATA -----
]
} |
...
Code Block | ||
---|---|---|
| ||
// ---- START: Proposed Admin API definitions ----
/**
* Describes supported and finalized features. You may anticipate
* certain exceptions when calling get() on the future obtained from the returned
* DescribeFeaturesResult.
*
* @param options options for the describeFeatures API,
*
* @return a result object containing:
* 1. List of cluster-wide finalized feature versions.
* 2. List of supported feature versions specific to the broker.
*/
DescribeFeaturesResult describeFeatures(DescribeFeaturesOptions options);
/**
* Update the feature versions supported cluster-wide. You may
* anticipate certain exceptions when calling get() on the futures
* obtained from the returned UpdateFeaturesResult.
*
* @param updates map of feature updates, keyed by the
* name of the feature
* @param options options for the updateFeatures API
*
* @return the results of the FeatureUpdate provided in the request
*/
UpdateFeaturesResult updateFeatures(Map<String, FeatureUpdate> featureUpdates, UpdateFeaturesOptions options);
/**
* Options for {@link AdminClient#describeFeatures(DescribeFeaturesOptions)}.
*
* The API of this class is evolving.
*/
@InterfaceStability.Evolving
public class DescribeFeaturesOptions extends AbstractOptions<DescribeFeaturesOptions> {
/**
* Sets a flag indicating that the describe features request must be issued only to the controller.
* - True means the {@link Admin#describeFeatures(DescribeFeaturesOptions)} request must be
* issued only to the controller.
* - False means the {@link Admin#describeFeatures(DescribeFeaturesOptions)} request can be
* issued to any random broker.
*/
public DescribeFeaturesOptions sendRequestToController(boolean sendRequestToController).
/**
* - Returns true if the Admin#describeFeatures(DescribeFeaturesOptions) request must be
* issued only to the controller.
* - Returns false if the Admin#describeFeatures(DescribeFeaturesOptions) request can be
* issued to any random broker.
*/
public boolean sendRequestToController();
}
// ---- END: Proposed Admin API definitions ----
// Represents a range of version levels supported by every broker in a cluster for some feature.
class FinalizedVersionRange {
// The cluster-wide finalized value of the feature min version level (value >= 1).
short minVersionLevel();
// The cluster-wide finalized value of the feature max version level (value >=1 and value >= minVersionLevel).
short maxVersionLevel();
}
// Represents a range of versions that a particular broker supports for some feature.
class SupportedVersionRange {
// The minimum version (value >= 1) of the supported feature.
short minVersion();
// The maximum version (value >=1 and value >= minVersion) of the supported feature.
short maxVersion();
}
/**
* Represents an update to a Feature, which can be sent to the controller
* for processing.
*/
class FeatureUpdate {
/**
* The cluster-wide finalized NEW value of the feature max version level.
* - When >= 1, it's the new value to-be-updated for the finalized feature.
* - When < 1, it indicates the deletion of a finalized feature.
*/
short maxVersionLevel();
/**
* Return true only if downgrade/deletion of a feature should be allowed.
* Note that despite this allowDowngrade flag being set, certain downgrades
* may be rejected by the controller if it is deemed unsafe to downgrade
* the max version level of some specific feature.
*/
bool allowDowngrade();
}
/**
* Encapsulates details about finalized as well as supported features. This is particularly useful
* to hold the result returned by the `Admin#describeFeatures(DescribeFeaturesOptions)` API.
*/
class FeatureMetadata {
/**
* Returns a map of finalized feature versions. Each entry in the map contains a key being a
* feature name and the value being a range of version levels supported by every broker in the
* cluster.
*/
Map<String, FinalizedVersionRange> finalizedFeatures();
/**
* The monotonically increasing epoch for the finalized features.
* If the returned value is empty, it means the finalized features are absent/unavailable.
*/
Optional<Long> finalizedFeaturesEpoch();
/**
* Returns a map of supported feature versions. Each entry in the map contains a key being a
* feature name and the value being a range of versions supported by a particular broker in the
* cluster.
*/
Map<String, SupportedVersionRange> supportedFeatures();
}
class DescribeFeaturesResult {
/**
* The data returned in the future contains the latest entire set of
* finalized cluster-wide features, as well as the entire set of
* features supported by the broker serving this read request.
*/
KafkaFuture<FeatureMetadata> featureMetadata();
}
class UpdateFeaturesResult {
/**
* Returns a future which succeeds only if all the FeatureUpdate in the request succeed.
*/
KafkaFuture<Void> all();
/**
* Returns a map with key being feature name and value being
* the future which can be used to check the status of the FeatureUpdate
* in the request.
*
* Possible error codes:
* - NONE: The FeatureUpdate succeeded.
* - NOT_CONTROLLER: The FeatureUpdate failed since the request was processed by a broker that's not the controller.
* - CLUSTER_AUTHORIZATION_FAILED: The FeatureUpdate failed since there wasn't sufficient permission to perform the update.
* - INVALID_REQUEST: The FeatureUpdate failed because it is invalid.
* - FEATURE_UPDATE_FAILED: The FeatureUpdate failed because it can not be applied (ex: due to version incompatibilities)
*/
Map<String, KafkaFuture<Void>> values();
} |
...