github.com/axw/juju@v0.0.0-20161005053422-4bd6544d08d4/environs/storage/interfaces.go (about)

     1  // Copyright 2013 Canonical Ltd.
     2  // Licensed under the AGPLv3, see LICENCE file for details.
     3  
     4  package storage
     5  
     6  import (
     7  	"io"
     8  
     9  	"github.com/juju/utils"
    10  )
    11  
    12  // A StorageReader can retrieve and list files from a storage provider.
    13  type StorageReader interface {
    14  	// Get opens the given storage file and returns a ReadCloser
    15  	// that can be used to read its contents.  It is the caller's
    16  	// responsibility to close it after use.  If the name does not
    17  	// exist, it should return a *NotFoundError.
    18  	Get(name string) (io.ReadCloser, error)
    19  
    20  	// List lists all names in the storage with the given prefix, in
    21  	// alphabetical order.  The names in the storage are considered
    22  	// to be in a flat namespace, so the prefix may include slashes
    23  	// and the names returned are the full names for the matching
    24  	// entries.
    25  	List(prefix string) ([]string, error)
    26  
    27  	// URL returns a URL that can be used to access the given storage file.
    28  	URL(name string) (string, error)
    29  
    30  	// DefaultConsistencyStrategy returns the appropriate polling for waiting
    31  	// for this storage to become consistent.
    32  	// If the storage implementation has immediate consistency, the
    33  	// strategy won't need to wait at all.  But for eventually-consistent
    34  	// storage backends a few seconds of polling may be needed.
    35  	//
    36  	// TODO(katco): 2016-08-09: lp:1611427
    37  	DefaultConsistencyStrategy() utils.AttemptStrategy
    38  
    39  	// ShouldRetry returns true is the specified error is such that an
    40  	// operation can be performed again with a chance of success. This is
    41  	// typically the case where the storage implementation does not have
    42  	// immediate consistency and needs to be given a chance to "catch up".
    43  	ShouldRetry(error) bool
    44  }
    45  
    46  // A StorageWriter adds and removes files in a storage provider.
    47  type StorageWriter interface {
    48  	// Put reads from r and writes to the given storage file.
    49  	// The length must give the total length of the file.
    50  	Put(name string, r io.Reader, length int64) error
    51  
    52  	// Remove removes the given file from the environment's
    53  	// storage. It should not return an error if the file does
    54  	// not exist.
    55  	Remove(name string) error
    56  
    57  	// RemoveAll deletes all files that have been stored here.
    58  	// If the underlying storage implementation may be shared
    59  	// with other actors, it must be sure not to delete their
    60  	// file as well.
    61  	// Nevertheless, use with care!  This method is only mean
    62  	// for cleaning up an environment that's being destroyed.
    63  	RemoveAll() error
    64  }
    65  
    66  // Storage represents storage that can be both
    67  // read and written.
    68  type Storage interface {
    69  	StorageReader
    70  	StorageWriter
    71  }