CacheServer (Apache Geode 1.15.4)

org.apache.geode.cache.server

## Interface CacheServer

-     public interface CacheServer

  A cache server that serves the contents of a `Cache` to client VMs in another distributed system via a socket. A cache server is used in conjunction with a client `Pool` to connect two regions that reside in different distributed systems.
  Since:
    GemFire 5.7
  See Also:
    `Cache.addCacheServer()`, `Cache.getCacheServers()`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_BIND_ADDRESS` The default ip address or host name that the cache server's socket will listen on for client connections.
    `static String[]` | `DEFAULT_GROUPS` Deprecated. as of 7.0 use the groups gemfire property
    `static String` | `DEFAULT_HOSTNAME_FOR_CLIENTS` The default ip address or host name that will be given to clients as the host this cache server is listening on.
    `static long` | `DEFAULT_LOAD_POLL_INTERVAL` The default frequency at which to poll the load probe for the load on this cache server.
    `static ServerLoadProbe` | `DEFAULT_LOAD_PROBE` The default load balancing probe.
    `static int` | `DEFAULT_MAX_CONNECTIONS` The default number of sockets accepted by a CacheServer.
    `static int` | `DEFAULT_MAX_THREADS` The default limit to the maximum number of cache server threads that can be created to service client requests.
    `static int` | `DEFAULT_MAXIMUM_MESSAGE_COUNT` The default maximum number of messages that can be enqueued in a client-queue.
    `static int` | `DEFAULT_MAXIMUM_TIME_BETWEEN_PINGS` The default maximum amount of time between client pings.
    `static int` | `DEFAULT_MESSAGE_TIME_TO_LIVE` The default time (in seconds ) after which a message in the client queue will expire.
    `static boolean` | `DEFAULT_NOTIFY_BY_SUBSCRIPTION` The default notify-by-subscription value which tells the `CacheServer` whether or not to notify clients based on key subscription.
    `static int` | `DEFAULT_PORT` The default port on which a `CacheServer` is configured to serve.
    `static int` | `DEFAULT_SOCKET_BUFFER_SIZE` The default socket buffer size for socket buffers from the cache server to the client.
    `static boolean` | `DEFAULT_TCP_NO_DELAY` The default setting for outgoing tcp/ip connections.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Set<ClientSession>` | `getAllClientSessions()` Returns a set of all `ClientSession`s
    `String` | `getBindAddress()` Returns a string representing the ip address or host name that this cache server will listen on.
    `ClientSession` | `getClientSession(DistributedMember member)` Returns the `ClientSession` associated with the `DistributedMember`
    `ClientSession` | `getClientSession(String durableClientId)` Returns the `ClientSession` associated with the durable client id
    `ClientSubscriptionConfig` | `getClientSubscriptionConfig()` Get the ClientSubscriptionConfig for this cache server.
    `String[]` | `getGroups()` Deprecated. as of 7.0 use the groups gemfire property
    `String` | `getHostnameForClients()` Returns a string representing the ip address or host name that server locators will tell clients that this cache server is listening on.
    `Set<InterestRegistrationListener>` | `getInterestRegistrationListeners()` Returns a read-only set of `InterestRegistrationListener`s registered with this notifier.
    `long` | `getLoadPollInterval()` Get the frequency in milliseconds to poll the load probe on this cache server.
    `ServerLoadProbe` | `getLoadProbe()` Get the load probe for this cache server.
    `int` | `getMaxConnections()` Returns the maximum allowed client connections
    `int` | `getMaximumMessageCount()` Returns the maximum number of messages that can be enqueued in a client-queue.
    `int` | `getMaximumTimeBetweenPings()` Returns the maximum amount of time between client pings.
    `int` | `getMaxThreads()` Returns the maximum number of threads allowed in this cache server to service client requests.
    `int` | `getMessageTimeToLive()` Returns the time (in seconds ) after which a message in the client queue will expire.
    `boolean` | `getNotifyBySubscription()` Deprecated. as of 6.0.1. This method is no more in use, by default notifyBySubscription attribute is set to true.
    `int` | `getPort()` Returns the port on which this cache server listens for clients.
    `int` | `getSocketBufferSize()` Returns the configured buffer size of the socket connection for this `CacheServer`.
    `boolean` | `getTcpNoDelay()` Get the outgoing connection tcp-no-delay setting.
    `boolean` | `isRunning()` Returns whether this cache server is running
    `void` | `registerInterestRegistrationListener(InterestRegistrationListener listener)` Registers a new `InterestRegistrationListener` with the set of `InterestRegistrationListener`s.
    `void` | `setBindAddress(String address)` Sets the ip address or host name that this cache server is to listen on for client connections.
    `void` | `setGroups(String[] groups)` Deprecated. as of 7.0 use the groups gemfire property
    `void` | `setHostnameForClients(String name)` Sets the ip address or host name that this cache server is to listen on for client connections.
    `void` | `setLoadPollInterval(long loadPollInterval)` Set the frequency in milliseconds to poll the load probe on this cache server
    `void` | `setLoadProbe(ServerLoadProbe loadProbe)` Set the load probe for this cache server.
    `void` | `setMaxConnections(int maxCons)` Sets the maximum number of client connections allowed.
    `void` | `setMaximumMessageCount(int maxMessageCount)` Sets maximum number of messages that can be enqueued in a client-queue.
    `void` | `setMaximumTimeBetweenPings(int maximumTimeBetweenPings)` Sets the maximum amount of time between client pings.
    `void` | `setMaxThreads(int maxThreads)` Sets the maximum number of threads allowed in this cache server to service client requests.
    `void` | `setMessageTimeToLive(int messageTimeToLive)` Sets the time (in seconds ) after which a message in the client queue will expire.
    `void` | `setNotifyBySubscription(boolean b)` Deprecated. as of 6.0.1. This method is no longer in use, by default notifyBySubscription attribute is set to true.
    `void` | `setPort(int port)` Sets the port on which this cache server listens for clients.
    `void` | `setSocketBufferSize(int socketBufferSize)` Sets the buffer size in bytes of the socket connection for this `CacheServer`.
    `void` | `setTcpNoDelay(boolean noDelay)` Configures the tcpNoDelay setting of sockets used to send messages to clients.
    `void` | `start()` Starts this cache server.
    `void` | `stop()` Stops this cache server.
    `void` | `unregisterInterestRegistrationListener(InterestRegistrationListener listener)` Unregisters an existing `InterestRegistrationListener` from the set of `InterestRegistrationListener`s.

- - ### Field Detail

    - #### DEFAULT_PORT

          static final int DEFAULT_PORT

      The default port on which a `CacheServer` is configured to serve.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_CONNECTIONS

          static final int DEFAULT_MAX_CONNECTIONS

      The default number of sockets accepted by a CacheServer. When the maximum is reached the cache server will stop accepting new connections. Current value: 800
      Since:
        GemFire 5.7
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_THREADS

          static final int DEFAULT_MAX_THREADS

      The default limit to the maximum number of cache server threads that can be created to service client requests. Once this number of threads exist then connections must share the same thread to service their request. A selector is used to detect client connection requests and dispatch them to the thread pool. The default of `0` causes a thread to be bound to every connection and to be dedicated to detecting client requests on that connection. A selector is not used in this default mode. Current value: 0
      Since:
        GemFire 5.7
      See Also:
        Constant Field Values

    - #### DEFAULT_NOTIFY_BY_SUBSCRIPTION

          static final boolean DEFAULT_NOTIFY_BY_SUBSCRIPTION

      The default notify-by-subscription value which tells the `CacheServer` whether or not to notify clients based on key subscription.
      See Also:
        Constant Field Values

    - #### DEFAULT_SOCKET_BUFFER_SIZE

          static final int DEFAULT_SOCKET_BUFFER_SIZE

      The default socket buffer size for socket buffers from the cache server to the client.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAXIMUM_TIME_BETWEEN_PINGS

          static final int DEFAULT_MAXIMUM_TIME_BETWEEN_PINGS

      The default maximum amount of time between client pings. This value is used by the `ClientHealthMonitor` to determine the health of this `CacheServer`'s clients.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAXIMUM_MESSAGE_COUNT

          static final int DEFAULT_MAXIMUM_MESSAGE_COUNT

      The default maximum number of messages that can be enqueued in a client-queue.
      See Also:
        Constant Field Values

    - #### DEFAULT_MESSAGE_TIME_TO_LIVE

          static final int DEFAULT_MESSAGE_TIME_TO_LIVE

      The default time (in seconds ) after which a message in the client queue will expire.
      See Also:
        Constant Field Values

    - #### DEFAULT_GROUPS

          @Deprecated
           @Immutable
          static final String[] DEFAULT_GROUPS

      Deprecated. as of 7.0 use the groups gemfire property
      The default list of server groups a cache server belongs to. The current default is an empty list.
      Since:
        GemFire 5.7

    - #### DEFAULT_LOAD_PROBE

          @Immutable
          static final ServerLoadProbe DEFAULT_LOAD_PROBE

      The default load balancing probe. The default load balancing probe reports the connections counts of this cache server.
      Since:
        GemFire 5.7

    - #### DEFAULT_LOAD_POLL_INTERVAL

          static final long DEFAULT_LOAD_POLL_INTERVAL

      The default frequency at which to poll the load probe for the load on this cache server. Defaults to 5000 (5 seconds).
      Since:
        GemFire 5.7
      See Also:
        Constant Field Values

    - #### DEFAULT_BIND_ADDRESS

          static final String DEFAULT_BIND_ADDRESS

      The default ip address or host name that the cache server's socket will listen on for client connections. The current default is an empty string.
      Since:
        GemFire 5.7
      See Also:
        Constant Field Values

    - #### DEFAULT_HOSTNAME_FOR_CLIENTS

          static final String DEFAULT_HOSTNAME_FOR_CLIENTS

      The default ip address or host name that will be given to clients as the host this cache server is listening on. The current default is an empty string.
      Since:
        GemFire 5.7
      See Also:
        Constant Field Values

    - #### DEFAULT_TCP_NO_DELAY

          static final boolean DEFAULT_TCP_NO_DELAY

      The default setting for outgoing tcp/ip connections. By default the product enables tcpNoDelay.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getPort

          int getPort()

      Returns the port on which this cache server listens for clients.
      Returns:
        the port on which this cache server listens for clients

    - #### setPort

          void setPort(int port)

      Sets the port on which this cache server listens for clients.
      Parameters:
        `port` - the port on which this cache server listens for clients
      Throws:
        `IllegalStateException` - If this cache server is running

    - #### getBindAddress

          String getBindAddress()

      Returns a string representing the ip address or host name that this cache server will listen on.
      Returns:
        the ip address or host name that this cache server is to listen on
      Since:
        GemFire 5.7
      See Also:
        `DEFAULT_BIND_ADDRESS`

    - #### setBindAddress

          void setBindAddress(String address)

      Sets the ip address or host name that this cache server is to listen on for client connections.

      Setting a specific bind address will cause the cache server to always use this address and ignore any address specified by "server-bind-address" or "bind-address" in the `gemfire.properties` file (see `DistributedSystem` for a description of these properties).

      The value `""` does not override the `gemfire.properties`. It will cause the local machine's default address to be listened on if the properties file does not specify and address. If you wish to override the properties and want to have your cache server bind to all local addresses then use this bind address `"0.0.0.0"`.

      A `null` value will be treated the same as the default `""`.

      Parameters:
        `address` - the ip address or host name that this cache server is to listen on
      Since:
        GemFire 5.7
      See Also:
        `DEFAULT_BIND_ADDRESS`

    - #### getHostnameForClients

          String getHostnameForClients()

      Returns a string representing the ip address or host name that server locators will tell clients that this cache server is listening on.
      Returns:
        the ip address or host name to give to clients so they can connect to this cache server
      Since:
        GemFire 5.7
      See Also:
        `DEFAULT_HOSTNAME_FOR_CLIENTS`

    - #### setHostnameForClients

          void setHostnameForClients(String name)

      Sets the ip address or host name that this cache server is to listen on for client connections.

      Setting a specific hostname-for-clients will cause server locators to use this value when telling clients how to connect to this cache server. This is useful in the case where the cache server may refer to itself with one hostname, but the clients need to use a different hostname to find the cache server.

      The value `""` causes the `bind-address` to be given to clients.

      A `null` value will be treated the same as the default `""`.

      Parameters:
        `name` - the ip address or host name that will be given to clients so they can connect to this cache server
      Since:
        GemFire 5.7
      See Also:
        `DEFAULT_HOSTNAME_FOR_CLIENTS`

    - #### setNotifyBySubscription

          @Deprecated
          void setNotifyBySubscription(boolean b)

      Deprecated. as of 6.0.1. This method is no longer in use, by default notifyBySubscription attribute is set to true.
      Sets whether this cache server should notify clients based on key subscription. If false, then an update to any key on the cache server causes an update to be sent to all clients. This update does not push the actual data to the clients. Instead, it causes the client to locally invalidate or destroy the corresponding entry. The next time the client requests the key, it goes to the cache server for the value. If true, then an update to any key on the cache server causes an update to be sent to only those clients who have registered interest in that key. Other clients are not notified of the change. In addition, the actual value is pushed to the client. The client does not need to request the new value from the cache server.
      Parameters:
        `b` - whether this cache server should notify clients based on key subscription
      Since:
        GemFire 4.2

    - #### getNotifyBySubscription

          @Deprecated
          boolean getNotifyBySubscription()

      Deprecated. as of 6.0.1. This method is no more in use, by default notifyBySubscription attribute is set to true.
      Answers whether this cache server should notify clients based on key subscription.
      Returns:
        whether this cache server should notify clients based on key subscription
      Since:
        GemFire 4.2

    - #### setSocketBufferSize

          void setSocketBufferSize(int socketBufferSize)

      Sets the buffer size in bytes of the socket connection for this `CacheServer`. The default is 32768 bytes.
      Parameters:
        `socketBufferSize` - The size in bytes of the socket buffer
      Since:
        GemFire 4.2.1

    - #### getSocketBufferSize

          int getSocketBufferSize()

      Returns the configured buffer size of the socket connection for this `CacheServer`. The default is 32768 bytes.
      Returns:
        the configured buffer size of the socket connection for this `CacheServer`
      Since:
        GemFire 4.2.1

    - #### setMaximumTimeBetweenPings

          void setMaximumTimeBetweenPings(int maximumTimeBetweenPings)

      Sets the maximum amount of time between client pings. This value is used by the `ClientHealthMonitor` to determine the health of this `CacheServer`'s clients. The default is 60000 ms.
      Parameters:
        `maximumTimeBetweenPings` - The maximum amount of time between client pings
      Since:
        GemFire 4.2.3

    - #### getMaximumTimeBetweenPings

          int getMaximumTimeBetweenPings()

      Returns the maximum amount of time between client pings. This value is used by the `ClientHealthMonitor` to determine the health of this `CacheServer`'s clients. The default is 60000 ms.
      Returns:
        the maximum amount of time between client pings.
      Since:
        GemFire 4.2.3

    - #### start

          void start()
              throws IOException

      Starts this cache server. Once the cache server is running, its configuration cannot be changed.
      Throws:
        `IOException` - If an error occurs while starting the cache server

    - #### isRunning

          boolean isRunning()

      Returns whether this cache server is running
      Returns:
        whether this cache server is running

    - #### stop

          void stop()

      Stops this cache server. Note that the `CacheServer` can be reconfigured and restarted if desired.

    - #### getMaxConnections

          int getMaxConnections()

      Returns the maximum allowed client connections
      Returns:
        the maximum number of client connections allowed

    - #### setMaxConnections

          void setMaxConnections(int maxCons)

      Sets the maximum number of client connections allowed. When the maximum is reached the cache server will stop accepting connections.
      Parameters:
        `maxCons` - the maximum number of client connections allowed
      See Also:
        `DEFAULT_MAX_CONNECTIONS`

    - #### getMaxThreads

          int getMaxThreads()

      Returns the maximum number of threads allowed in this cache server to service client requests. The default of `0` causes the cache server to dedicate a thread for every client connection.
      Returns:
        the maximum number of threads allowed in this cache server to service client requests
      Since:
        GemFire 5.1

    - #### setMaxThreads

          void setMaxThreads(int maxThreads)

      Sets the maximum number of threads allowed in this cache server to service client requests. The default of `0` causes the cache server to dedicate a thread for every client connection.
      Parameters:
        `maxThreads` - the maximum number of threads allowed in this cache server to service client requests
      Since:
        GemFire 5.1
      See Also:
        `DEFAULT_MAX_THREADS`

    - #### getMaximumMessageCount

          int getMaximumMessageCount()

      Returns the maximum number of messages that can be enqueued in a client-queue.
      Returns:
        the maximum number of messages that can be enqueued in a client-queue

    - #### setMaximumMessageCount

          void setMaximumMessageCount(int maxMessageCount)

      Sets maximum number of messages that can be enqueued in a client-queue.
      Parameters:
        `maxMessageCount` - the maximum number of messages that can be enqueued in a client-queue
      See Also:
        `DEFAULT_MAXIMUM_MESSAGE_COUNT`

    - #### getMessageTimeToLive

          int getMessageTimeToLive()

      Returns the time (in seconds ) after which a message in the client queue will expire.
      Returns:
        the time (in seconds ) after which a message in the client queue will expire

    - #### setMessageTimeToLive

          void setMessageTimeToLive(int messageTimeToLive)

      Sets the time (in seconds ) after which a message in the client queue will expire.
      Parameters:
        `messageTimeToLive` - the time (in seconds ) after which a message in the client queue will expire
      See Also:
        `DEFAULT_MESSAGE_TIME_TO_LIVE`

    - #### setGroups

          @Deprecated
          void setGroups(String[] groups)

      Deprecated. as of 7.0 use the groups gemfire property
      Sets the list of server groups this cache server will belong to. By default cache servers belong to the default global server group which all cache servers always belong to.
      Parameters:
        `groups` - possibly empty array of `String` where each string is a server groups that this cache server will be a member of.
      Since:
        GemFire 5.7
      See Also:
        `DEFAULT_GROUPS`

    - #### getGroups

          @Deprecated
          String[] getGroups()

      Deprecated. as of 7.0 use the groups gemfire property
      Returns the list of server groups that this cache server belongs to.
      Returns:
        a possibly empty array of `String`s where each string is a server group. Modifying this array will not change the server groups that this cache server belongs to.
      Since:
        GemFire 5.7

    - #### getLoadProbe

          ServerLoadProbe getLoadProbe()

      Get the load probe for this cache server. See `ServerLoadProbe` for details on the load probe.
      Returns:
        the load probe used by this cache server.
      Since:
        GemFire 5.7

    - #### setLoadProbe

          void setLoadProbe(ServerLoadProbe loadProbe)

      Set the load probe for this cache server. See `ServerLoadProbe` for details on how to implement a load probe.
      Parameters:
        `loadProbe` - the load probe to use for this cache server.
      Since:
        GemFire 5.7

    - #### getLoadPollInterval

          long getLoadPollInterval()

      Get the frequency in milliseconds to poll the load probe on this cache server.
      Returns:
        the frequency in milliseconds that we will poll the load probe.

    - #### setLoadPollInterval

          void setLoadPollInterval(long loadPollInterval)

      Set the frequency in milliseconds to poll the load probe on this cache server
      Parameters:
        `loadPollInterval` - the frequency in milliseconds to poll the load probe. Must be greater than 0.

    - #### getTcpNoDelay

          boolean getTcpNoDelay()

      Get the outgoing connection tcp-no-delay setting. If it is set to true (the default) this cache server is configured to enable tcp-no-delay on outgoing tcp/ip sockets. If it is set to false this cache server is configured to disable tcp-no-delay on outgoing sockets.
      Returns:
        the tcp-no-delay setting

    - #### setTcpNoDelay

          void setTcpNoDelay(boolean noDelay)

      Configures the tcpNoDelay setting of sockets used to send messages to clients. TcpNoDelay is enabled by default.
      Parameters:
        `noDelay` - if false, sets tcp-no-delay to false on out-going connections

    - #### getClientSubscriptionConfig

          ClientSubscriptionConfig getClientSubscriptionConfig()

      Get the ClientSubscriptionConfig for this cache server. See `ClientSubscriptionConfig` for details on the client subscription configuration.
      Returns:
        the ClientSubscriptionConfig for this cache server
      Since:
        GemFire 5.7

    - #### getClientSession

          ClientSession getClientSession(DistributedMember member)

      Returns the `ClientSession` associated with the `DistributedMember`
      Parameters:
        `member` - a `DistributedMember`
      Returns:
        the `ClientSession` associated with the `DistributedMember`
      Since:
        GemFire 6.0

    - #### getClientSession

          ClientSession getClientSession(String durableClientId)

      Returns the `ClientSession` associated with the durable client id
      Parameters:
        `durableClientId` - a durable client id
      Returns:
        the `ClientSession` associated with the durable
      Since:
        GemFire 6.0

    - #### getAllClientSessions

          Set<ClientSession> getAllClientSessions()

      Returns a set of all `ClientSession`s
      Returns:
        a set of all `ClientSession`s
      Since:
        GemFire 6.0

    - #### registerInterestRegistrationListener

          void registerInterestRegistrationListener(InterestRegistrationListener listener)

      Registers a new `InterestRegistrationListener` with the set of `InterestRegistrationListener`s.
      Parameters:
        `listener` - The `InterestRegistrationListener` to register
      Since:
        GemFire 6.0

    - #### unregisterInterestRegistrationListener

          void unregisterInterestRegistrationListener(InterestRegistrationListener listener)

      Unregisters an existing `InterestRegistrationListener` from the set of `InterestRegistrationListener`s.
      Parameters:
        `listener` - The `InterestRegistrationListener` to unregister
      Since:
        GemFire 6.0

    - #### getInterestRegistrationListeners

          Set<InterestRegistrationListener> getInterestRegistrationListeners()

      Returns a read-only set of `InterestRegistrationListener`s registered with this notifier.
      Returns:
        a read-only set of `InterestRegistrationListener`s registered with this notifier
      Since:
        GemFire 6.0