README for tv_grab_nl_java
==========================

NOTICE
------
tv_grab_nl_java has been discontinued. I would recommend tvgrabpiAPI 
(https:/tvgrabbers/tvgrabpyAPI) for grabbing Dutch XMLTV data.

English Summary
---------------
tv_grab_nl_java is an XMLTV-compatible grabber for Dutch television that uses
TVGids.nl, rtl.nl, horizon.tv (UPC) and/or ziggogids.nl as sources.

Algemeen
--------
tv_grab_nl_java is een XMLTV-compatibele grabber voor Nederlandse televisie 
die TVGids.nl, rtl.nl, horizon.tv (UPC) en ziggogids.nl als bron kan gebruiken. 
tv_grab_nl_java is geschreven in Java en gebruikt o.a. de JSON-interface van TVGids.nl.

Kenmerken van tv_grab_nl_java:
- detailinformatie wordt gecached
- links naar zenderlogo's worden automatisch toegevoegd 
- kijkwijzeraanbevelingen worden toegevoegd (alleen tvgids)
- --configure behoudt de zenderinstellingen van het oude configuratiebestand 
  als default
- geeft informatie over acteurs, presentatie, regisseur weer in xmltv
  (afhankelijk van de bron)
- geschikt voor mythtv

Geschiedenis
------------
Zie het bestand 'Changelog' voor de geschiedenis van deze grabber

Installatie (Linux)
-------------------

1. Het programma vereist een Java runtime, versie 6 of hoger. Onder Debian te 
   installeren met 
   $ apt-get install openjdk-6-jre

2. Download de laatste .zip file van https:/janpascal/tv_grab_nl_java/releases
   en pak 'm uit.
   $ unzip tv_grab_nl_java-<VERSIE>.zip
   $ cd tv_grab_nl_java-<VERSIE> 

3. Plaats de tv_grab_nl_java.jar file uit de zipfile in /usr/local/share/java/
   en plaats tv_grab_nl_java in /usr/local/bin. Gebruik hiervoor het 
   meegeleverde script install.sh, of:
   $ sudo mkdir /usr/local/share/java
   $ sudo cp tv_grab_nl_java.jar /usr/local/share/java/
   $ sudo cp tv_grab_nl_java /usr/local/bin
   $ chmod a+x /usr/local/bin/tv_grab_nl_java

Installatie (Windows)
-------------------

1. Het programma vereist een Java runtime, versie 6 of hoger. Te downloaden van
   de URL http://www.oracle.com/technetwork/java/javase/downloads/index.html
   Kies de laatste versie van de Java JRE.

2. Download het Windows installatiebestand (Setup-tv_grab_nl_java-<VERSIE>.exe)
   van https:/janpascal/tv_grab_nl_java/releases
   en draai de installer. 

3. Na de installatie is er in een startmenu een link naar tv_grab_nl_java
   gemaakt. Selecteer de 'Configure' optie in het startmenu om tv_grab_nl_java
   te configureren. Zie verder onder 'Configuratie'.

4. Start de tool vanuit je eigen script. Gebruik de link uit het startmenu om te
   zien hoe de tool moet worden aangeroepen. Bij een standaardinstallatie is
   dit:

   C:\windows\system32\java.exe -jar "c:\Program Files\tv_grab_nl_java\tv_grab_nl_java.jar" --output tv.xml

   Voeg je eigen opties aan deze command line toe. Zie verder onder 'Gebruik'.

Configuratie
------------

Je kunt tv_grab_nl_java configureren met de --configure optie. De tool haalt 
dan de beschikbare kanalen op van tvgids.nl en rtl.nl en vraagt je van welke 
kanalen je de programmagegevens op wilt halen. 

$ tv_grab_nl_java --configure

Er wordt eerst een aantal algemene vragen gesteld. Hiervoor is de defaultwaarde
meestal prima. Je wordt eerst gevraagd welke van de beschikbare bronnen je wilt
gebruiken.  Vervolgens zoekt het programma uit voor welke kanalen er
programma-informatie beschikbaar is uit de door jou geselecteerde bronnen.
Daarna volgt een lange reeks vragen over de kanalen van de bronnen die je hebt
geselecteerd.

Je hebt telkens de keus uit:
- Y (yes): gebruik kanaal
- N (no): gebruik kanaal niet
- A (all): gebruik kanaal en alle volgende kanalen
- none: gebruik kanaal en alle volgende kanalen niet
- k (keep): gebruik voor dit en de volgende kanalen de keuzes van de vorige keer

De configuratie wordt opgeslagen in het bestand $HOME/.xmltv/tv_grab_nl_java.conf. 
Je kunt dit bestand eventueel handmatig bewerken. Als je tv_grab_nl_java nogmaals 
aanroept met de --configure optie, dan worden je eerdere keuzes als default gebruikt. 

Pas op met het handmatig bewerken van het configuratiebestand. Fouten in dit
bestand kunnen ertoe leiden dat de grabber niet meer werkt. De volgende velden
kunnen handmatig worden bewerkt:
- fetch-channel-logos. Vul in 'yes' (standaard) of 'no'. Bij 'no' worden in het
  uitvoerbestand geen channel-logo's opgenomen. Dit kun je gebruiken als je zelf
  channel-logo's hebt ingesteld en niet wilt dat deze worden overschreven.
- nice-time-milliseconds (standaard 500). Het aantal milliseconden tussen
  achtereenvolgende verzoeken naar de webservers van tvgids etc. Een kortere
  tijd maakt de grabber sneller, maar kan ertoe leiden dat de provider je
  'vervelend' gaat vinden en je blokkeert. De standaardwaarde van 500 is een
  goed compromis.
- per channel:-regel kan het xmltvid aangepast worden (in de derde kolom). Je
  kunt kanalen ook uit- en aanzetten door in de vijfde kolom "enabled" of 
  "disabled" in te vullen.

Gebruik
-------
$ tv_grab_nl_java [opties]

Beschikbare opties:
--capabilities        Show grabber capabilities
--description         Display a description to identify this grabber
--help                Show this help
--license             Show software license information
--config-file <arg>   Configuration file location
--cache <arg>         Cache file location
--clear-cache         Verwijder gecachede programmagegevens
--configure           Interactive configuration
--output <arg>        Set xlmtv output filename
--quiet               Disable progress display. Also set log-level to ERROR.
--log-level           Zet het logging-level. Defaultwaarde is INFO, andere mogelijkheden zijn
					  ERROR,WARN,INFO,DEBUG en TRACE
--offset <arg>        Start day for grabbing (0=today)
--days <arg>          Number of days to grab

Voorbeeld:
$ tv_grab_nl_java --offset 1 --days 2 --output uitvoer.xml
Dit commando haalt de programma-informatie van de geselecteerde kanalen op voor 
morgen en overmorgen en schrijft de resultaten weg in het bestand 'uitvoer.xml'.

Compileren
----------
Als je de tool vanaf de source code wilt compileren, dan heb je een Java6 SDK
nodig en maven2. De source code staat in git.
1. Code downloaden:
   $ git clone git:/janpascal/tv_grab_nl_java.git
   $ cd tv_grab_nl_java
2. Compileren:
   $ mvn compile
3. jar file met alle dependencies erin maken:
   $ mvn assembly:single
   Deze stap levert de jar file in target/tv_grab_nl_java-<VERSION>-dep.jar
4. Het release.sh script maakt een release zipfile, inclusief deze README en het
   tv_grab_nl_java script, en een Windows installerbestand.

De git repository is ook meteen een Eclipse project. Hiervoor heb je Eclipse
Indigo nodig, inclusief de git (www.eclipse.org/egit/) en maven
(http://www.eclipse.org/m2e/) plugins. Importeer dan het project direct van
github via File/Import/Git/Projects from Git.
Het adres van de git repository is git:/janpascal/tv_grab_nl_java.git

License
-------
Copyright (c) 2012-2015 Jan-Pascal van Best <[email protected]>

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

The full license text can be found in the LICENSE file.

Laatste aanpassing
------------------
2014-01-02 (versie 1.5.1)