environs: turn environment configuration into a concrete type

environs/interface.go

 package environs
 
 import (
         "errors"
         "io"
         "launchpad.net/juju-core/state"
         "launchpad.net/juju-core/environs/config"
 )
 
 // A EnvironProvider represents a computing and storage provider.
 type EnvironProvider interface {
         // Open opens the environment and returns it.
         Open(config *config.Config) (Environ, error)
 
-        // TODO: add Validate
+        // Validate ensures that config is a valid configuration for this
+        // provider, applying changes to it if necessary, and returns the
+        // validated configuration.
+        // If old is not nil, it holds the previous environment configuration
+        // for consideration when validating changes.
+        // TODO: Validate(config, old *config.Config) (valid *config.Config, err error)
 }
 
 var ErrNoDNSName = errors.New("DNS name not allocated")
 
 // Instance represents the provider-specific notion of a machine.
 type Instance interface {
         // Id returns a provider-generated identifier for the Instance.
         Id() string
 
         // DNSName returns the DNS name for the instance.
         // If the name is not yet allocated, it will return
         // an ErrNoDNSName error.
         DNSName() (string, error)
 
         // WaitDNSName returns the DNS name for the instance,
         // waiting until it is allocated if necessary.
         WaitDNSName() (string, error)
 
         // OpenPorts opens the given ports on the instance, which
         // should have been started with the given machine id.
         OpenPorts(machineId int, ports []state.Port) error
 
         // ClosePorts closes the given ports on the instance, which
         // should have been started with the given machine id.
         ClosePorts(machineId int, ports []state.Port) error
 
         // Ports returns the set of ports open on the instance, which
         // should have been started with the given machine id.
+        // The ports are returned as sorted by state.SortPorts.
         Ports(machineId int) ([]state.Port, error)
 }
 
 var ErrNoInstances = errors.New("no instances found")
 var ErrPartialInstances = errors.New("only some instances were found")
 
 // NotFoundError records an error when something has not been found.
 type NotFoundError struct {
         // error is the underlying error.
         error
@@ skipping 103 matching lines @@
         // yet be visible in the environment, so this method
         // can wait until they are.
         //
         // When Destroy has been called, any Environ referring to the
         // same remote environment may become invalid
         Destroy(insts []Instance) error
 
         // AssignmentPolicy returns the environment's unit assignment policy.
         AssignmentPolicy() state.AssignmentPolicy
 }