public interface IgniteServices extends IgniteAsyncSupport
Instance of IgniteServices
which spans all cluster nodes can be obtained from Ignite as follows:
Ignite ignite = Ignition.ignite(); IgniteServices svcs = ignite.services();You can also obtain an instance of the services facade over a specific cluster group:
// Cluster group over remote nodes (excluding the local node). ClusterGroup remoteNodes = ignite.cluster().forRemotes(); // Services instance spanning all remote cluster nodes. IgniteServices svcs = ignite.services(remoteNodes);
With distributed services you can do the following:
deploy(...)
methods,
you can also automatically deploy services on startup by specifying them in IgniteConfiguration
like so:
IgniteConfiguration cfg = new IgniteConfiguration(); ServiceConfiguration svcCfg1 = new ServiceConfiguration(); // Cluster-wide singleton configuration. svcCfg1.setName("myClusterSingletonService"); svcCfg1.setMaxPerNodeCount(1); svcCfg1.setTotalCount(1); svcCfg1.setService(new MyClusterSingletonService()); ServiceConfiguration svcCfg2 = new ServiceConfiguration(); // Per-node singleton configuration. svcCfg2.setName("myNodeSingletonService"); svcCfg2.setMaxPerNodeCount(1); svcCfg2.setService(new MyNodeSingletonService()); cfg.setServiceConfiguration(svcCfg1, svcCfg2); ... Ignition.start(cfg);
// Simple service implementation. public class MyIgniteService implements Service { ... // Example of ignite resource injection. All resources are optional. // You should inject resources only as needed. @IgniteInstanceResource private Ignite ignite; ... @Override public void cancel(ServiceContext ctx) { // No-op. } @Override public void execute(ServiceContext ctx) { // Loop until service is cancelled. while (!ctx.isCancelled()) { // Do something. ... } } } ... IgniteServices svcs = ignite.services(); svcs.deployClusterSingleton("mySingleton", new MyIgniteService());
Modifier and Type | Method and Description |
---|---|
void |
cancel(String name)
Cancels service deployment.
|
void |
cancelAll()
Cancels all deployed services.
|
void |
cancelAll(Collection<String> names)
Cancels services with specified names.
|
IgniteFuture<Void> |
cancelAllAsync()
Asynchronously cancels all deployed services.
|
IgniteFuture<Void> |
cancelAllAsync(Collection<String> names)
Asynchronously cancels services with specified names.
|
IgniteFuture<Void> |
cancelAsync(String name)
Asynchronously cancels service deployment.
|
ClusterGroup |
clusterGroup()
Gets the cluster group to which this
IgniteServices instance belongs. |
void |
deploy(ServiceConfiguration cfg)
Deploys multiple instances of the service on the grid according to provided
configuration.
|
void |
deployAll(Collection<ServiceConfiguration> cfgs)
Deploys multiple services described by provided configurations.
|
IgniteFuture<Void> |
deployAllAsync(Collection<ServiceConfiguration> cfgs)
Asynchronously deploys multiple services described by provided configurations.
|
IgniteFuture<Void> |
deployAsync(ServiceConfiguration cfg)
Asynchronously deploys multiple instances of the service on the grid according to provided
configuration.
|
void |
deployClusterSingleton(String name,
Service svc)
Deploys a cluster-wide singleton service.
|
IgniteFuture<Void> |
deployClusterSingletonAsync(String name,
Service svc)
Asynchronously deploys a cluster-wide singleton service.
|
void |
deployKeyAffinitySingleton(String name,
Service svc,
@Nullable String cacheName,
Object affKey)
Deploys one instance of this service on the primary node for a given affinity key.
|
IgniteFuture<Void> |
deployKeyAffinitySingletonAsync(String name,
Service svc,
@Nullable String cacheName,
Object affKey)
Asynchronously deploys one instance of this service on the primary node for a given affinity key.
|
void |
deployMultiple(String name,
Service svc,
int totalCnt,
int maxPerNodeCnt)
Deploys multiple instances of the service on the grid.
|
IgniteFuture<Void> |
deployMultipleAsync(String name,
Service svc,
int totalCnt,
int maxPerNodeCnt)
Asynchronously deploys multiple instances of the service on the grid.
|
void |
deployNodeSingleton(String name,
Service svc)
Deploys a per-node singleton service.
|
IgniteFuture<Void> |
deployNodeSingletonAsync(String name,
Service svc)
Asynchronously deploys a per-node singleton service.
|
<T> T |
service(String name)
Deprecated.
Use the proxies like
serviceProxy(String, Class, boolean) . References to local services
corrupt the service statistics and bring no real performance optimization. |
Collection<ServiceDescriptor> |
serviceDescriptors()
Gets metadata about all deployed services in the grid.
|
<T> T |
serviceProxy(String name,
Class<? super T> svcItf,
boolean sticky)
Gets a handle on remote or local service.
|
<T> T |
serviceProxy(String name,
Class<? super T> svcItf,
boolean sticky,
long timeout)
Gets a handle on remote or local service with the timeout.
|
<T> T |
serviceProxy(String name,
Class<? super T> svcItf,
boolean sticky,
ServiceCallContext callCtx)
Gets a handle on remote or local service with the specified caller context.
|
<T> T |
serviceProxy(String name,
Class<? super T> svcItf,
boolean sticky,
ServiceCallContext callCtx,
long timeout)
Gets a handle on remote or local service with the specified caller context and the timeout.
|
<T> Collection<T> |
services(String name)
Deprecated.
Use the proxies like
serviceProxy(String, Class, boolean) . References to local services
corrupt the service statistics and bring no real performance optimization. |
IgniteServices |
withAsync()
Deprecated.
|
future, isAsync
ClusterGroup clusterGroup()
IgniteServices
instance belongs.IgniteServices
instance belongs.@IgniteAsyncSupported void deployClusterSingleton(String name, Service svc) throws ServiceDeploymentException
Note that in case of topology changes, due to network delays, there may be a temporary situation when a singleton service instance will be active on more than one node (e.g. crash detection delay).
This method is analogous to calling
deployMultiple(name, svc, 1, 1)
method.
name
- Service name.svc
- Service instance.ServiceDeploymentException
- If failed to deploy service.IgniteFuture<Void> deployClusterSingletonAsync(String name, Service svc)
Note that in case of topology changes, due to network delays, there may be a temporary situation when a singleton service instance will be active on more than one node (e.g. crash detection delay).
This method is analogous to calling
deployMultipleAsync(name, svc, 1, 1)
method.
name
- Service name.svc
- Service instance.@IgniteAsyncSupported void deployNodeSingleton(String name, Service svc) throws ServiceDeploymentException
This method is analogous to calling
deployMultiple(name, svc, 0, 1)
method.
name
- Service name.svc
- Service instance.ServiceDeploymentException
- If failed to deploy service.IgniteFuture<Void> deployNodeSingletonAsync(String name, Service svc)
This method is analogous to calling
deployMultipleAsync(name, svc, 0, 1)
method.
name
- Service name.svc
- Service instance.@IgniteAsyncSupported void deployKeyAffinitySingleton(String name, Service svc, @Nullable @Nullable String cacheName, Object affKey) throws ServiceDeploymentException
Note that in case of topology changes, due to network delays, there may be a temporary situation when a service instance will be active on more than one node (e.g. crash detection delay).
This method is analogous to the invocation of deploy(org.apache.ignite.services.ServiceConfiguration)
method as follows:
ServiceConfiguration cfg = new ServiceConfiguration(); cfg.setName(name); cfg.setService(svc); cfg.setCacheName(cacheName); cfg.setAffinityKey(affKey); cfg.setTotalCount(1); cfg.setMaxPerNodeCount(1); ignite.services().deploy(cfg);
name
- Service name.svc
- Service instance.cacheName
- Name of the cache on which affinity for key should be calculated, null
for
default cache.affKey
- Affinity cache key.ServiceDeploymentException
- If failed to deploy service.IgniteFuture<Void> deployKeyAffinitySingletonAsync(String name, Service svc, @Nullable @Nullable String cacheName, Object affKey)
Note that in case of topology changes, due to network delays, there may be a temporary situation when a service instance will be active on more than one node (e.g. crash detection delay).
This method is analogous to the invocation of
deployAsync(org.apache.ignite.services.ServiceConfiguration)
method as follows:
ServiceConfiguration cfg = new ServiceConfiguration(); cfg.setName(name); cfg.setService(svc); cfg.setCacheName(cacheName); cfg.setAffinityKey(affKey); cfg.setTotalCount(1); cfg.setMaxPerNodeCount(1); ignite.services().deployAsync(cfg);
name
- Service name.svc
- Service instance.cacheName
- Name of the cache on which affinity for key should be calculated, null
for
default cache.affKey
- Affinity cache key.@IgniteAsyncSupported void deployMultiple(String name, Service svc, int totalCnt, int maxPerNodeCnt) throws ServiceDeploymentException
'totalCnt'
parameter making sure that
there are no more than 'maxPerNodeCnt'
service instances running
on each node. Whenever topology changes, Ignite will automatically rebalance
the deployed services within cluster to make sure that each node will end up with
about equal number of deployed instances whenever possible.
Note that at least one of 'totalCnt'
or 'maxPerNodeCnt'
parameters must have
value greater than 0
.
This method is analogous to the invocation of deploy(org.apache.ignite.services.ServiceConfiguration)
method as follows:
ServiceConfiguration cfg = new ServiceConfiguration(); cfg.setName(name); cfg.setService(svc); cfg.setTotalCount(totalCnt); cfg.setMaxPerNodeCount(maxPerNodeCnt); ignite.services().deploy(cfg);
name
- Service name.svc
- Service instance.totalCnt
- Maximum number of deployed services in the grid, 0
for unlimited.maxPerNodeCnt
- Maximum number of deployed services on each node, 0
for unlimited.ServiceDeploymentException
- If failed to deploy service.IgniteFuture<Void> deployMultipleAsync(String name, Service svc, int totalCnt, int maxPerNodeCnt)
'totalCnt'
parameter making sure that
there are no more than 'maxPerNodeCnt'
service instances running
on each node. Whenever topology changes, Ignite will automatically rebalance
the deployed services within cluster to make sure that each node will end up with
about equal number of deployed instances whenever possible.
Note that at least one of 'totalCnt'
or 'maxPerNodeCnt'
parameters must have
value greater than 0
.
This method is analogous to the invocation of
deployAsync(org.apache.ignite.services.ServiceConfiguration)
method as follows:
ServiceConfiguration cfg = new ServiceConfiguration(); cfg.setName(name); cfg.setService(svc); cfg.setTotalCount(totalCnt); cfg.setMaxPerNodeCount(maxPerNodeCnt); ignite.services().deployAsync(cfg);
name
- Service name.svc
- Service instance.totalCnt
- Maximum number of deployed services in the grid, 0
for unlimited.maxPerNodeCnt
- Maximum number of deployed services on each node, 0
for unlimited.@IgniteAsyncSupported void deploy(ServiceConfiguration cfg) throws ServiceDeploymentException
cfg.getTotalCount()
parameter
making sure that there are no more than
cfg.getMaxPerNodeCount()
service instances running on each node. Whenever topology changes, Ignite will automatically rebalance
the deployed services within cluster to make sure that each node will end up with
about equal number of deployed instances whenever possible.
If cfg.getAffinityKey()
is not null
, then Ignite will deploy the service on the primary node for given affinity key.
The affinity will be calculated on the cache with
cfg.getCacheName()
name.
If cfg.getNodeFilter()
is not null
, then Ignite will deploy service on all grid nodes for which
the provided filter evaluates to true
.
The node filter will be checked in addition to the underlying cluster group filter, or the
whole grid, if the underlying cluster group includes all the cluster nodes.
Note that at least one of 'totalCnt'
or 'maxPerNodeCnt'
parameters must have
value greater than 0
.
Here is an example of creating service deployment configuration:
ServiceConfiguration cfg = new ServiceConfiguration(); cfg.setName(name); cfg.setService(svc); cfg.setTotalCount(0); // Unlimited. cfg.setMaxPerNodeCount(2); // Deploy 2 instances of service on each node. ignite.services().deploy(cfg);
cfg
- Service configuration.ServiceDeploymentException
- If failed to deploy service.IgniteFuture<Void> deployAsync(ServiceConfiguration cfg)
cfg.getTotalCount()
parameter
making sure that there are no more than
cfg.getMaxPerNodeCount()
service instances running on each node. Whenever topology changes, Ignite will automatically rebalance
the deployed services within cluster to make sure that each node will end up with
about equal number of deployed instances whenever possible.
If cfg.getAffinityKey()
is not null
, then Ignite
will deploy the service on the primary node for given affinity key. The affinity will be calculated
on the cache with cfg.getCacheName()
name.
If cfg.getNodeFilter()
is not null
, then Ignite will deploy service on all grid nodes
for which the provided filter evaluates to true
.
The node filter will be checked in addition to the underlying cluster group filter, or the
whole grid, if the underlying cluster group includes all the cluster nodes.
Note that at least one of 'totalCnt'
or 'maxPerNodeCnt'
parameters must have
value greater than 0
.
Here is an example of creating service deployment configuration:
ServiceConfiguration cfg = new ServiceConfiguration(); cfg.setName(name); cfg.setService(svc); cfg.setTotalCount(0); // Unlimited. cfg.setMaxPerNodeCount(2); // Deploy 2 instances of service on each node. ignite.services().deployAsync(cfg);
cfg
- Service configuration.void deployAll(Collection<ServiceConfiguration> cfgs) throws ServiceDeploymentException
ServiceConfiguration
). Whenever topology changes,
Ignite will automatically rebalance the deployed services within cluster to make sure that each node will end up
with about equal number of deployed instances whenever possible.
If deployment of some of the provided services fails, then ServiceDeploymentException
containing a list
of failed services will be thrown. It is guaranteed that all services that were provided to this method and are
not present in the list of failed services are successfully deployed by the moment of the exception being thrown.
Note that if exception is thrown, then partial deployment may have occurred.cfgs
- Collection
of service configurations to be deployed.ServiceDeploymentException
- If failed to deploy services.deploy(ServiceConfiguration)
,
deployAllAsync(Collection)
IgniteFuture<Void> deployAllAsync(Collection<ServiceConfiguration> cfgs)
ServiceConfiguration
). Whenever topology
changes, Ignite will automatically rebalance the deployed services within cluster to make sure that each node
will end up with about equal number of deployed instances whenever possible.
If deployment of some of the provided services fails, then ServiceDeploymentException
containing a list
of failed services will be thrown from get()
method of the returned future. It is
guaranteed that all services, that were provided to this method and are not present in the list of failed
services, are successfully deployed by the moment of the exception being thrown. Note that if exception is
thrown, then partial deployment may have occurred.cfgs
- Collection
of service configurations to be deployed.deploy(ServiceConfiguration)
,
deployAll(Collection)
@IgniteAsyncSupported void cancel(String name) throws IgniteException
Service.cancel(org.apache.ignite.services.ServiceContext)
method will be called on it.
Note that Ignite cannot guarantee that the service exits from
Service.execute(org.apache.ignite.services.ServiceContext)
method whenever Service.cancel(org.apache.ignite.services.ServiceContext)
is called. It is up to the user to make sure that the service code properly reacts to cancellations.
Supports asynchronous execution (see IgniteAsyncSupport
).
name
- Name of service to cancel.IgniteException
- If failed to cancel service.IgniteFuture<Void> cancelAsync(String name)
Service.cancel(org.apache.ignite.services.ServiceContext)
method will be called on it.
Note that Ignite cannot guarantee that the service exits from
Service.execute(org.apache.ignite.services.ServiceContext)
method whenever Service.cancel(org.apache.ignite.services.ServiceContext)
is called. It is up to the user to
make sure that the service code properly reacts to cancellations.
name
- Name of service to cancel.@IgniteAsyncSupported void cancelAll(Collection<String> names) throws IgniteException
Note that depending on user logic, it may still take extra time for a service to finish execution, even after it was cancelled.
Supports asynchronous execution (see IgniteAsyncSupport
).
names
- Names of services to cancel.IgniteException
- If failed to cancel services.IgniteFuture<Void> cancelAllAsync(Collection<String> names)
Note that depending on user logic, it may still take extra time for a service to finish execution, even after it was cancelled.
names
- Names of services to cancel.@IgniteAsyncSupported void cancelAll() throws IgniteException
Note that depending on user logic, it may still take extra time for a service to finish execution, even after it was cancelled.
Supports asynchronous execution (see IgniteAsyncSupport
).
IgniteException
- If failed to cancel services.IgniteFuture<Void> cancelAllAsync()
Note that depending on user logic, it may still take extra time for a service to finish execution, even after it was cancelled.
Collection<ServiceDescriptor> serviceDescriptors()
@Deprecated <T> T service(String name)
serviceProxy(String, Class, boolean)
. References to local services
corrupt the service statistics and bring no real performance optimization.T
- Service typename
- Service name.ServiceConfiguration.setStatisticsEnabled(boolean)
@Deprecated <T> Collection<T> services(String name)
serviceProxy(String, Class, boolean)
. References to local services
corrupt the service statistics and bring no real performance optimization.T
- Service type.name
- Service name.ServiceConfiguration.setStatisticsEnabled(boolean)
<T> T serviceProxy(String name, Class<? super T> svcItf, boolean sticky) throws IgniteException
T
- Service type.name
- Service name.svcItf
- Interface for the service.sticky
- Whether or not Ignite should always contact the same remote
service or try to load-balance between services.IgniteException
- If failed to create service proxy.<T> T serviceProxy(String name, Class<? super T> svcItf, boolean sticky, long timeout) throws IgniteException
T
- Service type.name
- Service name.svcItf
- Interface for the service.sticky
- Whether or not Ignite should always contact the same remote
service or try to load-balance between services.timeout
- If greater than 0 created proxy will wait for service availability only specified time,
and will limit remote service invocation time.IgniteException
- If failed to create service proxy.<T> T serviceProxy(String name, Class<? super T> svcItf, boolean sticky, ServiceCallContext callCtx) throws IgniteException
T
- Service type.name
- Service name.svcItf
- Interface for the service.sticky
- Whether or not Ignite should always contact the same remote
service or try to load-balance between services.callCtx
- Service call context.IgniteException
- If failed to create service proxy.ServiceCallContext
<T> T serviceProxy(String name, Class<? super T> svcItf, boolean sticky, ServiceCallContext callCtx, long timeout) throws IgniteException
T
- Service type.name
- Service name.svcItf
- Interface for the service.sticky
- Whether or not Ignite should always contact the same remote
service or try to load-balance between services.callCtx
- Service call context.timeout
- If greater than 0 created proxy will wait for service availability only specified time,
and will limit remote service invocation time.IgniteException
- If failed to create service proxy.ServiceCallContext
@Deprecated IgniteServices withAsync()
withAsync
in interface IgniteAsyncSupport
Follow @ApacheIgnite
Ignite Database and Caching Platform : ver. 2.16.0 Release Date : December 15 2023