Smee.Entity (Smee v0.2.0) View Source

Smee wraps up metadata for individual entities in %Entity{} structs, and the Smee.Entity module contains functions that may be useful when working with them.

Many of the functions mirror those in the Smee.Metadata module - the same actions but on a smaller unit of XML.

Like %Metadata{} structs the XML in entities can be compressed and decompressed, but unlike Metadata structs they have parsed xmerl data in them by default too.

Wherever possible use Entity.update/2 to make changes, do not write to the Entity struct directly. If you must write directly you can use Entity.update/1 to resync the state of the record.

Link to this section Summary

Functions

Returns an entity that contains parsed XML data, greatly increasing its size but possibly making future processing faster.

Raises an exception if the entity has expired (based on valid_until datetime), otherwise returns the entity.

Returns a compressed entity, containing gzipped XML. This greatly reduces the size of the entity record.

Returns true if the XML data in an entity has been compressed

Returns a decompressed entity, with plain-text XML data. This makes the struct much larger.

Returns a new %Entity{} struct if passed XML data for an entity and parent %Metadata{}.

Returns true if the entity has expired (based on valid_until datetime)

Returns a suggested filename for the entity.

Returns a suggested filename for the entity in the specified format.

Returns true if the entity has an IdP role.

Returns a new %Entity{} struct if passed XML data.

Returns the priority of the entity as a value between 0 and 9

Returns an entity with parsed XML data removed, greatly reducing its size but possibly making future processing slower.

Returns true if the entity has an SP role.

Returns the trustiness level of the entity as a float between 0.0 and 0.9.

Resyncs the internal state of an %Entity{} struct

Returns an updates %Entity{} struct with new XML, refreshing various parts of the struct correctly.

Raises an exception if the entity has invalid XML, otherwise returns the entity.

Returns a parsed Erlang xmerl structure representing the entities XML, for use with xmerl, SweetXML and other tools.

Returns the plain-text XML of the entity, whether or not it has been compressed.

Link to this section Types

Specs

t() :: %Smee.Entity{
  changes: integer(),
  compressed: boolean(),
  data: nil | binary(),
  data_hash: nil | binary(),
  downloaded_at: nil | DateTime.t(),
  label: nil | binary(),
  metadata_uri: nil | binary(),
  metadata_uri_hash: nil | binary(),
  modified_at: nil | DateTime.t(),
  priority: integer(),
  size: integer(),
  trustiness: float(),
  uri: nil | binary(),
  uri_hash: nil | binary(),
  valid_until: nil | DateTime.t(),
  xdoc: nil | binary()
}

Link to this section Functions

Specs

bulkup(entity :: t()) :: t()

Returns an entity that contains parsed XML data, greatly increasing its size but possibly making future processing faster.

Specs

check_date!(entity :: t()) :: t()

Raises an exception if the entity has expired (based on valid_until datetime), otherwise returns the entity.

If no valid_until has been set (if it's nil) then the entity will always be returned.

Specs

compress(entity :: t()) :: t()

Returns a compressed entity, containing gzipped XML. This greatly reduces the size of the entity record.

Specs

compressed?(entity :: t()) :: boolean()

Returns true if the XML data in an entity has been compressed

Specs

decompress(entity :: t()) :: t()

Returns a decompressed entity, with plain-text XML data. This makes the struct much larger.

Link to this function

derive(data, metadata, options \\ [])

View Source

Specs

derive(data :: binary(), metadata :: Smee.Metadata.t(), options :: keyword()) ::
  t()

Returns a new %Entity{} struct if passed XML data for an entity and parent %Metadata{}.

Defaults values are set using the parent metadata where possible.

You can set or override various parts of the struct by passing options:

  • md_uri - a URI that identifies a parent
  • downloaded_at - A DateTime to record when the record was downloaded
  • modified_at - A DateTime to record when the record was updated upstream
  • valid_until - A DateTime to indicate when an entity expires
  • priority - An integer between 0 and 9 to show priority
  • trustiness - a Float between 0.0 and 0.9 to indicate, well, trustiness.

You won't normally need to do this yourself as entities can be extracted from Smee.Metadata.

Specs

expired?(entity :: t()) :: boolean()

Returns true if the entity has expired (based on valid_until datetime)

If no valid_until has been set (if it's nil) then false will be returned

Specs

filename(entity :: t()) :: binary()

Returns a suggested filename for the entity.

Specs

filename(entity :: t(), format :: atom()) :: binary()

Returns a suggested filename for the entity in the specified format.

Two formats can be specified: :sha1 and :uri

Specs

idp?(entity :: t()) :: boolean()

Returns true if the entity has an IdP role.

An entity may have more than one role.

Link to this function

new(data, options \\ [])

View Source

Specs

new(data :: binary(), options :: keyword()) :: t()

Returns a new %Entity{} struct if passed XML data.

You can set or override various parts of the struct by passing options:

  • md_uri - a URI that identifies a parent
  • downloaded_at - A DateTime to record when the record was downloaded
  • modified_at - A DateTime to record when the record was updated upstream
  • valid_until - A DateTime to indicate when an entity expires
  • priority - An integer between 0 and 9 to show priority
  • trustiness - a Float between 0.0 and 0.9 to indicate, well, trustiness.

You won't normally need to do this yourself as entities can be extracted from Smee.Metadata.

Specs

priority(entity :: t()) :: integer()

Returns the priority of the entity as a value between 0 and 9

Specs

slim(entity :: t()) :: t()

Returns an entity with parsed XML data removed, greatly reducing its size but possibly making future processing slower.

Specs

sp?(entity :: t()) :: boolean()

Returns true if the entity has an SP role.

An entity may have more than one role.

Specs

trustiness(entity :: t()) :: float()

Returns the trustiness level of the entity as a float between 0.0 and 0.9.

Specs

update(entity :: t()) :: t()

Resyncs the internal state of an %Entity{} struct

If changes have been made using Entity.update/2 then this will not be needed - it's there for when the struct has been changed directly

Specs

update(entity :: t(), xml :: binary()) :: t()

Returns an updates %Entity{} struct with new XML, refreshing various parts of the struct correctly.

This should be the only way updated Entities are produced - the raw struct should not be changed directly.

Specs

validate!(entity :: t()) :: t()

Raises an exception if the entity has invalid XML, otherwise returns the entity.

Specs

xdoc(entity :: t()) :: tuple()

Returns a parsed Erlang xmerl structure representing the entities XML, for use with xmerl, SweetXML and other tools.

Specs

xml(entity :: t()) :: binary()

Returns the plain-text XML of the entity, whether or not it has been compressed.