All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.brooklyn.api.mgmt.Task Maven / Gradle / Ivy

There is a newer version: 1.1.0
Show newest version
/*
 * 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.api.mgmt;

import java.util.Set;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.FutureTask;
import java.util.concurrent.TimeoutException;

import org.apache.brooklyn.util.time.Duration;

import com.google.common.util.concurrent.ListenableFuture;

/**
 * Represents a unit of work for execution.
 *
 * When used with an {@link ExecutionManager} or {@link ExecutionContext} it will record submission time,
 * execution start time, end time, and any result. A task can be submitted to the ExecutionManager or
 * ExecutionContext, in which case it will be returned, or it may be created by submission
 * of a {@link Runnable} or {@link Callable} and thereafter it can be treated just like a {@link Future}.
 */
public interface Task extends ListenableFuture, TaskAdaptable {
    
    public String getId();
    
    public Set getTags();
    /** if {@link #isSubmitted()} returns the time when the task was submitted; or -1 otherwise */
    public long getSubmitTimeUtc();
    /** if {@link #isBegun()} returns the time when the task was starts;
     * guaranteed to be >= {@link #getSubmitTimeUtc()} > 0 if started, or -1 otherwise */
    public long getStartTimeUtc();
    /** if {@link #isDone()} (for any reason) returns the time when the task ended;
     * guaranteed to be >= {@link #getStartTimeUtc()} > 0 if ended, or -1 otherwise */
    public long getEndTimeUtc();
    public String getDisplayName();
    public String getDescription();
    
    /** task which submitted this task, if was submitted by a task */
    public Task getSubmittedByTask();

    /** The thread where the task is running, if it is running. */
    public Thread getThread();

    /**
     * Whether task has been submitted
     *
     * Submitted tasks are normally expected to start running then complete,
     * but unsubmitted tasks are sometimes passed around for someone else to submit them.
     */
    public boolean isSubmitted();

    /**
     * Whether task has started running.
     *
     * Will remain true after normal completion or non-cancellation error.
     * will be true on cancel iff the thread did actually start.
     */
    public boolean isBegun();

    /**
     * Whether the task threw an error, including cancellation (implies {@link #isDone()})
     */
    public boolean isError();

    /**
     * As {@link Future#isDone()}. In particular if cancelled, this will return true
     * as soon as it is cancelled. The thread for this task may still be running,
     * if the cancellation (often an interruption, but may be weaker) has not applied,
     * and submitted threads may also be running depending on cancellation parameters.
     * 

* {@link #get()} is guaranteed to return immediately, throwing in the case of cancellation * prior to completion (and including the case above where a thread may still be running). *

* To check whether cancelled threads for this task have completed, * inspect {@link #getEndTimeUtc()}, which is guaranteed to be set when threads complete * if the thread is started (as determinable by whether {@link #getStartTimeUtc()} is set). * (The threads of submitted/child tasks will usually be independent; to determine their * completion requires inspecting the {@link ExecutionManager}.) */ @Override public boolean isDone(); /** * Causes calling thread to block until the task is started. */ public void blockUntilStarted(); /** * Causes calling thread to block until the task is ended. *

* Either normally or by cancellation or error, but without throwing error on cancellation or error. * (Errors are logged at debug.) */ public void blockUntilEnded(); /** * As {@link #blockUntilEnded()}, but returning after the given timeout; * true if the task has ended and false otherwise */ public boolean blockUntilEnded(Duration timeout); public String getStatusSummary(); /** * Returns detailed status, suitable for a hover. * * Plain-text format, with new-lines (and sometimes extra info) if multiline enabled. */ public String getStatusDetail(boolean multiline); /** As {@link #get(long, java.util.concurrent.TimeUnit)} */ public T get(Duration duration) throws InterruptedException, ExecutionException, TimeoutException; /** As {@link #get()}, but propagating checked exceptions as unchecked for convenience. */ public T getUnchecked(); /** As {@link #get()}, but propagating checked exceptions as unchecked for convenience * (including a {@link TimeoutException} if the duration expires) */ public T getUnchecked(Duration duration); /** As {@link Future#cancel(boolean)}. Note that {@link #isDone()} and {@link #blockUntilEnded(Duration)} return immediately * once a task is cancelled, consistent with the underlying {@link FutureTask} behaviour. * TODO Fine-grained control over underlying jobs, e.g. to ensure anything represented by this task is actually completed, * is not (yet) publicly exposed. See the convenience method blockUntilInternalTasksEnded in the Tasks set of helpers * for more discussion. */ public boolean cancel(boolean mayInterruptIfRunning); }