| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you 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 org.apache.brooklyn.entity.software.base; |
| |
| import java.util.Collection; |
| import java.util.Map; |
| import java.util.Set; |
| import java.util.regex.Pattern; |
| |
| import com.google.common.collect.Sets; |
| import org.apache.brooklyn.api.entity.Entity; |
| import org.apache.brooklyn.api.location.MachineProvisioningLocation; |
| import org.apache.brooklyn.api.location.PortRange; |
| import org.apache.brooklyn.api.sensor.AttributeSensor; |
| import org.apache.brooklyn.config.ConfigKey; |
| import org.apache.brooklyn.core.annotation.Effector; |
| import org.apache.brooklyn.core.config.ConfigKeys; |
| import org.apache.brooklyn.core.config.ConfigUtils; |
| import org.apache.brooklyn.core.config.MapConfigKey; |
| import org.apache.brooklyn.core.entity.AbstractEntity; |
| import org.apache.brooklyn.core.entity.Attributes; |
| import org.apache.brooklyn.core.entity.BrooklynConfigKeys; |
| import org.apache.brooklyn.core.entity.lifecycle.Lifecycle; |
| import org.apache.brooklyn.core.entity.lifecycle.Lifecycle.Transition; |
| import org.apache.brooklyn.core.entity.trait.Startable; |
| import org.apache.brooklyn.core.sensor.AttributeSensorAndConfigKey; |
| import org.apache.brooklyn.core.sensor.Sensors; |
| import org.apache.brooklyn.util.collections.MutableMap; |
| import org.apache.brooklyn.util.collections.MutableSet; |
| import org.apache.brooklyn.util.core.flags.SetFromFlag; |
| import org.apache.brooklyn.util.core.flags.TypeCoercions; |
| import org.apache.brooklyn.util.guava.Maybe; |
| import org.apache.brooklyn.util.time.Duration; |
| |
| import com.google.common.annotations.Beta; |
| import com.google.common.collect.ImmutableSet; |
| import com.google.common.reflect.TypeToken; |
| |
| public interface SoftwareProcess extends Entity, Startable { |
| |
| AttributeSensor<String> HOSTNAME = Attributes.HOSTNAME; |
| AttributeSensor<String> ADDRESS = Attributes.ADDRESS; |
| AttributeSensor<String> SUBNET_HOSTNAME = Attributes.SUBNET_HOSTNAME; |
| AttributeSensor<String> SUBNET_ADDRESS = Attributes.SUBNET_ADDRESS; |
| |
| ConfigKey<Collection<Integer>> REQUIRED_OPEN_LOGIN_PORTS = ConfigKeys.newConfigKey( |
| new TypeToken<Collection<Integer>>() {}, |
| "requiredOpenLoginPorts", |
| "The port(s) to be opened, to allow login", |
| ImmutableSet.of(22)); |
| |
| ConfigKey<String> INBOUND_PORTS_CONFIG_REGEX = ConfigKeys.newStringConfigKey("inboundPorts.configRegex", |
| "Regex governing the opening of ports based on config names", |
| ".*\\.port"); |
| |
| ConfigKey<Boolean> INBOUND_PORTS_AUTO_INFER = ConfigKeys.newBooleanConfigKey("inboundPorts.autoInfer", |
| "If set to false turns off the opening of ports based on naming convention, and also those that are of type PortRange in Java entities", |
| true); |
| |
| @SetFromFlag("startTimeout") |
| ConfigKey<Duration> START_TIMEOUT = BrooklynConfigKeys.START_TIMEOUT; |
| |
| @SetFromFlag("startLatch") |
| ConfigKey<Boolean> START_LATCH = BrooklynConfigKeys.START_LATCH; |
| |
| @SetFromFlag("setupLatch") |
| ConfigKey<Boolean> SETUP_LATCH = BrooklynConfigKeys.SETUP_LATCH; |
| |
| @SetFromFlag("installResourcesLatch") |
| ConfigKey<Boolean> INSTALL_RESOURCES_LATCH = BrooklynConfigKeys.INSTALL_RESOURCES_LATCH; |
| |
| @SetFromFlag("installLatch") |
| ConfigKey<Boolean> INSTALL_LATCH = BrooklynConfigKeys.INSTALL_LATCH; |
| |
| @SetFromFlag("runtimeResourcesLatch") |
| ConfigKey<Boolean> RUNTIME_RESOURCES_LATCH = BrooklynConfigKeys.RUNTIME_RESOURCES_LATCH; |
| |
| @SetFromFlag("customizeLatch") |
| ConfigKey<Boolean> CUSTOMIZE_LATCH = BrooklynConfigKeys.CUSTOMIZE_LATCH; |
| |
| @SetFromFlag("launchLatch") |
| ConfigKey<Boolean> LAUNCH_LATCH = BrooklynConfigKeys.LAUNCH_LATCH; |
| |
| @SetFromFlag("skipStart") |
| ConfigKey<Boolean> ENTITY_STARTED = BrooklynConfigKeys.SKIP_ENTITY_START; |
| |
| @SetFromFlag("skipStartIfRunning") |
| ConfigKey<Boolean> SKIP_ENTITY_START_IF_RUNNING = BrooklynConfigKeys.SKIP_ENTITY_START_IF_RUNNING; |
| |
| @SetFromFlag("skipInstall") |
| ConfigKey<Boolean> SKIP_INSTALLATION = BrooklynConfigKeys.SKIP_ENTITY_INSTALLATION; |
| |
| @SetFromFlag("preInstallCommand") |
| ConfigKey<String> PRE_INSTALL_COMMAND = BrooklynConfigKeys.PRE_INSTALL_COMMAND; |
| |
| @SetFromFlag("postInstallCommand") |
| ConfigKey<String> POST_INSTALL_COMMAND = BrooklynConfigKeys.POST_INSTALL_COMMAND; |
| |
| @SetFromFlag("preLaunchCommand") |
| ConfigKey<String> PRE_LAUNCH_COMMAND = BrooklynConfigKeys.PRE_LAUNCH_COMMAND; |
| |
| @SetFromFlag("postLaunchCommand") |
| ConfigKey<String> POST_LAUNCH_COMMAND = BrooklynConfigKeys.POST_LAUNCH_COMMAND; |
| |
| @SetFromFlag("env") |
| MapConfigKey<Object> SHELL_ENVIRONMENT = BrooklynConfigKeys.SHELL_ENVIRONMENT; |
| |
| @SetFromFlag("version") |
| ConfigKey<String> SUGGESTED_VERSION = BrooklynConfigKeys.SUGGESTED_VERSION; |
| |
| @SetFromFlag("downloadUrl") |
| AttributeSensorAndConfigKey<String,String> DOWNLOAD_URL = Attributes.DOWNLOAD_URL; |
| |
| @SetFromFlag("downloadAddonUrls") |
| AttributeSensorAndConfigKey<Map<String,String>,Map<String,String>> DOWNLOAD_ADDON_URLS = Attributes.DOWNLOAD_ADDON_URLS; |
| |
| @SetFromFlag("installLabel") |
| ConfigKey<String> INSTALL_UNIQUE_LABEL = BrooklynConfigKeys.INSTALL_UNIQUE_LABEL; |
| |
| @SetFromFlag("expandedInstallDir") |
| AttributeSensorAndConfigKey<String,String> EXPANDED_INSTALL_DIR = BrooklynConfigKeys.EXPANDED_INSTALL_DIR; |
| |
| @SetFromFlag("installDir") |
| AttributeSensorAndConfigKey<String,String> INSTALL_DIR = BrooklynConfigKeys.INSTALL_DIR; |
| @Deprecated |
| ConfigKey<String> SUGGESTED_INSTALL_DIR = BrooklynConfigKeys.SUGGESTED_INSTALL_DIR; |
| |
| @SetFromFlag("runDir") |
| AttributeSensorAndConfigKey<String,String> RUN_DIR = BrooklynConfigKeys.RUN_DIR; |
| @Deprecated |
| ConfigKey<String> SUGGESTED_RUN_DIR = BrooklynConfigKeys.SUGGESTED_RUN_DIR; |
| |
| public static final ConfigKey<Boolean> OPEN_IPTABLES = ConfigKeys.newBooleanConfigKey("openIptables", |
| "Whether to open the INBOUND_PORTS via iptables rules; " + |
| "if true then ssh in to run iptables commands, as part of machine provisioning", false); |
| |
| public static final ConfigKey<Boolean> STOP_IPTABLES = ConfigKeys.newBooleanConfigKey("stopIptables", |
| "Whether to stop iptables entirely; " + |
| "if true then ssh in to stop the iptables service, as part of machine provisioning", false); |
| |
| public static final ConfigKey<Boolean> DONT_REQUIRE_TTY_FOR_SUDO = ConfigKeys.newBooleanConfigKey("dontRequireTtyForSudo", |
| "Whether to explicitly set /etc/sudoers, so don't need tty (will leave unchanged if 'false'); " + |
| "some machines require a tty for sudo; brooklyn by default does not use a tty " + |
| "(so that it can get separate error+stdout streams); you can enable a tty as an " + |
| "option to every ssh command, or you can do it once and " + |
| "modify the machine so that a tty is not subsequently required.", |
| false); |
| |
| /** |
| * Files to be copied to the server before pre-install. |
| * <p> |
| * Map of {@code classpath://foo/file.txt} (or other url) source to destination path, |
| * as {@code subdir/file} relative to installation directory or {@code /absolute/path/to/file}. |
| * |
| * @see #PRE_INSTALL_TEMPLATES |
| */ |
| @Beta |
| @SuppressWarnings("serial") |
| @SetFromFlag("preInstallFiles") |
| ConfigKey<Map<String, String>> PRE_INSTALL_FILES = ConfigKeys.newConfigKey(new TypeToken<Map<String, String>>() { }, |
| "files.preinstall", "Mapping of files, to be copied before install, to destination name relative to installDir"); |
| |
| /** |
| * Templates to be filled in and then copied to the server before install. |
| * |
| * @see #PRE_INSTALL_FILES |
| */ |
| @Beta |
| @SuppressWarnings("serial") |
| @SetFromFlag("preInstallTemplates") |
| ConfigKey<Map<String, String>> PRE_INSTALL_TEMPLATES = ConfigKeys.newConfigKey(new TypeToken<Map<String, String>>() { }, |
| "templates.preinstall", "Mapping of templates, to be filled in and copied before pre-install, to destination name relative to installDir"); |
| |
| /** |
| * Files to be copied to the server before install. |
| * <p> |
| * Map of {@code classpath://foo/file.txt} (or other url) source to destination path, |
| * as {@code subdir/file} relative to installation directory or {@code /absolute/path/to/file}. |
| * |
| * @see #INSTALL_TEMPLATES |
| */ |
| @Beta |
| @SuppressWarnings("serial") |
| @SetFromFlag("installFiles") |
| ConfigKey<Map<String, String>> INSTALL_FILES = ConfigKeys.newConfigKey(new TypeToken<Map<String, String>>() { }, |
| "files.install", "Mapping of files, to be copied before install, to destination name relative to installDir"); |
| |
| /** |
| * Templates to be filled in and then copied to the server before install. |
| * |
| * @see #INSTALL_FILES |
| */ |
| @Beta |
| @SuppressWarnings("serial") |
| @SetFromFlag("installTemplates") |
| ConfigKey<Map<String, String>> INSTALL_TEMPLATES = ConfigKeys.newConfigKey(new TypeToken<Map<String, String>>() { }, |
| "templates.install", "Mapping of templates, to be filled in and copied before install, to destination name relative to installDir"); |
| |
| /** |
| * Files to be copied to the server after customisation. |
| * <p> |
| * Map of {@code classpath://foo/file.txt} (or other url) source to destination path, |
| * as {@code subdir/file} relative to runtime directory or {@code /absolute/path/to/file}. |
| * |
| * @see #RUNTIME_TEMPLATES |
| */ |
| @Beta |
| @SuppressWarnings("serial") |
| @SetFromFlag("runtimeFiles") |
| ConfigKey<Map<String, String>> RUNTIME_FILES = ConfigKeys.newConfigKey(new TypeToken<Map<String, String>>() { }, |
| "files.runtime", "Mapping of files, to be copied before customisation, to destination name relative to runDir"); |
| |
| /** |
| * Templates to be filled in and then copied to the server after customisation. |
| * |
| * @see #RUNTIME_FILES |
| */ |
| @Beta |
| @SuppressWarnings("serial") |
| @SetFromFlag("runtimeTemplates") |
| ConfigKey<Map<String, String>> RUNTIME_TEMPLATES = ConfigKeys.newConfigKey(new TypeToken<Map<String, String>>() { }, |
| "templates.runtime", "Mapping of templates, to be filled in and copied before customisation, to destination name relative to runDir"); |
| |
| @SetFromFlag("provisioningProperties") |
| MapConfigKey<Object> PROVISIONING_PROPERTIES = new MapConfigKey<Object>(Object.class, |
| "provisioning.properties", "Custom properties to be passed in when provisioning a new machine", MutableMap.<String,Object>of()); |
| |
| @SetFromFlag("maxRebindSensorsDelay") |
| ConfigKey<Duration> MAXIMUM_REBIND_SENSOR_CONNECT_DELAY = ConfigKeys.newConfigKey(Duration.class, |
| "softwareProcess.maxSensorRebindDelay", |
| "The maximum delay to apply when reconnecting sensors when rebinding to this entity. " + |
| "Brooklyn will wait a random amount of time, up to the value of this config key, to " + |
| "avoid a thundering herd problem when the entity shares its machine with " + |
| "several others. Set to null or to 0 to disable any delay.", |
| Duration.TEN_SECONDS); |
| |
| /** |
| * Sets the object that manages the sequence of calls of the entity's driver. |
| */ |
| @Beta |
| @SetFromFlag("lifecycleEffectorTasks") |
| ConfigKey<SoftwareProcessDriverLifecycleEffectorTasks> LIFECYCLE_EFFECTOR_TASKS = ConfigKeys.newConfigKey(SoftwareProcessDriverLifecycleEffectorTasks.class, |
| "softwareProcess.lifecycleTasks", "An object that handles lifecycle of an entity's associated machine.", |
| new SoftwareProcessDriverLifecycleEffectorTasks()); |
| |
| ConfigKey<Boolean> RETRIEVE_USAGE_METRICS = ConfigKeys.newBooleanConfigKey( |
| "metrics.usage.retrieve", |
| "Whether to retrieve the usage (e.g. performance) metrics", |
| true); |
| |
| /** Controls the behavior when starting (stop, restart) {@link Startable} children as part of the start (stop, restart) effector on this entity |
| * <p> |
| * (NB: restarts are currently not propagated to children in the default {@link SoftwareProcess} |
| * due to the various semantics which may be desired; this may change, but if entities have specific requirements for restart, |
| * developers should either subclass the {@link SoftwareProcessDriverLifecycleEffectorTasks} and/or lean on sensors from the parent */ |
| enum ChildStartableMode { |
| /** do nothing with {@link Startable} children */ |
| NONE(true, false, false), |
| /** start (stop) {@link Startable} children concurrent with *driver* start (stop), |
| * in foreground, so invoking entity will wait for children to complete. |
| * <p> |
| * if the child requires the parent to reach a particular state before acting, |
| * when running in foreground the parent should communicate its state using sensors |
| * which the child listens for. |
| * note that often sensors at the parent are not activated until it is started, |
| * so the usual sensors connected at an entity may not be available when running in this mode */ |
| FOREGROUND(false, false, false), |
| /** as {@link #FOREGROUND} but {@link ChildStartableMode#isLate} */ |
| FOREGROUND_LATE(false, false, true), |
| /** start {@link Startable} children concurrent with *driver* start (stop, restart), |
| * but in background, ie disassociated from the effector task at this entity |
| * (so that this entity can complete start/stop independent of children) */ |
| BACKGROUND(false, true, false), |
| /** as {@link #BACKGROUND} but {@link ChildStartableMode#isLate} */ |
| BACKGROUND_LATE(false, true, true); |
| |
| /** whether starting (stopping, restarting) children is disabled */ |
| public final boolean isDisabled; |
| /** whether starting (stopping, restarting) children is backgrounded, so parent should not wait on them */ |
| public final boolean isBackground; |
| /** whether starting (stopping, restarting) children should be nested, so start occurs after the driver is started, |
| * and stop before the driver is stopped (if false the children operations are concurrent with the parent), |
| * (with restart always being done in parallel though this behaviour may change) */ |
| public final boolean isLate; |
| |
| private ChildStartableMode(boolean isDisabled, boolean isBackground, boolean isLate) { |
| this.isDisabled = isDisabled; |
| this.isBackground = isBackground; |
| this.isLate = isLate; |
| } |
| |
| } |
| |
| @SetFromFlag("childStartMode") |
| ConfigKey<ChildStartableMode> CHILDREN_STARTABLE_MODE = ConfigKeys.newConfigKey(ChildStartableMode.class, |
| "children.startable.mode", "Controls behaviour when starting Startable children as part of this entity's lifecycle.", |
| ChildStartableMode.NONE); |
| |
| @SuppressWarnings("rawtypes") |
| AttributeSensor<MachineProvisioningLocation> PROVISIONING_LOCATION = Sensors.newSensor( |
| MachineProvisioningLocation.class, "softwareservice.provisioningLocation", "Location used to provision a machine where this is running"); |
| |
| AttributeSensor<Boolean> SERVICE_PROCESS_IS_RUNNING = Sensors.newBooleanSensor("service.process.isRunning", |
| "Whether the process for the service is confirmed as running"); |
| |
| AttributeSensor<Lifecycle> SERVICE_STATE_ACTUAL = Attributes.SERVICE_STATE_ACTUAL; |
| AttributeSensor<Transition> SERVICE_STATE_EXPECTED = Attributes.SERVICE_STATE_EXPECTED; |
| |
| AttributeSensor<String> PID_FILE = Sensors.newStringSensor("softwareprocess.pid.file", "PID file"); |
| |
| @Beta |
| public static class RestartSoftwareParameters { |
| @Beta /** @since 0.7.0 semantics of parameters to restart being explored */ |
| public static final ConfigKey<Boolean> RESTART_CHILDREN = ConfigKeys.newConfigKey(Boolean.class, "restartChildren", |
| "Whether to restart children; default false", false); |
| |
| @Beta /** @since 0.7.0 semantics of parameters to restart being explored */ |
| public static final ConfigKey<Object> RESTART_MACHINE = ConfigKeys.newConfigKey(Object.class, "restartMachine", |
| "Whether to restart/replace the machine provisioned for this entity: 'true', 'false', or 'auto' are supported, " |
| + "with the default being 'auto' which means to restart or reprovision the machine if there is no simpler way known to restart the entity " |
| + "(for example, if the machine is unhealthy, it would not be possible to restart the process, not even via a stop-then-start sequence); " |
| + "if the machine was not provisioned for this entity, this parameter has no effect", |
| RestartMachineMode.AUTO.toString().toLowerCase()); |
| |
| // we supply a typed variant for retrieval; we want the untyped (above) to use lower case as the default in the GUI |
| // (very hard if using enum, since enum takes the name, and RendererHints do not apply to parameters) |
| @Beta /** @since 0.7.0 semantics of parameters to restart being explored */ |
| public static final ConfigKey<RestartMachineMode> RESTART_MACHINE_TYPED = ConfigKeys.newConfigKey(RestartMachineMode.class, "restartMachine"); |
| |
| public enum RestartMachineMode { TRUE, FALSE, AUTO } |
| } |
| |
| @Beta |
| public static class StopSoftwareParameters { |
| //IF_NOT_STOPPED includes STARTING, STOPPING, RUNNING |
| public enum StopMode { ALWAYS, IF_NOT_STOPPED, NEVER }; |
| |
| @Beta /** @since 0.7.0 semantics of parameters to restart being explored */ |
| public static final ConfigKey<StopMode> STOP_PROCESS_MODE = ConfigKeys.newConfigKey(StopMode.class, "stopProcessMode", |
| "When to stop the process with regard to the entity state. " + |
| "ALWAYS will try to stop the process even if the entity is marked as stopped, " + |
| "IF_NOT_STOPPED stops the process only if the entity is not marked as stopped, " + |
| "NEVER doesn't stop the process.", StopMode.IF_NOT_STOPPED); |
| |
| @Beta /** @since 0.7.0 semantics of parameters to restart being explored */ |
| public static final ConfigKey<StopMode> STOP_MACHINE_MODE = ConfigKeys.newConfigKey(StopMode.class, "stopMachineMode", |
| "When to stop the machine with regard to the entity state. " + |
| "ALWAYS will try to stop the machine even if the entity is marked as stopped, " + |
| "IF_NOT_STOPPED stops the machine only if the entity is not marked as stopped, " + |
| "NEVER doesn't stop the machine.", StopMode.IF_NOT_STOPPED); |
| } |
| |
| // NB: the START, STOP, and RESTART effectors themselves are (re)defined by MachineLifecycleEffectorTasks |
| |
| /** |
| * @since 0.8.0 |
| */ |
| @Effector(description="Populates the attribute service.notUp.diagnostics, with any available health indicators") |
| @Beta |
| void populateServiceNotUpDiagnostics(); |
| } |
