README

   1 README for NonameTV
   2 -------------------
   3
   4 LICENSE
   5
   6 This program is free software: you can redistribute it and/or modify
   7 it under the terms of the GNU Affero General Public License as
   8 published by the Free Software Foundation, either version 3 of the
   9 License, or (at your option) any later version.
  10
  11 This program is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 Affero General Public License for more details.
  15
  16 You should have received a copy of the GNU Affero General Public
  17 License along with this program.  If not, see
  18 <http://www.gnu.org/licenses/>.
  19
  20 INTRODUCTION
  21
  22 The system consists of three main parts: the Importers, the Database
  23 and the Exporters.
  24
  25 IMPORTERS
  26
  27 Importers are used to import data from different sources into the database.
  28 There is one importers for each data provider. All importers inherit
  29 from the NonameTV::Importer class and thus provide a consistent interface.
  30
  31 Data is imported in batches. A batch is the smallest unit of data that
  32 can be identified by the importer. Usually, a batch corresponds to
  33 a file provided by the data provider.
  34
  35 All Importers that import data via HTTP inherit from one of
  36 NonameTV::Importer::BaseOne, BaseDaily or BaseWeekly. These baseclasses
  37 provide helper-functions that handle data provided in a single file per
  38 channel, one file per day and channel or one file per week and channel.
  39
  40 There is an override-mechanism implemented in the importers that can be
  41 used to override faulty data provided by the data-providers. Sometimes
  42 the data is plain wrong and you need to edit it before feeding it to
  43 the importers. See tools/nonametv-import-download for instructions.
  44
  45 The Importers are run via the command-line tool tools/nonametv-import:
  46
  47 perl -I lib tools/nonametv-import Infomedia --verbose
  48
  49 DATABASE
  50
  51 All data is stored in a MySQL-database in a consistent format. All
  52 strings are encoded in utf-8 in the database and all times are stored
  53 in UTC-timezone.  The channels and trans_cat tables are updated
  54 manually (using the mysql frontend of your choice.) The programs and
  55 batches tables are updated by the Importers and cannot be updated
  56 manually.
  57
  58 EXPORTERS
  59
  60 The Exporters take the data in the database and export it in another format.
  61 The only Exporter that exist today is the Xmltv exporter that exports data
  62 in a format that tv_grab_se_swedb can utilize.
  63
  64 AVOIDING UNNECESSARY UPDATES
  65
  66 tv_grab_se_swedb utilizes http-caching to avoid downloading data that
  67 hasn't changed since the last time tv_grab_se_swedb was run. This
  68 saves a lot of bandwidth for the server if utilized correctly.
  69
  70 Additionally, some of the Importers take a lot of time to run and we want
  71 to avoid Importing data if nothing has changed. There are a number of
  72 mechanisms in place to avoid doing unnecessary work:
  73
  74 All Importers use HTTP-caching (if they fetch data via HTTP) and only
  75 processes data if it has actually changed since it was last downloaded.
  76 To force an update (for example if the Importer-code has been improved),
  77 use the parameter --force-update:
  78
  79 perl -I lib tools/nonametv-import Infomedia --force-update
  80
  81 The Exporter only exports data for batches that have actually changed.
  82 Furthermore, after exporting a file, the Exporter checks to see if the
  83 exported file is different from the previous file for that period. If
  84 the new file is identical to the old file, the old file is left untouched.
  85
  86 After the export-step, rsync is used to copy the data from the
  87 xmltv_staging directory to the xmltv-directory. Once more, only files
  88 that have actually changed (detected by checking file contents) are
  89 copied. This can be useful during development, since you can do an
  90 export, see that something went wrong (for example by using
  91 tools/nonametv-xmltv-compare-run and look at the changes). Then revert
  92 your changes and run export again. Since the newly exported files are
  93 then identical to the files in the xmltv/directory, the next run of
  94 rsync will not copy any files even though the date on the files has been
  95 updated.