plugins/storage/volume/adaptive/src/main/java/org/apache/cloudstack/storage/datastore/adapter/ProviderAdapter.java

// 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.cloudstack.storage.datastore.adapter;

import java.util.Map;

/**
 * A simple DataStore adaptive interface.  This interface allows the ManagedVolumeDataStoreDriverImpl
 * to interact with the external provider without the provider needing to interface with any CloudStack
 * objects, factories or database tables, simplifying the implementation and maintenance of the provider
 * interface.
 */
public interface ProviderAdapter {
    // some common keys across providers.  Provider code determines what to do with it
    public static final String API_USERNAME_KEY = "api_username";
    public static final String API_PASSWORD_KEY = "api_password";
    public static final String API_TOKEN_KEY = "api_token";
    public static final String API_PRIVATE_KEY = "api_privatekey";
    public static final String API_URL_KEY = "api_url";
    public static final String API_SKIP_TLS_VALIDATION_KEY = "api_skiptlsvalidation";
    // one of: basicauth (default), apitoken, privatekey
    public static final String API_AUTHENTICATION_TYPE_KEY = "api_authn_type";

    /**
     * Refresh the connector with the provided details
     * @param details
     */
    public void refresh(Map<String,String> details);

    /**
     * Return if currently connected/configured properly, otherwise throws a RuntimeException
     * with information about what is misconfigured
     * @return
     */
    public void validate();

    /**
     * Forcefully remove/disconnect
     */
    public void disconnect();

    /**
     * Create a new volume on the storage provider
     * @param context
     * @param volume
     * @param diskOffering
     * @param sizeInBytes
     * @return
     */
    public ProviderVolume create(ProviderAdapterContext context, ProviderAdapterDataObject volume, ProviderAdapterDiskOffering diskOffering, long sizeInBytes);

    /**
     * Attach the volume to the target object for the provided context.  Returns the scope-specific connection value (for example, the LUN)
     * @param context
     * @param request
     * @return
     */
    public String attach(ProviderAdapterContext context, ProviderAdapterDataObject request);

    /**
     * Detach the host from the storage context
     * @param context
     * @param request
     */
    public void detach(ProviderAdapterContext context, ProviderAdapterDataObject request);

    /**
     * Delete the provided volume/object
     * @param context
     * @param request
     */
    public void delete(ProviderAdapterContext context, ProviderAdapterDataObject request);

    /**
     * Copy a source object to a destination volume.  The source object can be a Volume, Snapshot, or Template
     */
    public ProviderVolume copy(ProviderAdapterContext context, ProviderAdapterDataObject sourceVolume, ProviderAdapterDataObject targetVolume);

    /**
     * Make a device-specific snapshot of the provided volume
     */
    public ProviderSnapshot snapshot(ProviderAdapterContext context, ProviderAdapterDataObject sourceVolume, ProviderAdapterDataObject targetSnapshot);

    /**
     * Revert the snapshot to its base volume.  Replaces the base volume with the snapshot point on the storage array
     * @param context
     * @param request
     * @return
     */
    public ProviderVolume revert(ProviderAdapterContext context, ProviderAdapterDataObject request);

    /**
     * Resize a volume
     * @param context
     * @param request
     * @param totalNewSizeInBytes
     */
    public void resize(ProviderAdapterContext context, ProviderAdapterDataObject request, long totalNewSizeInBytes);

    /**
     * Return the managed volume info from storage system.
     * @param context
     * @param request
     * @return ProviderVolume object or null if the object was not found but no errors were encountered.
     */
    public ProviderVolume getVolume(ProviderAdapterContext context, ProviderAdapterDataObject request);

    /**
     * Return the managed snapshot info from storage system
     * @param context
     * @param request
     * @return ProviderSnapshot object or null if the object was not found but no errors were encountered.
     */
    public ProviderSnapshot getSnapshot(ProviderAdapterContext context, ProviderAdapterDataObject request);

    /**
     * Given an array-specific address, find the matching volume information from the array
     * @param addressType
     * @param address
     * @return
     */
    public ProviderVolume getVolumeByAddress(ProviderAdapterContext context, ProviderVolume.AddressType addressType, String address);

    /**
     * Returns stats about the managed storage where the volumes and snapshots are created/managed
     * @return
     */
    public ProviderVolumeStorageStats getManagedStorageStats();

    /**
     * Returns stats about a specific volume
     * @return
     */
    public ProviderVolumeStats getVolumeStats(ProviderAdapterContext context, ProviderAdapterDataObject request);

    /**
     * Returns true if the given hostname is accessible to the storage provider.
     * @param context
     * @param request
     * @return
     */
    public boolean canAccessHost(ProviderAdapterContext context, String hostname);
}