org.apache.ignite

## Class Ignition

- java.lang.Object
- - org.apache.ignite.Ignition

Direct Known Subclasses:
  G

    public class Ignition
    extends Object

This class defines a factory for the main Ignite API. It controls Grid life cycle and allows listening for grid events.

# Grid Loaders

Although user can apply grid factory directly to start and stop grid, grid is often started and stopped by grid loaders. Grid loaders can be found in `org.apache.ignite.startup` package, for example:

- `CommandLineStartup`
- `IgniteServletStartup`

# Examples

Use `start()` method to start grid with default configuration. You can also use `IgniteConfiguration` to override some default configuration. Below is an example on how to start grid with custom configuration for URI deployment.

     GridConfiguration cfg = new GridConfiguration();

     GridUriDeployment deploySpi = new GridUriDeployment();

     deploySpi.setUriList(Collections.singletonList("classes://tmp/output/classes"));

     cfg.setDeploymentSpi(deploySpi);

     Ignition.start(cfg);

Here is how a grid instance can be configured from Spring XML configuration file. The example below configures a grid instance with additional user attributes (see `ClusterNode.attributes()`) and specifies a grid name:

     <bean id="grid.cfg" class="org.apache.ignite.configuration.IgniteConfiguration">
         ...
         <property name="gridName" value="grid"/>
         <property name="userAttributes">
             <map>
                 <entry key="group" value="worker"/>
             </map>
         </property>
         ...
     </bean>

A grid instance with Spring configuration above can be started as following. Note that you do not need to pass path to Spring XML file if you are using `IGNITE_HOME/config/default-config.xml`. Also note, that the path can be absolute or relative to IGNITE_HOME.

     ...
     Ignition.start("/path/to/spring/xml/file.xml");
     ...

You can also instantiate grid directly from Spring without using `Ignition`. For more information refer to `IgniteSpringBean` documentation.

### Field Summary

Fields
`static int` `KILL_EXIT_CODE` This is kill code that can be used by external tools, like Shell scripts, to auto-stop the Ignite JVM process without restarting.
`static int` `RESTART_EXIT_CODE` This is restart code that can be used by external tools, like Shell scripts, to auto-restart the Ignite JVM process.

### Constructor Summary

Constructors
`protected` `Ignition()` Enforces singleton.

### Method Summary

Methods
`static void` `addListener(IgnitionListener lsnr)` Adds a lsnr for grid life cycle events.
`static List<Ignite>` `allGrids()` Gets a list of all grids started so far.
`static Ignite` `ignite()` Gets an instance of default no-name grid.
`static Ignite` `ignite(String name)` Gets an named grid instance.
`static Ignite` `ignite(UUID locNodeId)` Gets a grid instance for given local node ID.
`static boolean` `isDaemon()` Gets daemon flag.
`static void` `kill(boolean cancel)` Stops all started grids.
`static boolean` `removeListener(IgnitionListener lsnr)` Removes lsnr added by `addListener(IgnitionListener)` method.
`static void` `restart(boolean cancel)` Restarts all started grids.
`static void` `setDaemon(boolean daemon)` Sets daemon flag.
`static Ignite` `start()` Starts grid with default configuration.
`static Ignite` `start(IgniteConfiguration cfg)` Starts grid with given configuration.
`static Ignite` `start(String springCfgPath)` Starts all grids specified within given Spring XML configuration file.
`static Ignite` `start(URL springCfgUrl)` Starts all grids specified within given Spring XML configuration file URL.
`static IgniteState` `state()` Gets state of grid default grid.
`static IgniteState` `state(String name)` Gets states of named grid.
`static boolean` `stop(boolean cancel)` Stops default grid.
`static boolean` `stop(String name, boolean cancel)` Stops named grid.
`static void` `stopAll(boolean cancel)` Stops all started grids in current JVM.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### RESTART_EXIT_CODE

    public static final int RESTART_EXIT_CODE

This is restart code that can be used by external tools, like Shell scripts, to auto-restart the Ignite JVM process. Note that there is no standard way for a JVM to restart itself from Java application and therefore we rely on external tools to provide that capability.

Note that standard `ignite.{sh|bat}` scripts support restarting when JVM process exits with this code.

See Also:
  Constant Field Values

#### KILL_EXIT_CODE

    public static final int KILL_EXIT_CODE

This is kill code that can be used by external tools, like Shell scripts, to auto-stop the Ignite JVM process without restarting.

See Also:
  Constant Field Values

### Constructor Detail

#### Ignition

    protected Ignition()

Enforces singleton.

### Method Detail

#### setDaemon

    public static void setDaemon(boolean daemon)

Sets daemon flag.

If daemon flag is set then all grid instances created by the factory will be daemon, i.e. the local node for these instances will be a daemon node. Note that if daemon flag is set - it will override the same settings in `IgniteConfiguration.isDaemon()`. Note that you can set on and off daemon flag at will.

Parameters:
  `daemon` - Daemon flag to set.

#### isDaemon

    public static boolean isDaemon()

Gets daemon flag.

If daemon flag it set then all grid instances created by the factory will be daemon, i.e. the local node for these instances will be a daemon node. Note that if daemon flag is set - it will override the same settings in `IgniteConfiguration.isDaemon()`. Note that you can set on and off daemon flag at will.

Returns:
  Daemon flag.

#### state

    public static IgniteState state()

Gets state of grid default grid.

Returns:
  Default grid state.

#### state

    public static IgniteState state(@Nullable
                    String name)

Gets states of named grid. If name is `null`, then state of default no-name grid is returned.

Parameters:
  `name` - Grid name. If name is `null`, then state of default no-name grid is returned.
Returns:
  Grid state.

#### stop

    public static boolean stop(boolean cancel)

Stops default grid. This method is identical to `G.stop(null, cancel)` apply. Note that method does not wait for all tasks to be completed.

Parameters:
  `cancel` - If `true` then all jobs currently executing on default grid will be cancelled by calling `ComputeJob.cancel()` method. Note that just like with `Thread.interrupt()`, it is up to the actual job to exit from execution
Returns:
  `true` if default grid instance was indeed stopped, `false` otherwise (if it was not started).

#### stop

    public static boolean stop(@Nullable
               String name,
               boolean cancel)

Stops named grid. If `cancel` flag is set to `true` then all jobs currently executing on local node will be interrupted. If grid name is `null`, then default no-name grid will be stopped. If wait parameter is set to `true` then grid will wait for all tasks to be finished.

Parameters:
  `name` - Grid name. If `null`, then default no-name grid will be stopped.
  `cancel` - If `true` then all jobs currently will be cancelled by calling `ComputeJob.cancel()` method. Note that just like with `Thread.interrupt()`, it is up to the actual job to exit from execution. If `false`, then jobs currently running will not be canceled. In either case, grid node will wait for completion of all jobs running on it before stopping.
Returns:
  `true` if named grid instance was indeed found and stopped, `false` otherwise (the instance with given `name` was not found).

#### stopAll

    public static void stopAll(boolean cancel)

Stops all started grids in current JVM. If `cancel` flag is set to `true` then all jobs currently executing on local node will be interrupted. If wait parameter is set to `true` then grid will wait for all tasks to be finished.

Note: it is usually safer and more appropriate to stop grid instances individually instead of blanket operation. In most cases, the party that started the grid instance should be responsible for stopping it.

Parameters:
  `cancel` - If `true` then all jobs currently executing on all grids will be cancelled by calling `ComputeJob.cancel()` method. Note that just like with `Thread.interrupt()`, it is up to the actual job to exit from execution

#### restart

    public static void restart(boolean cancel)

Restarts all started grids. If `cancel` flag is set to `true` then all jobs currently executing on the local node will be interrupted. If `wait` parameter is set to `true` then grid will wait for all tasks to be finished.

Note: it is usually safer and more appropriate to stop grid instances individually instead of blanket operation. In most cases, the party that started the grid instance should be responsible for stopping it.

Note also that restarting functionality only works with the tools that specifically support Ignite's protocol for restarting. Currently only standard `ignite.{sh|bat}` scripts support restarting of JVM Ignite's process.

Parameters:
  `cancel` - If `true` then all jobs currently executing on all grids will be cancelled by calling `ComputeJob.cancel()` method. Note that just like with `Thread.interrupt()`, it is up to the actual job to exit from execution.
See Also:
  `RESTART_EXIT_CODE`

#### kill

    public static void kill(boolean cancel)

Stops all started grids. If `cancel` flag is set to `true` then all jobs currently executing on the local node will be interrupted. If `wait` parameter is set to `true` then grid will wait for all tasks to be finished.

Note: it is usually safer and more appropriate to stop grid instances individually instead of blanket operation. In most cases, the party that started the grid instance should be responsible for stopping it.

Note that upon completion of this method, the JVM with forcefully exist with exit code `KILL_EXIT_CODE`.

Parameters:
  `cancel` - If `true` then all jobs currently executing on all grids will be cancelled by calling `ComputeJob.cancel()` method. Note that just like with `Thread.interrupt()`, it is up to the actual job to exit from execution.
See Also:
  `KILL_EXIT_CODE`

#### start

    public static Ignite start()
                        throws IgniteException

Starts grid with default configuration. By default this method will use grid configuration defined in `IGNITE_HOME/config/default-config.xml` configuration file. If such file is not found, then all system defaults will be used.

Returns:
  Started grid.
Throws:
  `IgniteException` - If default grid could not be started. This exception will be thrown also if default grid has already been started.

#### start

    public static Ignite start(IgniteConfiguration cfg)
                        throws IgniteException

Starts grid with given configuration. Note that this method is no-op if grid with the name provided in given configuration is already started.

Parameters:
  `cfg` - Grid configuration. This cannot be `null`.
Returns:
  Started grid.
Throws:
  `IgniteException` - If grid could not be started. This exception will be thrown also if named grid has already been started.

#### start

    public static Ignite start(@Nullable
               String springCfgPath)
                        throws IgniteException

Starts all grids specified within given Spring XML configuration file. If grid with given name is already started, then exception is thrown. In this case all instances that may have been started so far will be stopped too.

Usually Spring XML configuration file will contain only one Grid definition. Note that Grid configuration bean(s) is retrieved form configuration file by type, so the name of the Grid configuration bean is ignored.

Parameters:
  `springCfgPath` - Spring XML configuration file path or URL.
Returns:
  Started grid. If Spring configuration contains multiple grid instances, then the 1st found instance is returned.
Throws:
  `IgniteException` - If grid could not be started or configuration read. This exception will be thrown also if grid with given name has already been started or Spring XML configuration file is invalid.

#### start

    public static Ignite start(URL springCfgUrl)
                        throws IgniteException

Starts all grids specified within given Spring XML configuration file URL. If grid with given name is already started, then exception is thrown. In this case all instances that may have been started so far will be stopped too.

Usually Spring XML configuration file will contain only one Grid definition. Note that Grid configuration bean(s) is retrieved form configuration file by type, so the name of the Grid configuration bean is ignored.

Parameters:
  `springCfgUrl` - Spring XML configuration file URL. This cannot be `null`.
Returns:
  Started grid. If Spring configuration contains multiple grid instances, then the 1st found instance is returned.
Throws:
  `IgniteException` - If grid could not be started or configuration read. This exception will be thrown also if grid with given name has already been started or Spring XML configuration file is invalid.

#### ignite

    public static Ignite ignite()
                         throws IgniteIllegalStateException

Gets an instance of default no-name grid. Note that caller of this method should not assume that it will return the same instance every time.

This method is identical to `G.grid(null)` apply.

Returns:
  An instance of default no-name grid. This method never returns `null`.
Throws:
  `IgniteIllegalStateException` - Thrown if default grid was not properly initialized or grid instance was stopped or was not started.

#### allGrids

    public static List<Ignite> allGrids()

Gets a list of all grids started so far.

Returns:
  List of all grids started so far.

#### ignite

    public static Ignite ignite(UUID locNodeId)
                         throws IgniteIllegalStateException

Gets a grid instance for given local node ID. Note that grid instance and local node have one-to-one relationship where node has ID and instance has name of the grid to which both grid instance and its node belong. Note also that caller of this method should not assume that it will return the same instance every time.

Parameters:
  `locNodeId` - ID of local node the requested grid instance is managing.
Returns:
  An instance of named grid. This method never returns `null`.
Throws:
  `IgniteIllegalStateException` - Thrown if grid was not properly initialized or grid instance was stopped or was not started.

#### ignite

    public static Ignite ignite(@Nullable
                String name)
                         throws IgniteIllegalStateException

Gets an named grid instance. If grid name is `null` or empty string, then default no-name grid will be returned. Note that caller of this method should not assume that it will return the same instance every time.

Note that Java VM can run multiple grid instances and every grid instance (and its node) can belong to a different grid. Grid name defines what grid a particular grid instance (and correspondingly its node) belongs to.

Parameters:
  `name` - Grid name to which requested grid instance belongs to. If `null`, then grid instance belonging to a default no-name grid will be returned.
Returns:
  An instance of named grid. This method never returns `null`.
Throws:
  `IgniteIllegalStateException` - Thrown if default grid was not properly initialized or grid instance was stopped or was not started.

#### addListener

    public static void addListener(IgnitionListener lsnr)

Adds a lsnr for grid life cycle events.

Note that unlike other listeners in Ignite this listener will be notified from the same thread that triggers the state change. Because of that it is the responsibility of the user to make sure that listener logic is light-weight and properly handles (catches) any runtime exceptions, if any are expected.

Parameters:
  `lsnr` - Listener for grid life cycle events. If this listener was already added this method is no-op.

#### removeListener

    public static boolean removeListener(IgnitionListener lsnr)

Removes lsnr added by `addListener(IgnitionListener)` method.

Parameters:
  `lsnr` - Listener to remove.
Returns:
  `true` if lsnr was added before, `false` otherwise.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0-RC1
Release Date | : February 17 2015