Author: ygrego Date: 2015-02-04 13:39:59 +0000 (Wed, 04 Feb 2015) New Revision: 770 Url: http://forge.nuiton.org/projects/sandbox/repository/revisions/770 Log: Adding of documentations for properties and classes of 'SearchManagerObject'. Modified: oipf/js/impl/SearchManagerObject.js Modified: oipf/js/impl/SearchManagerObject.js =================================================================== --- oipf/js/impl/SearchManagerObject.js 2015-02-04 10:29:19 UTC (rev 769) +++ oipf/js/impl/SearchManagerObject.js 2015-02-04 13:39:59 UTC (rev 770) @@ -16,17 +16,84 @@ var SearchManagerObject = Class.extend({ /* - *\param Integer - *\param Integer - *\param Object + * Description: + * This function is the DOM 0 event handler for events indicating changes in metadata. This SHALL be raised + * under the following circumstances: + * 1) When a new version of the metadata is discovered. Note that new versions of metadata can be made + * available without any of the individual items of metadata changing. It is an application's responsibility to + * determine what, if anything, has changed. + * + * 2) When the values of the blocked or locked properties on a content item change due to changes in the + * parental control subsystem (e.g. parental control being enabled or disabled, or a content item being + * unlocked with a PIN). + * + * + * The specified function is called with the arguments action, info and object. These arguments are defined as follows: + * + * • Integer action – the type of update that has taken place. This field will take one of the following values: + * --------------------------------------------------------------------------------------------------------------------------------------------------------------- + * Value | Description + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 1 | A new version of metadata is available (see section 4.1.2.1.2 of [OIPF_META2]) and applications SHOULD discard all references to + * | Programme objects immediately and re-acquire them. + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 2 | A change to the parental control flags for a content item has occurred (e.g. the user has unlocked the parental control features of the receiver, + * | allowing a blocked item to be played). + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 3 | A flag affecting the filtering criteria of a channel has changed. Applications MAY listen for events with this action code to update lists of favourite + * | channels, for instance. + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * + * • Integer info – extended information about the type of update that has taken place. + * If the action argument is set to the value 3, the value of this field SHALL be one or more of the following: + * ----------------------------------------------------------------- + * Value | Description + * ------ ---------------------------------------------------------- + * 1 | The list of blocked channels has changed. + * ------ ---------------------------------------------------------- + * 2 | A list of favourite channels has changed. + * ------ ---------------------------------------------------------- + * 4 | The list of hidden channels has changed. + * ----------------------------------------------------------------- + * If the action argument is set to the value 2, the value of this field SHALL be one or more of: + * ----------------------------------------------------------------- + * Value | Description + * ------ ---------------------------------------------------------- + * 1 | The block status of a content item has changed. + * ------ ---------------------------------------------------------- + * 2 | The lock status of a content item has changed. + * ----------------------------------------------------------------- + * This field is treated as a bitfield, so values MAY be combined to allow multiple reasons to be passed. + * + * • Object object – the affected channel, programme, or CoD asset prior to the change. If more than + * one is affected, then this argument SHALL take the value null. */ - onMetadataUpdate: function(action, info, object) { + onMetadataUpdate: function(action, info, object) {channels, for instance. }, /* - *\param MetadataSearch - *\param Integer + * Description: + * This function is the DOM 0 event handler for events relating to metadata searches. The specified function is called with the arguments search and state. + * These arguments are defined as follows: + * • MetadataSearch search – the affected search + * + * • Integer state – the new state of the search + * --------------------------------------------------------------------------------------------------------------------------------------------------------------- + * Value | Description + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 0 | Search has finished. This event SHALL be generated when a search has completed. + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 1 | This value is not used. + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 2 | This value is not used. + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 3 | The MetadataSearch object has returned to the idle state, either because of a call to SearchResults.abort() or because the parameters for the search + * | have been modified (e.g. the query, constraints or search target). + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- + * 4 | The search cannot be completed due to a lack of resources or any other reason (e.g. insufficient memory is available to cache all of the requested + * | results). + * ------ -------------------------------------------------------------------------------------------------------------------------------------------------------- */ onMetadataSearch: function(search, state) { console.log("[INFO]: onMetadataSearch called", search); @@ -63,28 +130,149 @@ }, /* - * \param Integer - * \return MetadataSearch + * Description : + * Create a MetadataSearch object that can be used to search the metadata. + * + * Argument: + * -searchTarget: The metadata that should be searched. + * Valid values of the searchTarget parameter are: + * ----------------------------------------------------------------- + * Value | Description + * ------ ---------------------------------------------------------- + * 1 | Metadata relating to scheduled content SHALL be searched. + * ------ ---------------------------------------------------------- + * 2 | Metadata relating to on-demand content SHALL be searched. + * ----------------------------------------------------------------- + * + * These values are treated as a bitfield, allowing searches to be carried out across multiple search targets. + * + * Return MetadataSearch */ createSearch: function(searchTarget) { - return new MetadataSearch(); + return new MetadataSearch(searchTarget); }, /* - *\return ChannelConfig + * Description : + * Create a MetadataSearch object that can be used to search the metadata. + * Returns the channel line-up of the tuner in the form of a ChannelConfig object as defined + * in section 7.13.9. This includes the favourite lists. + * The ChannelConfig object returned from this function SHALL be identical to the + * ChannelConfig object returned from the getChannelConfig() method on the + * video/broadcast object as defined in section 7.13.1.3. + * + * Return MetadataSearch */ getChannelConfig: function() { - + return oipfObjectFactory.createChannelConfig(); } }); +/* +* Description: +* 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 below: +* +* --------------------------------------------------------------------------------------------------------------------------------------------------------------- +* State | Description +* ---------- ---------------------------------------------------------------------------------------------------------------------------------------------------- +* Idle | The 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. +* ---------- --------------------------------------------------------------------------------------------------------------------------------------------------- +* Searching | Results 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. +* ---------- ------------------------------------------------------------------------------------------------------------------------------------------------------- +* Found | Search 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. +*/ var MetadataSearch = Class.extend({ /* + * Description: + * The subset of search results that has been requested by the application. * - *\type SearchResults + * Visibility Type: readonly SearchResults */ result: null, @@ -92,6 +280,7 @@ * Description : * The target(s) of the search. Valid values are: * + * ----------------------------------------------------------------- * Value | Description * ------ ---------------------------------------------------------- * 1 | Metadata relating to scheduled content SHALL be searched. @@ -99,9 +288,8 @@ * * These values SHALL be treated as a bitfield, allowing searches to be carried out across multiple search * targets. - * - * Type Integer - * + * + * Visibility: readonly */ searchTarget: null, @@ -145,13 +333,54 @@ }); +/* +* Description: +* The SearchResults class represents the results of a metadata search. Since the result set may contain a large number +* of items, applications request a ‘window’ on to the result set, similar to the functionality provided by the OFFSET and +* LIMIT clauses in SQL. +* +* Applications MAY request the contents of the result in groups of an arbitrary size, based on an offset from the beginning +* of the result set. The data SHALL be fetched from the appropriate source, and the application SHALL be notified when +* the data is available. +* The set of results SHALL only be valid if a call to getResults() has been made and a MetadataSearch event notifying +* the application that results are available has been dispatched. If this event has not been dispatched, the set of results +* SHALL be empty (i.e. the value of the totalSize property SHALL be 0 and calls to item() SHALL return +* undefined ). +* In addition to the properties and methods defined below a SearchResults object SHALL support the array notation to +* access the results in this collection. +*/ var SearchResults = Class.extend({ - //Integer + /* + * Description : + * The number of items in the current window within the overall result set. The value of this property SHALL be + * zero until getResults() has been called and a MetadataSearch event notifying the application that results + * are available has been dispatched. If the current window onto the result set is in fact the whole result set then + * length will be the same as totalSize. Otherwise length will be less than totalSize. + * + * Visibility: readonly + */ lentgh: null, + /* + * Description : + * The number of items in the current window within the overall result set. The value of this property SHALL be + * zero until getResults() has been called and a MetadataSearch event notifying the application that results + * are available has been dispatched. If the current window onto the result set is in fact the whole result set then + * length will be the same as totalSize. Otherwise length will be less than totalSize. + * + * Visibility Type: readonly Integer + */ offset: null, + /* + * Description : + * The total number of items in the result set. + * The value of this property SHALL be zero until getResults() has been called and a MetadataSearch + * event notifying the application that results are available has been dispatched. + * + * Visibility: readonly + */ totalSize: null, init: function() { @@ -159,26 +388,45 @@ }, /* + * Description: + * Perform the search and retrieve the specified subset of the items that match the query. + * Results SHALL be returned asynchronously. A MetadataSearch event with state=0 + * SHALL be dispatched when results are available. + * This method SHALL always return false. + * + * Arguments: + * - offset: The number of items at the start of the result set to be skipped before data is retrieved. * - *\param Integer - *\param Interger - * - *\return Boolean always to false + * - count: The number of results to retrieve. + * */ getResults: function(offset, count) { - }, + /* + * Description: + * Abort any outstanding request for results and remove any query, constraints or ordering + * rules set on the MetadataSearch object that is associated with this SearchResults + * object. Regardless of whether or not there is an outstanding request for results, items + * currently in the collection SHALL be removed (i.e. the value of the length property SHALL + * be 0 and any calls to item() SHALL return undefined ). All cached search results SHALL + * be discarded. + * + */ abort: function() { }, /* - * - *\param Integer - * - *\return Object Instance of Programme, CODAsset, CODFolder , or CODService + * Description: + * Return the item at position index in the collection of currently available results, or + * undefined if no item is present at that position. This function SHALL only return objects + * that are instances of Programme , CODAsset , CODFolder , or CODService . + * + * Arguments: + * - index: The index into the result set. + * */ item: function(index) {