org.apache.ignite.cluster

## Interface ClusterGroup

All Known Subinterfaces:
  ClusterGroupEx, IgniteCluster, IgniteClusterEx

All Known Implementing Classes:
  ClusterGroupAdapter, IgniteClusterAsyncImpl, IgniteClusterImpl

    public interface ClusterGroup

Defines grid projection which represents a common functionality over a group of nodes. The `Ignite` interface itself also extends `GridProjection` which makes an instance of `Ignite` a projection over all grid nodes.

# Clustering

Grid projection allows to group grid nodes into various subgroups to perform distributed operations on them. All `'forXXX(...)'` methods will create a child grid projection from existing projection. If you create a new projection from current one, then the resulting projection will include a subset of nodes from current projection. The following code snippet shows how to create and nest grid projections:

     Grid g = Ignition.ignite();

     // Projection over remote nodes.
     GridProjection remoteNodes = g.forRemotes();

     // Projection over random remote node.
     GridProjection randomNode = remoteNodes.forRandom();

     // Projection over all nodes with cache named "myCache" enabled.
     GridProjection cacheNodes = g.forCacheNodes("myCache");

     // Projection over all nodes that have user attribute "group" set to value "worker".
     GridProjection workerNodes = g.forAttribute("group", "worker");

# Features

Grid projection provides the following functionality over the underlying group of nodes:

- `IgniteCompute` - functionality for executing tasks and closures over nodes in this projection.
- `IgniteMessaging` - functionality for topic-based message exchange over nodes in this projection.
- `IgniteEvents` - functionality for querying and listening to events on nodes in this projection.

### Method Summary

Methods
`ClusterGroup` `forAttribute(String name, String val)` Creates projection for nodes containing given name and value specified in user attributes.
`ClusterGroup` `forCacheNodes(String cacheName)` Creates projection for all nodes that have cache with specified name running.
`ClusterGroup` `forClientNodes(String cacheName)` Creates projection for all nodes that have cache with specified name running and cache distribution mode is `CacheDistributionMode.CLIENT_ONLY` or `CacheDistributionMode.NEAR_ONLY`.
`ClusterGroup` `forDaemons()` Gets projection consisting from the daemon nodes in this projection.
`ClusterGroup` `forDataNodes(String cacheName)` Creates projection for all nodes that have cache with specified name running and cache distribution mode is `CacheDistributionMode.PARTITIONED_ONLY` or `CacheDistributionMode.NEAR_PARTITIONED`.
`ClusterGroup` `forHost(ClusterNode node)` Gets grid projection consisting from the nodes in this projection residing on the same host as given node.
`ClusterGroup` `forNode(ClusterNode node, ClusterNode... nodes)` Creates a grid projection for the given node.
`ClusterGroup` `forNodeId(UUID id, UUID... ids)` Creates a grid projection for a node with specified ID.
`ClusterGroup` `forNodeIds(Collection<UUID> ids)` Creates a grid projection over nodes with specified node IDs.
`ClusterGroup` `forNodes(Collection<? extends ClusterNode> nodes)` Creates a grid projection over a given set of nodes.
`ClusterGroup` `forOldest()` Creates grid projection with one oldest node in the current projection.
`ClusterGroup` `forOthers(ClusterGroup prj)` Creates a grid projection for nodes not included into given projection.
`ClusterGroup` `forOthers(ClusterNode node, ClusterNode... nodes)` Creates a grid projection for nodes other than given nodes.
`ClusterGroup` `forPredicate(IgnitePredicate<ClusterNode> p)` Creates a grid projection which includes all nodes that pass the given predicate filter.
`ClusterGroup` `forRandom()` Creates grid projection with one random node from current projection.
`ClusterGroup` `forRemotes()` Gets grid projection consisting from the nodes in this projection excluding the local node.
`ClusterGroup` `forStreamer(String streamerName, String... streamerNames)` Creates projection for all nodes that have streamer with specified name running.
`ClusterGroup` `forYoungest()` Creates grid projection with one youngest node in the current projection.
`Ignite` `ignite()` Gets instance of grid.
`ClusterMetrics` `metrics()` Gets a metrics snapshot for this projection.
`ClusterNode` `node()` Gets first node from the list of nodes in this projection.
`ClusterNode` `node(UUID nid)` Gets a node for given ID from this grid projection.
`Collection<ClusterNode>` `nodes()` Gets read-only collections of nodes in this projection.
`IgnitePredicate<ClusterNode>` `predicate()` Gets predicate that defines a subset of nodes for this projection.

### Method Detail

#### ignite

    Ignite ignite()

Gets instance of grid.

Returns:
  Grid instance.

#### forNodes

    ClusterGroup forNodes(Collection<? extends ClusterNode> nodes)

Creates a grid projection over a given set of nodes.

Parameters:
  `nodes` - Collection of nodes to create a projection from.
Returns:
  Projection over provided grid nodes.

#### forNode

    ClusterGroup forNode(ClusterNode node,
                       ClusterNode... nodes)

Creates a grid projection for the given node.

Parameters:
  `node` - Node to get projection for.
  `nodes` - Optional additional nodes to include into projection.
Returns:
  Grid projection for the given node.

#### forOthers

    ClusterGroup forOthers(ClusterNode node,
                         ClusterNode... nodes)

Creates a grid projection for nodes other than given nodes.

Parameters:
  `node` - Node to exclude from new grid projection.
  `nodes` - Optional additional nodes to exclude from projection.
Returns:
  Projection that will contain all nodes that original projection contained excluding given nodes.

#### forOthers

    ClusterGroup forOthers(ClusterGroup prj)

Creates a grid projection for nodes not included into given projection.

Parameters:
  `prj` - Projection to exclude from new grid projection.
Returns:
  Projection for nodes not included into given projection.

#### forNodeIds

    ClusterGroup forNodeIds(Collection<UUID> ids)

Creates a grid projection over nodes with specified node IDs.

Parameters:
  `ids` - Collection of node IDs.
Returns:
  Projection over nodes with specified node IDs.

#### forNodeId

    ClusterGroup forNodeId(UUID id,
                         UUID... ids)

Creates a grid projection for a node with specified ID.

Parameters:
  `id` - Node ID to get projection for.
  `ids` - Optional additional node IDs to include into projection.
Returns:
  Projection over node with specified node ID.

#### forPredicate

    ClusterGroup forPredicate(IgnitePredicate<ClusterNode> p)

Creates a grid projection which includes all nodes that pass the given predicate filter.

Parameters:
  `p` - Predicate filter for nodes to include into this projection.
Returns:
  Grid projection for nodes that passed the predicate filter.

#### forAttribute

    ClusterGroup forAttribute(String name,
                            @Nullable
                            String val)

Creates projection for nodes containing given name and value specified in user attributes.

User attributes for every node are optional and can be specified in grid node configuration. See `IgniteConfiguration.getUserAttributes()` for more information.

Parameters:
  `name` - Name of the attribute.
  `val` - Optional attribute value to match.
Returns:
  Grid projection for nodes containing specified attribute.

#### forCacheNodes

    ClusterGroup forCacheNodes(String cacheName)

Creates projection for all nodes that have cache with specified name running.

Parameters:
  `cacheName` - Cache name.
Returns:
  Projection over nodes that have specified cache running.

#### forDataNodes

    ClusterGroup forDataNodes(String cacheName)

Creates projection for all nodes that have cache with specified name running and cache distribution mode is `CacheDistributionMode.PARTITIONED_ONLY` or `CacheDistributionMode.NEAR_PARTITIONED`.

Parameters:
  `cacheName` - Cache name.
Returns:
  Projection over nodes that have specified cache running.
See Also:
  `CacheConfiguration.getDistributionMode()`

#### forClientNodes

    ClusterGroup forClientNodes(String cacheName)

Creates projection for all nodes that have cache with specified name running and cache distribution mode is `CacheDistributionMode.CLIENT_ONLY` or `CacheDistributionMode.NEAR_ONLY`.

Parameters:
  `cacheName` - Cache name.
Returns:
  Projection over nodes that have specified cache running.
See Also:
  `CacheConfiguration.getDistributionMode()`

#### forStreamer

    ClusterGroup forStreamer(String streamerName,
                           @Nullable
                           String... streamerNames)

Creates projection for all nodes that have streamer with specified name running.

Parameters:
  `streamerName` - Streamer name.
  `streamerNames` - Optional additional streamer names to include into projection.
Returns:
  Projection over nodes that have specified streamer running.

#### forRemotes

    ClusterGroup forRemotes()

Gets grid projection consisting from the nodes in this projection excluding the local node.

Returns:
  Grid projection consisting from the nodes in this projection excluding the local node, if any.

#### forHost

    ClusterGroup forHost(ClusterNode node)

Gets grid projection consisting from the nodes in this projection residing on the same host as given node.

Parameters:
  `node` - Node residing on the host for which projection is created.
Returns:
  Projection for nodes residing on the same host as passed in node.

#### forDaemons

    ClusterGroup forDaemons()

Gets projection consisting from the daemon nodes in this projection.

Daemon nodes are the usual grid nodes that participate in topology but not visible on the main APIs, i.e. they are not part of any projections. The only way to see daemon nodes is to use this method.

Daemon nodes are used primarily for management and monitoring functionality that is build on Ignite and needs to participate in the topology but also needs to be excluded from "normal" topology so that it won't participate in task execution or in-memory data grid storage.

Returns:
  Grid projection consisting from the daemon nodes in this projection.

#### forRandom

    ClusterGroup forRandom()

Creates grid projection with one random node from current projection.

Returns:
  Grid projection with one random node from current projection.

#### forOldest

    ClusterGroup forOldest()

Creates grid projection with one oldest node in the current projection. The resulting projection is dynamic and will always pick the next oldest node if the previous one leaves topology even after the projection has been created.

Returns:
  Grid projection with one oldest node from the current projection.

#### forYoungest

    ClusterGroup forYoungest()

Creates grid projection with one youngest node in the current projection. The resulting projection is dynamic and will always pick the newest node in the topology, even if more nodes entered after the projection has been created.

Returns:
  Grid projection with one youngest node from the current projection.

#### nodes

    Collection<ClusterNode> nodes()

Gets read-only collections of nodes in this projection.

Returns:
  All nodes in this projection.

#### node

    @Nullable
    ClusterNode node(UUID nid)

Gets a node for given ID from this grid projection.

Parameters:
  `nid` - Node ID.
Returns:
  Node with given ID from this projection or `null` if such node does not exist in this projection.

#### node

    @Nullable
    ClusterNode node()

Gets first node from the list of nodes in this projection. This method is specifically useful for projection over one node only.

Returns:
  First node from the list of nodes in this projection or `null` if projection is empty.

#### predicate

    IgnitePredicate<ClusterNode> predicate()

Gets predicate that defines a subset of nodes for this projection.

Returns:
  Predicate that defines a subset of nodes for this projection.

#### metrics

    ClusterMetrics metrics()
                           throws IgniteException

Gets a metrics snapshot for this projection.

Returns:
  Grid projection metrics snapshot.
Throws:
  `IgniteException` - If projection is empty.

2015 Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Fabric | : ver. 1.0.0-RC3
Release Date | : March 24 2015