tpalfy commented on a change in pull request #4510:
URL: https://github.com/apache/nifi/pull/4510#discussion_r487977149
##########
File path:
nifi-api/src/main/java/org/apache/nifi/controller/NodeTypeProvider.java
##########
@@ -34,4 +36,12 @@
* @return true if this instance is the primary node in the cluster; false
otherwise
*/
boolean isPrimary();
+
+ /**
+ * @return In case of the instance is clustered, returns the collection of
the host of the expected members
+ * in the cluster, regardless of their state. This includes the current
host. In case of non-clustered instance
+ * the result will be an empty set.
+ */
Review comment:
```suggestion
* @return Names/IP addresses of all expected hosts in the cluster
(including the current one). For a standalone NiFi this returns an empty set
instead.
*/
```
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services/src/main/java/org/apache/nifi/hazelcast/services/util/LongUtil.java
##########
@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.util;
+
+/**
+ * Helper methods to work with long values effectively.
+ */
+public final class LongUtil {
Review comment:
Any reason why we can't (or shouldn't) use guava's `Longs.toByteArray`
and `Longs.fromByteArray` here?
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services-api/src/main/java/org/apache/nifi/hazelcast/services/cachemanager/HazelcastCacheManager.java
##########
@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.cachemanager;
+
+import org.apache.nifi.controller.ControllerService;
+import org.apache.nifi.hazelcast.services.cache.HazelcastCache;
+
+/**
+ * Controller service responsible for providing cache instances and managing
connection with the Hazelcast server.
+ */
+public interface HazelcastCacheManager extends ControllerService {
+
+ /**
+ * Returns a cache instance maintaining a Hazelcast connection.
+ *
+ * @param name Name of the cache instance. Cache instances having the same
name are depending on the same Hazelcast data structure!
+ * @param ttlInMillis The guaranteed lifetime of a cache entry in
milliseconds. In case of 0, the entry will exists until it's deletion.
+ *
+ * @return Cache instance. Depending on the implementation it is not
guaranteed if it will be a new instance.
Review comment:
```suggestion
* @return Cache instance. Depending on the implementation it is not
guaranteed that it will be a new instance.
```
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services-api/src/main/java/org/apache/nifi/hazelcast/services/cache/HazelcastCache.java
##########
@@ -0,0 +1,120 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.cache;
+
+import java.util.function.Predicate;
+
+/**
+ * Represents a cache storage. The API gives no restriction for the data
structure used or to the Hazelcast setup. There
+ * can be multiple separate cache instances, sharing the same underlying
Hazelcast. The cache instances with the same name
+ * are pointing to the same data structure. It is recommended to use unique
names for the different purposes.
+ */
+public interface HazelcastCache {
+ /**
+ * Serves as identifier for the cache. Defines the underlying data
structure.
+ *
+ * @return The name of the cache.
+ */
+ String name();
+
+ /**
+ * Returns the value of the cache entry defined by the the key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return The serialized value of the cache entry if it exits. The
serialization and deserialization is handled by the client. In case the entry
does not exist, the result is null.
+ */
+ byte[] get(String key);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, it will be overwritten. In case the entry is locked by an other client,
the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. In case the entry
already exists, the new value. The value must not be null. The serialization
and deserialization is handled by the client.
+ *
+ * @return True if the writing was successful.
+ */
+ boolean put(String key, byte[] value);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, no changes will be applied. In case the entry is locked by an other
client, the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. The value must not be
null. The serialization and deserialization is handled by the client.
+ *
+ * @return The serialized value of the cache entry if exists already. Null
otherwise. The serialization and deserialization is handled by the client.
+ */
+ byte[] putIfAbsent(String key, byte[] value);
+
+ /**
+ * Returns true if an entry with the given key exists in the cache.
Returns false otherwise.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if an entry with the given key exists.
+ */
+ boolean contains(String key);
+
+ /**
+ * Removes the entry from the cache with the given key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if the entry existed in the cache before the removal,
false otherwise.
+ */
+ boolean remove(String key);
+
+ /**
+ * Removes all matching entries from the cache. An entry is considered
matching if it's key matches to the provided predicate.
+ *
+ * @param keyMatcher The predicate determines if an entry is matching.
+ *
+ * @return The number of deleted entries.
+ *
+ * Note: the implementation of this method is not necessary atomic.
Because of this, in some cases the number of deleted entries might
+ * not match with the number of matching entries in the moment of calling.
There is no guarantee for that, during the execution of the method a new
matching entry is not added
+ * or an already existing is being deleted.
+ */
+ int removeAll(Predicate<String> keyMatcher);
+
+ /**
+ * Entry lock prevents the entry with the given key from modification by
other clients until releasing the lock (closing the connection will
automatically release the lock).
+ * Non-existing keys might be locked by this way as well. This is not
considered as transaction and other clients might read the value during the
entry is locked. For further
+ * information please check Hazelcast documentation.
+ *
+ * Note: the current implementation of Hazelcast (4.X) also prevents the
modification by the same client but different thread, thus the lock is bounded
to client and thread as well.
Review comment:
```suggestion
* Locks an entry with the given key to prevent its modification by
other clients. Closing the connection automatically releases the lock.
* Non-existing keys might be locked in this way as well. This operation
is not transactional and other clients might read the value while the entry is
locked. For further
* information please check Hazelcast documentation.
*
* Note: the current implementation of Hazelcast (4.X) also prevents
modification by the same client on a different thread.
```
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services/src/test/java/org/apache/nifi/hazelcast/services/DummyStringDeserializer.java
##########
@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services;
+
+import org.apache.nifi.distributed.cache.client.Deserializer;
+import
org.apache.nifi.distributed.cache.client.exception.DeserializationException;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Simple deserializer for testing purposes.
+ */
+public final class DummyStringDeserializer implements Deserializer<String> {
Review comment:
I would consider serialization and deserialization parts of the same
responsibility.
We could merge this with `DummyStringSerializer ` into a single class.
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services-api/src/main/java/org/apache/nifi/hazelcast/services/cache/HazelcastCache.java
##########
@@ -0,0 +1,120 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.cache;
+
+import java.util.function.Predicate;
+
+/**
+ * Represents a cache storage. The API gives no restriction for the data
structure used or to the Hazelcast setup. There
+ * can be multiple separate cache instances, sharing the same underlying
Hazelcast. The cache instances with the same name
+ * are pointing to the same data structure. It is recommended to use unique
names for the different purposes.
+ */
+public interface HazelcastCache {
+ /**
+ * Serves as identifier for the cache. Defines the underlying data
structure.
+ *
+ * @return The name of the cache.
+ */
+ String name();
+
+ /**
+ * Returns the value of the cache entry defined by the the key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return The serialized value of the cache entry if it exits. The
serialization and deserialization is handled by the client. In case the entry
does not exist, the result is null.
+ */
+ byte[] get(String key);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, it will be overwritten. In case the entry is locked by an other client,
the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. In case the entry
already exists, the new value. The value must not be null. The serialization
and deserialization is handled by the client.
+ *
+ * @return True if the writing was successful.
+ */
+ boolean put(String key, byte[] value);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, no changes will be applied. In case the entry is locked by an other
client, the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. The value must not be
null. The serialization and deserialization is handled by the client.
+ *
+ * @return The serialized value of the cache entry if exists already. Null
otherwise. The serialization and deserialization is handled by the client.
+ */
+ byte[] putIfAbsent(String key, byte[] value);
+
+ /**
+ * Returns true if an entry with the given key exists in the cache.
Returns false otherwise.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if an entry with the given key exists.
+ */
+ boolean contains(String key);
+
+ /**
+ * Removes the entry from the cache with the given key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if the entry existed in the cache before the removal,
false otherwise.
+ */
+ boolean remove(String key);
+
+ /**
+ * Removes all matching entries from the cache. An entry is considered
matching if it's key matches to the provided predicate.
Review comment:
```suggestion
* Removes all matching entries from the cache. An entry is considered
matching if its key matches the provided predicate.
```
##########
File path:
nifi-api/src/main/java/org/apache/nifi/controller/NodeTypeProvider.java
##########
@@ -34,4 +36,12 @@
* @return true if this instance is the primary node in the cluster; false
otherwise
*/
boolean isPrimary();
+
+ /**
+ * @return In case of the instance is clustered, returns the collection of
the host of the expected members
+ * in the cluster, regardless of their state. This includes the current
host. In case of non-clustered instance
+ * the result will be an empty set.
+ */
+ Set<String> getClusterMembers();
Review comment:
Not sure if this responsibility belongs to this class. Though I see
there's hardly a better place that is accessible from a controller service...
Maybe we could hide it as much as possible:
```suggestion
default Set<String> getClusterMembers() {
if (!isClustered()) {
return Collections.emptySet();
} else {
throw new IllegalStateException("Clustered environment is not
handled!");
}
}
```
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services-api/src/main/java/org/apache/nifi/hazelcast/services/cache/HazelcastCache.java
##########
@@ -0,0 +1,120 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.cache;
+
+import java.util.function.Predicate;
+
+/**
+ * Represents a cache storage. The API gives no restriction for the data
structure used or to the Hazelcast setup. There
+ * can be multiple separate cache instances, sharing the same underlying
Hazelcast. The cache instances with the same name
+ * are pointing to the same data structure. It is recommended to use unique
names for the different purposes.
+ */
+public interface HazelcastCache {
+ /**
+ * Serves as identifier for the cache. Defines the underlying data
structure.
+ *
+ * @return The name of the cache.
+ */
+ String name();
+
+ /**
+ * Returns the value of the cache entry defined by the the key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return The serialized value of the cache entry if it exits. The
serialization and deserialization is handled by the client. In case the entry
does not exist, the result is null.
+ */
+ byte[] get(String key);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, it will be overwritten. In case the entry is locked by an other client,
the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. In case the entry
already exists, the new value. The value must not be null. The serialization
and deserialization is handled by the client.
+ *
+ * @return True if the writing was successful.
+ */
+ boolean put(String key, byte[] value);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, no changes will be applied. In case the entry is locked by an other
client, the method will wait of return
Review comment:
```suggestion
* Adds a new entry to the cache under the given key. If the entry
already exists, no changes will be applied. In case the entry is locked by an
other client, the method will wait or return
```
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services-api/src/main/java/org/apache/nifi/hazelcast/services/cache/HazelcastCache.java
##########
@@ -0,0 +1,120 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.cache;
+
+import java.util.function.Predicate;
+
+/**
+ * Represents a cache storage. The API gives no restriction for the data
structure used or to the Hazelcast setup. There
+ * can be multiple separate cache instances, sharing the same underlying
Hazelcast. The cache instances with the same name
+ * are pointing to the same data structure. It is recommended to use unique
names for the different purposes.
+ */
+public interface HazelcastCache {
+ /**
+ * Serves as identifier for the cache. Defines the underlying data
structure.
+ *
+ * @return The name of the cache.
+ */
+ String name();
+
+ /**
+ * Returns the value of the cache entry defined by the the key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return The serialized value of the cache entry if it exits. The
serialization and deserialization is handled by the client. In case the entry
does not exist, the result is null.
+ */
+ byte[] get(String key);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, it will be overwritten. In case the entry is locked by an other client,
the method will wait of return
Review comment:
```suggestion
* Adds a new entry to the cache under the given key. If the entry
already exists, it will be overwritten. In case the entry is locked by an other
client, the method will wait or return
```
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services-api/src/main/java/org/apache/nifi/hazelcast/services/cache/HazelcastCache.java
##########
@@ -0,0 +1,120 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.cache;
+
+import java.util.function.Predicate;
+
+/**
+ * Represents a cache storage. The API gives no restriction for the data
structure used or to the Hazelcast setup. There
+ * can be multiple separate cache instances, sharing the same underlying
Hazelcast. The cache instances with the same name
+ * are pointing to the same data structure. It is recommended to use unique
names for the different purposes.
+ */
+public interface HazelcastCache {
+ /**
+ * Serves as identifier for the cache. Defines the underlying data
structure.
+ *
+ * @return The name of the cache.
+ */
+ String name();
+
+ /**
+ * Returns the value of the cache entry defined by the the key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return The serialized value of the cache entry if it exits. The
serialization and deserialization is handled by the client. In case the entry
does not exist, the result is null.
+ */
+ byte[] get(String key);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, it will be overwritten. In case the entry is locked by an other client,
the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. In case the entry
already exists, the new value. The value must not be null. The serialization
and deserialization is handled by the client.
+ *
+ * @return True if the writing was successful.
+ */
+ boolean put(String key, byte[] value);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, no changes will be applied. In case the entry is locked by an other
client, the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. The value must not be
null. The serialization and deserialization is handled by the client.
+ *
+ * @return The serialized value of the cache entry if exists already. Null
otherwise. The serialization and deserialization is handled by the client.
+ */
+ byte[] putIfAbsent(String key, byte[] value);
+
+ /**
+ * Returns true if an entry with the given key exists in the cache.
Returns false otherwise.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if an entry with the given key exists.
+ */
+ boolean contains(String key);
+
+ /**
+ * Removes the entry from the cache with the given key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if the entry existed in the cache before the removal,
false otherwise.
+ */
+ boolean remove(String key);
+
+ /**
+ * Removes all matching entries from the cache. An entry is considered
matching if it's key matches to the provided predicate.
+ *
+ * @param keyMatcher The predicate determines if an entry is matching.
+ *
+ * @return The number of deleted entries.
+ *
+ * Note: the implementation of this method is not necessary atomic.
Because of this, in some cases the number of deleted entries might
+ * not match with the number of matching entries in the moment of calling.
There is no guarantee for that, during the execution of the method a new
matching entry is not added
+ * or an already existing is being deleted.
+ */
Review comment:
```suggestion
* Note: the implementation of this method is not necessarily atomic.
Because of this, in some cases the number of deleted entries might
* not be equal to the number of matching entries at the moment of
calling. There is no guarantee that during the execution of the method a new
matching entry is not added
* or an already existing is not deleted.
*/
```
##########
File path:
nifi-nar-bundles/nifi-hazelcast-bundle/nifi-hazelcast-services-api/src/main/java/org/apache/nifi/hazelcast/services/cache/HazelcastCache.java
##########
@@ -0,0 +1,120 @@
+/*
+ * 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.
+ */
+package org.apache.nifi.hazelcast.services.cache;
+
+import java.util.function.Predicate;
+
+/**
+ * Represents a cache storage. The API gives no restriction for the data
structure used or to the Hazelcast setup. There
+ * can be multiple separate cache instances, sharing the same underlying
Hazelcast. The cache instances with the same name
+ * are pointing to the same data structure. It is recommended to use unique
names for the different purposes.
+ */
+public interface HazelcastCache {
+ /**
+ * Serves as identifier for the cache. Defines the underlying data
structure.
+ *
+ * @return The name of the cache.
+ */
+ String name();
+
+ /**
+ * Returns the value of the cache entry defined by the the key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return The serialized value of the cache entry if it exits. The
serialization and deserialization is handled by the client. In case the entry
does not exist, the result is null.
+ */
+ byte[] get(String key);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, it will be overwritten. In case the entry is locked by an other client,
the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. In case the entry
already exists, the new value. The value must not be null. The serialization
and deserialization is handled by the client.
+ *
+ * @return True if the writing was successful.
+ */
+ boolean put(String key, byte[] value);
+
+ /**
+ * Adds a new entry to the cache under the given key. If the entry already
exists, no changes will be applied. In case the entry is locked by an other
client, the method will wait of return
+ * with false depending on the implementation.
+ *
+ * @param key Key of the entry, must not be null.
+ * @param value The serialized value of the entry. The value must not be
null. The serialization and deserialization is handled by the client.
+ *
+ * @return The serialized value of the cache entry if exists already. Null
otherwise. The serialization and deserialization is handled by the client.
+ */
+ byte[] putIfAbsent(String key, byte[] value);
+
+ /**
+ * Returns true if an entry with the given key exists in the cache.
Returns false otherwise.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if an entry with the given key exists.
+ */
+ boolean contains(String key);
+
+ /**
+ * Removes the entry from the cache with the given key.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return True if the entry existed in the cache before the removal,
false otherwise.
+ */
+ boolean remove(String key);
+
+ /**
+ * Removes all matching entries from the cache. An entry is considered
matching if it's key matches to the provided predicate.
+ *
+ * @param keyMatcher The predicate determines if an entry is matching.
+ *
+ * @return The number of deleted entries.
+ *
+ * Note: the implementation of this method is not necessary atomic.
Because of this, in some cases the number of deleted entries might
+ * not match with the number of matching entries in the moment of calling.
There is no guarantee for that, during the execution of the method a new
matching entry is not added
+ * or an already existing is being deleted.
+ */
+ int removeAll(Predicate<String> keyMatcher);
+
+ /**
+ * Entry lock prevents the entry with the given key from modification by
other clients until releasing the lock (closing the connection will
automatically release the lock).
+ * Non-existing keys might be locked by this way as well. This is not
considered as transaction and other clients might read the value during the
entry is locked. For further
+ * information please check Hazelcast documentation.
+ *
+ * Note: the current implementation of Hazelcast (4.X) also prevents the
modification by the same client but different thread, thus the lock is bounded
to client and thread as well.
+ *
+ * @param key Key of the entry, must not be null.
+ *
+ * @return The entry lock instance.
+ */
+ HazelcastCacheEntryLock acquireLock(String key);
+
+ /**
+ * Represents a lock on a given entry based on key. The lock is bounded to
a cache and does not allow other caches to modify the entry in any manner until
it is released. Calling close
+ * on the instance will release the lock if not already released.
Review comment:
```suggestion
Represents a lock on a given entry based on key. The lock is bound to a
cache and does not allow other clients(? not sure - otherwise not sure what
this should mean) to modify the entry in any manner until it is released.
Calling close
* on the instance will release the lock if not already released.
```
Not sure in this case what "instance" refers to. The
`HazelcastCacheEntryLock` instance? If so how else can one release the lock?
(There is no "releaseLock" method here.)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
