/* dCache - http://www.dcache.org/
*
* Copyright (C) 2014 Deutsches Elektronen-Synchrotron
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package org.dcache.pool.nearline.spi;
import com.google.common.util.concurrent.ListenableFuture;
import java.util.UUID;
/**
* A request to a nearline storage.
*
* The request is parametrised with the type of the result of the request.
*
* A request has a lifetime containing three stages: queued, activated and
* completed/failed. Activation is signalled by calling activated, while
* completion/failure is signaled by calling completed/failed.
*/
public interface NearlineRequest<T>
{
/**
* Returns an identifier uniquely identifying this request.
*
* @return A unique identifier
*/
UUID getId();
/**
* A deadline for the request.
*
* If the request does not complete before the deadline, the pool will
* likely cancel the request. The deadline is not a promise that the
* request will be cancelled, nor is it a promise that the request will
* not be cancelled ahead of time.
*
* The current implementation of timeouts is temporary. Currently the
* pool allows timeouts to be configured starting at the activation
* timeout and the deadline reflects these. Eventually, pool specific
* timeouts wil be removed and replaced by two timeouts: One defined
* by the user submitting the request (e.g. a stage request by the SRM)
* and optionally a provider specific timeout. This deadline will reflect
* the former.
*
* @return Deadline in milliseconds since the epoch
*/
long getDeadline();
/**
* Signals that the request is being activated.
*
* An activated request is actively being processed rather than just being
* queued. Note however than an external HSM may itself queue requests. Such
* requests are still considered active by dCache.
*
* The activation may not be instantaneous as dCache may perform additional
* name space lookups during activation. For this reason the result is
* provided asynchronously. A NearlineStorage should not proceed with
* processing the request until activation has completed.
*
* @return An asynchronous reply indicating when to proceed with processing
* the request. The activation may fail and a NearlineStorage must
* fail the entire request by calling {@code failed} with the exception
* returned by the future.
*/
ListenableFuture<Void> activate();
/**
* Signals that the request has failed.
*
* Any exception is allowed and will be translated to a CacheException before
* propagation to dCache. Exceptions are translated as follows:
*
* <ul>
* <li>Any {@link java.util.concurrent.ExecutionException} has its <i>cause</i> unwrapped
* and the cause is translated according to these rules.
* <li>Any {@link InterruptedException} and {@link java.util.concurrent.CancellationException} are
* considered as indication that the request has been cancelled.
* <li>Any {@link diskCacheV111.util.CacheException} is propagated untouched.
* <li>Any other exception is propagated, but is most likely turned wrapped in a CacheException
* by the code that invoked the request.
* </ul>
*
* @param cause Exception indicating the cause of the failure
*/
void failed(Exception cause);
/**
* Signals that the request has failed.
*
* Identical to calling <code>failed(new CacheException(rc, msg))</code>, but avoids
* the dependency on that specific exception type.
*
* Summary of return codes:
*
* Return Code Meaning Behaviour for PUT FILE Behaviour for GET FILE
* 30 <= rc < 40 User defined Deactivates request Reports problem to poolmanager
* 41 No space left on device Pool retries Disables pool and reports problem to poolmanager
* 42 Disk read I/O error Pool retries Disables pool and reports problem to poolmanager
* 43 Disk write I/O error Pool retries Disables pool and reports problem to poolmanager
* other - Pool retries Reports problem to poolmanager
*
* @param rc Return code
* @param msg Error message
*/
void failed(int rc, String msg);
/**
* Signals that the request has completed successfully.
*
* @param result The result of the request
*/
void completed(T result);
}