com.gemstone.gemfire.cache.util.GatewayHub Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of gemfire-core Show documentation
SnappyData store based off Pivotal GemFireXD
The newest version!
/*
 * 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);
}