HazelcastAPI IMap Arayüzü

Giriş

Şu satırı dahil ederiz

import com.hazelcast.IMap;

ConcurrentMap ve dolayısıyla Map arayüzünden kalıtır. Açıklaması şöyle

The distributed map implementation has a method to lock a specific key. If the lock is not available, the current thread is blocked until the lock has been released. We can get a lock on the key even if it is not present in the map. If the key does not exist in the map, any thread apart from the lock owner will get blocked if it tries to put the locked key in the map.

Veri Nasıl Dağıtılır

Soru ve cevap şöyle. Dolayısıyla keySet() ve localKeySet() farklı şeyler yaparlar

Q : Does each member in the Hazelcast cluster maintain the information about the set of all keys in a given map or only about the subset of those keys in the partition(s) that it owns ?

A: Members do not maintain a global key set. Each member is aware of local entries only. Hence keySet() is a distributed operation hitting all members while localKeySet() is just a local operation.

External Data Store

IMap bellekte saklanır ancak veri tabanından okuma ve veri tabanına yazma imkanı da sağlar.

- To load data from external systems in a map you will use the Java MapLoader interface.
- To save map entries to an external system, you will use the Java MapStore interface.

Veri tabanından okuma ve ver tabanına yazma için MapStore Arayüzü yazısına bakabilirsiniz

Bazı IMap metodları Java metodlarındaki imzaları karşılamak için gereksiz MapStore/MapLoader çağrıları yapıyor. Bunlardan kaçınmak için IMap farklı metodlar sunuyor. Bunlar şöyle

IMap.remove() -> IMap.delete()
IMap.put() ->  IMap.putTransient()
IMap.containsKey() -> ?

Operation Objects

Açıklaması şöyle

Almost every operation on IMap is encapsulated into one of operation objects (see also: Command pattern). This operation is later dispatched to one or all cluster members and executed remotely in a separate thread pool, or even on a different machine.

PutOperation

DistributedObjectDestroyOperation : map.destroy() ile çağrılır

MapFetchEntriesOperation - Operation for fetching a chunk of entries from a single IMap partition

Transactional Operation Step Objects

Bir transaction içinde IMap'e yapılan adımlar (step)

Bunlar IMapOpStep arayüzünden kalıtıyor

TxnLockAndGetOpSteps

Kullanım

Örnek

Şöyle yaparız

HazelcastInstance hazelcastInstance = ...;
ConcurrentMap<String, String> nameByEmailMap = hazelcastInstance.getMap("nameByEmail");

Açıklaması şöyle

In the fragment above, we are using Hazelcast's Distributed Map, which is presented and used in the code as ConcurrentMap. This gives a simple and flexible way to work with cached data as with simple map. All the heavy lifting to distribute cached data throughout the cluster Hazelcast performs behind the scenes. So, the usage of the cache as a map is fully transparent for developers.

Örnek

Şöyle yaparız. Spring ile JSON kullanmak için özel bir ayar yapmadıysak, Key ve Value nesnelerinin Serializable olması gerekir.

public class Doctor implements Serializable {
  ...
}

@Bean
public Map<String, Doctor> doctorMap(HazelcastInstance hazelcastInstance) {
  return hazelcastInstance.getMap("doctorMap");
}

@Autowired
private Map<String, Doctor> doctorMap;

@GetMapping(path = { "/get/{doctorNumber}" })
public Doctor getDoctor(@PathVariable("doctorNumber") String doctorNumber) {
  //First call is to check if doctormap has doctor details if yes,
  //return the value otherwise call database.
  Doctor doctor = doctorMap.get(doctorNumber);
  if (doctor == null){
    doctor = ...; 
  }
  return doctor;
}

@PostMapping("/add")
public void createDoctor(@RequestBody Doctor doctor) {
  //save doctor details in cache
  doctorMap.put(doctor.getDoctorNumber(), doctor);
  ...
}
@DeleteMapping(path = { "/delete/{doctorNumber}" })
public Doctor deleteDoctor(@PathVariable("doctorNumber") String doctorNumber) {
  //remove doctor details from both cache and database
  doctorMap.remove(doctorNumber);
  ...
}

constructor

HazelcastInstance.getMap() tarafından döndürülür

Örnek

Şöyle yaparız

IMap<String, String> map = hazelcastInstance.getMap("my-map");

addEntryListener metodu

EntryListener nesnesi ekler. addEntryListener() yerine EntryListenerConfig kullanılabilir

addIndex metodu

addIndex metodu yazısına taşıdım

addInterceptor metodu

MapInterceptor nesnesi ekler

addLocalEntryListener metodu

addEntryListener metodu gibidir. Farklı olarak EntryListener bu member'da sadece kendi sahibi olduğu key değerler için tetiklenir. 

deleteAsync metodu

İmzası şöyle. Belirtilen key değerini asenkron olarak siler

CompletionStage<Boolean> deleteAsync(K key);

destroy metodu

Map'i siler

Örnek

Şöyle yaparız

instance.getMap(mapName).destroy();

executeOnEntries metodu

Açıklaması şöyle

When using the executeOnEntries method, if the number of entries is high and you do not need the results, then returning null with the process() method is a good practice. This method is offered by the EntryProcessor interface. By returning null, results of the processing are not collected and thus out of memory errors are eliminated.

Örnek

Şöyle yaparız

HazelcastInstance instance = Hazelcast.newHazelcastInstance();

IMap<Integer, String> map = instance.getMap("test");
map.set(1, "a");
map.set(2, "b");
map.set(3, "c");
//Result map does not have key = 1
Map<Integer, String> result = map.executeOnEntries(
  entry -> entry.getKey() > 1 ? entry.getValue() : null);

get metodu

Örnek

Şöyle yaparız

public String getDataByKey(String key) {
  IMap<String, String> map = hazelcastInstance.getMap("my-map");
  return map.get(key);
}

getAsync metodu

İmzası şöyle

CompletionStage<V> getAsync(K key);

Hemen value değerini döndürmez. Açıklaması şöyle

It may or may not be executed before calling future.get(), but it will block and will get the result when you call it if the result is still not there.

 Şöyle yaparız

CompletionStage future = map.getAsync(key);
// do some other stuff, when ready get the result.
Object value = future.toCompletableFuture().get();

getEntryView metodu

EntryView döner

keySet metodu - com.hazelcast.query.Predicate

Açıklaması şöyle

Predicate API doesn't support joins at all

Örnek

Şöyle yaparız

map.keySet(Predicates.equal(...));

localKeySet metodu

ClientMapProxy bu metod için exception fırlatıyor. 

MapProxyImpl ise bu member'daki keyset nesnesini döndürür

lock metodu - key

Sadece belirtilen key'in olduğu partition kilitlenir. Yani dağıtık bir lock değildir

Örnek

Şöyle yaparız

import com.hazelcast.core.Hazelcast;
import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.core.IMap;

HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance();
IMap txLockMap = hazelcast.getMap("txLockMap");
String lock = "...";
txLockMap.lock(key);

try {
  txLockMap.tryLock(key,10,TimeUnit.SECONDS);
} catch (Exception e){
  ...
}

txLockMap.isLocked(key);

try {
  txLockMap.unlock(key);
} catch (Exception e){
  ...
}

put metodu

Açıklaması şöyle

IMap.put and other modifying operations return success in case of backup timeout (hazelcast.operation.backup.timeout.millis) even if synchronous backup is configured for IMap. This is by design and described in the documentation.

Örnek

Şöyle yaparız

public String createData(String key, String value) {
  IMap<String, String> map = hazelcastInstance.getMap("my-map");
  map.put(key, value);
  return "Data is stored.";
}

putAll metodu

İmzası şöyle. Belitilen map nesnesinin tamamını IMap nesnesin ekler

void putAll(Map<? extends K, ? extends V> m);

Örnek

Şöyle yaparız

Map<Integer, Integer> entriesToAdd = new HashMap<>();

// Populate data structures
Random random = new Random();
IntStream.range(0, maxValue)
  .forEach(i -> {
    int value = random.nextInt();
    entriesToAdd.put(i, value);
  });
// Populate IMap
IMap<Integer, Integer> map = hz.getMap("map");
map.putAll(entriesToAdd);

putIfAbsent metodu

Örnek

Şöyle yaparız

HazelcastInstance hz = Hazelcast.newHazelcastInstance();
ConcurrentMap<String,String> map = hz.getMap("my-map");
map.put("key","value");
String value = map.get("key");
map.putIfAbsent("somekey","somevalue");
map.replace("key","value","newvalue");

putTransient metodu

İmzası şöyle

void putTransient(K key, V value, long ttl, TimeUnit ttlUnit);
void putTransient(K key, V value, long ttl, TimeUnit ttlUnit, long maxIdle, 
  TimeUnit maxIdleUnit);

Birinci metod, belirtilen TTL kadar yaşayan bir key-value çiftini ekler. TTL en son yazma zamanını temel alır. TTL 0 ise bu çift bayatlamaz. Eksi bir değerse, MapConfiguration'da belirtilen değer kadar yaşar. Varsayılan değer 0 yani sonsuzdur. 

İkinci metod TTL yanında bir de maxIdle tanımlama imkanı tanıyor. maxIdle TTL gibidir ancak hem yazma hem de okuma zamanını temel alır. Buna göre key-value çiftinin bayatlaması hesaplanır

remove metodu

Örnek

Şöyle yaparız

public String deleteData(String key) {
  IMap<String, String> map = hazelcastInstance.getMap("my-map");
  return map.remove(key);
}

removeEntryListener metodu

İmzası şöyle

boolean removeEntryListener(UUID id);

addEntryListener() çağrısı sonucunda yeni eklenen listener için bir UUID döndürülür. Bu UUID ile listener silinebilir.

Örnek

Şöyle yaparız

IMap map = inst.getMap("map1");
UUID mapRegistrationId = map1.addEntryListener(...);
...
map.removeEntryListener(mapRegistrationId);

set metodu

Örnek

Şöyle yaparız

public String update(String key, String value) {
  IMap<String, String> map = hazelcastInstance.getMap("my-map");
  map.set(key, value);
  return "Data is stored.";
}

setAsync metodu

put() metodu gibidir. Belirtilen key ve value değerini asenkron olarak işler

values

İki tane metod var. Her ikisi de sonuçları heap te saklar

Collection<V> values();
Collection<V> values(@Nonnull Predicate<K, V> predicate);