ApiOmat Native Module gives you the possbility to create observable, distributed maps based on Hazelcast for your module.

Each map is dedicated to your app and used system. As ID the given name will be used. Key and values of the map can be anything that implements the Serializable interface.

Map handler

The map handler is the "entry point" to get access to map and his methods like registering listener, etc.. Call AOM.getOrCreateDistributedMapHandler(appName, moduleName, mapName) to get an access handler.

Example

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );

Access the map

Map can be accessed via map handler (see above). On map handler you can call getMap().

Example

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
IDistributedMap<String, String> map = mapHandler.getMap();

Add and get values from map

Like maps in Java also the dsitbuted map supports adding and getting of values.

Put a key value pair

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
mapHandler.getMap( ).put( "k", "a value" );

Get value by key

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
String value = mapHandler.getMap( ).get( "k");
TestModule.AOM.log("Value under key 'k' in map 'DistributedMap':" + value );

Furthermore there are more operations that can be done on a map like:

Getting all values: map.values()
Getting values for a set of keys: map.getAll(set_of_keys)
Check if entry with key exists: map.containsKey(k)
Check if entry with value exists: map.containsValue(v)

Removing an entry from map

There are several ways to remove or delete an entry from map.

Remove by key with return of old value

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
String oldValue = mapHandler.getMap( ).remove("k");

Remove by key and value with return of the success status

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
boolean success = mapHandler.getMap( ).remove("k", "a value");

Delete by key without getting old value

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
mapHandler.getMap( ).delete("k");

Clear the complete map

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
mapHandler.getMap( ).clear();

Observe a distributed map

The distributed maps are observable so that you can implement listeners that will be called when sth in the map changes. Be aware that your listeners always will be informed until you remove them explicit.

Listener must be implement the com.apiomat.nativemodule.interfaces.dmap.IDistributedMapListener interface. The following actions can be observed:

Adding an entry (entryAdded(event))
Update on entry (entryUpdated(event))
Removing of entry (entryRemoved(event))
Clearing the map (mapCleared())

Adding a new listener

Adding map listener

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
final String listenerId = mapHandler.addListener( new IDistributedMapListener<String, String>( )
        {
            @Override
            public void entryUpdated( IDistributedMapEntryEvent<String, String> event )
            {
                TestModule.AOM.log( appName, "Entry updated: " + event );
            }
            @Override
            public void entryRemoved( IDistributedMapEntryEvent<String, String> event )
            {
                TestModule.AOM.log( appName, "Entry removed: " + event );
            }
            @Override
            public void entryAdded( IDistributedMapEntryEvent<String, String> event )
            {
                TestModule.AOM.log( appName, "Entry added: " + event );
            }
            @Override
            public void mapCleared( )
            {
                TestModule.AOM.log( appName, "Map was cleared. " );
            }
        } );

Removing a listener

To remove a listener his unique ID must be used:

Remove listener from map

final ADistributedMapHandler<String, String> mapHandler =
            TestModule.AOM.getOrCreateDistributedMapHandler( "TestApp", "TestModule", "DistributedMap" );
mapHandler.removeListener(listenerId);

Working with distributed maps