com.hazelcast.core

Class Hazelcast

java.lang.Object

com.hazelcast.core.Hazelcast

public final class Hazelcast
extends Object

Factory for HazelcastInstance's, a node in a cluster.

Method Summary

Modifier and Type	Method and Description
static HazelcastInstance	bootstrappedInstance() Returns either a local Hazelcast instance or a "bootstrapped" Hazelcast client for a remote Hazelcast cluster, depending on the context.
static Set<HazelcastInstance>	getAllHazelcastInstances() Returns all active/running HazelcastInstances on this JVM.
static HazelcastInstance	getHazelcastInstanceByName(String instanceName) Returns an existing HazelcastInstance with instanceName.
static HazelcastInstance	getOrCreateHazelcastInstance() Gets or creates a HazelcastInstance with the default XML configuration looked up in: System property: Hazelcast will first check if "hazelcast.config" system property is set to a file or a classpath:... path.
static HazelcastInstance	getOrCreateHazelcastInstance(Config config) Gets or creates the HazelcastInstance with a certain name.
static HazelcastInstance	newHazelcastInstance() Creates a new HazelcastInstance (a new node in a cluster).
static HazelcastInstance	newHazelcastInstance(Config config) Creates a new HazelcastInstance (a new node in a cluster).
static void	setOutOfMemoryHandler(OutOfMemoryHandler outOfMemoryHandler) Sets OutOfMemoryHandler to be used when an OutOfMemoryError is caught by Hazelcast threads.
static void	shutdownAll() Shuts down all member HazelcastInstances running on this JVM.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

shutdownAll

public static void shutdownAll()

Shuts down all member HazelcastInstances running on this JVM. It doesn't shutdown all members of the cluster but just the ones running on this JVM.

See Also:

newHazelcastInstance(Config)

newHazelcastInstance

public static HazelcastInstance newHazelcastInstance(Config config)

Creates a new HazelcastInstance (a new node in a cluster). This method allows you to create and run multiple instances of Hazelcast cluster members on the same JVM.

To shutdown all running HazelcastInstances (all members on this JVM) call shutdownAll().

Parameters:

config - Configuration for the new HazelcastInstance (member)

Returns:

the new HazelcastInstance

See Also:

shutdownAll(), getHazelcastInstanceByName(String)

newHazelcastInstance

public static HazelcastInstance newHazelcastInstance()

Creates a new HazelcastInstance (a new node in a cluster). This method allows you to create and run multiple instances of Hazelcast cluster members on the same JVM.

To shutdown all running HazelcastInstances (all members on this JVM) call shutdownAll(). Hazelcast will look into two places for the configuration file:

1. System property: Hazelcast will first check if "hazelcast.config" system property is set to a file or a classpath:... path. Examples: -Dhazelcast.config=C:/myhazelcast.xml , -Dhazelcast.config=classpath:the-hazelcast-config.xml , -Dhazelcast.config=classpath:com/mydomain/hazelcast.xml
2. "hazelcast.xml" file in current working directory
3. Classpath: Hazelcast will check classpath for hazelcast.xml file.

If Hazelcast doesn't find any config file, it will start with the default configuration (hazelcast-default.xml) located in hazelcast.jar.

Returns:

the new HazelcastInstance

See Also:

shutdownAll(), getHazelcastInstanceByName(String)

getHazelcastInstanceByName

public static HazelcastInstance getHazelcastInstanceByName(String instanceName)

Returns an existing HazelcastInstance with instanceName.

To shutdown all running HazelcastInstances (all members on this JVM) call shutdownAll().

Parameters:

instanceName - Name of the HazelcastInstance (member)

Returns:

an existing HazelcastInstance

See Also:

newHazelcastInstance(Config), shutdownAll()

getOrCreateHazelcastInstance

public static HazelcastInstance getOrCreateHazelcastInstance()

Gets or creates a HazelcastInstance with the default XML configuration looked up in:

1. System property: Hazelcast will first check if "hazelcast.config" system property is set to a file or a classpath:... path. Examples: -Dhazelcast.config=C:/myhazelcast.xml , -Dhazelcast.config=classpath:the-hazelcast-config.xml , -Dhazelcast.config=classpath:com/mydomain/hazelcast.xml
2. "hazelcast.xml" file in current working directory
3. Classpath: Hazelcast will check classpath for hazelcast.xml file.

If a configuration file is not located, an IllegalArgumentException will be thrown. If a Hazelcast instance with the same name as the configuration exists, then it is returned, otherwise it is created.

Returns:

the HazelcastInstance

Throws:

IllegalArgumentException - if the instance name of the config is null or empty or if no config file can be located.

getOrCreateHazelcastInstance

public static HazelcastInstance getOrCreateHazelcastInstance(Config config)

Gets or creates the HazelcastInstance with a certain name. If a Hazelcast instance with the same name as the configuration exists, then it is returned, otherwise it is created. If config is null, then an XML configuration file is looked up in the following order:

1. System property: Hazelcast will first check if "hazelcast.config" system property is set to a file or a classpath:... path. Examples: -Dhazelcast.config=C:/myhazelcast.xml , -Dhazelcast.config=classpath:the-hazelcast-config.xml , -Dhazelcast.config=classpath:com/mydomain/hazelcast.xml
2. "hazelcast.xml" file in current working directory
3. Classpath: Hazelcast will check classpath for hazelcast.xml file.

Parameters:

config - the Config.

Returns:

the HazelcastInstance

Throws:

IllegalArgumentException - if the instance name of the config is null or empty or if no config file can be located.

getAllHazelcastInstances

public static Set<HazelcastInstance> getAllHazelcastInstances()

Returns all active/running HazelcastInstances on this JVM.

To shutdown all running HazelcastInstances (all members on this JVM) call shutdownAll().

Returns:

all active/running HazelcastInstances on this JVM

See Also:

newHazelcastInstance(Config), getHazelcastInstanceByName(String), shutdownAll()

bootstrappedInstance

@Nonnull
public static HazelcastInstance bootstrappedInstance()

Returns either a local Hazelcast instance or a "bootstrapped" Hazelcast client for a remote Hazelcast cluster, depending on the context. The main goal of this factory method is to simplify submitting a Jet job to a remote Hazelcast cluster while also making it convenient to test on the local machine.

When you submit a job to a Hazelcast instance that runs locally in your JVM, it will have all the dependency classes available. However, when you take the same job to a remote Hazelcast cluster, you'll often find that it fails with a ClassNotFoundException because the remote cluster doesn't have all the classes you use in the job.

Normally you would have to explicitly add all the dependency classes to the JobConfig, either one by one or packaged into a JAR. If you're submitting a job using the command-line tool hazelcast submit, the JAR to attach is the same JAR that contains the code that submits the job.

This factory takes all of the above into account in order to provide a smoother experience:

• When not called from hazelcast submit, it returns a local HazelcastInstance, either by creating a new one or looking up a cached one. The instance won't join any cluster.
• When called from hazelcast submit, it returns a "bootstrapped" instance of Hazelcast client that automatically attaches the JAR to all jobs you submit using it.

With these semantics in place it's simple to write code that works both in your local development/testing environment (using a local Hazelcast instance) and in production (using the remote cluster).

To use this feature, follow these steps:

1. Write your main() method and your code the usual way, making sure you use this method (instead of HazelcastClient.newHazelcastClient()) to acquire a Hazelcast client instance.
2. Create a runnable JAR (e.g. jet-job.jar) with your entry point declared as the Main-Class in MANIFEST.MF. The JAR should include all dependencies required to run it (except the Hazelcast classes — these are already available on the cluster classpath).
3. Submit the job by writing hazelcast submit hz-job.jar on the command line. This assumes you have downloaded the Hazelcast distribution package and its bin directory is on your system path. The Hazelcast client will use the configuration file <distro_root>/config/hazelcast-client.yaml. Adjust that file as needed.
4. The same code will work if you run it directly from your IDE. In this case it will create a local Hazelcast instance for itself to run on.

For example, you can write a class like this:

 public class CustomJetJob {
   public static void main(String[] args) {
     HazelcastInstance hz = Hazelcast.bootstrappedInstance();
     hz.getJet().newJob(buildPipeline()).join();
   }

   public static Pipeline buildPipeline() {
       // ...
   }
 }
 

Since:

5.0

setOutOfMemoryHandler

public static void setOutOfMemoryHandler(OutOfMemoryHandler outOfMemoryHandler)

Sets OutOfMemoryHandler to be used when an OutOfMemoryError is caught by Hazelcast threads.

Warning: OutOfMemoryHandler may not be called although JVM throws OutOfMemoryError. Because error may be thrown from an external (user thread) thread and Hazelcast may not be informed about OutOfMemoryError.

Parameters:

outOfMemoryHandler - set when an OutOfMemoryError is caught by Hazelcast threads

See Also:

OutOfMemoryError, OutOfMemoryHandler