com.gemstone.gemfire.cache.util.GatewayHub Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of gemfire-core Show documentation
Show all versions of gemfire-core Show documentation
SnappyData store based off Pivotal GemFireXD
/*
* Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you
* may not use this file except in compliance with the License. You
* may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
* implied. See the License for the specific language governing
* permissions and limitations under the License. See accompanying
* LICENSE file.
*/
package com.gemstone.gemfire.cache.util;
import com.gemstone.gemfire.CancelCriterion;
import com.gemstone.gemfire.cache.Cache;
import com.gemstone.gemfire.cache.GatewayException;
import java.io.IOException;
import java.util.List;
/**
* A GatewayHub manages a collection of Gateways. It
* has three primary purposes, namely:
*
* - To start as primary or secondary
*
- To distribute local
EntryEvents to its Gateways
* which in turn queue them for distribution to remote sites or
* GatewayEventListeners as GatewayEvents
* - To start a listener to accept incoming
GatewayEvents from
* remote sites
*
*
*
* @see com.gemstone.gemfire.cache.util.Gateway
* @see com.gemstone.gemfire.cache.util.GatewayEvent
* @see com.gemstone.gemfire.cache.util.GatewayEventListener
*
* @since 4.2
*/
public interface GatewayHub {
/**
* The default buffer size (32768 bytes) for socket buffers from a sending
* GatewayHub to the receiving one.
*/
public static final int DEFAULT_SOCKET_BUFFER_SIZE = 32768;
/**
* The default maximum amount of time (60000 ms) between client pings. This
* value is used by the ClientHealthMonitor to determine the
* health of this GatewayHub's clients.
*/
public static final int DEFAULT_MAXIMUM_TIME_BETWEEN_PINGS = 60000;
/**
* The 'none' startup policy.
* This setting (the default) means that the VM will attempt to become the
* primary GatewayHub. If it can become the primary
* GatewayHub, it will. If not, then it will become a secondary
* GatewayHub.
*/
public static final String STARTUP_POLICY_NONE = "none";
/**
* The 'primary' startup policy.
* This setting means that the VM will attempt to become the primary
* GatewayHub. If it can become the primary
* GatewayHub, it will. If not, then it will log a warning
* and become a secondary GatewayHub.
*/
public static final String STARTUP_POLICY_PRIMARY = "primary";
/**
* The 'secondary' startup policy.
* This setting means that the VM will wait for
* {@link #STARTUP_POLICY_SECONDARY_WAIT} milliseconds for another VM to
* start as the primary GatewayHub. If another VM does start as
* the primary GatewayHub within
* {@link #STARTUP_POLICY_SECONDARY_WAIT} milliseconds, then this VM will
* start as a secondary GatewayHub. If not, then it will log a
* warning and start as the primary GatewayHub.
*/
public static final String STARTUP_POLICY_SECONDARY = "secondary";
/**
* The default startup policy ({@link #STARTUP_POLICY_NONE}).
*/
public static final String DEFAULT_STARTUP_POLICY = STARTUP_POLICY_NONE;
/**
* The amount of time in milliseconds a GatewayHub defined with
* secondary startup policy waits for a primary GatewayHub to
* start before logging a warning and becoming the primary
* GatewayHub itself. This value is 60000 milliseconds.
*/
public static final int STARTUP_POLICY_SECONDARY_WAIT = 60000;
/**
* The default value (false) for manually starting a GatewayHub.
*
* @since 5.7
*/
public static final boolean DEFAULT_MANUAL_START = false;
/**
* The default value (-1) for this GatewayHub's port.
* This is not a valid port for creating connections and should only be
* used in cases in which the GatewayHub does not accept
* any connections, such as database write behind applications.
* @since 5.7
*/
public static final int DEFAULT_PORT = -1;
/**
* The default ip address or host name that this GatewayHub's
* socket will listen on for connections.
* The current default is null.
* @since 6.5.1
*/
public static final String DEFAULT_BIND_ADDRESS = null;
/**
* Returns the port on which this GatewayHub listens for
* remote connections
* @return the port on which this GatewayHub listens for
* remote connections
*/
public int getPort();
/**
* Sets the port on which this GatewayHub listens for
* remote connections
* @param port The port on which this GatewayHub listens
* for remote connections
*/
public void setPort(int port);
/**
* Sets the identifier for this GatewayHub
* @param id The identifier for this GatewayHub
*/
public void setId(String id);
/**
* Returns the identifier of this GatewayHub
* @return the identifier of this GatewayHub
*/
public String getId();
/**
* Sets the buffer size in bytes of the socket connection for this
* GatewayHub. The default is 32768 bytes.
*
* @param socketBufferSize The size in bytes of the socket buffer
*
* @since 4.2.1
*/
public void setSocketBufferSize(int socketBufferSize);
/**
* Returns the configured buffer size of the socket connection for this
* GatewayHub. The default is 32768 bytes.
* @return the configured buffer size of the socket connection for this
* GatewayHub
*
* @since 4.2.1
*/
public int getSocketBufferSize();
/**
* Sets the maximum amount of time between client pings. This value is
* used by the ClientHealthMonitor to determine the health
* of any foreign Gateways connected to this
* GatewayHub. The default is 60000 ms.
*
* @param maximumTimeBetweenPings The maximum amount of time between client
* pings
*
* @since 4.2.3
*/
public void setMaximumTimeBetweenPings(int maximumTimeBetweenPings);
/**
* Returns the maximum amount of time between client pings. This value is
* used by the ClientHealthMonitor to determine the health
* of any foreign Gateways connected to this
* GatewayHub. The default is 60000 ms.
* @return the maximum amount of time between client pings.
*
* @since 4.2.3
*/
public int getMaximumTimeBetweenPings();
/**
* Starts this GatewayHub and notifies all of its
* Gateways to start. Starting a GatewayHub does
* several actions, including:
*
* - Attempts to start as primary or secondary depending on the start up
* policy
*
- Starts the listener to accept incoming
GatewayEvents from
* remote sites if the listen port is set
* - Starts its
Gateways using {@link #startGateways} to queue
* and send local EntryEvents to remote sites or local
* GatewayEventListeners as GatewayEvents
*
*
* Once the GatewayHub is running, its configuration cannot be
* changed.
*
* @throws IOException
* If an error occurs while starting the GatewayHub
*/
public void start() throws IOException;
/**
* Starts this GatewayHub and notifies all of its
* Gateways to start if startGateways is true. Starting a
* GatewayHub does several actions, including:
*
* - Attempts to start as primary or secondary depending on the start up
* policy
*
- Starts the listener to accept incoming
GatewayEvents from
* remote sites if the listen port is set
* - If the startGateways argument is true, Starts its
Gateways
* using {@link #startGateways} to queue and send local
* EntryEvents to remote sites or local
* GatewayEventListeners as GatewayEvents. If the
* startGateways argument is false, this GatewayHub will start
* just as a receiver of remote GatewayEvents. It will neither
* send nor queue local events for remote delivery. Setting startGateways to
* false is useful when updates to the local site should not be sent to the
* remote sites (e.g. during an initial load).
*
*
* Once the GatewayHub is running, its configuration cannot be
* changed.
*
* @param startGateways
* Whether to notify the Gateways to start
*/
public void start(boolean startGateways) throws IOException;
/**
* Starts all of this GatewayHub's Gateways. This
* can be used to start Gateways that have been stopped using
* {@link #stopGateways} or not started when this GatewayHub is
* started.
*
* @throws IOException
*/
public void startGateways() throws IOException;
/**
* Stops all of this GatewayHub's Gateways. Stopping
* the Gateways will cause this GatewayHub to act
* just as a receiver of remote GatewayEvents. It will neither
* send nor queue local events for remote delivery. Stopping
* Gateways is useful when updates to the local site should not
* be sent to the remote sites (e.g. during an initial load). This action has
* no effect on this GatewayHub's primary/secondary status.
*/
public void stopGateways();
/**
* Returns whether this GatewayHub is running
*
* @return whether this GatewayHub is running
*
* @deprecated use getCancelCriterion().cancelInProgress() instead
*/
@Deprecated
public boolean isRunning();
/**
* Stops this GatewayHub. Stopping a GatewayHub does
* several actions, including:
*
* - Stops the listener so that
GatewayEvents are no longer
* received from remote sites
* - Stops each of its
Gateways using {@link #stopGateways} so
* that GatewayEvents are no longer sent to remote sites
* - Releases its primary lock if it is the primary. If another
*
GatewayHub is running in the local site, it will take over as
* primary if it is not already primary.
*
*
* Note that the GatewayHub can be reconfigured and restarted if
* desired. In this case, the GatewayHub will restart as
* secondary if another GatewayHub is already running in the
* local site.
*/
public void stop();
/**
* Returns this GatewayHub's GemFire cache
* @return this GatewayHub's GemFire cache
*/
public Cache getCache();
/**
* Adds a Gateway to this GatewayHub's
* known Gateways.
*
* @param id The id of the Gateway
*
* @return the added Gateway
*
* @throws GatewayException if this GatewayHub already defines
* a Gateway with this id
*/
public Gateway addGateway(String id) throws GatewayException;
/**
* Adds a Gateway to this GatewayHub's known
* Gateways.
*
* @param id
* The id of the Gateway
* @param concurrencyLevel
* The concurrency level (number of parallel threads) processing
* GatewayEvents *
* @return the added Gateway
*
* @throws GatewayException
* if this GatewayHub already defines a
* Gateway with this id
*
* @since 6.5.1
*/
public Gateway addGateway(String id, int concurrencyLevel) throws GatewayException;
/**
* Removes a Gateway from this GatewayHub.
*
* @param id The id of the Gateway
*
* @throws GatewayException if this GatewayHub does not contain
* a Gateway with this id
*/
public void removeGateway(String id) throws GatewayException;
/**
* Returns this GatewayHub's list of known
* Gateways
* @return this GatewayHub's list of known
* Gateways
*/
public List getGateways();
/**
* Returns the ids of this GatewayHub's list of known
* Gateways
* @return the ids of this GatewayHub's list of known
* Gateways
*/
public List getGatewayIds();
/**
* Returns whether this GatewayHub is the primary hub.
* @return whether this GatewayHub is the primary hub
*/
public boolean isPrimary();
/**
* Returns detailed string representation of this GatewayHub.
* @return detailed string representation of this GatewayHub
*/
public String toDetailedString();
/**
* Sets the startup policy for this GatewayHub.
* @see #STARTUP_POLICY_NONE
* @see #STARTUP_POLICY_PRIMARY
* @see #STARTUP_POLICY_SECONDARY
*
* @param startupPolicy the startup policy for this GatewayHub
*
* @throws GatewayException if the input startup policy is not valid.
*
* @since 5.1
*/
public void setStartupPolicy(String startupPolicy) throws GatewayException;
/**
* Returns the startup policy for this GatewayHub.
* @return the startup policy for this GatewayHub
*
* @since 5.1
*/
public String getStartupPolicy();
/**
* Return a mutex to lock when iterating over the list of gateways
* @return the mutex to synchronize with
*/
public Object getAllGatewaysLock();
/**
* Sets the manual start boolean property for this GatewayHub.
* This property is mainly used for controlling when a GatewayHub
* configured in xml is started. By default, a GatewayHub is
* started right after the Regions are created. Setting this to
* true allows the application to start a GatewayHub when desired
* (e.g. after all remote Regions are created and initialized).
*
* @param manualStart
* the manual start boolean property for this GatewayHub
*
* @since 5.7
*/
public void setManualStart(boolean manualStart);
/**
* Returns the manual start boolean property for this
* GatewayHub.
*
* @return the manual start boolean property for this
* GatewayHub
*
* @since 5.7
*/
public boolean getManualStart();
/**
* Returns the CancelCriterion for this GatewayHub.
*
* @since 6.0
* @return the CancelCriterion for this GatewayHub
*/
public CancelCriterion getCancelCriterion();
/**
* Notifies all of this GatewayHub's Gateways to
* pause sending events. Events will continue to be queued while the
* Gateway is paused. Pausing a Gateway only affects
* outgoing events. It has no affect on incoming ones. It also has no effect
* on the primary status of this GatewayHub.
*
* @since 6.0
*/
public void pauseGateways();
/**
* Notifies all of this GatewayHub's Gateways to
* resume sending events. Processing the queue will resume when a
* Gateway is resumed.
*
* @since 6.0
*/
public void resumeGateways();
/**
* Returns a string representing the ip address or host name that this
* GatewayHub will listen on.
* @return the ip address or host name that this GatewayHub
* will listen on
* @see #DEFAULT_BIND_ADDRESS
* @since 6.5.1
*/
public String getBindAddress();
/**
* Sets the ip address or host name that this GatewayHub will
* listen on for connections.
* Setting a specific bind address will cause the GatewayHub
* to always use this address and ignore any address specified by "server-bind-address"
* or "bind-address" in the gemfire.properties file
* (see {@link com.gemstone.gemfire.distributed.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 GatewayHub
* 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 "".
* @param address the ip address or host name that this GatewayHub
* will listen on
* @see #DEFAULT_BIND_ADDRESS
* @since 6.5.1
*/
public void setBindAddress(String address);
}