Checklist for Hazelcast config changes

These classes should be checked that all structures and fields have been covered. This list can be used as a checklist when adding new configuration types. This is an exhaustive list of places which deal with configuration. Actual cases of adding or altering configuration may or may not need to change each one, it depends on how the configuration will be used and which config features will be supported (e.g. will dynamic config be supported or not, is the config only on member or is it also set on the client).

Dynamic config

• ClientDynamicClusterConfig, DynamicConfigurationAwareConfig
• ConfigurationService, ClusterWideConfigurationService, ClusterWideConfigurationService#registerConfigLocally, EnterpriseClusterWideConfigurationService, EnterpriseClusterWideConfigurationService#ConfigUpdate#scanAll, EnterpriseClusterWideConfigurationService#ConfigUpdate#applyAll
• DynamicConfigGeneratorUtil, DynamicConfigXmlGenerator, DynamicConfigYamlGenerator, AbstractDynamicConfigGeneratorTest, DynamicConfigXmlGeneratorTest, DynamicConfigYamlGeneratorTest
• RewriteUtil#generateRewriteChunk, RewriteUtil#checkDynamicConfigurationNotPersistedYet
• DynamicConfigAdd*ConfigCodec (If you update a config that can be dynamically updated, check the dynamic configuration change codecs to cover this change)
• if you add a new top-level configuration, ensure that it is included in ClusterWideConfigurationService#allConfigurations

Permissions

• PermissionConfig
• com.hazelcast.security.SecurityUtil#createPermission
• com.hazelcast.security.SecurityUtilTest#testCreatePermission()
• com.hazelcast.security.permission.ActionConstants#PERMISSION_FACTORY_MAP
• com.hazelcast.client.security.ClientSecurityTest

Hazelcast Member config

• add or update read-only config in com.hazelcast.internal.config.*ReadOnly
• hazelcast-config-x.y.[xsd&json]
• MemberDomConfigProcessor, YamlMemberDomConfigProcessor (only if YAML needs to derive)
• XML & YAML tests: AbstractConfigBuilderTest -> [XML&Yaml]ConfigBuilderTest
  • XML-specific tests: XmlOnlyConfigBuilderTest
  • YAML-specific tests: YamlOnlyConfigBuilderTest
• ConfigXmlGenerator, ConfigXmlGeneratorTest
• ConfigCompatibilityChecker (used by ConfigDefaultsTest, XmlOnlyConfigBuilderTest#testConfig2Xml2FullConfig and XmlOnlyConfigBuilderTest#testConfig2Xml2FullConfig_withAdvancedNetworkConfig and XmlOnlyConfigBuilderTest#testConfig2Xml2DefaultConfig)
• full configs:
  • hazelcast-fullconfig-without-network.[xml&yaml] (included into the two below)
  • hazelcast-fullconfig.[xml&yaml]
  • hazelcast-fullconfig-advanced-network-config.[xml&yaml]
• hazelcast-default.[xml&yaml] and hazelcast-full-example.[xml&yaml]
• if you have permissions, also add them to
  • the permissions type in the hazelcast-config-x.y.xsd.
  • MemberDomConfigProcessor#handleSecurityPermissions
  • hazelcast-fullconfig-without-network.[xml&yaml] (verified by AbstractConfigBuilderTest#testAllPermissionsCovered)

Verify

• equality of xml and yaml files: XmlYamlConfigBuilderEqualsTest (relies on ConfigXmlGenerator)
• declarative config tests (in intellij):
  • Test kind: Pattern
  • Pattern: ^.*Yaml.*Test$||com.hazelcast.internal.config.yaml.W3cDomTest||com.hazelcast.config.ServiceConfigTest||^.*Xml.*Test$||^.*XML.*Test$

YAML configuration schema update

After updating hazelcast-full-example.yaml with new properties, some of the unittests (eg. XmlYamlConfigBuilderEqualsTest#testFullExample()) will fail with SchemaViolationConfigurationExceptions, because the JSON schema doesn't include the new properties yet.

To fix that:

• you need to update the hazelcast/src/main/resources/hazelcast-config-5.0.json schema file to reflect your changes.
• please also add some new tests (or modify existing ones) to cover the schema change

NOTE: for each new property please add proper "description" and "default" attributes in the schema

NOTE: please do not skip the tests!

The tests of the schema are under the root directory hazelcast/src/test/resources/com/hazelcast/config/yaml/testcases/. The tests are defined in json files, which are separated into subdirectories of the root:

• the member-only tests are in member/ (run by MemberYamlSchemaTest)
• the client-only tests are in client/ (run by ClientYamlSchemaTest)
• the tests that apply to both member and client config are in common/ (run by both tests)

Each testcase is declared in a json file following this structure:

• the "instance" property defines the actual config (in json format) which will be validated against the schema under test (so the only child of "instance" will be "hazelcast" or "hazelcast-client")
• the "error" defines the validation error expected by the test, to be thrown . This is in json as well The structure of expected errors is documented here, but you won't have to write it by hand. For happy-path tests (where the config should be valid) the "error" should be null (but you shouldn't omit the "error" key)

To add tests to your changes, please

• add a happy-path test json file under the appropriate subdirectory, which means a valid config under "instance", with "error": null
• add at least one failure-path test json by
  • passing an "instance" with a config that fails in as many ways as possible (including basic type errors, unrecognized properties, range failures, etc)
  • initially setting "error": null
  • running the test and verifying that the logged validation error covers every sub-failures you expect
  • copy the logged validation error json into the "error" property of the test json file
  • running the test again to check if it passes

Hazelcast Client config

• ClientConfig
• hazelcast-client-config-x.y.xsd
• hazelcast-config-x.y.json for the client-side changes, as described in the above section
• hazelcast-client-full.[xml&yaml]
• hazelcast-client-full-example.[xml&yaml]
• ClientDomConfigProcessor , YamlClientDomConfigProcessor (only if YAML needs to derive)
• ClientConfigSections (for root client configs)
• AbstractClientConfigBuilderTest
• ClientConfigXmlGenerator and its test ClientConfigXmlGeneratorTest
• FailoverClientConfigSupport and its test FailoverConfigTest

JSON

• check if there is a corresponding JSON DTO, e.g. WanReplicationConfigDTO where the field needs to be added

Hazelcast Spring config

• hazelcast-spring-x.y.xsd
• SpringXmlConfigBuilder, fullConfig-applicationContext-hazelcast.xml and TestFullApplicationContext
  • add under root element to be able to create an instance of the data structure declaratively (see here). If added here, also add in HazelcastNamespaceHandler
  • if you have permissions, also add them to hazelcast-spring-x.y.xsd under client-permissions element.
  • if you have advanced networking changes, also add them to advancedNetworkConfig-applicationContext-hazelcast.xml and TestAdvancedNetworkApplicationContext.

Hazelcast Spring client config

• TestClientApplicationContext
• HazelcastClientBeanDefinitionParser
• node-client-applicationContext-hazelcast.xml
• hazelcast-spring-x.y.xsd