// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= Baseline Topology

:javaFile: {javaCodeDir}/ClusterAPI.java
:csharpFile: {csharpCodeDir}/BaselineTopology.cs

The _baseline topology_ is a set of nodes meant to hold data.
The concept of baseline topology was introduced to give you the ability to control when you want to
link:data-modeling/data-partitioning#rebalancing[rebalance the data in the cluster]. For example, if
you have a cluster of 3 nodes where the data is distributed between the nodes, and you add 2 more nodes, the rebalancing
process re-distributes the data between all 5 nodes. The rebalancing process happens when the
baseline topology changes, which can either happen automatically or be triggered manually.

The baseline topology only includes server nodes; client nodes are never included because they do not store data.

The purpose of the baseline topology is to:

* Avoid unnecessary data transfer when a server node leaves the cluster for a short period of time, for example, due to
occasional network failures or scheduled server maintenance.
* Give you the ability to control when you want to rebalance the data.

Baseline topology changes automatically when <<Baseline Topology Autoadjustment>> is enabled. This is the default
behavior for pure in-memory clusters. For persistent clusters, the baseline topology autoadjustment feature must be enabled
manually. By default, it is disabled and you have to change the baseline topology manually. You can change the baseline
topology using the link:control-script#activation-deactivation-and-topology-management[control script].

[CAUTION]
====
Any attempt to create a cache while the baseline topology is being changed results in an exception.
For more details, see link:key-value-api/basic-cache-operations#creating-caches-dynamically[Creating Caches Dynamically].
====

== Baseline Topology in Pure In-Memory Clusters
In pure in-memory clusters, the default behavior is to adjust the baseline topology to the set of all server nodes
automatically when you add or remove server nodes from the cluster. The data is rebalanced automatically, too.
You can disable the baseline autoadjustment feature and manage baseline topology manually.

NOTE: In previous releases, baseline topology was relevant only to clusters with persistence.
However, since version 2.8.0, it applies to in-memory clusters as well.
If you have a pure in-memory cluster, the transition should be transparent for you because, by default, the baseline topology changes automatically when a server node leaves or joins the cluster.

== Baseline Topology in Persistent Clusters

If your cluster has at least one data region in which persistence is enabled, the cluster is inactive when you start it for the first time.
In the inactive state, all operations are prohibited.
The cluster must be activated before you can create caches and upload data.
Cluster activation sets the current set of server nodes as the baseline topology.
When you restart the cluster, it is activated automatically as soon as all nodes that are registered in the baseline topology join in.
However, if some nodes do not join after a restart, you must to activate the cluster manually.

You can activate the cluster using one of the following tools:

* link:control-script#activating-cluster[Control script]
* link:restapi#change-cluster-state[REST API command]
* Programmatically:
+
[tabs]
--
tab:Java[]

[source, java]
----
include::{javaFile}[tags=activate,indent=0]
----

tab:C#/.NET[]
[source, csharp]
----
include::{csharpFile}[tags=activate,indent=0]
----
tab:C++[]
--

== Baseline Topology Autoadjustment

Instead of changing the baseline topology manually, you can let the cluster do it automatically. This feature is called
Baseline Topology Autoadjustment. When it is enabled, the cluster monitors the state of its server nodes and sets the
baseline on the current topology automatically when the cluster topology is stable for a configurable period of time.

Here is what happens when the set of nodes in the cluster changes:

* The cluster waits for a configurable amount of time (5 min by default).
* If there are no other topology changes during this period, Ignite sets the baseline topology to the current set of nodes.
* If the set of nodes changes during this period, the timeout is updated.

Each change in the set of nodes resets the timeout for autoadjustment.
When the timeout expires and the current set of nodes is different from the baseline topology (for example, new nodes
are present or some old nodes left), Ignite changes the baseline topology to the current set of nodes.
This also triggers data rebalancing.

The autoadjustment timeout allows you to avoid data rebalancing when a node disconnects for a short period due to a
temporary network problem or when you want to quickly restart the node.
You can set the timeout to a higher value if you expect temporary changes in the set of nodes and don't want to change
the baseline topology.

Baseline topology is autoadjusted only if the cluster is in the active state.

To enable automatic baseline adjustment, you can use the
link:control-script#enabling-baseline-topology-autoadjustment[control script] or the
programmatic API methods shown below:

[tabs]
--
tab:Java[]

[source, java]
----
include::{javaFile}[tags=enable-autoadjustment,indent=0]
----

tab:C#/.NET[]
[source, csharp]
----
include::{csharpFile}[tags=enable-autoadjustment,indent=0]
----
tab:C++[]
--


To disable automatic baseline adjustment, use the same method with `false` passed in:


[tabs]
--
tab:Java[]
[source, java]
----
include::{javaFile}[tags=disable-autoadjustment,indent=0]
----

tab:C#/.NET[]
[source, csharp]
----
include::{csharpFile}[tags=disable-autoadjustment,indent=0]
----
tab:C++[]
--


== Monitoring Baseline Topology

You can use the following tools to monitor and/or manage the baseline topology:

* link:control-script[Control Script]
* link:monitoring-metrics/metrics#monitoring-topology[JMX Beans]