/*
 * RHQ Management Platform
 * Copyright (C) 2005-2008 Red Hat, Inc.
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License, version 2, as
 * published by the Free Software Foundation, and/or the GNU Lesser
 * General Public License, version 2.1, also as published by the Free
 * Software Foundation.
 *
 * 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 General Public License and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with this program;
 * if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
package org.rhq.core.clientapi.server.content;

import java.io.InputStream;
import java.io.OutputStream;
import java.util.Set;

import org.rhq.core.communications.command.annotation.Asynchronous;
import org.rhq.core.communications.command.annotation.LimitedConcurrency;
import org.rhq.core.communications.command.annotation.Timeout;
import org.rhq.core.domain.content.Repo;
import org.rhq.core.domain.content.PackageDetailsKey;
import org.rhq.core.domain.content.PackageVersion;
import org.rhq.core.domain.content.composite.PackageVersionMetadataComposite;
import org.rhq.core.clientapi.server.content.ContentDiscoveryReport;
import org.rhq.core.domain.content.transfer.DeployPackagesResponse;
import org.rhq.core.domain.content.transfer.RemovePackagesResponse;
import org.rhq.core.domain.content.transfer.ResourcePackageDetails;
import org.rhq.core.domain.util.PageControl;
import org.rhq.core.domain.util.PageList;

/**
 * Server-side interface for interacting with the server's content subsystem.
 */
public interface ContentServerService {
    /**
     * Concurrency control parameter to limit the number of content reports that are handled.
     */
    String CONCURRENCY_LIMIT_CONTENT_REPORT = "rhq.server.concurrency-limit.content-report";

    /**
     * Concurrency control setting to limit the number of packages that can be downloaded.
     */
    String CONCURRENCY_LIMIT_CONTENT_DOWNLOAD = "rhq.server.concurrency-limit.content-download";

    /**
     * Sends a set of newly discovered packages to the server. The collection of packages represents the current set of
     * packages deployed on the specified resource. As such, entries may be either new packages or packages that have
     * been returned from a previous discovery. Any packages that were known for the resource that are not in this
     * collection of package are considered deleted from the resource.
     *
     * @param report report containing the current set of packages installed on the resource.
     */
    @Asynchronous(guaranteedDelivery = true)
    @LimitedConcurrency(CONCURRENCY_LIMIT_CONTENT_REPORT)
    void mergeDiscoveredPackages(ContentDiscoveryReport report);

    /**
     * Informs the server that a previous request to deploy a package has completed.
     *
     * @param response indicates the original request and the result of executing it
     */
    @Asynchronous(guaranteedDelivery = true)
    void completeDeployPackageRequest(DeployPackagesResponse response);

    /**
     * Informs the server that a previous request to delete a package has completed.
     *
     * @param response indicates the original request and the result of executing it
     */
    @Asynchronous(guaranteedDelivery = true)
    void completeDeletePackageRequest(RemovePackagesResponse response);

    /**
     * Informs the server that a previous request to get a package's bits has completed.
     *
     * @param response      indicates the original request and the result of executing it
     * @param contentStream stream of the package bits being retrieved
     */
    @Asynchronous(guaranteedDelivery = true)
    void completeRetrievePackageBitsRequest(ContentServiceResponse response, InputStream contentStream);

    /**
     * Informs the server that a package installation (as indicated in the specified request ID) requires dependency
     * packages to be installed. The server will look in its package store to make sure the correct package versions can
     * be found. The server will take the necessary server-side actions to ensure the integrity of the initial request
     * (such as attaching the dependency packages to the initial request entity). In the case of a failure, the server
     * should not mark the request entity as a failure; the natural workflow of a failure response coming back to the
     * server from the agent will take care of that. This method should return the fully populated package descriptions.
     * If the package was not found in the package database, it will be omitted from the returned set.
     *
     * @param  requestId          refers back to the request ID of the package deployment for which these dependencies
     *                            were found
     * @param  dependencyPackages provides information on the dependency package (name, type, version, architecture);
     *
     * @return fully populated metadata on the packages known to the server for each of the specified keys; if the
     *         server does not know about a package, it will not be present in the returned set
     */
    Set<ResourcePackageDetails> loadDependencies(int requestId, Set<PackageDetailsKey> dependencyPackages);

    /**
     * Requests that the server download and stream the bits for the specified package. If the package cannot be found,
     * an exception will be thrown.
     *
     * @param  resourceId        identifies the resource to which the bits will be installed
     * @param  packageDetailsKey identifies the package to download
     * @param  outputStream      an output stream where the server should write the package contents. It is up to the
     *                           caller to prepare this output stream in order to write the package content to an
     *                           appropriate location.
     *
     * @return the number of bytes written to the output stream - this is the size of the package version that was
     *         downloaded
     */
    @Timeout(45 * 60 * 1000L)
    @LimitedConcurrency(CONCURRENCY_LIMIT_CONTENT_DOWNLOAD)
    long downloadPackageBitsGivenResource(int resourceId, PackageDetailsKey packageDetailsKey, OutputStream outputStream);

    /**
     * Requests that the server download and stream the bits for the specified package. If the package cannot be found,
     * an exception will be thrown.
     *
     * @param  resourceId        identifies the resource to which the bits will be installed
     * @param  packageDetailsKey identifies the package to download
     * @param  outputStream      an output stream where the server should write the package contents. It is up to the
     *                           caller to prepare this output stream in order to write the package content to an
     *                           appropriate location.
     * @param  startByte         the first byte (inclusive) of the byte range to retrieve and output (bytes start at
     *                           index 0)
     * @param  endByte           the last byte (inclusive) of the byte range to retrieve and output (-1 means up to EOF)
     *                           (bytes start at index 0)
     *
     * @return the number of bytes written to the output stream - this is the size of the chunk downloaded
     */
    @Timeout(45 * 60 * 1000L)
    @LimitedConcurrency(CONCURRENCY_LIMIT_CONTENT_DOWNLOAD)
    long downloadPackageBitsRangeGivenResource(int resourceId, PackageDetailsKey packageDetailsKey,
        OutputStream outputStream, long startByte, long endByte);

    /**
     * Downloads the package bits used to create a package used as the backing of a resource.
     *
     * @param parentResourceId  identifies the parent resource under which the new resource is being created
     * @param resourceTypeName  type of child resource being created
     * @param packageDetailsKey package being used to create the child resource
     * @param outputStream      an output stream where the server should write the package contents. It is up to the
     *                          caller to prepare this output stream in order to write the package content to an
     *                          appropriate location.
     * 
     * @return the number of bytes written to the output stream
     */
    @Timeout(45 * 60 * 1000L)
    @LimitedConcurrency(CONCURRENCY_LIMIT_CONTENT_DOWNLOAD)
    long downloadPackageBitsForChildResource(int parentResourceId, String resourceTypeName,
        PackageDetailsKey packageDetailsKey, OutputStream outputStream);

    /**
     * Requests all {@link PackageVersion#getMetadata() metadata} for all package versions that the given resource
     * component is subscribed to (see {@link Repo#getResources()}. The returned object has the metadata bytes that
     * are meaningful to the calling plugin component.
     *
     * <p>Callers should consider caching the returned metadata. Use {@link #getResourceSubscriptionMD5(int)} to get the
     * MD5 hashcode of the metadata for the resource to aid in determining when a cache of metadata is stale.</p>
     *
     * @param  resourceId identifies the resource requesting the data; all package versions in all the resource's
     *                    subscribed repos will be represented in the returned map
     * @param  pc         this method can potentially return a large set; this page control object allows the caller to
     *                    page through that large set, as opposed to requesting the entire set in one large chunk
     *
     * @return the list of all package versions' metadata
     */
    @LimitedConcurrency(CONCURRENCY_LIMIT_CONTENT_DOWNLOAD)
    PageList<PackageVersionMetadataComposite> getPackageVersionMetadata(int resourceId, PageControl pc);

    /**
     * Gets the MD5 hash of the resource's "content subscription". If any changes were made to the repos this
     * resource is subscribed to, a changed MD5 will be returned.
     *
     * @param  resourceId identifies the resource requesting the MD5; if any change to any package version in any
     *                    resource's subscribed repos will be used when generating the MD5
     *
     * @return the MD5 of all package versions' metadata
     *
     * @see    #getPackageVersionMetadata(int, PageControl)
     */
    String getResourceSubscriptionMD5(int resourceId);

    /**
     * Requests the size, in bytes, of the identified package version.
     *
     * @param  resourceId        identifies the resource requesting the info
     * @param  packageDetailsKey identifies the package whose size is to be returned
     *
     * @return the size, in number of bytes, of the package version
     */
    long getPackageBitsLength(int resourceId, PackageDetailsKey packageDetailsKey);
    
    /**
     * Requests loading of lazy loaded package. By this method the package content will be 
     * loaded to server and ready to stream to the client.
     *   
     * @param resourceId
     * @param packageDetailsKey
     * @return
     */
    @Timeout(90 * 60 * 1000L)
    @LimitedConcurrency(CONCURRENCY_LIMIT_CONTENT_DOWNLOAD)
    boolean preLoadRemoteContent(int resourceId, PackageDetailsKey packageDetailsKey);
}