github.com/mhilton/juju-juju@v0.0.0-20150901100907-a94dd2c73455/api/base/caller.go (about)

     1  // Copyright 2012, 2013 Canonical Ltd.
     2  // Licensed under the AGPLv3, see LICENCE file for details.
     3  
     4  package base
     5  
     6  import (
     7  	"github.com/juju/names"
     8  )
     9  
    10  // APICaller is implemented by the client-facing State object.
    11  type APICaller interface {
    12  	// APICall makes a call to the API server with the given object type,
    13  	// id, request and parameters. The response is filled in with the
    14  	// call's result if the call is successful.
    15  	APICall(objType string, version int, id, request string, params, response interface{}) error
    16  
    17  	// BestFacadeVersion returns the newest version of 'objType' that this
    18  	// client can use with the current API server.
    19  	BestFacadeVersion(facade string) int
    20  
    21  	// EnvironTag returns the tag of the environment the client is
    22  	// connected to.
    23  	EnvironTag() (names.EnvironTag, error)
    24  }
    25  
    26  // FacadeCaller is a wrapper for the common paradigm that a given client just
    27  // wants to make calls on a facade using the best known version of the API. And
    28  // without dealing with an id parameter.
    29  type FacadeCaller interface {
    30  	// FacadeCall will place a request against the API using the requested
    31  	// Facade and the best version that the API server supports that is
    32  	// also known to the client.
    33  	FacadeCall(request string, params, response interface{}) error
    34  
    35  	// Name returns the facade name.
    36  	Name() string
    37  
    38  	// BestAPIVersion returns the API version that we were able to
    39  	// determine is supported by both the client and the API Server
    40  	BestAPIVersion() int
    41  
    42  	// RawAPICaller returns the wrapped APICaller. This can be used if you need
    43  	// to switch what Facade you are calling (such as Facades that return
    44  	// Watchers and then need to use the Watcher facade)
    45  	RawAPICaller() APICaller
    46  }
    47  
    48  type facadeCaller struct {
    49  	facadeName  string
    50  	bestVersion int
    51  	caller      APICaller
    52  }
    53  
    54  var _ FacadeCaller = facadeCaller{}
    55  
    56  // FacadeCall will place a request against the API using the requested
    57  // Facade and the best version that the API server supports that is
    58  // also known to the client. (id is always passed as the empty string.)
    59  func (fc facadeCaller) FacadeCall(request string, params, response interface{}) error {
    60  	return fc.caller.APICall(
    61  		fc.facadeName, fc.bestVersion, "",
    62  		request, params, response)
    63  }
    64  
    65  // Name returns the facade name.
    66  func (fc facadeCaller) Name() string {
    67  	return fc.facadeName
    68  }
    69  
    70  // BestAPIVersion returns the version of the Facade that is going to be used
    71  // for calls. It is determined using the algorithm defined in api
    72  // BestFacadeVersion. Callers can use this to determine what methods must be
    73  // used for compatibility.
    74  func (fc facadeCaller) BestAPIVersion() int {
    75  	return fc.bestVersion
    76  }
    77  
    78  // RawAPICaller returns the wrapped APICaller. This can be used if you need to
    79  // switch what Facade you are calling (such as Facades that return Watchers and
    80  // then need to use the Watcher facade)
    81  func (fc facadeCaller) RawAPICaller() APICaller {
    82  	return fc.caller
    83  }
    84  
    85  // NewFacadeCaller wraps an APICaller for a given facade name and the
    86  // best available version.
    87  func NewFacadeCaller(caller APICaller, facadeName string) FacadeCaller {
    88  	return NewFacadeCallerForVersion(caller, facadeName, caller.BestFacadeVersion(facadeName))
    89  }
    90  
    91  // NewFacadeCallerForVersion wraps an APICaller for a given facade
    92  // name and version.
    93  func NewFacadeCallerForVersion(caller APICaller, facadeName string, version int) FacadeCaller {
    94  	return facadeCaller{
    95  		facadeName:  facadeName,
    96  		bestVersion: version,
    97  		caller:      caller,
    98  	}
    99  }