com.hazelcast.crdt.pncounter.PNCounter Maven / Gradle / Ivy
/*
* Copyright (c) 2008-2024, Hazelcast, Inc. All Rights Reserved.
*
* Licensed 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.
*/
package com.hazelcast.crdt.pncounter;
import com.hazelcast.core.ConsistencyLostException;
import com.hazelcast.core.DistributedObject;
import com.hazelcast.partition.NoDataMemberInClusterException;
/**
* PN (Positive-Negative) CRDT counter.
*
* The counter supports adding and subtracting values as well as
* retrieving the current counter value.
* Each replica of this counter can perform operations locally without
* coordination with the other replicas, thus increasing availability.
* The counter guarantees that whenever two nodes have received the
* same set of updates, possibly in a different order, their state is
* identical, and any conflicting updates are merged automatically.
* If no new updates are made to the shared state, all nodes that can
* communicate will eventually have the same data.
*
* The updates to this counter are applied locally when invoked on a
* CRDT replica. A replica can be any hazelcast instance which is not a
* client or a lite member. The number of replicas in the cluster is
* determined in the server-side PN counter configuration.
*
* When invoking updates from non-replica instance, the invocation is remote.
* This may lead to indeterminate state - the update may be applied but the
* response has not been received. In this case, the caller will be notified
* with a {@link com.hazelcast.spi.exception.TargetDisconnectedException}
* when invoking from a client or a
* {@link com.hazelcast.core.MemberLeftException} when invoked from a member.
*
* The read and write methods provide monotonic read and RYW (read-your-write)
* guarantees. These guarantees are session guarantees which means that if
* no replica with the previously observed state is reachable, the session
* guarantees are lost and the method invocation will throw a
* {@link ConsistencyLostException}. This does not mean
* that an update is lost. All the updates are part of some replica and
* will be eventually reflected in the state of all other replicas. This
* exception just means that you cannot observe your own writes because
* all replicas that contain your updates are currently unreachable.
* After you have received a {@link ConsistencyLostException}, you can either
* wait for a sufficiently up-to-date replica to become reachable in which
* case the session can be continued, or you can reset the session by calling
* the {@link #reset()} method. If you have called the {@link #reset()} method,
* a new session is started with the next invocation to a CRDT replica.
*
* If the PN Counter is used through a client, the invocations might throw
* {@link com.hazelcast.spi.exception.TargetNotMemberException}, indicating that
* the invocation targets are not members of the cluster anymore. That might
* happen when the client is connected to a new cluster, but the member list is
* not updated yet, or all the replica members of the PN Counter is dead but
* the corresponding member list update is not received yet. Upon receiving
* the exception, one has to wait until the member list is updated on the
* client side and try again.
*
* NOTE:
* The CRDT state is kept entirely on non-lite (data) members. If there
* aren't any and the methods here are invoked on a lite member, they will
* fail with an {@link NoDataMemberInClusterException}.
*
* @since 3.10
*/
public interface PNCounter extends DistributedObject {
/**
* Returns the current value of the counter.
*
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long get();
/**
* Adds the given value to the current value.
*
* @param delta the value to add
* @return the previous value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long getAndAdd(long delta);
/**
* Adds the given value to the current value.
*
* @param delta the value to add
* @return the updated value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long addAndGet(long delta);
/**
* Subtracts the given value from the current value.
*
* @param delta the value to add
* @return the previous value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long getAndSubtract(long delta);
/**
* Subtracts the given value from the current value.
*
* @param delta the value to subtract
* @return the updated value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long subtractAndGet(long delta);
/**
* Decrements by one the current value.
*
* @return the updated value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long decrementAndGet();
/**
* Increments by one the current value.
*
* @return the updated value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long incrementAndGet();
/**
* Decrements by one the current value.
*
* @return the previous value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long getAndDecrement();
/**
* Increments by one the current value.
*
* @return the previous value
* @throws NoDataMemberInClusterException if the cluster does not contain
* any data members
* @throws ConsistencyLostException if the session guarantees have
* been lost (see class level javadoc)
*/
long getAndIncrement();
/**
* Resets the observed state by this PN counter. This method may be used
* after a method invocation has thrown a {@link ConsistencyLostException}
* to reset the proxy and to be able to start a new session.
*/
void reset();
}