(PUP-1699) Add caching for directory based environments

This also corrects a problem in the benchmark "many modules" - the
intention
was to measure directory based environments but it ended up measuring
legacy based.
(PUP-1699) Change default time to live for directory env to 5s
(maint) Remove TODO comment
(PUP-1699) Use Puppet.override to provide some spec envs

A few specs relying on mocking Puppet::Node::Environment.new to return
a specific test environment were colliding with the new environments
cacheing layer.  Switched to using puppet override to supply a static
environment.
(maint) Update defined_types benchmark to ensure correct environment
(PUP-1699) Remove dead code, fix documentation.

This fixes a number of comments from review.
(maint) Remove explicit setting of configured environment in benchmarks

The earlier slowdown is now not observable and the benchmarks have
been switched back to not explicitly set the configured environment.
(PUP-1699) Retain an instance of a Catalog's environment

A catalog used to have the symbolic name if it's environment set, but
did not retain a reference to the actual environment instance.  This
could would likely allow the catalog to reference it's original
environment for a legacy, memoized environment, but does not work with
newer cacheing models for directory environments.  The problem was
showing up specifically in the
spec/integration/parser/ruby_manifest_spec which would compile a catalog
and then interrogate the catalog to see if it contained the expected
resources.  Resources have unfortunate behavior causing them to lookup
environment in order to load types in support of the
Resource#parse_title.  But the current_environment retrieved by the
resource in the spec was likely different than the one overridden during
compilation, and if it had never performed an initial import, might fail
attempting to lookup classes which were not on its path.

To short circuit some of this madness, the compiler is explicitly
setting a new Catalog#environment_instance, and Catalog#to_catalog is
ensuring that it copies when duplicating.  Catalog#resource then
overrides current_environment to this instance.
(PUP-1699) Create a real env in doc_spec tests
(PUP-1699) Set a stub environment_instance when deserializing catalog

The environment is not transferred over the wire, and the agent should
not care about an environment.  But because master and agent share the
same code, when the agent deserializes a Catalog, it now needs an
environment_instance to reference.  We are supplying a stub environment.
(PUP-1699) Tie resource environment to catalog

Previously resources would end up "floating away" from the catalog that
contained them because they wouldn't use the catalog as their
source for an environment. This also extended to catalogs, which lost
track of their environment at times. So in order to have resources use
the environment of their catalog, the catalog needed to have a
guaranteed environment.

This adds an environment parameter to the catalog constructor and uses
it to drive the environment to use for everything in that catalog. The
resource now uses its catalog's environment, if it has a catalog, or it
uses the new NONE environment, if it does not have a catalog.

When catalogs are deserialized, they also need to have a reference to
*some* environment. However, since they only have a name of the
environment, there isn't any guarantee that an environment of that name
is available locally. To deal with this there is a new "remote"
environment constructor to be able to create references to the remote
environment of the catalog. This is used as the environment of a
deserialized catalog.

We (Joshua Partlow and Andrew Parker) tried to have the environment a
required parameter of catalog construction, but it appears that creating
catalogs is public API and so cannot be changed (we verified this by
checking stdlib tests).
(PUP-1699) Add remote environment to plugin downloader calls

Puppet::Configurer::Downloader is also called by the plugin face, but we
were not submitting an environment there.  On Ruby 1.9.3 this nil
environment was being interned as :'' and would produce a failure server
side when a request with an empty environment was parsed.  On Ruby
1.8.7, nil raises an error when interned and it was failing much sooner
on the agent side.

To resolve this, we're passing in a reference to the configured
environment. Also added an integration test for the plugin face, because we
weren't seeing any failure in our test suite.
Merge pull request #2580 from jpartlow/feature/master/pup-1699-cache-environments

Feature/master/pup 1699 cache environments
Merge branch 'master' of https://github.com/puppetlabs/puppet