resx v0.0.4 Resx.Producer behaviour

A producer is an interface for working with a referenceable resource.

This could be anything from a type of storage or networking protocol, to generation of content (e.g. you might expose some procedural generation algorithm as a producer), to manipulations on other resources (there is already a common way to handle this through Resx.Transformer).

Link to this section Summary

Callbacks

Implement the behaviour for checking if two references point to the same resource

Implement the behaviour for checking whether a resource exists for the given reference

Implement the behaviour for retrieving a resource

Optionally implement the behaviour to retrieve the attribute for a resource

Optionally implement the behaviour to retrieve the attribute keys for a resource

Implement the behaviour to retrieve the attributes for a resource

Implement the behaviour to retrieve the URI for a resource reference

Implement the behaviour for retrieving the URI schemes this producer can handle

Implement the behaviour to retrieve source (if any)

Optionally implement the behaviour for retrieving a resource stream

Link to this section Callbacks

Link to this callback alike?(reference_a, reference_b)
alike?(reference_a :: Resx.ref(), reference_b :: Resx.ref()) :: boolean()

Implement the behaviour for checking if two references point to the same resource.

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

If the references are alike return true, otherwise return false.

Link to this callback exists?(reference)
exists?(reference :: Resx.ref()) ::
  {:ok, exists :: boolean()} | Resx.error(Resx.reference_error())

Implement the behaviour for checking whether a resource exists for the given reference.

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

If the resource exists return { :ok, true }, if it does not exist return { :ok, false }. Otherwise return an appropriate error.

Link to this callback open(reference, options)
open(reference :: Resx.ref(), options :: keyword()) ::
  {:ok, resource :: Resx.Resource.t(Resx.Resource.Content.t())}
  | Resx.error(Resx.resource_error() | Resx.reference_error())

Implement the behaviour for retrieving a resource.

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

The options keyword allows for your implementation to expose some configurable settings.

If the resource was successfully retrieved return { :ok, resource }. Where resource is the Resx.Resource struct. Otherwise return an appropriate error.

Link to this callback resource_attribute(reference, field)
resource_attribute(
  reference :: Resx.ref(),
  field :: Resx.Resource.attribute_key()
) ::
  {:ok, attribute_value :: any()}
  | Resx.error(Resx.resource_error() | Resx.reference_error() | :unknown_key)

Optionally implement the behaviour to retrieve the attribute for a resource.

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

If the attribute was successfully retrieved for the resource return { :ok, value }, where value is the value of the attribute. Otherwise return an appropriate error.

Link to this callback resource_attribute_keys(reference)
resource_attribute_keys(reference :: Resx.ref()) ::
  {:ok, [field :: Resx.Resource.attribute_key()]}
  | Resx.error(Resx.resource_error() | Resx.reference_error())

Optionally implement the behaviour to retrieve the attribute keys for a resource.

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

If the attribute was successfully retrieved for the resource return { :ok, keys }, where keys are the field names of the different attributes. Otherwise return an appropriate error.

Link to this callback resource_attributes(reference)
resource_attributes(reference :: Resx.ref()) ::
  {:ok,
   attribute_values :: %{optional(Resx.Resource.attribute_key()) => any()}}
  | Resx.error(Resx.resource_error() | Resx.reference_error())

Implement the behaviour to retrieve the attributes for a resource.

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

If the attributes were successfully retrieved for the resource return { :ok, %{ key => value } }, where key is the field names of the attribute, and value is the value of the attribute. Otherwise return an appropriate error.

Link to this callback resource_uri(reference)
resource_uri(reference :: Resx.Resource.Reference.t()) ::
  {:ok, Resx.uri()} | Resx.error(Resx.resource_error() | Resx.reference_error())

Implement the behaviour to retrieve the URI for a resource reference.

The reference to the resource is an existing Resx.Resource.Reference struct.

If the URI can be created return { :ok, uri }. Otherwise return an appropriate error.

Link to this callback schemes()
schemes() :: [String.t(), ...]

Implement the behaviour for retrieving the URI schemes this producer can handle.

Return a list of the scheme names.

Link to this callback source(reference)
source(reference :: Resx.ref()) ::
  {:ok, source :: Resx.ref() | nil} | Resx.error(Resx.reference_error())

Implement the behaviour to retrieve source (if any).

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

If the source can be retrieved return { :ok, source }, where source is either the reference chain for the source or nil if there is none. Otherwise return an appropriate error.

Link to this callback stream(reference, options)
stream(reference :: Resx.ref(), options :: keyword()) ::
  {:ok, resource :: Resx.Resource.t(Resx.Resource.Content.Stream.t())}
  | Resx.error(Resx.resource_error() | Resx.reference_error())

Optionally implement the behaviour for retrieving a resource stream.

The reference to the resource can either be an existing Resx.Resource.Reference struct, or a URI.

The options keyword allows for your implementation to expose some configurable settings.

If the resource was successfully retrieved return { :ok, resource }. Where resource is the Resx.Resource struct. Otherwise return an appropriate error.