entitycache

Documentation

Overview

Package entitycache provides a cache of charmstore entities and base-entities, designed to be used for individual charmstore API requests.

Index

• type Cache
  • func New(store Store) *Cache
  • func (c *Cache) AddBaseEntityFields(fields map[string]int)
  • func (c *Cache) AddEntityFields(fields map[string]int)
  • func (c *Cache) BaseEntity(id *charm.URL, fields map[string]int) (*mongodoc.BaseEntity, error)
  • func (c *Cache) Close()
  • func (c *Cache) CustomIter(q StoreQuery, fields map[string]int) *Iter
  • func (c *Cache) Entity(id *charm.URL, fields map[string]int) (*mongodoc.Entity, error)
  • func (c *Cache) Iter(q *mgo.Query, fields map[string]int) *Iter
  • func (c *Cache) StartFetch(ids []*charm.URL)
• type Iter
  • func (i *Iter) Close()
  • func (i *Iter) Entity() *mongodoc.Entity
  • func (iter *Iter) Err() error
  • func (i *Iter) Next() bool
• type Store
• type StoreIter
• type StoreQuery

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache holds a cache of entities and base entities. Whenever an entity is fetched, its base entity is fetched too. It is OK to call methods on Cache concurrently.

func New

func New(store Store) *Cache

New returns a new cache that uses the given store for fetching entities.

func (*Cache) AddBaseEntityFields

func (c *Cache) AddBaseEntityFields(fields map[string]int)

AddBaseEntityFields arranges that any value subsequently returned from BaseEntity will have the given fields populated.

If all the required fields are added before retrieving any base entities, less database round trips will be required.

func (*Cache) AddEntityFields

func (c *Cache) AddEntityFields(fields map[string]int)

AddEntityFields arranges that any entity subsequently returned from Entity will have the given fields populated.

If all the required fields are added before retrieving any entities, fewer database round trips will be required.

func (*Cache) BaseEntity

func (c *Cache) BaseEntity(id *charm.URL, fields map[string]int) (*mongodoc.BaseEntity, error)

BaseEntity returns the base entity with the given id. If the entity is not found, it returns an error with a params.ErrNotFound cause. The returned entity will have at least the given fields filled out.

func (*Cache) Close

func (c *Cache) Close()

Close closes the cache, ensuring that there are no currently outstanding goroutines in progress.

func (*Cache) CustomIter

func (c *Cache) CustomIter(q StoreQuery, fields map[string]int) *Iter

CustomIter is the same as Iter except that it allows iteration through entities that aren't necessarily the direct result of a MongoDB query. Care must be taken to ensure that the fields returned are valid for the entities they purport to represent.

func (*Cache) Entity

func (c *Cache) Entity(id *charm.URL, fields map[string]int) (*mongodoc.Entity, error)

Entity returns the entity with the given id. If the entity is not found, it returns an error with a params.ErrNotFound cause. The returned entity will have at least the given fields filled out.

func (*Cache) Iter

func (c *Cache) Iter(q *mgo.Query, fields map[string]int) *Iter

Iter returns an iterator that iterates through all the entities found by the given query, which must be a query on the entities collection. The entities produced by the returned iterator will have at least the given fields populated.

func (*Cache) StartFetch

func (c *Cache) StartFetch(ids []*charm.URL)

StartFetch starts to fetch entities for all the given ids. The entities can be accessed by calling Entity and their associated base entities found by calling BaseEntity. This method does not wait for the entities to actually be fetched.

type Iter

type Iter struct {
	// contains filtered or unexported fields
}

Iter holds an iterator over a set of entities.

func (*Iter) Close

func (i *Iter) Close()

Close closes the iterator. This must be called if the iterator is abandoned without reaching its end.

func (*Iter) Entity

func (i *Iter) Entity() *mongodoc.Entity

Entity returns the current entity, or nil if the iterator has reached the end of its iteration. The base entity associated with the entity will be available via the EntityFetcher.BaseEntity method. The caller should treat the returned entity as read-only.

func (*Iter) Err

func (iter *Iter) Err() error

Err returns any error encountered by the the iterator. If the iterator has not terminated or been closed, it will always return nil.

func (*Iter) Next

func (i *Iter) Next() bool

Next reports whether there are any more entities available from the iterator. The iterator is automatically closed when Next returns false.

type Store

type Store interface {
	FindBestEntity(url *charm.URL, fields map[string]int) (*mongodoc.Entity, error)
	FindBaseEntity(url *charm.URL, fields map[string]int) (*mongodoc.BaseEntity, error)
}

Store holds the underlying storage used by the entity cache. It is implemented by *charmstore.Store.

type StoreIter

type StoreIter interface {
	Next(interface{}) bool
	Err() error
	Close() error
}

StoreIter represents an iterator over entities in the charm store.

type StoreQuery

type StoreQuery interface {
	// Iter returns an iterator over the query, selecting
	// at least the fields mentioned in the given map.
	Iter(fields map[string]int) StoreIter
}

StoreQuery represents a query on entities in the charm store It is represented as an interface rather than using *mgo.Query directly so that we can easily fake it in tests, and so that it's possible to use other different underlying representations.