Warning, /frameworks/knewstuff/docs/Design.txt is written in an unsupported language. File is not indexed.

0001 KNewStuff2 Engine Design
0002 ========================
0004 The KNewStuff2 engine is one of the central pieces of activity of the
0005 KNewStuff2 library. First and foremost, it handles the synchronization of
0006 data on the internet with data on the local hard disk. The local data
0007 might come from previous downloads, but also from (initial) installation.
0009 On startup, after being initialized to use a certain configuration,
0010 the engine loads up potentially dozens of files. This will require some
0011 activity on the harddisk, but will speed up network operations by quite
0012 a bit afterwards.
0014 There are three groups of files being loaded: the cache for providers,
0015 the cache for entries, and the registry of entries.
0016 The first two ones may contain all data about providers and entries
0017 ever downloaded by KNewStuff2. The cache doesn't have to survive
0018 machine reboots, but should generally live very long. A strategy for
0019 file replacements and invalidation will have to be found.
0020 The third group contains all the entries which are currently installed.
0021 This group starts out empty, or with some initial system-wide installed
0022 files. For every download, the corresponding cache file (which exists) is
0023 copied to the registry dir, afterwards the cached file isn't strictly
0024 needed anymore. Such files might also be removed again, in case the referenced
0025 data is deinstalled.
0027 Entity         | Loading                 | Root tag
0028 ---------------+-------------------------+---------
0029                |                         |
0030 provider cache | file(s)                 | <ghnsproviders>
0031                |                         |
0032 entry cache    | directory(ies)->file(s) | <ghnscache>
0033                |                         |
0034 entry registry | directory->file(s)      | <ghnsinstall>
0036 Directly after a download, the downloaded files are scanned for their
0037 objects (providers or entries), which are added to the in-memory cache.
0038 By doing so, they might replace older cached entries. For all those older
0039 entries which are already installed, their status is marked as updateable.
0041 On shutdown of the engine, e.g. when deleting the object, the whole
0042 cache in memory is freed, but the cache files remain of course.
0044 KNewStuff2 Workflow
0045 ===================
0047 There are two main workflows with KNewStuff: Uploads and downloads. Together
0048 and repeated over time, these workflows form the data sharing cycle.
0049 In addition, when DXS is used, some direct interaction with the service is
0050 possible, which adds a few workflows. Those will be explained after upload
0051 and download.
0053 Uploads
0054 -------
0055 The engine fetches information about the providers which accept uploads for
0056 a certain mime type or data type. Basically, the list of providers is taken
0057 minus those who do not support uploads, because not all of them do.
0058 A provider selection dialog lets the user select one of the remaining
0059 providers. In case no upload is possible at all, a webpage with uploading
0060 capabilities or at least information about contact by e-mail may be offered
0061 by at least one provider. This so-called 'noupload' fallback page will be
0062 displayed in a browser to the user.
0064 If upload is available, the upload dialog pops up. In it, metadata about the
0065 upload can be edited. Some of it (especially preview images) might be preset
0066 already by the application.
0067 Upload then happens through the engine again. The upload might require
0068 authentication, which is handled transparently.
0070 When server-side versioning is activated, then no version number needs to be
0071 given by the user for updates to existing entries.
0074 ---------
0075 Similar to uploads, all providers suitable for the application's data types
0076 are loaded. However, they appear in parallel, whereas only one provider is
0077 selected for uploads. Each provider might offer different data types, some
0078 matching those needed by the application, some rather not. The provider's
0079 download URL is used to download meta information about all entries, and those
0080 whose data type is not of interest are filtered out.
0081 The provider can offer "tagged" download URLs, the so-called feeds, for
0082 the latest entries, the highest rated ones, or certain other criteria. When
0083 this is the case, the generic download URL is not used, and instead the
0084 feeds are offered to the user as alternative selections, e.g. by being
0085 displayed as tabs on a dialog.
0087 Entries provide meta information which can be viewed, and which might include
0088 a preview image. They also reference the data itself, which is called payload.
0089 Installing the payload means downloading the data, and running it through
0090 a series of checks and installation steps. The data integrity is checked for
0091 using hash sums and digital signatures, if available. The installation routine
0092 moves the data file to its correct location, probably involving decompression,
0093 unpacking and the emission of signals.
0095 For each downloaded and installed entry, the meta information is kept in an
0096 entry registry. In general, all entries and providers are cached.
0097 Deinstallation works the other way around: The meta information is read,
0098 the data deleted and the meta file also deleted afterwards.
0100 Direct interaction
0101 ------------------
0102 As opposed to upload and download, all other workflows are only possible when
0103 the provider supports DXS. Such interaction includes:
0104 * Translation. An entry is referenced and a translation for it is submitted
0105   to the server. Translations might end up in an admin queue or be applied
0106   directly, depending on the site configuration.
0107 * Request for removal. Entries which are deemed unnecessary or offending
0108   are scheduled for removal into an admin queue.
0109 * Comments. Comments can be added (again ending up in a queue or applied
0110   directly), but they can also be requested for viewing.
0111 * Several others. See short descriptions in the feature guide.
0113 Library structure
0114 =================
0116 Proposed structure:
0117 knewstuff/knewstuff2/core - conventional ghns + coreengine
0118 knewstuff/knewstuff2/dxs  - dxs + dxsengine
0119 knewstuff/knewstuff2/ui   - dialogs
0120 knewstuff/knewstuff2      - workflow wrapper (engine)
0121 knewstuff/tests           - test applications
0122 knewstuff/data            - icons and other data
0123 knewstuff/doc             - documentation
0125 Under review:
0126 plasmagik/                - packaging handler
0129 knsrc file format:
0130 [KNewStuff2]
0131 Name=
0132 ProvidersUrl=
0133 TargetDir/InstallPath/etc=
0134 Uncompress=always/never/archive/subdir
0135 CachePolicy=never/resident/only/replaceable
0136 Categories=foo,bar
0138 [foo]
0139 TargetDir/InstallPath/etc=
0140 Uncompress=...
0141 CachePolicy=
0143 [bar]
0144 # empty, then use defaults