Java tutorial
/* * 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 static com.google.common.base.Preconditions.checkNotNull; import static org.apache.brooklyn.util.JavaGroovyEquivalents.elvis; import java.io.File; import java.io.InputStream; import java.io.Reader; import java.io.StringReader; import java.util.Map; import org.apache.brooklyn.api.entity.EntityLocal; import org.apache.brooklyn.api.location.Location; import org.apache.brooklyn.config.ConfigKey; import org.apache.brooklyn.core.entity.BrooklynConfigKeys; import org.apache.brooklyn.core.entity.lifecycle.Lifecycle; import org.apache.brooklyn.core.entity.lifecycle.ServiceStateLogic; import org.apache.brooklyn.util.collections.MutableMap; import org.apache.brooklyn.util.core.ResourceUtils; import org.apache.brooklyn.util.core.task.DynamicTasks; import org.apache.brooklyn.util.core.task.Tasks; import org.apache.brooklyn.util.core.text.TemplateProcessor; import org.apache.brooklyn.util.exceptions.Exceptions; import org.apache.brooklyn.util.os.Os; import org.apache.brooklyn.util.stream.ReaderInputStream; import org.apache.brooklyn.util.text.Strings; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import com.google.common.annotations.Beta; import com.google.common.base.Optional; import com.google.common.collect.ImmutableMap; /** * An abstract implementation of the {@link SoftwareProcessDriver}. */ public abstract class AbstractSoftwareProcessDriver implements SoftwareProcessDriver { private static final Logger log = LoggerFactory.getLogger(AbstractSoftwareProcessDriver.class); protected final EntityLocal entity; protected final ResourceUtils resource; protected final Location location; public AbstractSoftwareProcessDriver(EntityLocal entity, Location location) { this.entity = checkNotNull(entity, "entity"); this.location = checkNotNull(location, "location"); this.resource = ResourceUtils.create(entity); } /* * (non-Javadoc) * @see org.apache.brooklyn.entity.software.base.SoftwareProcessDriver#rebind() */ @Override public void rebind() { // no-op } /** * Start the entity. * <p> * This installs, configures and launches the application process. However, * users can also call the {@link #install()}, {@link #customize()} and * {@link #launch()} steps independently. The {@link #postLaunch()} will * be called after the {@link #launch()} metheod is executed, but the * process may not be completely initialised at this stage, so care is * required when implementing these stages. * <p> * The {@link BrooklynConfigKeys#ENTITY_STARTED} key can be set on the location * or the entity to skip the startup process if the entity is already running, * according to the {@link #isRunning()} method. To force the startup to be * skipped, {@link BrooklynConfigKeys#SKIP_ENTITY_START} can be set on the entity. * The {@link BrooklynConfigKeys#SKIP_ENTITY_INSTALLATION} key can also be used to * skip the {@link #setup()}, {@link #copyInstallResources()} and * {@link #install()} methods if set on the entity or location. * * @see #stop() */ @Override public void start() { boolean skipStart = false; Optional<Boolean> locationRunning = Optional .fromNullable(getLocation().getConfig(BrooklynConfigKeys.SKIP_ENTITY_START_IF_RUNNING)); Optional<Boolean> entityRunning = Optional .fromNullable(entity.getConfig(BrooklynConfigKeys.SKIP_ENTITY_START_IF_RUNNING)); Optional<Boolean> entityStarted = Optional .fromNullable(entity.getConfig(BrooklynConfigKeys.SKIP_ENTITY_START)); if (locationRunning.or(entityRunning).or(false)) { skipStart = isRunning(); } else { skipStart = entityStarted.or(false); } if (!skipStart) { DynamicTasks.queue("install", new Runnable() { public void run() { Optional<Boolean> locationInstalled = Optional .fromNullable(getLocation().getConfig(BrooklynConfigKeys.SKIP_ENTITY_INSTALLATION)); Optional<Boolean> entityInstalled = Optional .fromNullable(entity.getConfig(BrooklynConfigKeys.SKIP_ENTITY_INSTALLATION)); boolean skipInstall = locationInstalled.or(entityInstalled).or(false); if (!skipInstall) { DynamicTasks.queue("copy-pre-install-resources", new Runnable() { public void run() { waitForConfigKey(BrooklynConfigKeys.PRE_INSTALL_RESOURCES_LATCH); copyPreInstallResources(); } }); DynamicTasks.queue("pre-install", new Runnable() { public void run() { preInstall(); } }); DynamicTasks.queue("pre-install-command", new Runnable() { public void run() { runPreInstallCommand(); } }); DynamicTasks.queue("setup", new Runnable() { public void run() { waitForConfigKey(BrooklynConfigKeys.SETUP_LATCH); setup(); } }); DynamicTasks.queue("copy-install-resources", new Runnable() { public void run() { waitForConfigKey(BrooklynConfigKeys.INSTALL_RESOURCES_LATCH); copyInstallResources(); } }); DynamicTasks.queue("install (main)", new Runnable() { public void run() { waitForConfigKey(BrooklynConfigKeys.INSTALL_LATCH); install(); } }); } DynamicTasks.queue("post-install-command", new Runnable() { public void run() { runPostInstallCommand(); } }); } }); DynamicTasks.queue("customize", new Runnable() { public void run() { waitForConfigKey(BrooklynConfigKeys.CUSTOMIZE_LATCH); customize(); } }); DynamicTasks.queue("launch", new Runnable() { public void run() { DynamicTasks.queue("copy-runtime-resources", new Runnable() { public void run() { waitForConfigKey(BrooklynConfigKeys.RUNTIME_RESOURCES_LATCH); copyRuntimeResources(); } }); DynamicTasks.queue("pre-launch-command", new Runnable() { public void run() { runPreLaunchCommand(); } }); DynamicTasks.queue("launch (main)", new Runnable() { public void run() { waitForConfigKey(BrooklynConfigKeys.LAUNCH_LATCH); launch(); } }); DynamicTasks.queue("post-launch-command", new Runnable() { public void run() { runPostLaunchCommand(); } }); } }); } DynamicTasks.queue("post-launch", new Runnable() { public void run() { postLaunch(); } }); } @Override public abstract void stop(); /** * Implement this method in child classes to add some pre-install behavior */ public void preInstall() { } public abstract void runPreInstallCommand(); public abstract void setup(); public abstract void install(); public abstract void runPostInstallCommand(); public abstract void customize(); public abstract void runPreLaunchCommand(); public abstract void launch(); /** Only run if launch is run (if start is not skipped). */ public abstract void runPostLaunchCommand(); @Override public void kill() { stop(); } /** * Implement this method in child classes to add some post-launch behavior. * This is run even if start is skipped and launch is not run. */ public void postLaunch() { } @Override public void restart() { DynamicTasks.queue("stop (best effort)", new Runnable() { public void run() { DynamicTasks.markInessential(); boolean previouslyRunning = isRunning(); try { ServiceStateLogic.setExpectedState(getEntity(), Lifecycle.STOPPING); stop(); } catch (Exception e) { // queue a failed task so that there is visual indication that this task had a failure, // without interrupting the parent if (previouslyRunning) { log.warn(getEntity() + " restart: stop failed, when was previously running (ignoring)", e); DynamicTasks.queue(Tasks.fail("Primary job failure (when previously running)", e)); } else { log.debug(getEntity() + " restart: stop failed (but was not previously running, so not a surprise)", e); DynamicTasks.queue(Tasks.fail("Primary job failure (when not previously running)", e)); } // the above queued tasks will cause this task to be indicated as failed, with an indication of severity } } }); if (doFullStartOnRestart()) { DynamicTasks.waitForLast(); ServiceStateLogic.setExpectedState(getEntity(), Lifecycle.STARTING); start(); } else { DynamicTasks.queue("launch", new Runnable() { public void run() { ServiceStateLogic.setExpectedState(getEntity(), Lifecycle.STARTING); launch(); } }); DynamicTasks.queue("post-launch", new Runnable() { public void run() { postLaunch(); } }); } } @Beta /** ideally restart() would take options, e.g. whether to do full start, skip installs, etc; * however in the absence here is a toggle - not sure how well it works; * default is false which is similar to previous behaviour (with some seemingly-obvious tidies), * meaning install and configure will NOT be done on restart. */ protected boolean doFullStartOnRestart() { return false; } @Override public EntityLocal getEntity() { return entity; } @Override public Location getLocation() { return location; } public InputStream getResource(String url) { return resource.getResourceFromUrl(url); } /** * Files and templates to be copied to the server <em>before</em> pre-install. This allows the {@link #preInstall()} * process to have access to all required resources. * <p> * Will be prefixed with the entity's {@link #getInstallDir() install directory} if relative. * * @see SoftwareProcess#PRE_INSTALL_FILES * @see SoftwareProcess#PRE_INSTALL_TEMPLATES * @see #copyRuntimeResources() */ public void copyPreInstallResources() { copyResources(entity.getConfig(SoftwareProcess.PRE_INSTALL_FILES), entity.getConfig(SoftwareProcess.PRE_INSTALL_TEMPLATES)); } /** * Files and templates to be copied to the server <em>before</em> installation. This allows the {@link #install()} * process to have access to all required resources. * <p> * Will be prefixed with the entity's {@link #getInstallDir() install directory} if relative. * * @see SoftwareProcess#INSTALL_FILES * @see SoftwareProcess#INSTALL_TEMPLATES * @see #copyRuntimeResources() */ public void copyInstallResources() { copyResources(entity.getConfig(SoftwareProcess.INSTALL_FILES), entity.getConfig(SoftwareProcess.INSTALL_TEMPLATES)); } private void copyResources(Map<String, String> files, Map<String, String> templates) { // Ensure environment variables are not looked up here, otherwise sub-classes might // lookup port numbers and fail with ugly error if port is not set; better to wait // until in Entity's code (e.g. customize) where such checks are done explicitly. boolean hasAnythingToCopy = ((files != null && files.size() > 0) || (templates != null && templates.size() > 0)); if (hasAnythingToCopy) { createDirectory(getInstallDir(), "create install directory"); // TODO see comment in copyResource, that should be queued as a task like the above // (better reporting in activities console) if (files != null && files.size() > 0) { for (String source : files.keySet()) { String target = files.get(source); String destination = Os.isAbsolutish(target) ? target : Os.mergePathsUnix(getInstallDir(), target); copyResource(source, destination, true); } } if (templates != null && templates.size() > 0) { for (String source : templates.keySet()) { String target = templates.get(source); String destination = Os.isAbsolutish(target) ? target : Os.mergePathsUnix(getInstallDir(), target); copyTemplate(source, destination, true, MutableMap.<String, Object>of()); } } } } protected abstract void createDirectory(String directoryName, String summaryForLogging); /** * Files and templates to be copied to the server <em>after</em> customisation. This allows overwriting of * existing files such as entity configuration which may be copied from the installation directory * during the {@link #customize()} process. * <p> * Will be prefixed with the entity's {@link #getRunDir() run directory} if relative. * * @see SoftwareProcess#RUNTIME_FILES * @see SoftwareProcess#RUNTIME_TEMPLATES * @see #copyInstallResources() */ public void copyRuntimeResources() { try { createDirectory(getRunDir(), "create run directory"); Map<String, String> runtimeFiles = entity.getConfig(SoftwareProcess.RUNTIME_FILES); if (runtimeFiles != null && runtimeFiles.size() > 0) { for (String source : runtimeFiles.keySet()) { String target = runtimeFiles.get(source); String destination = Os.isAbsolutish(target) ? target : Os.mergePathsUnix(getRunDir(), target); copyResource(source, destination, true); } } Map<String, String> runtimeTemplates = entity.getConfig(SoftwareProcess.RUNTIME_TEMPLATES); if (runtimeTemplates != null && runtimeTemplates.size() > 0) { for (String source : runtimeTemplates.keySet()) { String target = runtimeTemplates.get(source); String destination = Os.isAbsolutish(target) ? target : Os.mergePathsUnix(getRunDir(), target); copyTemplate(source, destination, true, MutableMap.<String, Object>of()); } } } catch (Exception e) { log.warn("Error copying runtime resources", e); throw Exceptions.propagate(e); } } /** * @param template File to template and copy. * @param target Destination on server. * @return The exit code the SSH command run. */ public int copyTemplate(File template, String target) { return copyTemplate(template.toURI().toASCIIString(), target); } /** * @param template URI of file to template and copy, e.g. file://.., http://.., classpath://.. * @param target Destination on server. * @return The exit code of the SSH command run. */ public int copyTemplate(String template, String target) { return copyTemplate(template, target, false, ImmutableMap.<String, String>of()); } /** * @param template URI of file to template and copy, e.g. file://.., http://.., classpath://.. * @param target Destination on server. * @param extraSubstitutions Extra substitutions for the templater to use, for example * "foo" -> "bar", and in a template ${foo}. * @return The exit code of the SSH command run. */ public int copyTemplate(String template, String target, boolean createParent, Map<String, ?> extraSubstitutions) { String data = processTemplate(template, extraSubstitutions); return copyResource(MutableMap.<Object, Object>of(), new StringReader(data), target, createParent); } public abstract int copyResource(Map<Object, Object> sshFlags, String source, String target, boolean createParentDir); public abstract int copyResource(Map<Object, Object> sshFlags, InputStream source, String target, boolean createParentDir); /** * @param file File to copy. * @param target Destination on server. * @return The exit code the SSH command run. */ public int copyResource(File file, String target) { return copyResource(file.toURI().toASCIIString(), target); } /** * @param resource URI of file to copy, e.g. file://.., http://.., classpath://.. * @param target Destination on server. * @return The exit code of the SSH command run */ public int copyResource(String resource, String target) { return copyResource(MutableMap.of(), resource, target); } public int copyResource(String resource, String target, boolean createParentDir) { return copyResource(MutableMap.of(), resource, target, createParentDir); } @SuppressWarnings({ "rawtypes", "unchecked" }) public int copyResource(Map sshFlags, String source, String target) { return copyResource(sshFlags, source, target, false); } /** * @see #copyResource(Map, InputStream, String, boolean) */ public int copyResource(Reader source, String target) { return copyResource(MutableMap.of(), source, target, false); } /** * @see #copyResource(Map, InputStream, String, boolean) */ public int copyResource(Map<Object, Object> sshFlags, Reader source, String target, boolean createParent) { return copyResource(sshFlags, new ReaderInputStream(source), target, createParent); } /** * @see #copyResource(Map, InputStream, String, boolean) */ public int copyResource(InputStream source, String target) { return copyResource(MutableMap.of(), source, target, false); } public String getResourceAsString(String url) { return resource.getResourceAsString(url); } public String processTemplate(File templateConfigFile, Map<String, Object> extraSubstitutions) { return processTemplate(templateConfigFile.toURI().toASCIIString(), extraSubstitutions); } public String processTemplate(File templateConfigFile) { return processTemplate(templateConfigFile.toURI().toASCIIString()); } /** Takes the contents of a template file from the given URL (often a classpath://com/myco/myprod/myfile.conf or .sh) * and replaces "${entity.xxx}" with the result of entity.getXxx() and similar for other driver, location; * as well as replacing config keys on the management context * <p> * uses Freemarker templates under the covers **/ public String processTemplate(String templateConfigUrl) { return processTemplate(templateConfigUrl, ImmutableMap.<String, String>of()); } public String processTemplate(String templateConfigUrl, Map<String, ? extends Object> extraSubstitutions) { return processTemplateContents(getResourceAsString(templateConfigUrl), extraSubstitutions); } public String processTemplateContents(String templateContents) { return processTemplateContents(templateContents, ImmutableMap.<String, String>of()); } public String processTemplateContents(String templateContents, Map<String, ? extends Object> extraSubstitutions) { return TemplateProcessor.processTemplateContents(templateContents, this, extraSubstitutions); } protected void waitForConfigKey(ConfigKey<?> configKey) { Object val = entity.getConfig(configKey); if (val != null) log.debug("{} finished waiting for {} (value {}); continuing...", new Object[] { this, configKey, val }); } /** * @deprecated since 0.5.0; instead rely on {@link org.apache.brooklyn.api.entity.drivers.downloads.DownloadResolverManager} to include local-repo, such as: * * <pre> * {@code * DownloadResolver resolver = Entities.newDownloader(this); * List<String> urls = resolver.getTargets(); * } * </pre> */ protected String getEntityVersionLabel() { return getEntityVersionLabel("_"); } /** * @deprecated since 0.5.0; instead rely on {@link org.apache.brooklyn.api.entity.drivers.downloads.DownloadResolverManager} to include local-repo */ protected String getEntityVersionLabel(String separator) { return elvis(entity.getEntityType().getSimpleName(), entity.getClass().getName()) + (getVersion() != null ? separator + getVersion() : ""); } public String getVersion() { return getEntity().getConfig(SoftwareProcess.SUGGESTED_VERSION); } public abstract String getRunDir(); public abstract String getInstallDir(); }