FunctionService (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode.cache.execute, class: FunctionService

Package org.apache.geode.cache.execute

# Class FunctionService

java.lang.Object
org.apache.geode.cache.execute.FunctionService

public class FunctionService extends Object
Provides the entry point into execution of user defined Functions.

Function execution provides a means to route application behaviour to data or more generically to peers in a `DistributedSystem` or servers in a `Pool`.

Since:
  GemFire 6.0

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `FunctionService(org.apache.geode.internal.cache.execute.FunctionExecutionService functionExecutionService)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Function`
  `getFunction(String functionId)`
  Returns the `Function` defined by the functionId, returns null if no function is found for the specified functionId
  `static Map<String,Function>`
  `getRegisteredFunctions()`
  Returns all locally registered functions
  `static boolean`
  `isRegistered(String functionId)`
  Returns true if the function is registered to FunctionService
  `static Execution`
  `onMember(String... groups)`
  Returns an `Execution` object that can be used to execute a data independent function on one member of each group provided.
  `static Execution`
  `onMember(DistributedMember distributedMember)`
  Returns an `Execution` object that can be used to execute a data independent function on a `DistributedMember`.
  `static Execution`
  `onMembers(String... groups)`
  Returns an `Execution` object that can be used to execute a data independent function on all peer members.
  `static Execution`
  `onMembers(Set<DistributedMember> distributedMembers)`
  Returns an `Execution` object that can be used to execute a data independent function on the set of `DistributedMember`s.
  `static Execution`
  `onRegion(Region region)`
  Returns an `Execution` object that can be used to execute a data dependent function on the specified Region.
  When invoked from a GemFire client, the method returns an Execution instance that sends a message to one of the connected servers as specified by the `Pool` for the region.
  `static Execution`
  `onServer(Pool pool)`
  Returns an `Execution` object that can be used to execute a data independent function on a server in the provided `Pool`.
  `static Execution`
  `onServer(RegionService regionService)`
  Returns an `Execution` object that can be used to execute a data independent function on a server that the given cache is connected to.
  `static Execution`
  `onServers(Pool pool)`
  Returns an `Execution` object that can be used to execute a data independent function on all the servers in the provided `Pool`.
  `static Execution`
  `onServers(RegionService regionService)`
  Returns an `Execution` object that can be used to execute a data independent function on all the servers that the given cache is connected to.
  `static void`
  `registerFunction(Function function)`
  Registers the given `Function` with the `FunctionService` using `Function.getId()`.
  `static void`
  `unregisterFunction(String functionId)`
  Unregisters the given `Function` with the `FunctionService` using `Function.getId()`.

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

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

- ## Constructor Details

  - ### FunctionService

    protected FunctionService(org.apache.geode.internal.cache.execute.FunctionExecutionService functionExecutionService)

- ## Method Details

  - ### onRegion

    public static Execution onRegion(Region region)
    Returns an `Execution` object that can be used to execute a data dependent function on the specified Region.
    When invoked from a GemFire client, the method returns an Execution instance that sends a message to one of the connected servers as specified by the `Pool` for the region.
    Depending on the filters setup on the `Execution`, the function is executed on all GemFire members that define the data region, or a subset of members. `Execution.withFilter(Set)`). For DistributedRegions with DataPolicy.NORMAL, it throws UnsupportedOperationException. For DistributedRegions with DataPolicy.EMPTY, execute the function on any random member which has DataPolicy.REPLICATE
    . For DistributedRegions with DataPolicy.REPLICATE, execute the function locally. For Regions with DataPolicy.PARTITION, it executes on members where the data resides as specified by the filter.
    Parameters:
      `region` - the `Region` on which the returned `Execution` will execute functions
    Returns:
      an `Execution` object that can be used to execute a data dependent function on the specified `Region`
    Throws:
      `FunctionException` - if the region passed in is null
    Since:
      GemFire 6.0

  - ### onServer

    public static Execution onServer(Pool pool)
    Returns an `Execution` object that can be used to execute a data independent function on a server in the provided `Pool`.

    If the server goes down while dispatching or executing the function, an Exception will be thrown.

    Parameters:
      `pool` - from which to chose a server for execution
    Returns:
      an `Execution` object that can be used to execute a data independent function on a server in the provided `Pool`
    Throws:
      `FunctionException` - if Pool instance passed in is null
    Since:
      GemFire 6.0

  - ### onServers

    public static Execution onServers(Pool pool)
    Returns an `Execution` object that can be used to execute a data independent function on all the servers in the provided `Pool`. If one of the servers goes down while dispatching or executing the function on the server, an Exception will be thrown.
    Parameters:
      `pool` - the set of servers to execute the function
    Returns:
      an `Execution` object that can be used to execute a data independent function on all the servers in the provided `Pool`
    Throws:
      `FunctionException` - if Pool instance passed in is null
    Since:
      GemFire 6.0

  - ### onServer

    public static Execution onServer(RegionService regionService)
    Returns an `Execution` object that can be used to execute a data independent function on a server that the given cache is connected to.

    If the server goes down while dispatching or executing the function, an Exception will be thrown.

    Parameters:
      `regionService` - obtained from `ClientCacheFactory.create()` or `ClientCache.createAuthenticatedView(Properties)`.
    Returns:
      an `Execution` object that can be used to execute a data independent function on a server that the given cache is connected to
    Throws:
      `FunctionException` - if cache is null, is not on a client, or it does not have a default pool
    Since:
      GemFire 6.5

  - ### onServers

    public static Execution onServers(RegionService regionService)
    Returns an `Execution` object that can be used to execute a data independent function on all the servers that the given cache is connected to. If one of the servers goes down while dispatching or executing the function on the server, an Exception will be thrown.
    Parameters:
      `regionService` - obtained from `ClientCacheFactory.create()` or `ClientCache.createAuthenticatedView(Properties)`.
    Returns:
      an `Execution` object that can be used to execute a data independent function on all the servers that the given cache is connected to
    Throws:
      `FunctionException` - if cache is null, is not on a client, or it does not have a default pool
    Since:
      GemFire 6.5

  - ### onMember

    public static Execution onMember(DistributedMember distributedMember)
    Returns an `Execution` object that can be used to execute a data independent function on a `DistributedMember`. If the member is not found, executing the function will throw an Exception. If the member goes down while dispatching or executing the function on the member, an Exception will be thrown.
    Parameters:
      `distributedMember` - defines a member in the distributed system
    Returns:
      an `Execution` object that can be used to execute a data independent function on a `DistributedMember`
    Throws:
      `FunctionException` - if distributedMember is null
    Since:
      GemFire 7.0

  - ### onMembers

    public static Execution onMembers(String... groups)
    Returns an `Execution` object that can be used to execute a data independent function on all peer members. If the optional groups parameter is provided, function is executed on all members that belong to the provided groups.

    If one of the members goes down while dispatching or executing the function on the member, an Exception will be thrown.

    Parameters:
      `groups` - optional list of GemFire configuration property "groups" (see `groups`) on which to execute the function. Function will be executed on all members of each group
    Returns:
      an `Execution` object that can be used to execute a data independent function on all peer members
    Throws:
      `FunctionException` - if no members are found belonging to the provided groups
    Since:
      GemFire 7.0

  - ### onMembers

    public static Execution onMembers(Set<DistributedMember> distributedMembers)
    Returns an `Execution` object that can be used to execute a data independent function on the set of `DistributedMember`s. If one of the members goes down while dispatching or executing the function, an Exception will be thrown.
    Parameters:
      `distributedMembers` - set of distributed members on which `Function` to be executed
    Returns:
      an `Execution` object that can be used to execute a data independent function on the set of `DistributedMember`s provided
    Throws:
      `FunctionException` - if distributedMembers is null
    Since:
      GemFire 7.0

  - ### onMember

    public static Execution onMember(String... groups)
    Returns an `Execution` object that can be used to execute a data independent function on one member of each group provided.
    Parameters:
      `groups` - list of GemFire configuration property "groups" (see `groups`) on which to execute the function. Function will be executed on one member of each group
    Returns:
      an `Execution` object that can be used to execute a data independent function on one member of each group provided
    Throws:
      `FunctionException` - if no members are found belonging to the provided groups
    Since:
      GemFire 7.0

  - ### getFunction

    public static Function getFunction(String functionId)
    Returns the `Function` defined by the functionId, returns null if no function is found for the specified functionId
    Parameters:
      `functionId` - a functionId
    Returns:
      the `Function` defined by the functionId or null if no function is found for the specified functionId
    Throws:
      `FunctionException` - if functionID passed is null
    Since:
      GemFire 6.0

  - ### registerFunction

    public static void registerFunction(Function function)
    Registers the given `Function` with the `FunctionService` using `Function.getId()`.

    Registering a function allows execution of the function using `Execution.execute(String)`. Every member that could execute a function using its `Function.getId()` should register the function.

    Parameters:
      `function` - the `Function` to register
    Throws:
      `FunctionException` - if function instance passed is null or Function.getId() returns null
    Since:
      GemFire 6.0

  - ### unregisterFunction

    public static void unregisterFunction(String functionId)
    Unregisters the given `Function` with the `FunctionService` using `Function.getId()`.

    Parameters:
      `functionId` - the ID of the function
    Throws:
      `FunctionException` - if function instance passed is null or Function.getId() returns null
    Since:
      GemFire 6.0

  - ### isRegistered

    public static boolean isRegistered(String functionId)
    Returns true if the function is registered to FunctionService
    Parameters:
      `functionId` - the ID of the function
    Returns:
      whether the function is registered to FunctionService
    Throws:
      `FunctionException` - if function instance passed is null or Function.getId() returns null
    Since:
      GemFire 6.0

  - ### getRegisteredFunctions

    public static Map<String,Function> getRegisteredFunctions()
    Returns all locally registered functions
    Returns:
      A view of registered functions as a Map of `Function.getId()` to `Function`
    Since:
      GemFire 6.0