One of the most useful services Mortar can provide is its BundleService,
which gives any View (or any object with access to the Activity context) safe access to
the Activity lifecycle's persistence bundle. For fans of the Model View Presenter
pattern, we provide a persisted Presenter class that builds on BundleService.
Presenters are completely isolated from View concerns. They're particularly good at
surviving configuration changes, weathering the storm as Android destroys your portrait
Activity and Views and replaces them with landscape doppelgangers.

Mortar can similarly make Dagger ObjectGraphs (or Dagger2
Components) visible as system services. Or not — these services are
completely decoupled.

Everything is managed by MortarScope singletons, typically
backing the top level Application and Activity contexts. You can also spawn
your own shorter lived scopes to manage transient sessions, like the state of
an object being built by a set of wizard screens.

These nested scopes can shadow the services provided by higher level scopes.
For example, a Dagger extension graph specific to your wizard session
can cover the one normally available, transparently to the wizard Views.
Calls like ObjectGraphService.inject(getContext(), this) are now possible
without considering which graph will do the injection.

The Big Picture

An application will typically have a singleton MortarScope instance.
Its job is to serve as a delegate to the app's getSystemService method, something like:

This exposes a single, core service, the scope itself. From the scope you can
spawn child scopes, and you can register objects that implement the
Scoped
interface with it for setup and tear-down calls.

Scoped#onEnterScope(MortarScope)

Scoped#onExitScope(MortarScope)

To make a scope provide other services, like a Dagger ObjectGraph,
you register them while building the scope. That would make our Application's
getSystemService method look like this:

To take advantage of the BundleService describe above, you'll put similar code
into your Activity. If it doesn't exist already, you'll
build a sub-scope to back the Activity's getSystemService method, and
while building it set up the BundleServiceRunner. You'll also notify
the BundleServiceRunner each time onCreate and onSaveInstanceState are
called, to make the persistence bundle available to the rest of the app.

With that in place, any object in your app can sign up with the BundleService
to save and restore its state. This is nice for views, since Bundles are less
of a hassle than the Parcelable objects required by View#onSaveInstanceState,
and a boon to any business objects in the rest of your app.

Full Disclosure

This stuff has been in "rapid" development over a pretty long gestation period,
but is finally stabilizing. We don't expect drastic changes before cutting a
1.0 release, but we still cannot promise a stable API from release to release.

License

Copyright 2013 Square, Inc.
Licensed 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.