The MetadataSearch class

Support in HbbTV

Available since: HbbTV 1.5 (ETSI TS 102 796 V1.2.1, OIPF DAE V1.2)

Only the value ‘1’ of the searchTarget property is included.

For the createQuery method, only the following case-insensitive values for the field parameter are included – “Programme.startTime”, “Programme.name”, “Programme.programmeID”. These shall correspond to the properties of the same name.

The addRatingConstraint, addCurrentRatingConstraint and addChannelConstraint(ChannelList) methods are not included.

The orderBy method is not included – all search results shall be returned ordered first by channel, in the same order as presented to applications through a ChannelList object, then by start time in ascending order.

The count parameter of the findProgrammesFromStream method of the MetadataSearch class is not included.

Comment

Broadcast-related

A MetadataSearch object represents a query of the metadata about available programmes. Applications can create MetadataSearch objects using the createSearch() method on the application/oipfSearchManager object. When metadata queries are performed on a remote server, the protocol used is defined in section 4.1.2.2 of [OIPF_META2].

Each search consists of three steps:

  1. Definition of the query.  The application creates a MetadataSearch object, and either creates its associated Query object, or sets a query using the findProgrammesFromStream() method, and sets any applicable constraints and result ordering.
  2. Acquisition of results. The OITF acquires some or all of the items that match the specified query and constraints, and caches the requested subset of the results. This is typically triggered by a call to getResults().
  3. Retrieval.  The application accesses the results via the SearchResults class.

The MetadataSearch and SearchResults classes work together to manage an individual search.  For every search, the MetadataSearch object and its corresponding SearchResults object SHALL be in one of three states as described in Table 7.  Figure 13 below shows the transitions between these states:

Figure 13: State machine for a metadata search (informative)

Table 7: Metadata search states (normative)

StateDescription
IdleThe search is idle; no results are available. This is the initial state of the search. In this state, the application can set or modify the query, constraints or ordering rules that are applied to the search. No search results are available in this state – any calls to SearchResults.item() SHALL return undefined and the values of the length and totalSize properties on the SearchResults object SHALL return zero. Any search results that have been cached by the terminal SHALL be discarded when the Idle state is entered. Calling the SearchResults.getResults() method SHALL cause a state transition to the Searching state.
SearchingResults are being retrieved and are not yet available to applications. If the terminal has not previously cached the full set of search results, the terminal performs the search to gather the requested results. If a new version of the metadata is detected (e.g. due to an EIT update) while the search is in this state, results SHALL be retrieved from either the new or original version of the metadata but SHALL NOT be retrieved from a combination of the two versions. Calls to SearchResults.item() SHALL return undefined. Any modification of the search parameters (e.g. changing the query or adding/removing constraints, or calling findProgrammesFromStream()) by the application SHALL stop the current search and cause a transition to the Idle state. The terminal SHALL dispatch a MetadataSearch event with state=3. When all requested results have been found, the terminal SHALL dispatch a MetadataSearch event with state=0 and a state transition to the Found state SHALL occur. If the search cannot be completed due to a lack of resources or any other reason, the terminal SHALL dispatch a MetadataSearch event with state=4 and a state transition to the Idle state SHALL occur. Calls to the SearchResults.getResults()method SHALL abort the retrieval of search results and attempt to retrieve the newly-requested set of results instead. NOTE: Calling getResults() when in the searching state may be used to fetch a group of items starting at a different offset or with a different count.
FoundSearch results are available and can be retrieved by applications. The data exposed via the SearchResults.item() method is static and never changes as a result of any updates to the underlying metadata database until SearchResults.getResults() is next called. If a new version of the metadata is detected (e.g. due to an EIT update), a MetadataUpdate event is dispatched with action=1. Subsequent calls to SearchResult.getResults() SHALL return results based on the updated metadata. Calls to SearchResults.getResults() SHALL cause a state transition to the Searching state. Any modification of the search parameters (e.g. changing the query or adding/removing constraints, or calling findProgrammesFromStream()) by the application SHALL cause the current set of results to be discarded and SHALL cause a transition to the Idle state. The terminal SHALL dispatch a MetadataSearch event with state=3.

The findProgrammesFromStream() method acts as a shortcut for setting a query and a set of constraints on the MetadataSearch object . Regardless of whether the query and constraints are set explicitly by the application or via findProgrammesFromStream(), results are retrieved using the getResults() method.

Changes to the search parameters (e.g. changing the query or adding/removing constraints or modifying the search target, or calling findProgrammesFromStream()) SHALL be applied when the getResults() method on the corresponding SearchResults object is called. Due to the nature of metadata queries, searches are asynchronous and events are used to notify the application that results are available. MetadataSearch events SHALL be targeted at the application/oipfSearchManager object.

The present document is intentionally silent about the implementation of the search mechanism and the algorithm for retrieving and caching search results except where described in Table 7 above. When performing a search, the receiver MAY gather all search results and cache them (or cache a set of pointers into the full database), or gather only the subset of search results determined by the getResults() parameters, or take an alternative approach not described here.

Properties

readonly Integer searchTarget

The target(s) of the search. Valid values are:

Value

Description

1

Metadata relating to scheduled content SHALL be searched.

2

Metadata relating to on-demand content SHALL be searched.

These values SHALL be treated as a bitfield, allowing searches to be carried out across multiple search targets.

readonly SearchResults result
The subset of search results that has been requested by the application.

Methods

void setQuery( Query query )

Description

Set the query terms to be used for this search, discarding any previously-set query terms.

Setting the search parameters using this method will implicitly remove any existing constraints, ordering or queries created by prior calls to methods on this object.

Arguments

query

The query terms to be used

void addRatingConstraint( ParentalRatingScheme scheme, Integer threshold )

Description

Constrain the search to only include results whose parental rating value is below the specified threshold.

Arguments

scheme

The parental rating scheme upon which the constraint SHALL be based. If the value of this argument is null, any existing parental rating constraints SHALL be cleared.

threshold

The threshold above which results SHALL NOT be returned. If the value of this argument is null, any existing constraint for the specified parental rating scheme SHALL be cleared.

void addCurrentRatingConstraint()

Description

Constrain the search to only include results whose parental rating value is below the threshold currently set by the user.

void addChannelConstraint( Channel channel )

Description

Constrain the search to only include results from the specified channel. If a channel constraint has already been set, subsequent calls to addChannelConstraint() SHALL add the specified channel to the list of channels from which results should be returned.

For CoD searches, adding a channel constraint SHALL have no effect.

Arguments

channel

The channel from which results SHALL be returned. If the value of this argument is null, any existing channel constraint SHALL be removed.

void orderBy( String field, Boolean ascending )

Description

Set the order in which results SHOULD be returned in future. Any existing search results SHALL not be re-ordered. Subsequent calls to orderBy() will apply further levels of ordering within the order defined by previous calls. For example:

orderBy(“ServiceName”, true);

orderBy(“PublishedStart”, true);

will cause results to be ordered by service name and then by start time for results with the same channel number.

Arguments

field

The name of the field by which results SHOULD be sorted. A value of null indicates that any currently-set order SHALL be cleared and the default sort order should be used.

ascending

Flag indicating whether the results SHOULD be returned in ascending or descending order.

Query createQuery( String field, Integer comparison, String value )

Description

Create a metadata query for a specific value in a specific field within the metadata. Simple queries MAY be combined to create more complex queries. Applications SHALL follow the JavaScript type conversion rules to convert non-string values into their string representation, if necessary.

Arguments

field

The name of the field to compare. Fields are identified using the format <classname>.<propertyname> where classname SHALL be one of “Programme”, “CODAsset”, “CODService” or “CODFolder” and <propertyname> SHALL be a valid property name on the corresponding class.

comparison

The type of comparison. One of:

Value

Description

0

True if the specified value is equal to the value of the specified field.

1

True if the specified value is not equal to the value of the specified field.

2

True if the value of the specified field is greater than the specified value.

3

True if the value of the specified field is greater than or equal to the specified value.

4

True if the value of the specified field is less than the specified value.

5

True if the value of the specified field is less than or equal to the specified value.

6

True if the string value of the specified field contains the specified value. This operation SHALL be case insensitive, and SHALL match parts of a word as well as whole words (e.g. a value of “term” will match a field value of “Terminator”).

value

The value to check. Applications SHALL follow the JavaScript type conversion rules to convert non-string values into their string representation, if necessary

void findProgrammesFromStream( Channel channel, Integer startTime,
Integer count )

Description

Set a query and constraints for retrieving metadata for programmes from a given channel and given start time from metadata contained in the stream as defined in section 4.1.3 of [OIPF_META2]. Setting the search parameters using this method will implicitly remove any existing constraints, ordering or queries created by prior calls to methods on this object.

This method does not cause the search to be performed; applications must call getResults() to retrieve the results. Applications SHALL be notified of the progress of the search via MetadataSearch events as described in section 7.12.1.2.

Arguments

channel

The channel for which programme information should be found.

startTime

The start of the time period for which results should be returned measured in seconds since midnight (GMT) on 1/1/1970. The start time is inclusive; any programmes starting at the start time, or which are showing at the start time, will be included in the search results. If null, the search will start from the current time.

count

Optional argument giving the maximum number of programmes for which information should be fetched. This places an upper bound on the number of results that will be present in the result set – for instance, specifying a value of 2 for this argument will result in at most two results being returned by calls to getResults() even if a call to getResults() requests more results.

If this argument is not specified, no restrictions are imposed on the number of results which may be returned by calls to getResults().