Generic AHL API SpecificationChanges in Generic AHL API documentation
Changes in Generic AHL API
ContentsPurposeThe Adaptive History List subsystem provides a list of the user’s favorite items based on the user’s previous behavior. API DescriptionThe client-side module provides an API for applications to log items, request recommended lists, modify items, or to configure Adaptive History List Engine. The server-side module handles requests from clients and incorporates a weight-based sorting algorithm to arrange items in the most-used order. In order to implement sorting algorithm, the engine has two data storages. The most important items with optional names are stored in the primary storage and in the secondary storage there are stored only hashes of items. Secondary storage is used for more accurate sorting of items in primary storage when these will advance in future. Use CasesThere are twelve use cases here: AHL initialization
Engine configuration
Items managing
Observer managing
API Class StructureThe API interface class structure consists of two interfaces.
Related APIs
Using the AHL APITo use the AHL API, an application needs to firstly link the AHLE2CLIENT library to itself, and then create the AHL engine instance. In general, using the AHL API always contains the following steps:
See the following section for detailed instructions on how to use the interfaces. In examples for test cases we assume that there are following items in database (first item is most recently/frequently used): Example database content.
Create AHL clientTo create a new instance of AHL, a client application should call
The following code snippet demonstrates how to create an AHL client. After finishing work with AHL client, the pointer returned by
Related APIs
Get engine configurationThe following code snippet demonstrates how to get engine configuration. Set engine configurationThe following code snippet demonstrates how to set engine configuration. Adaptation speed determines how fast new items will advance on adaptive history list. The value set should be between 0 and 1, excluding. The closer the adaptation speed is to 1, the slower items will advance. Default value for adaptation speed is 0.95. The default size of the primary storage is 50 items and of secondary - 500. Log an itemThe following code snippet demonstrates how to log a new item to AHL database. Name and weight can be omitted. Weight can be used to categorize items: more important items should have higher base weight value. After that operation example database content does not change, because "Item" is already on first place. If it would be on further place it could advance and if it would not exist in database it could be added depending on other items weights. Rename an itemThe following code snippet demonstrates how to rename an item. Example database content after Rename.
Delete item(s)Delete a single itemThe following code snippet demonstrates how to delete one item from AHL database. Example database content after delete single item.
Delete many itemsThe following code snippet demonstrates how to delete several specified items from AHL database. Example database content after delete specified items.
Delete items matchingThe following code snippet demonstrates how to delete several items matching a specified string from AHL database. Example database content after delete items matching.
Clear itemsThe following code snippet demonstrates how to clear database (delete all items). After that operation database will be empty. Flush itemsThe following code snippet demonstrates how to write AHL database from memory to the disk file. Get Adaptive listThe following code snippet demonstrates how to get adaptive list of items. For example database content after "AdaptiveListL" call "items" table will consists following values {"AItem", "AFoo"} and in names table values {"AName", "Foo"}. Match can be omitted and then the first items are taken from the list. If the match is omitted in the previous example, the tables contain the following values: "items" {"Item", "Item3", "Item1"} and "names" {"Name", "Name3", "Name1"}. Order itemsThe following code snippet demonstrates how to order items based on adaptive list hierarchy. For example database content after "OrderByWeightL" call "sortedItems" table will consists following values {3, 1}. Set observerTo set an observer, the client application should provide a class implementing
interface
The following code snippet demonstrates how to set AHL engine observer. After consuming an event, the client application needs to set the observer again before handling further events, e.g.:
Related APIs
Cancel observerThe following code snippet demonstrates how to cancel AHL engine observer. Error handlingResponses from Adaptive History List Server and errors occurring due to incorrect parameters passed by the client to the API functions (e.g. out of range) are returned as return codes for synchronous functions and in the request status parameter for asynchronous functions. If a system error occurs in a client-side function, the function leaves. Error messages
Related APIs
Memory overheadMemory consumption on the client side depends on the size of requested or sent data. It can be up to 2.5 times more than the size of requested data for adaptive list and it will not exceed 1,5 of sent/received data for other use cases. Average memory consumption per database on server side is about 30kB in default configuration (primary storage 50 and secondary storage 500), maximal is about 180kB.
Related APIs
GlossaryDefinitionsAHL API definitions
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|