def fetch(self, name, many_handler=None):
     """Fetch a named result."""
     def _many_handler(values):
         # By default we just return the first of many (unless provided
         # a different callback that can translate many results into
         # something more meaningful).
         return values[0]
     if many_handler is None:
         many_handler = _many_handler
     try:
         providers = self._reverse_mapping[name]
     except KeyError:
         exceptions.raise_with_cause(exceptions.NotFound,
                                     "Name %r is not mapped as a produced"
                                     " output by any providers" % name)
     values = []
     for provider in providers:
         if provider.name is _TRANSIENT_PROVIDER:
             values.append(_item_from_single(provider,
                                             self._transients, name))
         else:
             try:
                 container = self._get(provider.name, only_last=True)
             except exceptions.NotFound:
                 pass
             else:
                 values.append(_item_from_single(provider,
                                                 container, name))
     if not values:
         raise exceptions.NotFound("Unable to find result %r,"
                                   " searched %s" % (name, providers))
     else:
         return many_handler(values)

 def save_logbook(self, book):
     try:
         logbooks = self._tables.logbooks
         with self._engine.begin() as conn:
             q = (sql.select([logbooks]).
                  where(logbooks.c.uuid == book.uuid))
             row = conn.execute(q).first()
             if row:
                 e_lb = self._converter.convert_book(row)
                 self._converter.populate_book(conn, e_lb)
                 e_lb.merge(book)
                 conn.execute(sql.update(logbooks)
                              .where(logbooks.c.uuid == e_lb.uuid)
                              .values(e_lb.to_dict()))
                 for fd in book:
                     e_fd = e_lb.find(fd.uuid)
                     if e_fd is None:
                         e_lb.add(fd)
                         self._insert_flow_details(conn, fd, e_lb.uuid)
                     else:
                         self._update_flow_details(conn, fd, e_fd)
                 return e_lb
             else:
                 conn.execute(sql.insert(logbooks, book.to_dict()))
                 for fd in book:
                     self._insert_flow_details(conn, fd, book.uuid)
                 return book
     except sa_exc.DBAPIError:
         exc.raise_with_cause(
             exc.StorageFailure,
             "Failed saving logbook '%s'" % book.uuid)

 def clear_all(self):
     try:
         logbooks = self._tables.logbooks
         with self._engine.begin() as conn:
             conn.execute(logbooks.delete())
     except sa_exc.DBAPIError:
         exc.raise_with_cause(exc.StorageFailure, "Failed clearing all entries")

 def _get_script(self, name):
     try:
         return self._scripts[name]
     except KeyError:
         exc.raise_with_cause(exc.NotFound,
                              "Can not access %s script (has this"
                              " board been connected?)" % name)

 def validate(self):
     with self._exc_wrapper():
         try:
             if self._conf.get('check_compatible', True):
                 k_utils.check_compatible(self._client, MIN_ZK_VERSION)
         except exc.IncompatibleVersion:
             exc.raise_with_cause(exc.StorageFailure, "Backend storage is"
                                  " not a compatible version")

 def close(self):
     self._validated = False
     if not self._owned:
         return
     try:
         k_utils.finalize_client(self._client)
     except (k_exc.KazooException, k_exc.ZookeeperError):
         exc.raise_with_cause(exc.StorageFailure,
                              "Unable to finalize client")

 def destroy_logbook(self, book_uuid):
     try:
         logbooks = self._tables.logbooks
         with self._engine.begin() as conn:
             q = logbooks.delete().where(logbooks.c.uuid == book_uuid)
             r = conn.execute(q)
             if r.rowcount == 0:
                 raise exc.NotFound("No logbook found with" " uuid '%s'" % book_uuid)
     except sa_exc.DBAPIError:
         exc.raise_with_cause(exc.StorageFailure, "Failed destroying logbook '%s'" % book_uuid)

def _item_from_single(provider, container, looking_for):
    """Returns item from a *single* provider."""
    try:
        return _item_from(container, provider.index)
    except _EXTRACTION_EXCEPTIONS:
        exceptions.raise_with_cause(
            exceptions.NotFound,
            "Unable to find result %r, expected to be able to find it"
            " created by %s but was unable to perform successful"
            " extraction" % (looking_for, provider))

 def get_atoms_for_flow(self, fd_uuid):
     gathered = []
     try:
         with contextlib.closing(self._engine.connect()) as conn:
             for ad in self._converter.atom_query_iter(conn, fd_uuid):
                 gathered.append(ad)
     except sa_exc.DBAPIError:
         exc.raise_with_cause(exc.StorageFailure, "Failed getting atom details in flow" " detail '%s'" % fd_uuid)
     for atom_details in gathered:
         yield atom_details

def _storagefailure_wrapper():
    try:
        yield
    except exc.TaskFlowException:
        raise
    except Exception as e:
        if isinstance(e, (IOError, OSError)) and e.errno == errno.ENOENT:
            exc.raise_with_cause(exc.NotFound, "Item not found: %s" % e.filename, cause=e)
        else:
            exc.raise_with_cause(exc.StorageFailure, "Storage backend internal error", cause=e)

 def _loads(blob, root_types=(dict,)):
     try:
         return misc.decode_msgpack(blob, root_types=root_types)
     except (msgpack.UnpackException, ValueError):
         # TODO(harlowja): remove direct msgpack exception access when
         # oslo.utils provides easy access to the underlying msgpack
         # pack/unpack exceptions..
         exc.raise_with_cause(exc.JobFailure,
                              "Failed to deserialize object from"
                              " msgpack blob (of length %s)" % len(blob))

 def _dumps(obj):
     try:
         return msgpackutils.dumps(obj)
     except (msgpack.PackException, ValueError):
         # TODO(harlowja): remove direct msgpack exception access when
         # oslo.utils provides easy access to the underlying msgpack
         # pack/unpack exceptions..
         exc.raise_with_cause(exc.JobFailure,
                              "Failed to serialize object to"
                              " msgpack blob")

 def get_atom_details(self, ad_uuid):
     try:
         atomdetails = self._tables.atomdetails
         with self._engine.begin() as conn:
             q = sql.select([atomdetails]).where(atomdetails.c.uuid == ad_uuid)
             row = conn.execute(q).first()
             if not row:
                 raise exc.NotFound("No atom details found with uuid" " '%s'" % ad_uuid)
             return self._converter.convert_atom_detail(row)
     except sa_exc.SQLAlchemyError:
         exc.raise_with_cause(exc.StorageFailure, "Failed getting atom details with" " uuid '%s'" % ad_uuid)

 def _get_results(looking_for, provider):
     """Gets the results saved for a given provider."""
     try:
         return self._get(provider.name, only_last=True)
     except exceptions.NotFound:
         exceptions.raise_with_cause(exceptions.NotFound,
                                     "Expected to be able to find"
                                     " output %r produced by %s but was"
                                     " unable to get at that providers"
                                     " results" % (looking_for,
                                                   provider))

 def _unclaimable_try_find_owner(cause):
     try:
         owner = self.find_owner(job)
     except Exception:
         owner = None
     if owner:
         message = "Job %s already claimed by '%s'" % (job.uuid, owner)
     else:
         message = "Job %s already claimed" % (job.uuid)
     excp.raise_with_cause(excp.UnclaimableJob,
                           message, cause=cause)

 def get_flows_for_book(self, book_uuid, lazy=False):
     gathered = []
     try:
         with contextlib.closing(self._engine.connect()) as conn:
             for fd in self._converter.flow_query_iter(conn, book_uuid):
                 if not lazy:
                     self._converter.populate_flow_detail(conn, fd)
                 gathered.append(fd)
     except sa_exc.DBAPIError:
         exc.raise_with_cause(exc.StorageFailure, "Failed getting flow details in" " logbook '%s'" % book_uuid)
     for flow_details in gathered:
         yield flow_details

 def test_raise_with(self):
     capture = None
     try:
         raise IOError('broken')
     except Exception:
         try:
             exc.raise_with_cause(exc.TaskFlowException, 'broken')
         except Exception as e:
             capture = e
     self.assertIsNotNone(capture)
     self.assertIsInstance(capture, exc.TaskFlowException)
     self.assertIsNotNone(capture.cause)
     self.assertIsInstance(capture.cause, IOError)

 def _get_results(looking_for, provider):
     """Gets the results saved for a given provider."""
     try:
         return self._get(provider.name, 'last_results', 'failure',
                          _EXECUTE_STATES_WITH_RESULTS,
                          states.EXECUTE)
     except exceptions.NotFound:
         exceptions.raise_with_cause(exceptions.NotFound,
                                     "Expected to be able to find"
                                     " output %r produced by %s but was"
                                     " unable to get at that providers"
                                     " results" % (looking_for,
                                                   provider))

 def _memory_lock(self, write=False):
     if write:
         lock = self.backend.lock.write_lock
     else:
         lock = self.backend.lock.read_lock
     with lock():
         try:
             yield
         except exc.TaskFlowException:
             raise
         except Exception:
             exc.raise_with_cause(exc.StorageFailure,
                                  "Storage backend internal error")

 def get_logbook(self, book_uuid, lazy=False):
     try:
         logbooks = self._tables.logbooks
         with contextlib.closing(self._engine.connect()) as conn:
             q = sql.select([logbooks]).where(logbooks.c.uuid == book_uuid)
             row = conn.execute(q).first()
             if not row:
                 raise exc.NotFound("No logbook found with" " uuid '%s'" % book_uuid)
             book = self._converter.convert_book(row)
             if not lazy:
                 self._converter.populate_book(conn, book)
             return book
     except sa_exc.DBAPIError:
         exc.raise_with_cause(exc.StorageFailure, "Failed getting logbook '%s'" % book_uuid)