com.gemstone.gemfire.distributed.Locator Maven / Gradle / Ivy
Show all versions of gemfire-core Show documentation
/*
* 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.distributed;
import java.io.File;
import java.io.IOException;
import java.net.InetAddress;
import java.util.*;
import java.util.concurrent.ConcurrentMap;
import com.gemstone.gemfire.distributed.internal.InternalLocator;
import com.gemstone.gemfire.i18n.LogWriterI18n;
import com.gemstone.gemfire.internal.SocketCreator;
import com.gemstone.gemfire.internal.i18n.LocalizedStrings;
/**
* Represents a distribution locator server that provides discovery information
* to members and clients of a GemFire distributed system. In most GemFire
* distributed cache architectures, distribution locators are run in their own
* process. A stand-alone locator process is managed using
* {@linkplain com.gemstone.gemfire.admin.DistributionLocator administration
* API} or the gemfire command line utility:
*
*
* $ gemfire start-locator
*
*
* The stand-alone locator configuration provides high-availability of
* membership information.
*
*
*
* This class allows a GemFire application VM to host a distribution locator.
* Such a configuration minimizes the number of processes that are required to
* run GemFire. However, hosting distribution locators is not generally
* recommended because if the application VM exits, the primary membership list
* for the distributed system would be lost and it would not be possible for new
* applications to connect to the distributed system.
*
*
*
* NOTE: In this release of the product locators log membership views and
* cache server status in a locatorXXXviews.log file, where XXX is the locator's port.
* This is a rolling log
* capped in size at 5mb. In order to log cache server status the locator will
* enable server-location, so the locator must be started with a DistributedSystem
* or be started so that it creates a DistributedSystem. This means that it is
* not possible in this release to use APIs to start a locator and then
* start a DistributedSystem.
*
*
*
* @author Bruce Schuchardt
* @since 4.0
*/
public abstract class Locator {
///////////////////// Instance Fields /////////////////////
/** The file to which this locator logs */
protected File logFile;
/** The port on which this locator listens */
protected int port;
/** The bind address for this locator */
protected InetAddress bindAddress;
/**
* the hostname to give to clients so they can connect to this locator.
* @since 5.7
*/
protected String hostnameForClients;
////////////////////// Static Methods //////////////////////
/**
* Starts a new distribution locator host by this VM. The locator's
* listening sockets will bind to all network addresses. The locator
* will look for a gemfire.properties file, or equivalent system
* properties to fill in the gaps in its configuration. If you are
* using multicast communications, the locator should be configured
* with the same settings that your applications will use.
*
The locator will not start a distributed system. The locator
* will provide peer location services only.
*
* @param port
* The port on which the locator will listen for membership
* information requests from new members
* @param logFile
* The file to which the locator logs information. The
* directory that contains the log file is used as the output
* directory of the locator (see -dir option to
* the gemfire command).
*
* @throws IllegalArgumentException
* If port is not in the range 0 to 65536
* @throws com.gemstone.gemfire.SystemIsRunningException
* If another locator is already running in
* outputDir
* @throws com.gemstone.gemfire.GemFireIOException
* If the directory containing the logFile does
* not exist or cannot be written to
* @throws IOException
* If the locator cannot be started
* @deprecated as of 7.0 use startLocatorAndDS instead.
*/
@Deprecated
public static Locator startLocator(int port, File logFile)
throws IOException {
return startLocator(port, logFile, false, (InetAddress)null, (Properties)null, true, false, null);
}
/**
* Starts a new distribution locator host by this VM, and an admin distributed
* system controlled by the locator. The locator's listening sockets will bind
* to all network addresses. The locator will use the given properties to
* start an AdminDistributedSystem.
*
* The locator starts a AdminDistributedSystem configured with the given
* properties to provide the system with a long-running process that can be
* relied on for stable membership information. The locator will provide provide
* peer and cache server location services.
*
* @since 5.0
*
* @param port
* The port on which the locator will listen for membership
* information requests from new members
* @param logFile
* The file to which the locator logs information. The
* directory that contains the log file is used as the output
* directory of the locator (see -dir option to
* the gemfire command).
* @param distributedSystemProperties
* The properties used to configure the locator's distributed
* system. If there are multiple locators in the system, this
* should note them in the "locators" setting. If The
* distributed system is using multicast, the "mcast-port"
* should also be set.
*
* @throws IllegalArgumentException
* If port is not in the range 0 to 65536
* @throws com.gemstone.gemfire.SystemIsRunningException
* If another locator is already running in
* outputDir
* @throws com.gemstone.gemfire.GemFireIOException
* If the directory containing the logFile does
* not exist or cannot be written to
* @throws IOException
* If the locator cannot be started
*/
public static Locator startLocatorAndDS(int port, File logFile, Properties distributedSystemProperties)
throws IOException {
return startLocator(port, logFile, (InetAddress)null, distributedSystemProperties, true, true, null);
}
/**
* Starts a new distribution locator host by this VM. The locator
* will look for a gemfire.properties file, or equivalent system
* properties to fill in the gaps in its configuration.
*
The locator will not start a distributed system. The locator
* will provice peer location services only.
*
* @param port
* The port on which the locator will listen for membership
* information requests from new members
* @param logFile
* The file to which the locator logs information. The
* directory that contains the log file is used as the output
* directory of the locator (see -dir option to
* the gemfire command).
* @param bindAddress
* The IP address to which the locator's socket binds
*
* @throws IllegalArgumentException
* If port is not in the range 0 to 65536
* @throws com.gemstone.gemfire.SystemIsRunningException
* If another locator is already running in
* outputDir
* @throws com.gemstone.gemfire.GemFireIOException
* If the directory containing the logFile does
* not exist or cannot be written to
* @throws IOException
* If the locator cannot be started
* @deprecated as of 7.0 use startLocatorAndDS instead.
*/
@Deprecated
public static Locator startLocator(int port, File logFile,
InetAddress bindAddress)
throws IOException {
return startLocator(port, logFile, false, bindAddress, (Properties)null, true, false, null);
}
/**
* Starts a new distribution locator host by this VM that binds to the given
* network address.
*
The locator starts a AdminDistributedSystem configured with the given
* properties to provide the system with
* a long-running process that can be relied on for stable membership
* information. The locator will provide provide
* peer and cache server location services.
*
* @since 5.0
*
* @param port
* The port on which the locator will listen for membership
* information requests from new members
* @param logFile
* The file to which the locator logs information. The
* directory that contains the log file is used as the output
* directory of the locator (see -dir option to
* the gemfire command).
* @param bindAddress
* The IP address to which the locator's socket binds
* @param dsProperties
* The properties used to configure the locator's DistributedSystem.
* If there are multiple locators, the "locators" property should
* be set. If multicast is being used, the "mcast-port" property
* should be set.
*
* @throws IllegalArgumentException
* If port is not in the range 0 to 65536
* @throws com.gemstone.gemfire.SystemIsRunningException
* If another locator is already running in
* outputDir
* @throws com.gemstone.gemfire.GemFireIOException
* If the directory containing the logFile does
* not exist or cannot be written to
* @throws IOException
* If the locator cannot be started
*/
public static Locator startLocatorAndDS(
int port,
File logFile,
InetAddress bindAddress,
java.util.Properties dsProperties
)
throws IOException
{
return startLocator(port, logFile, bindAddress, dsProperties, true, true, null);
}
/**
* Starts a new distribution locator host by this VM that binds to the given
* network address.
*
The locator starts a AdminDistributedSystem configured with the given
* properties to provide the system with
* a long-running process that can be relied on for stable membership
* information. The locator will provide provide
* peer and cache server location services.
*
* @since 5.7
*
* @param port
* The port on which the locator will listen for membership
* information requests from new members
* @param logFile
* The file to which the locator logs information. The
* directory that contains the log file is used as the output
* directory of the locator (see -dir option to
* the gemfire command).
* @param bindAddress
* The IP address to which the locator's socket binds
* @param dsProperties
* The properties used to configure the locator's DistributedSystem.
* If there are multiple locators, the "locators" property should
* be set. If multicast is being used, the "mcast-port" property
* should be set.
* @param peerLocator
* True if the locator should provide membership information to
* peers in the distributed system.
* @param serverLocator
* True if the locator should provide information about cache
* servers to clients connecting to the distributed system.
* @param hostnameForClients
* the name to give to clients for connecting to this locator
*
* @throws IllegalArgumentException
* If port is not in the range 0 to 65536
* or peerLocator and serverLocator
* are both false.
* @throws com.gemstone.gemfire.SystemIsRunningException
* If another locator is already running in
* outputDir
* @throws com.gemstone.gemfire.GemFireIOException
* If the directory containing the logFile does
* not exist or cannot be written to
* @throws IOException
* If the locator cannot be started
*
* @since 5.7
*/
public static Locator startLocatorAndDS(
int port,
File logFile,
InetAddress bindAddress,
java.util.Properties dsProperties,
boolean peerLocator,
boolean serverLocator,
String hostnameForClients
)
throws IOException
{
return startLocator(port, logFile, bindAddress, dsProperties, peerLocator, serverLocator, hostnameForClients);
}
/** all Locator methods that start locators should use this method to
* start the locator and its distributed system
*/
private static Locator startLocator(
int port,
File logFile,
InetAddress bindAddress,
java.util.Properties dsProperties,
boolean peerLocator,
boolean serverLocator,
String hostnameForClients
)
throws IOException
{
return InternalLocator.startLocator(port,
logFile,
null,
(LogWriterI18n)null,
(LogWriterI18n)null,
bindAddress,
dsProperties,
peerLocator,
serverLocator,
hostnameForClients);
}
/**
* @deprecated as of 7.0 use startLocator(int, File, InetAddress, java.util.Properties, peerLocator, serverLocator, hostnameForClients) instead.
*/
@Deprecated
private static Locator startLocator(
int port,
File logFile,
boolean startDistributedSystem,
InetAddress bindAddress,
java.util.Properties dsProperties,
boolean peerLocator,
boolean serverLocator,
String hostnameForClients
)
throws IOException
{
return InternalLocator.startLocator(port,
logFile,
null,
(LogWriterI18n)null,
(LogWriterI18n)null,
bindAddress,
startDistributedSystem,
dsProperties,
peerLocator,
serverLocator,
hostnameForClients);
}
/**
* Returns an unmodifiable List of all of the
* Locators that are hosted by this VM.
* @deprecated as of 7.0 use {@link #getLocator} instead
*/
@Deprecated
public static List getLocators() {
Locator result = getLocator();
if (result == null) {
return Collections.emptyList();
} else {
return Collections.singletonList(result);
}
}
/**
* Returns the locator if it exists in this JVM.
* Otherwise returns null.
* @return the locator that exists in this JVM; null if no locator.
* @since 7.0
*/
public static Locator getLocator() {
return InternalLocator.getLocator();
}
/**
* Examine the size of the collection of locators running in this VM
* @return the number of locators running in this VM
* @deprecated as of 7.0 use {@link #hasLocator} instead.
*/
@Deprecated
public static boolean hasLocators() {
return hasLocator();
}
/**
* Returns true if a locator exists in this JVM.
*
* @return true if a locator exists in this JVM.
* @since 7.0
*/
public static boolean hasLocator() {
return InternalLocator.hasLocator();
}
///////////////////// Instance Methods /////////////////////
/**
* Returns the port on which this locator runs
*/
public int getPort() {
return this.port;
}
/**
* Returns the distributed system started by this locator, if any
*/
public abstract DistributedSystem getDistributedSystem();
/**
* Returns the log file to which this locator's output is written
*/
public File getLogFile() {
return this.logFile;
}
/**
* Returns the IP address to which this locator's listening socket
* is bound.
*/
public InetAddress getBindAddress() {
return this.bindAddress;
}
/**
* Returns the hostname that will be given to clients so that they can
* connect to this locator. Returns null if clients should
* use the bind address.
* @since 5.7
*/
public String getHostnameForClients() {
String result = this.hostnameForClients;
if (result != null && result.equals("")) {
result = null;
}
return result;
}
public abstract ConcurrentMap> getAllServerLocatorsInfo();
public abstract Set getRemoteLocatorInfo(int dsId);
/**
* Indicates whether the locator provides peer location services
* to members
* @return if peer location is enabled
*/
public abstract boolean isPeerLocator();
/**
* Indicates whether the locator provides server location services
* to clients
* @return if server location is enabled
*/
public abstract boolean isServerLocator();
/**
* Stops this distribution locator.
*/
public abstract void stop();
/**
* Returns a brief description of this Locator
*/
@Override
public String toString() {
return LocalizedStrings.DistributionLocator_DISTRIBUTION_LOCATOR_ON_0
.toLocalizedString(asString());
}
/**
* Get the string representation of this Locator in host[port]
* format.
*/
public String asString() {
Object ba = this.bindAddress;
if (ba == null) {
try {
ba = SocketCreator.getHostName(SocketCreator.getLocalHost());
} catch (java.net.UnknownHostException uh) {
}
}
StringBuilder locatorString = new StringBuilder(String.valueOf(ba));
locatorString.append('[').append(this.port).append(']');
return locatorString.toString();
}
/**
* Starts a distribution locator from the command line.
*
* This method of starting the locator is provided as an
* alternative to the gemfire start-locator command to give
* you complete control over the java virtual machine's configuration.
*
* The gemfire stop-locator command can be used to stop
* a locator that is started with this class.
*
* java com.gemstone.gemfire.distributed.Locator port [bind-address] [gemfire-properties-file] [peer] [server]
*
* port - the tcp/ip port that the locator should listen on. This is the
* port number that applications will refer to in their locators property
* in gemfire.properties
*
* bind-address - the tcp/ip address that the locator should bind to. This
* can be missing or be an empty string, which causes the locator to listen
* on all host addresses.
*
* gemfire-properties-file - the location of a gemfire.properties file to be
* used in configuring the locator's distributed system. This can be missing
* or be an empty string, which will cause the locator to use the default
* search for gemfire.properties.
*
* peer - true to start the peer locator service, false to disable it.
* If unspecified, default to true.
*
* server - true to start the cache server locator service, false to disable it.
* If unspecified, defaults to true.
*
* hostname-for-clients - the ip address or host name that clients will be told
* to use to connect to this locator.
* If unspecified, defaults to the bind-address.
*
* @since 5.0
*/
public static void main(String args[]) {
com.gemstone.gemfire.internal.DistributionLocator.main(args);
}
}