View Source Smee.Entity (Smee v0.4.1)

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.

Summary

Functions

Returns the assurance certification URIs of the entity as a list

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

Returns a list of entity categories for this entity

Returns a list of supported entity categories

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 the entityID of the entity struct.

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 the Date of registration, if present, or nil.

Returns the URI for the entity's registration authority, if available, or nil.

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.

Tags an entity with one or more tags, replacing existing tags.

Returns the tags of the entity struct, a list of binary strings

Returns the MDQ hashed style entityID of the entity struct.

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.

Types

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

Functions

@spec assurance(entity :: t()) :: list()

Returns the assurance certification URIs of the entity as a list

The most common and useful assurance profile is almost certainly SIRTFI, but many others exist.

@spec bulkup(entity :: t()) :: t()

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

@spec categories(entity :: t()) :: list()

Returns a list of entity categories for this entity

Entity categories are official tags indicating that a service fits certain criteria. For instance, Research and Scholarship (indicated with the URI "http://refeds.org/category/research-and-scholarship") shows that a service will behave according to certain rules.

You can see a dump of all entity attributes, including entity categories, using Smee.Extract.list_entity_attrs/1

Link to this function

category_support(entity)

View Source
@spec category_support(entity :: t()) :: list()

Returns a list of supported entity categories

Category support is the counterpart of entity categories, indicating that a service will make use of those categories if an entity possesses them.

@spec 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.

@spec compress(entity :: t()) :: t()

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

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

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

@spec 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
@spec 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.

@spec 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

@spec filename(entity :: t()) :: binary()

Returns a suggested filename for the entity.

@spec 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

@spec id(entity :: t()) :: binary()

Returns the entityID of the entity struct.

(This is the same as the URI)

@spec 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
@spec 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.

@spec priority(entity :: t()) :: integer()

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

@spec registered_at(entity :: t()) :: Date.t() | nil

Returns the Date of registration, if present, or nil.

See registration_authority/1 for more information

Link to this function

registration_authority(entity)

View Source
@spec registration_authority(entity :: t()) :: binary() | nil

Returns the URI for the entity's registration authority, if available, or nil.

Interfederation means that entities may be initially published in a different federation to the one this record is currently published in. The registration authority URI, if present, shows that the entity was officially registered elsewhere.

@spec slim(entity :: t()) :: t()

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

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

Returns true if the entity has an SP role.

An entity may have more than one role.

@spec tag(entity :: t(), tags :: list() | nil | binary()) :: t()

Tags an entity with one or more tags, replacing existing tags.

Tags are arbitrary classifiers, initially inherited from source and metadata

@spec tags(entity :: t()) :: [binary()]

Returns the tags of the entity struct, a list of binary strings

Tags are arbitrary strings, which may be initially inherited from source and metadata

@spec transformed_id(entity :: t()) :: binary()

Returns the MDQ hashed style entityID of the entity struct.

(This is the same as the URI)

@spec trustiness(entity :: t()) :: float()

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

@spec 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

@spec 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.

@spec validate!(entity :: t()) :: t()

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

@spec xdoc(entity :: t()) :: tuple()

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

@spec xml(entity :: t()) :: binary()

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