Aktions' Requirements Document


Introductions

Abstract

Purpose of this document

Goals

Overview of the rest of the document

General Description

Application Programming Interface (API)

Routing Service

Data Retrieval Application

Audience

General Constraints

Action

System

Privacy & Security

Functional Requirements

Application Programming Interface (API)

Data Types

Adding Data

Retrieving Data

Connection Management

Configuration

Routing

Filtering

Specified Queries

Routing Service

Filtering

Routing

Data Management Facilities

Configurable

Data Retrieval Program

Data Retrieval and Display

Configuration of API Facilities

Demonstrate Use of API

Non-functional Requirements

Application Programming Interface

Platform Independent

Exports C-style Application Binary Interface

Routing Service

Only One Instance per System

Performance Characteristics

Data Retrieval Application

Provides Tutorial for API Use

System Evolution

Application Programming Interface

Routing and Filtering Service

Data Retrieval Application

User Interface Data Model

Separate Configuration Modules

Other Uses of the API

Appendix

Glossary

Footnotes


Introduction

Abstract

Computers have become a major aspect of everyday life, creating a need for improved usage statistics. Aktions is a software development kit designed to gather this information. The software helps developers understand how well their software meets user demand in a functional perspective.

This document describes the requirements for the first iteration of Aktions. It contains a general description of the system at large, the functional requirements we expect, non-functional restraints on the project, and possible features for future releases.

Purpose of this document

The purpose of this document is to outline and explain the specific requirements for the first iteration of Aktions. It enumerates the constraints under which the software is developed. Readers of this document should have a general knowledge of computers.

Goals

Our primary goal is the creation of several components that, when combined, provide the functionality outlined in the abstract. Aktions has 5 main components:

The goals of this iteration are

Overview of the rest of the document

The rest of this document reflects the requirements necessary to accomplish the goals for this iteration. It contains a general description of Aktions, its main components, and the interactions between them. It enumerates

  1. The functional and non-functional requirements for our first release,
  2. Potential functionality for future releases, and
  3. The projected evolution of the system with emphasis on privacy and security.

General Description

Aktions utilizes a client-server architecture. Clients send data to Aktions through an API. This data is then directed through the Routing Service and stored in an information repository. Programs can then query the repository for that data. The first iteration of Aktions development includes an API, a Routing Service, and a Data Retrieval Application.

Application Programming Interface (API)

The API provides a unified mechanism that exchanges information between an interactive program and the Routing Service. It encapsulates data gathering, filtering, and retrieval. The API functions are called directly by an application to submit, retrieve, or manipulate data. It also provides functions that configure Aktions.

Routing Service

The Routing Service provides a central path that all information must pass through. It provides logistical support for Aktions, serving as both a filter and front end for information repositories. All information in the system must pass through this service. It filters actions based on user specified rules, then routes them to an information repository. It implements the routing, filtering, insertion, and query functionality detailed in the API.

Data Retrieval Application

This program is a simple data retrieval and display application. It demonstrates the use of the API to store and retrieve actions from an information repository. This application will facilitate testing of the API and the Routing Service. It provides an example to developers, explaining a real use-case for the API.

Audience

The first iteration serves as a learning aid for the developers of Aktions. It should not be used in any third-party software. Future iterations of Aktions will serve developers and usability experts.

General Constraints

Action

An action is an exertion of will on a user interface system to accomplish a specific atomic task. Actions have the following characteristics:

Name
an identifier given to a specific atomic task, to differentiate it from other tasks.
Time
the absolute time than an action occurred. Time is defined by the system an action occurs on.
Entity
an individual capable of acting autonomously. Entities are distinguishable from one another.
Subsystem
the particular, quantifiable portion of a system where an action occurs.
Method
the form an exertion of will takes as it acts on a system.

System

The system is a personal computer running a graphical user interface. It includes the desktop, task bars, windows, and any controls or widgets characteristic to that environment. Aktions will focus on the K Desktop Environment as its first system.

Privacy & Security

The project rests on a foundation of privacy and security. Information common to an entity must be distinguishable from the rest of the data, yet individual entities must remain anonymous to Aktions. In addition, Aktions must remain security-conscious, disabling the ability for one entity to spy on another entity's settings. While the first iteration of Aktions is not concerned with ensuring privacy, it should remain flexible enough to accommodate this constraint in future iterations.

It is impossible to fully prevent a malicious program from submitting sensitive information to Aktions. However, it should be difficult for such programs to do so successfully. Any implementation of this constraint should not decrease functionality unless absolutely necessary.

Functional Requirements

Application Programming Interface (API)

Data Types

The following data types are defined by the API. They apply to all functions specified by the API.

Return Codes

ReturnCode is an enumerated value used to determine the success or failure of a particular function. It can have the following values

DENIED
the client lacks a connection with Aktions.
FAILURE
the function failed for an unknown reason.
INVALID INPUT
one of the arguments specified contained invalid information.
NOT IMPLEMENTED
the functionality is not presently implemented.
REJECTED
an insert operation failed due to a collision with a filter.
SUCCESS
indicates that the function was fully successful.

Identification Handles

ClientID, QueryID, RouteID, FilterID, and SpecifiedQueryID are numeric values used to uniquely identify a Client, Query, Route, Filter, or SpecifiedQuery respectively.

Action

The action data type includes the following fields:

Name
a descriptive title given to an action. Examples: "cut", "print", "bolden text".
Time
a date,time pairing that contains when an action occurred. Example: "10:10 AM, October 10, 2010".
Entity
the user or program that performed an action. Example: "zakaelri", "foobar", "dothatthing.exe".
Subsystem
the program where the action occurred. Example: "Kate", "Microsoft Word".
Method
how the action occurred. Example: "button","menu item","accelerator".

Search Constraints

Search Constraints include characteristics to search through, a conditional operator, and a value for the operator to apply to. All Search Constraints are evaluated with an "and" relationship to one another. If any Search Constraint fails for a particular action, that action is omitted from the returned results. To obtain an "or" relationship with a query, multiple queries must be used.

Conditional Operators

equals
Filters results where the characteristic is equal to the value.
does not equal
Filters results where the characteristic is not equal to the value.
contains
Filters results where the characteristic contains the value. Only applicable to textual characteristics.
greater than
Filters results where the characteristic possesses a mathematical relationship of > respective to value. Only applicable to numeric and date characteristics.
less than
Filters results where the characteristic possesses a mathematical relationship of < respective to value. Only applicable to numeric and date characteristics.
unique
Filters results to remove duplicate items from the set of actions. The unique operator can only be used once per query. The unique operator makes no guarantees to the contents of other characteristics.

Sorting Order

Queries can contain sorting instructions. Sorting orders specify the fields of an action to sort by, as well as whether to sort in ascending or descending order.

Client Data

Client data describes the client that is attempting to connect to Aktions. It contains the following fields

Name
The name of the client.
System
The platform that the client is running on or observing. Examples: "Windows XP", "Qt", "GNOME".
Version
The version of the client. This field is optional.

Routing Data

Routing data is given to the API to tell the routing service to connect to an information store or other program. The structure of this data is as follows

Name
the name of the new path being created. Examples: "HelperApplet", "ClipIt™", "Backup File".
Type
the type of route to create. Examples: "Flat File", "MySQL Database", "Tuplespace".
From
The name of where to get data from. The From attribute is optional; when it is omitted, Aktions assumes that information is coming from the API.
To
the place where data is being routed to. This can be a program or information store.

Adding Data

insert

The API provides a function to insert an action into the information repository. This method extracts the characteristics of an action, performs information scrubbing, and forwards the data to the routing & filtering service.

ReturnCode insert(IN ClientID, IN Action)

Retrieving Data

runQuery

The API provides a function to query the information repository. It must be possible to specify a list of constraints and a sorting order to a query.

ReturnCode runQuery(IN ClientID, IN List SearchConstraint, OPTIONAL IN List SortOrder, OUT List Action)

runSpecifiedQuery

It is also possible to query data using a previously stored query, by providing a QueryID.

ReturnCode runSpecifiedQuery(IN ClientID, IN QueryID, OUT List Action)

Connection Management

addClient

addClient negotiates connection status, facilitates resource allocation, and provides client-specific data for Aktions. addClient negotiates a communication mechanism between a client and routing service. Aktions will not accept data unless a clientID has been associated with the program via this function.

ReturnCode addClient(IN ClientData, OUT ClientID)

removeClient

A function must be provided to disconnect from the Aktions system. removeClient closes the communication mechanism between a client and routing service. This invaliates the ClientID associated with the client.

ReturnCode removeClient(IN ClientID)

Configuration

Several functions must be provided to configure Aktions. Configurable sections include information routing and filtering, and creating stored queries.

Routing

Users can define routes that direct actions to an information repository or other program.

addRoute

addRoute tells Aktions to send incoming data down a path.

ReturnCode addRoute(IN ClientID, IN RouteData, OUT RouteID)
listAllPublicRoutes

listAllPublicRoutes returns a list of all routes stored by the routing service along with their respective RouteIDs.

ReturnCode listAllPublicRoutes(IN ClientID, OUT List RouteData, OUT List RouteID)
removeRoutes

removeRoutes tells Aktions to stop sending information down a previously added path.

ReturnCode removeRoute(IN ClientID, IN RouteID)

Filtering

Users can define filters that stop actions that match the filter from being stored in the information repository. When any field in an action matches a filter, that action is dropped.

addFilter

addFilter creates a filter.

ReturnCode addFilter(IN ClientID, IN Constraint, OUT FilterID)
removeFilter

removeFilter deletes a filter.

ReturnCode listYourFilters(IN ClientID, OUT List Constraint, OUT List FilterID)
listYourFilters

listYourFilters returns a listing of all filters associated with the client that makes a request, along with their respective FilterIDs.

ReturnCode removeFilter(IN ClientID, IN FilterID)

Specified Queries

Users can specify queries to be stored by the Routing Service.

addSpecifiedQuery

addSpecifiedQuery is used to create a stored query.

ReturnCode addSpecifiedQuery(IN ClientID, IN List Constraint, IN List SortOrder, OUT SpecifiedQueryID)
listSpecifiedQueries

listSpecifiedQueries returns a listing of all queries stored by Aktions, along with their respective SpecifiedQueryIDs.

ReturnCode listSpecifiedQueries(IN ClientID, OUT List Constraint, OUT List SortOrder, OUT List SpecifiedQueryID)
removeSpecifiedQueries

removeSpecifiedQuery deletes a stored query from Aktions.

ReturnCode removeSpecifiedQuery(IN ClientID, IN SpecifiedQueryID)

Routing Service

Filtering

All actions pass through a filtering system before being stored in or retrieved from an information repository. This allows users to decide exactly what data collected or ignored. Actions can be filtered according to an arbitrary set of filtering rules. Of primary importance are entity and program filters. Entity filters discard information based on the entity field of an action, and subsystem filters discard information based on the subsystem field of an action.

Routing

After the information passes through the filters it is routed to one or more information repositories. The Routing Service is capable of handling several routes concurrently. The first iteration will only provide one route. However, the routing system is extensible, so other routes can be implemented in future releases.

Data Management Facilities

The service provides facilities for managing the various information repositories available to Aktions. It is extensible, so that Aktions can support any information repository that implements the functionality required by Aktions.

Configurable

Description

The service is configurable at runtime through the API. Applications that use the API may configure the various options in the service after they have connected to it. This removes the need for a system-wide configuration file, registry settings, etc. Configuration options are outlined in the Application Programming Interface.

Default configuration

The default configuration filters all incoming actions and queries from clients that have not connected to it. Once an application has connected to the service, that client must configure a default route for Aktions. After the route has been configured, the service will accept data.

Data Retrieval Program

Data Retrieval and Display

This application retrieves and displays information from Aktions. It provides limited analytical tools, whose purpose is largely to sort and search through incoming data.

Configuration of API Facilities

This application configures the Routing Service. It allows a user to define routes, filters, and stored queries.

Demonstrate Use of API

This application demonstrates the use of the API for developers. It provides an example of using the API to both store and retrieve actions. The application tracks its users, and sends their actions to Aktions via the API. It uses the API to retrieve specific information for display. It also uses the API to configure the Routing Service.

Non-functional Requirements

Application Programming Interface

Platform Independent

The Aktions API should remain independent of operating system, platform-specific libraries, or computer architecture. Platform independence increases portability of the system. This can increase the potential audience. In addition, highly portable code tends to be more robust, as developers cannot assume qualities of the underlying system.

Exports C-style Application Binary Interface

Regardless of the underlying implementation, the Aktions API must export "C-Style" function names for linking purposes. This removes name mangling and standardizes the way programmers use the API across all platforms and languages.

Routing Service

Only One Instance per System

Only one instance of the service is allowed to run at a time. This should have positive effects on performance. It also allows effective system wide action filtering.

Performance Characteristics

Aktions cannot have a human-noticeable impact upon the performance characteristics of the system it is monitoring. Aktions is designed to run on interactive systems that must remain responsive at all times.

Data Retrieval Application

Provides Tutorial for API Use

The Data Retrieval Application should provide a tutorial which demonstrates how to integrate the API into an existing or new application. It demonstrates the use of all the available functionality.

System Evolution

Application Programming Interface

The API could be extended to accept additional information describing other events which occur throughout the system. It could record application crashes, system events, and window switches.

The scope of our project currently includes only the ability to collect information. Adding the capability to send actions to applications increases the utility of the API for debugging purposes. This could also allow users to record common activities and create batches of actions for execution by the application.

The API could provide helper applications which automatically generate the source code for using Aktions in a particular project. This reduces the errors caused through hand coding and frees up more developer time.

Routing and Filtering Service

Only 1 route is available for data transfer. Additional routes could be added. These routes could facilitate exporting, remote storage, backup, and additional storage mechanisms. Aktions could also include routes which allow one application to monitor the events of another.

Data Retrieval Application

The Data Retrieval Application will be expanded to incorporate tools which analyze the collected data. These tools can range from aggregate statistics analysis to real-world use case generation. A pluggable module could be developed to allow developers to incorporate their own tools into the application.

User Interface Data Model

Creating a data model that incorporates a set of generic interface elements would benefit the project greatly. It would facilitate the development of platform independent analysis tools, and enable comparisons between different platforms.

Separate Configuration Modules

Configuration of Aktions is only possible through the Data Retrieval Application. An application should be created to enable configuration without that development tool installed.

Other Uses of the API

An application could be built which collects run-time data from programs without requiring Aktions to be built into an application. Other applications could "subscribe" to a feed and help users configure or user their system (somewhat similar to Microsoft's ClipIt™).

Appendix

Glossary

Application Programming Interface (API)
the interface that a computer system or application provides in order to allow requests for service to be made of it by other computer programs, and/or to allow data to be exchanged between them .
Application Binary Interface (ABI)
describes the low-level interface between an application program and the operating system, between an application and its libraries, or between component parts of an application .
Information Repository
a construct capable of storing and retrieving information pertinent to Aktions. An information repository can range from a remote database to a local text file.

Footnotes

For more information: Wikipedia. K Desktop Environment. "http://en.wikipedia.org/wiki/K_desktop_environment"

For more information: Wikipedia. Name Mangling. "http://en.wikipedia.org/wiki/Name_mangling".

For more information: Wikipedia. Application Programming Interface "http://en.wikipedia.org/wiki/Application_programming_interface"

For more information: Wikipedia. Application Binary Interface. "http://en.wikipedia.org/wiki/Application_binary_interface".


This site hosted by: SourceForge.net Logo