Smee.Metadata (Smee v0.2.0) View Source

The Metadata module wraps up Metadata XML into a struct and contains functions that may be helpful when working with them. The metadata is either an aggregate (as used by federations to contain many entity records) or a single entity.

Many of the functions mirror those in the Smee.Entity module - the same actions but on larger source XML rather than on fragments.

The XML in metadata structs can be compressed or decompressed, but unlike Entities there is no cached, parsed xmlerl record by default - this is to save time and memory.

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

Methods in Smee.Metadata can be used to extract individual entity records each containing a fragment of XML. It's strongly recommended to stream these using stream_entities2 to save on memory, or select a particular entity using entity2.

Link to this section Summary

Functions

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

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

Returns true if the XML data in an metadata struct has been compressed

Returns the number of entities in the metadata file

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

Returns a new metadata struct based on the streamed entities passed as the first parameter.

Returns all entities in the metadata as a list of entity structs.

Returns the specified entity from the metadata in an :ok/:error struct

Returns the specified entity from the metadata or raises an exception if not found

Returns a list of all entity IDs in the metadata

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

Returns a suggested filename for the metadata.

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

Returns a new metadata struct based on the XML data passed as the first parameter.

Returns one randomly selected entity from the metadata

Returns a stream of all entities in the metadata.

Resyncs the internal state of a %Metadata{} struct

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

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

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

Link to this section Types

Specs

t() :: %Smee.Metadata{
  cache_duration: nil | binary(),
  cert_fingerprint: nil | binary(),
  cert_url: nil | binary(),
  changes: integer(),
  compressed: boolean(),
  data: nil | binary(),
  data_hash: nil | binary(),
  downloaded_at: nil | DateTime.t(),
  entity_count: integer(),
  etag: nil | binary(),
  file_uid: nil | binary(),
  id: nil | binary(),
  label: nil | binary(),
  modified_at: nil | DateTime.t(),
  priority: integer(),
  size: integer(),
  trustiness: float(),
  type: atom(),
  uri: nil | binary(),
  uri_hash: nil | binary(),
  url: nil | binary(),
  url_hash: nil | binary(),
  valid_until: nil | DateTime.t(),
  verified: boolean()
}

Link to this section Functions

Specs

check_date!(metadata :: t()) :: t()

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

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

Specs

compress(metadata :: t()) :: t()

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

Specs

compressed?(metadata :: t()) :: boolean()

Returns true if the XML data in an metadata struct has been compressed

Specs

count(metadata :: t()) :: integer()

Returns the number of entities in the metadata file

Specs

decompress(metadata :: t()) :: t()

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

Link to this function

derive(enum, options \\ [])

View Source

Specs

derive(data :: Enumerable.t() | Smee.Entity.t(), options :: keyword()) :: t()

Returns a new metadata struct based on the streamed entities passed as the first parameter.

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

  • url - the original location of the metadata
  • uri - a URI that identifies the metadata (Name)
  • 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.
  • etag - a string to use as an etag (unique content identifier).
  • cert_url - location of a certificate to use for signature verification
  • cert_fingerprint - fingerprint of the certificate to use for certificate verification
  • label - a description for the metadata

Specs

entities(metadata :: t()) :: [Smee.Entity.t()]

Returns all entities in the metadata as a list of entity structs.

This can produce very large lists very slowly. The stream_entities2 function is much better.

Specs

entity(metadata :: t(), uri :: binary()) :: Smee.Entity.t() | nil

Returns the specified entity from the metadata in an :ok/:error struct

Specs

entity!(metadata :: t(), uri :: binary()) :: Smee.Entity.t()

Returns the specified entity from the metadata or raises an exception if not found

Specs

entity_ids(metadata :: t()) :: [binary()]

Returns a list of all entity IDs in the metadata

Specs

expired?(metadata :: t()) :: boolean()

Returns true if the metadata 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(metadata :: t()) :: binary()

Returns a suggested filename for the metadata.

Link to this function

filename(metadata, atom)

View Source

Specs

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

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

Two formats can be specified: :sha1 and :uri

Link to this function

new(data, options \\ [])

View Source

Specs

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

Returns a new metadata struct based on the XML data passed as the first parameter.

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

  • url - the original location of the metadata
  • uri - a URI that identifies the metadata (Name)
  • 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.
  • etag - a string to use as an etag (unique content identifier).
  • cert_url - location of a certificate to use for signature verification
  • cert_fingerprint - fingerprint of the certificate to use for certificate verification
  • label - a description for the metadata

In most cases it is better to use Smee.Source and then Smee.Fetch to generate a metadata struct.

Specs

random_entity(metadata :: t()) :: Smee.Entity.t()

Returns one randomly selected entity from the metadata

Link to this function

stream_entities(metadata, options \\ [])

View Source

Specs

stream_entities(metadata :: t(), options :: keyword()) :: Enumerable.t()

Returns a stream of all entities in the metadata.

Specs

update(metadata :: t()) :: t()

Resyncs the internal state of a %Metadata{} struct

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

Specs

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

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

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

Specs

validate!(metadata :: t()) :: t()

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

Specs

xml(metadata :: t()) :: binary()

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