/*
* Copyright 2012 Netflix, Inc.
*
* 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.
*/
package com.netflix.appinfo;
import java.util.Map;
import com.google.inject.ImplementedBy;
/**
* Configuration information required by the instance to register with Eureka
* server. Once registered, users can look up information from
* {@link com.netflix.discovery.EurekaClient} based on virtual hostname (also called VIPAddress),
* the most common way of doing it or by other means to get the information
* necessary to talk to other instances registered with <em>Eureka</em>.
*
* <P>
* As requirements of registration, an id and an appname must be supplied. The id should be
* unique within the scope of the appname.
* </P>
*
* <p>
* Note that all configurations are not effective at runtime unless and
* otherwise specified.
* </p>
*
* @author Karthik Ranganathan
*
*/
@ImplementedBy(CloudInstanceConfig.class)
public interface EurekaInstanceConfig {
/**
* Get the unique Id (within the scope of the appName) of this instance to be registered with eureka.
*
* @return the (appname scoped) unique id for this instance
*/
String getInstanceId();
/**
* Get the name of the application to be registered with eureka.
*
* @return string denoting the name.
*/
String getAppname();
/**
* Get the name of the application group to be registered with eureka.
*
* @return string denoting the name.
*/
String getAppGroupName();
/**
* Indicates whether the instance should be enabled for taking traffic as
* soon as it is registered with eureka. Sometimes the application might
* need to do some pre-processing before it is ready to take traffic.
*
* :( public API typos are the worst. I think this was meant to be "OnInit".
*
* @return true to immediately start taking traffic, false otherwise.
*/
boolean isInstanceEnabledOnit();
/**
* Get the <code>non-secure</code> port on which the instance should receive
* traffic.
*
* @return the non-secure port on which the instance should receive traffic.
*/
int getNonSecurePort();
/**
* Get the <code>Secure port</code> on which the instance should receive
* traffic.
*
* @return the secure port on which the instance should receive traffic.
*/
int getSecurePort();
/**
* Indicates whether the <code>non-secure</code> port should be enabled for
* traffic or not.
*
* @return true if the <code>non-secure</code> port is enabled, false
* otherwise.
*/
boolean isNonSecurePortEnabled();
/**
* Indicates whether the <code>secure</code> port should be enabled for
* traffic or not.
*
* @return true if the <code>secure</code> port is enabled, false otherwise.
*/
boolean getSecurePortEnabled();
/**
* Indicates how often (in seconds) the eureka client needs to send
* heartbeats to eureka server to indicate that it is still alive. If the
* heartbeats are not received for the period specified in
* {@link #getLeaseExpirationDurationInSeconds()}, eureka server will remove
* the instance from its view, there by disallowing traffic to this
* instance.
*
* <p>
* Note that the instance could still not take traffic if it implements
* {@link HealthCheckCallback} and then decides to make itself unavailable.
* </p>
*
* @return time in seconds
*/
int getLeaseRenewalIntervalInSeconds();
/**
* Indicates the time in seconds that the eureka server waits since it
* received the last heartbeat before it can remove this instance from its
* view and there by disallowing traffic to this instance.
*
* <p>
* Setting this value too long could mean that the traffic could be routed
* to the instance even though the instance is not alive. Setting this value
* too small could mean, the instance may be taken out of traffic because of
* temporary network glitches.This value to be set to atleast higher than
* the value specified in {@link #getLeaseRenewalIntervalInSeconds()}
* .
* </p>
*
* @return value indicating time in seconds.
*/
int getLeaseExpirationDurationInSeconds();
/**
* Gets the virtual host name defined for this instance.
*
* <p>
* This is typically the way other instance would find this instance by
* using the virtual host name.Think of this as similar to the fully
* qualified domain name, that the users of your services will need to find
* this instance.
* </p>
*
* @return the string indicating the virtual host name which the clients use
* to call this service.
*/
String getVirtualHostName();
/**
* Gets the secure virtual host name defined for this instance.
*
* <p>
* This is typically the way other instance would find this instance by
* using the secure virtual host name.Think of this as similar to the fully
* qualified domain name, that the users of your services will need to find
* this instance.
* </p>
*
* @return the string indicating the secure virtual host name which the
* clients use to call this service.
*/
String getSecureVirtualHostName();
/**
* Gets the <code>AWS autoscaling group name</code> associated with this
* instance. This information is specifically used in an AWS environment to
* automatically put an instance out of service after the instance is
* launched and it has been disabled for traffic..
*
* @return the autoscaling group name associated with this instance.
*/
String getASGName();
/**
* Gets the hostname associated with this instance. This is the exact name
* that would be used by other instances to make calls.
*
* @param refresh
* true if the information needs to be refetched, false
* otherwise.
* @return hostname of this instance which is identifiable by other
* instances for making remote calls.
*/
String getHostName(boolean refresh);
/**
* Gets the metadata name/value pairs associated with this instance. This
* information is sent to eureka server and can be used by other instances.
*
* @return Map containing application-specific metadata.
*/
Map<String, String> getMetadataMap();
/**
* Returns the data center this instance is deployed. This information is
* used to get some AWS specific instance information if the instance is
* deployed in AWS.
*
* @return information that indicates which data center this instance is
* deployed in.
*/
DataCenterInfo getDataCenterInfo();
/**
* Get the IPAdress of the instance. This information is for academic
* purposes only as the communication from other instances primarily happen
* using the information supplied in {@link #getHostName(boolean)}.
*
* @return the ip address of this instance.
*/
String getIpAddress();
/**
* Gets the relative status page {@link java.net.URL} <em>Path</em> for this
* instance. The status page URL is then constructed out of the
* {@link #getHostName(boolean)} and the type of communication - secure or
* unsecure as specified in {@link #getSecurePort()} and
* {@link #getNonSecurePort()}.
*
* <p>
* It is normally used for informational purposes for other services to find
* about the status of this instance. Users can provide a simple
* <code>HTML</code> indicating what is the current status of the instance.
* </p>
*
* @return - relative <code>URL</code> that specifies the status page.
*/
String getStatusPageUrlPath();
/**
* Gets the absolute status page {@link java.net.URL} for this instance. The users
* can provide the {@link #getStatusPageUrlPath()} if the status page
* resides in the same instance talking to eureka, else in the cases where
* the instance is a proxy for some other server, users can provide the full
* {@link java.net.URL}. If the full {@link java.net.URL} is provided it takes precedence.
*
* <p>
* * It is normally used for informational purposes for other services to
* find about the status of this instance. Users can provide a simple
* <code>HTML</code> indicating what is the current status of the instance.
* . The full {@link java.net.URL} should follow the format
* http://${eureka.hostname}:7001/ where the value ${eureka.hostname} is
* replaced at runtime.
* </p>
*
* @return absolute status page URL of this instance.
*/
String getStatusPageUrl();
/**
* Gets the relative home page {@link java.net.URL} <em>Path</em> for this instance.
* The home page URL is then constructed out of the
* {@link #getHostName(boolean)} and the type of communication - secure or
* unsecure as specified in {@link #getSecurePort()} and
* {@link #getNonSecurePort()}.
*
* <p>
* It is normally used for informational purposes for other services to use
* it as a landing page.
* </p>
*
* @return relative <code>URL</code> that specifies the home page.
*/
String getHomePageUrlPath();
/**
* Gets the absolute home page {@link java.net.URL} for this instance. The users can
* provide the {@link #getHomePageUrlPath()} if the home page resides in the
* same instance talking to eureka, else in the cases where the instance is
* a proxy for some other server, users can provide the full {@link java.net.URL}. If
* the full {@link java.net.URL} is provided it takes precedence.
*
* <p>
* It is normally used for informational purposes for other services to use
* it as a landing page. The full {@link java.net.URL} should follow the format
* http://${eureka.hostname}:7001/ where the value ${eureka.hostname} is
* replaced at runtime.
* </p>
*
* @return absolute home page URL of this instance.
*/
String getHomePageUrl();
/**
* Gets the relative health check {@link java.net.URL} <em>Path</em> for this
* instance. The health check page URL is then constructed out of the
* {@link #getHostName(boolean)} and the type of communication - secure or
* unsecure as specified in {@link #getSecurePort()} and
* {@link #getNonSecurePort()}.
*
* <p>
* It is normally used for making educated decisions based on the health of
* the instance - for example, it can be used to determine whether to
* proceed deployments to an entire farm or stop the deployments without
* causing further damage.
* </p>
*
* @return - relative <code>URL</code> that specifies the health check page.
*/
String getHealthCheckUrlPath();
/**
* Gets the absolute health check page {@link java.net.URL} for this instance. The
* users can provide the {@link #getHealthCheckUrlPath()} if the health
* check page resides in the same instance talking to eureka, else in the
* cases where the instance is a proxy for some other server, users can
* provide the full {@link java.net.URL}. If the full {@link java.net.URL} is provided it
* takes precedence.
*
* <p>
* It is normally used for making educated decisions based on the health of
* the instance - for example, it can be used to determine whether to
* proceed deployments to an entire farm or stop the deployments without
* causing further damage. The full {@link java.net.URL} should follow the format
* http://${eureka.hostname}:7001/ where the value ${eureka.hostname} is
* replaced at runtime.
* </p>
*
* @return absolute health check page URL of this instance.
*/
String getHealthCheckUrl();
/**
* Gets the absolute secure health check page {@link java.net.URL} for this instance.
* The users can provide the {@link #getSecureHealthCheckUrl()} if the
* health check page resides in the same instance talking to eureka, else in
* the cases where the instance is a proxy for some other server, users can
* provide the full {@link java.net.URL}. If the full {@link java.net.URL} is provided it
* takes precedence.
*
* <p>
* It is normally used for making educated decisions based on the health of
* the instance - for example, it can be used to determine whether to
* proceed deployments to an entire farm or stop the deployments without
* causing further damage. The full {@link java.net.URL} should follow the format
* http://${eureka.hostname}:7001/ where the value ${eureka.hostname} is
* replaced at runtime.
* </p>
*
* @return absolute health check page URL of this instance.
*/
String getSecureHealthCheckUrl();
/**
* An instance's network addresses should be fully expressed in it's {@link DataCenterInfo}.
* For example for instances in AWS, this will include the publicHostname, publicIp,
* privateHostname and privateIp, when available. The {@link com.netflix.appinfo.InstanceInfo}
* will further express a "default address", which is a field that can be configured by the
* registering instance to advertise it's default address. This configuration allowed
* for the expression of an ordered list of fields that can be used to resolve the default
* address. The exact field values will depend on the implementation details of the corresponding
* implementing DataCenterInfo types.
*
* @return an ordered list of fields that should be used to preferentially
* resolve this instance's default address, empty String[] for default.
*/
String[] getDefaultAddressResolutionOrder();
/**
* Get the namespace used to find properties.
* @return the namespace used to find properties.
*/
String getNamespace();
}