resources

Documentation

Overview

Package resources

Summary

The package meant to provide interfaces that commonly remade when we work with external resources. The package meant to used together with the specs package that holds the interface contract specifications.

Index

• func LookupID(i interface{}) (id interface{}, ok bool)
• func LookupIDStructField(ent interface{}) (reflect.StructField, reflect.Value, bool)
• func SetID(ptr interface{}, id interface{}) error
• type Creator
• type CreatorPublisher
• type Deleter
• type DeleterPublisher
• type Finder
• type OnePhaseCommitProtocol
• type Subscriber
• type Subscription
• type T
• type TestEntity
• type TwoPhaseCommitProtocol
• type Updater
• type UpdaterPublisher

Functions

func LookupID

func LookupID(i interface{}) (id interface{}, ok bool)

func LookupIDStructField

func LookupIDStructField(ent interface{}) (reflect.StructField, reflect.Value, bool)

func SetID

func SetID(ptr interface{}, id interface{}) error

Types

type Creator

type Creator interface {
	// Create takes a ptr to a entity<T> and store it into the resource.
	// It also updates the entity<T> ext:"ID" field with the associated uniq resource id.
	// The reason behind this links the id and not returning the id is that,
	// in most case the Create error value is the only thing that is checked for errors,
	// and introducing an extra value also introduce boiler plates in the handling.
	Create(ctx context.Context, ptr interface{}) error
}

type CreatorPublisher

type CreatorPublisher interface {
	// SubscribeToCreate create a subscription to create event feed.
	// 	eg.: storage.SubscribeToCreate(“, cache.CreateEventHandler())
	//
	// If event stream repeatability from a certain point is a requirement,
	// it needs to be further specified with a resource contract.
	SubscribeToCreate(context.Context, T, Subscriber) (Subscription, error)
}

type Deleter

type Deleter interface {
	// DeleteByID will remove a <T> type entity from the storage by a given ID
	DeleteByID(ctx context.Context, T T, id interface{}) error
	// DeleteAll will erase all entity from the resource that has <T> type
	DeleteAll(context.Context, T) error
}

Deleter request to destroy a business entity in the Resource that implement it's test.

type DeleterPublisher

type DeleterPublisher interface {
	SubscribeToDeleteByID(context.Context, T, Subscriber) (Subscription, error)
	SubscribeToDeleteAll(context.Context, T, Subscriber) (Subscription, error)
}

type Finder

type Finder interface {
	// FindByID will link an entity that is found in the resource to the received ptr,
	// and report back if it succeeded finding the entity in the resource.
	// It also reports if there was an unexpected exception during the execution.
	// It was an intentional decision to not use error to represent "not found" case,
	// but tell explicitly this information in the form of return bool value.
	FindByID(ctx context.Context, ptr, id interface{}) (_found bool, _err error)
	// FindAll will return all entity that has <T> type
	FindAll(context.Context, T) iterators.Interface
}

type OnePhaseCommitProtocol

type OnePhaseCommitProtocol interface {
	// BeginTx creates a context with a transaction.
	// All statements that receive this context should be executed within the given transaction in the context.
	// After a BeginTx command will be executed in a single transaction until an explicit COMMIT or ROLLBACK is given.
	//
	// In case the resource support some form of isolation level,
	// or other ACID related property of the transaction,
	// then it is advised to prepare this information in the context before calling BeginTx.
	// e.g.:
	//   ...
	//   var err error
	//   ctx = r.ContextWithIsolationLevel(ctx, sql.LevelSerializable)
	//   ctx, err = r.BeginTx(ctx)
	//
	BeginTx(context.Context) (context.Context, error)
	// Commit commits the current transaction.
	// All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs.
	CommitTx(context.Context) error
	// Rollback rolls back the current transaction and causes all the updates made by the transaction to be discarded.
	RollbackTx(context.Context) error
}

type Subscriber

type Subscriber interface {
	// Handle handles the the subscribed event.
	// Context may or may not have meta information about the received event.
	// To ensure expectations, define a resource specification <contract> about what must be included in the context.
	Handle(ctx context.Context, ent interface{}) error
	// Error allow the subscription implementation to communicate unexpected situations that needs to be handled by the subscriber.
	// For e.g. the connection is lost and the subscriber might have cached values
	// that must be invalidated on the next successful Handle call
	Error(ctx context.Context, err error) error
}

type Subscription

type Subscription interface {
	io.Closer
}

type T

type T = interface{}

type TestEntity

type TestEntity struct {
	ID string `ext:"ID"`
}

type TwoPhaseCommitProtocol

type TwoPhaseCommitProtocol interface {
	OnePhaseCommitProtocol
	// PrepareTx communicate with the resource that the current transaction is done and should be prepared for commit later.
	//
	// Prepare transaction is not intended for use in applications or interactive sessions.
	// Its purpose is to allow an external transaction manager to perform atomic global transactions across multiple databases or other transactional resources.
	// Unless you're writing a transaction manager, you probably shouldn't be using PrepareTx.
	//
	// This command must be used on a context made with BeginTx.
	// Calling CommitTx or RollbackTx with the received context
	// must be interpreted as Two Phase Commit Protocol's Commit or Rollback action.
	PrepareTx(context.Context) (context.Context, error)
}

type Updater

type Updater interface {
	// Update will takes a ptr that points to an entity
	// and update the corresponding stored entity with the received entity field values
	Update(ctx context.Context, ptr interface{}) error
}

type UpdaterPublisher

type UpdaterPublisher interface {
	// SubscribeToUpdate create a subscription to the update event feed.
	// If event stream repeatability from a certain point is a requirement,
	// it needs to be further specified with a resource contract.
	SubscribeToUpdate(context.Context, T, Subscriber) (Subscription, error)
}