CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-hazelcast--hazelcast

In-memory distributed computing platform for real-time stream processing and data storage with SQL capabilities

—

Pending
Overview
Eval results
Files

core-api.mddocs/

Core API and Instance Management

The Hazelcast Core API provides the fundamental interfaces for creating and managing Hazelcast instances, accessing distributed objects, and controlling the instance lifecycle.

Main Entry Point

HazelcastInstance Interface

import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.core.DistributedObject;
import com.hazelcast.config.Config;
import com.hazelcast.cluster.Cluster;
import com.hazelcast.partition.PartitionService;

public interface HazelcastInstance {
    // Instance information
    String getName();
    Config getConfig();
    
    // Distributed objects access
    <K, V> IMap<K, V> getMap(String name);
    <E> IQueue<E> getQueue(String name);
    <E> IList<E> getList(String name);
    <E> ISet<E> getSet(String name);
    <K, V> MultiMap<K, V> getMultiMap(String name);
    <K, V> ReplicatedMap<K, V> getReplicatedMap(String name);
    <E> ITopic<E> getTopic(String name);
    <E> ITopic<E> getReliableTopic(String name);
    <E> Ringbuffer<E> getRingbuffer(String name);
    
    // Executor services
    IExecutorService getExecutorService(String name);
    DurableExecutorService getDurableExecutorService(String name);
    IScheduledExecutorService getScheduledExecutorService(String name);
    
    // Specialized data structures
    FlakeIdGenerator getFlakeIdGenerator(String name);
    CardinalityEstimator getCardinalityEstimator(String name);
    PNCounter getPNCounter(String name);
    
    // Services
    CPSubsystem getCPSubsystem();
    SqlService getSql();
    JetService getJet();
    Cluster getCluster();
    PartitionService getPartitionService();
    LifecycleService getLifecycleService();
    ClientService getClientService();
    LoggingService getLoggingService();
    SplitBrainProtectionService getSplitBrainProtectionService();
    
    // Cache management
    ICacheManager getCacheManager();
    
    // Transaction support
    TransactionContext newTransactionContext();
    TransactionContext newTransactionContext(TransactionOptions options);
    <T> T executeTransaction(TransactionalTask<T> task);
    <T> T executeTransaction(TransactionOptions options, TransactionalTask<T> task);
    
    // Distributed object management
    Collection<DistributedObject> getDistributedObjects();
    <T extends DistributedObject> T getDistributedObject(String serviceName, String name);
    UUID addDistributedObjectListener(DistributedObjectListener distributedObjectListener);
    boolean removeDistributedObjectListener(UUID registrationId);
    
    // Local endpoint and context
    Endpoint getLocalEndpoint();
    ConcurrentMap<String, Object> getUserContext();
    
    // XA Transaction support
    HazelcastXAResource getXAResource();
    
    // Lifecycle
    void shutdown();
}

Factory Methods

Server Instance Factory

import com.hazelcast.core.Hazelcast;
import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.config.Config;
import java.util.Set;

public class Hazelcast {
    // Create new instance
    public static HazelcastInstance newHazelcastInstance();
    public static HazelcastInstance newHazelcastInstance(Config config);
    
    // Get existing instances
    public static HazelcastInstance getHazelcastInstanceByName(String instanceName);
    public static HazelcastInstance getOrCreateHazelcastInstance(Config config);
    public static Set<HazelcastInstance> getAllHazelcastInstances();
    
    // For Jet jobs
    public static HazelcastInstance bootstrappedInstance();
    
    // Shutdown operations
    public static void shutdownAll();
    
    // Memory management
    public static void setOutOfMemoryHandler(OutOfMemoryHandler outOfMemoryHandler);
}

Client Factory

import com.hazelcast.client.HazelcastClient;
import com.hazelcast.client.config.ClientConfig;
import com.hazelcast.client.config.ClientFailoverConfig;
import java.util.Collection;

public class HazelcastClient {
    // Create new client
    public static HazelcastInstance newHazelcastClient();
    public static HazelcastInstance newHazelcastClient(ClientConfig config);
    
    // Failover client
    public static HazelcastInstance newHazelcastFailoverClient();
    public static HazelcastInstance newHazelcastFailoverClient(ClientFailoverConfig clientFailoverConfig);
    
    // Get existing clients
    public static HazelcastInstance getHazelcastClientByName(String instanceName);
    public static HazelcastInstance getOrCreateHazelcastClient(ClientConfig config);
    public static Collection<HazelcastInstance> getAllHazelcastClients();
    
    // Shutdown operations
    public static void shutdownAll();
    public static void shutdown(HazelcastInstance instance);
    
    // Memory management  
    public static void setOutOfMemoryHandler(OutOfMemoryHandler outOfMemoryHandler);
}

Instance Creation Examples

Basic Server Instance

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

// Default configuration
HazelcastInstance hz = Hazelcast.newHazelcastInstance();

// Named instance
Config config = new Config();
config.setInstanceName("my-hazelcast-instance");
HazelcastInstance namedHz = Hazelcast.newHazelcastInstance(config);

// Get existing instance
HazelcastInstance existing = Hazelcast.getHazelcastInstanceByName("my-hazelcast-instance");

Basic Client Instance

import com.hazelcast.client.HazelcastClient;
import com.hazelcast.client.config.ClientConfig;

// Default client configuration
HazelcastInstance client = HazelcastClient.newHazelcastClient();

// Custom client configuration
ClientConfig clientConfig = new ClientConfig();
clientConfig.setInstanceName("my-client");
clientConfig.getNetworkConfig().addAddress("192.168.1.100:5701", "192.168.1.101:5701");
HazelcastInstance customClient = HazelcastClient.newHazelcastClient(clientConfig);

Programmatic Configuration

import com.hazelcast.config.Config;
import com.hazelcast.config.MapConfig;
import com.hazelcast.config.NetworkConfig;

Config config = new Config();

// Instance settings
config.setInstanceName("production-cluster");
config.setClusterName("prod");

// Map configuration
MapConfig mapConfig = new MapConfig("user-sessions");
mapConfig.setBackupCount(2);
mapConfig.setTimeToLiveSeconds(1800); // 30 minutes
config.addMapConfig(mapConfig);

// Network configuration
NetworkConfig networkConfig = config.getNetworkConfig();
networkConfig.setPort(5701);
networkConfig.setPortAutoIncrement(true);
networkConfig.setPortCount(20);

HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);

Distributed Object Management

Base Interface

import com.hazelcast.core.DistributedObject;

public interface DistributedObject {
    String getName();
    String getServiceName();
    String getPartitionKey();
    void destroy();
}

Accessing Distributed Objects

// Maps
IMap<String, User> userMap = hz.getMap("users");
IMap<Long, Order> orderMap = hz.getMap("orders");

// Collections
IQueue<Task> taskQueue = hz.getQueue("tasks");
IList<String> messages = hz.getList("messages");
ISet<String> uniqueItems = hz.getSet("unique-items");

// Topics
ITopic<String> notifications = hz.getTopic("notifications");
ITopic<Event> events = hz.getReliableTopic("events");

// Specialized structures
FlakeIdGenerator idGen = hz.getFlakeIdGenerator("user-ids");
CardinalityEstimator estimator = hz.getCardinalityEstimator("page-views");
PNCounter counter = hz.getPNCounter("global-counter");

Lifecycle Management

LifecycleService Interface

import com.hazelcast.core.LifecycleService;
import com.hazelcast.core.LifecycleListener;
import com.hazelcast.core.LifecycleEvent;
import java.util.UUID;

public interface LifecycleService {
    boolean isRunning();
    UUID addLifecycleListener(LifecycleListener lifecycleListener);
    boolean removeLifecycleListener(UUID registrationId);
    void shutdown();
    void terminate();
}

LifecycleListener Interface

public interface LifecycleListener {
    void stateChanged(LifecycleEvent event);
}

public class LifecycleEvent {
    public enum LifecycleState {
        STARTING, STARTED, SHUTTING_DOWN, SHUTDOWN, MERGING, MERGED, 
        CLIENT_CONNECTED, CLIENT_DISCONNECTED
    }
    
    public LifecycleState getState();
    public HazelcastInstance getSource();
}

Lifecycle Management Example

LifecycleService lifecycle = hz.getLifecycleService();

// Add lifecycle listener
UUID listenerId = lifecycle.addLifecycleListener(new LifecycleListener() {
    @Override
    public void stateChanged(LifecycleEvent event) {
        System.out.println("Lifecycle state changed: " + event.getState());
        
        switch (event.getState()) {
            case STARTED:
                System.out.println("Instance started successfully");
                break;
            case SHUTTING_DOWN:
                System.out.println("Instance is shutting down");
                break;
            case SHUTDOWN:
                System.out.println("Instance has shut down");
                break;
        }
    }
});

// Check if running
if (lifecycle.isRunning()) {
    System.out.println("Instance is running");
}

// Graceful shutdown
lifecycle.shutdown();

// Remove listener
lifecycle.removeLifecycleListener(listenerId);

Exception Handling

Core Exceptions

import com.hazelcast.core.HazelcastException;
import com.hazelcast.core.HazelcastInstanceNotActiveException;
import com.hazelcast.core.HazelcastOverloadException;
import com.hazelcast.core.OperationTimeoutException;
import com.hazelcast.core.MemberLeftException;
import com.hazelcast.core.ConsistencyLostException;

// Base exception
public class HazelcastException extends RuntimeException {
    public HazelcastException(String message);
    public HazelcastException(String message, Throwable cause);
}

// Specific exceptions
public class HazelcastInstanceNotActiveException extends IllegalStateException {}
public class HazelcastOverloadException extends HazelcastException {}
public class OperationTimeoutException extends HazelcastException {}
public class MemberLeftException extends HazelcastException {}
public class ConsistencyLostException extends HazelcastException {}

Exception Handling Example

try {
    HazelcastInstance hz = Hazelcast.newHazelcastInstance();
    IMap<String, String> map = hz.getMap("test");
    
    String result = map.get("key");
    
} catch (HazelcastInstanceNotActiveException e) {
    System.err.println("Instance is not active: " + e.getMessage());
} catch (OperationTimeoutException e) {
    System.err.println("Operation timed out: " + e.getMessage());
} catch (HazelcastException e) {
    System.err.println("Hazelcast operation failed: " + e.getMessage());
}

Utility Interfaces

Execution Callbacks

import com.hazelcast.core.ExecutionCallback;
import com.hazelcast.core.MultiExecutionCallback;
import java.util.Map;

public interface ExecutionCallback<V> {
    void onResponse(V response);
    void onFailure(Throwable t);
}

public interface MultiExecutionCallback {
    void onResponse(Member member, Object value);
    void onComplete(Map<Member, Object> values);
}

Function Interface

import com.hazelcast.core.IFunction;
import java.io.Serializable;

public interface IFunction<E, R> extends Serializable {
    R apply(E input);
}

Service Interfaces

Client Service

import com.hazelcast.client.ClientService;
import com.hazelcast.client.Client;
import java.util.Collection;

public interface ClientService {
    Collection<Client> getConnectedClients();
    void addClientListener(ClientListener clientListener);
    void removeClientListener(ClientListener clientListener);
}

public interface Client extends Endpoint {
    String getUuid();
    String getName();  
    String getClientType();
    InetSocketAddress getSocketAddress();
}

public interface ClientListener {
    void clientConnected(Client client);
    void clientDisconnected(Client client);
}

Logging Service

import com.hazelcast.logging.LoggingService;
import com.hazelcast.logging.LogListener;
import com.hazelcast.logging.LogEvent;

public interface LoggingService {
    void addLogListener(Level level, LogListener logListener);
    void removeLogListener(LogListener logListener);
}

public interface LogListener {
    void log(LogEvent logEvent);
}

public class LogEvent {
    public LogRecord getLogRecord();
    public Member getMember();
}

Split Brain Protection Service

import com.hazelcast.splitbrainprotection.SplitBrainProtectionService;
import com.hazelcast.splitbrainprotection.SplitBrainProtection;

public interface SplitBrainProtectionService {
    SplitBrainProtection getSplitBrainProtection(String splitBrainProtectionName);
}

public interface SplitBrainProtection {
    String getName();
    boolean isPresent();
    int getSize();
}

Transaction Support Types

import com.hazelcast.transaction.TransactionContext;
import com.hazelcast.transaction.TransactionOptions;
import com.hazelcast.transaction.TransactionalTask;
import com.hazelcast.transaction.HazelcastXAResource;

public interface TransactionContext {
    void beginTransaction();
    void commitTransaction();
    void rollbackTransaction();
    String getTxnId();
    TransactionOptions getTransactionOptions();
    
    // Transactional data structures
    <K, V> TransactionalMap<K, V> getMap(String name);
    <E> TransactionalQueue<E> getQueue(String name);
    <E> TransactionalList<E> getList(String name);
    <E> TransactionalSet<E> getSet(String name);
    <K, V> TransactionalMultiMap<K, V> getMultiMap(String name);
}

public class TransactionOptions {
    public static final TransactionOptions DEFAULT = new TransactionOptions();
    
    public TransactionOptions setTimeout(long timeout, TimeUnit timeUnit);
    public TransactionOptions setTransactionType(TransactionType transactionType);
    public long getTimeoutMillis();
    public TransactionType getTransactionType();
}

public interface TransactionalTask<T> extends Serializable {
    T execute(TransactionContext context) throws TransactionException;
}

public interface HazelcastXAResource extends XAResource {
    void clearContext();
    TransactionContext getTransactionContext();
}

Distributed Object Support

import com.hazelcast.core.DistributedObjectListener;
import com.hazelcast.core.DistributedObjectEvent;
import com.hazelcast.cluster.Endpoint;

public interface DistributedObjectListener extends EventListener {
    void distributedObjectCreated(DistributedObjectEvent event);
    void distributedObjectDestroyed(DistributedObjectEvent event);
}

public class DistributedObjectEvent {
    public enum EventType { CREATED, DESTROYED }
    
    public String getObjectName();
    public String getServiceName();
    public EventType getEventType();
    public Member getMember();
}

public interface Endpoint {
    UUID getUuid();
    InetSocketAddress getSocketAddress();
    Map<String, String> getAttributes();
}

Best Practices

Instance Management

// Use try-with-resources pattern for automatic cleanup
public class HazelcastManager implements AutoCloseable {
    private final HazelcastInstance hazelcast;
    
    public HazelcastManager(Config config) {
        this.hazelcast = Hazelcast.newHazelcastInstance(config);
    }
    
    public HazelcastInstance getInstance() {
        return hazelcast;
    }
    
    @Override
    public void close() {
        if (hazelcast != null && hazelcast.getLifecycleService().isRunning()) {
            hazelcast.shutdown();
        }
    }
}

// Usage
try (HazelcastManager manager = new HazelcastManager(config)) {
    HazelcastInstance hz = manager.getInstance();
    // Use hz for operations
}

Error Recovery

public HazelcastInstance createResilientInstance(Config config) {
    int maxRetries = 3;
    int retryDelay = 1000; // ms
    
    for (int i = 0; i < maxRetries; i++) {
        try {
            return Hazelcast.newHazelcastInstance(config);
        } catch (Exception e) {
            if (i == maxRetries - 1) {
                throw new RuntimeException("Failed to create Hazelcast instance after " + maxRetries + " attempts", e);
            }
            
            try {
                Thread.sleep(retryDelay);
            } catch (InterruptedException ie) {
                Thread.currentThread().interrupt();
                throw new RuntimeException("Interrupted while retrying", ie);
            }
        }
    }
    
    throw new RuntimeException("Should not reach here");
}

Install with Tessl CLI

npx tessl i tessl/maven-com-hazelcast--hazelcast

docs

cluster-management.md

configuration.md

core-api.md

data-structures.md

index.md

sql-service.md

stream-processing.md

tile.json