0838e87c2283864c727f45ef43665e86985c3cb1
[utils] / crawler / kiss / docs / content / xdocs / index.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3   Copyright 2002-2004 The Apache Software Foundation or its licensors,
4   as applicable.
5
6   Licensed under the Apache License, Version 2.0 (the "License");
7   you may not use this file except in compliance with the License.
8   You may obtain a copy of the License at
9
10       http://www.apache.org/licenses/LICENSE-2.0
11
12   Unless required by applicable law or agreed to in writing, software
13   distributed under the License is distributed on an "AS IS" BASIS,
14   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   See the License for the specific language governing permissions and
16   limitations under the License.
17 -->
18 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
19 <document> 
20   <header> 
21     <title>Automatic Recording for KiSS Hard Disk Recorders</title> 
22   </header> 
23   <body>
24     <warning>
25       KiSS makes regular updates to their site that sometimes require adaptations
26       to the crawler. If it stops working, check out the most recent version here. 
27     </warning> 
28     <section id="changelog">
29       <title>Changelog</title>
30       
31           <section>
32         <title>7 September 2006</title>
33         <ul>
34           <li>KiSS modified the login procedure. It is now working again.</li>
35           <li>Generalized the startup scripts. They should now be insensitive to the specific libraries used. </li>
36         </ul>
37       </section>
38       <section>
39         <title>31 August 2006</title>
40         <ul>
41           <li>Added windows bat file for running the crawler under windows.
42               Very add-hoc, will be generalized. </li>
43         </ul>
44       </section>
45       <section>
46         <title>24 August 2006</title>
47         <ul>
48           <li>The crawler now uses desktop login for crawling. Also, it is much more efficient since
49           it no longer needs to crawl the individual programs. This is because the channel page
50             includes descriptions of programs in javascript popups which can be used by the crawler.
51           The result is a significant reduction of the load on the KiSS EPG site. Also, the delay
52             between requests has been increased to further reduce load on the KiSS EPG site. </li>
53           <li>
54             The crawler now crawls programs for tomorrow instead of for today.
55           </li>
56           <li>
57             The web based crawler is configured to run only between 7pm and 12pm. It used to run at
58             5am. 
59           </li>
60         </ul>
61       </section>
62       
63       <section>
64         <title>13-20 August 2006</title>
65         <p>
66           There were several changes to the login procedure, requiring modifications to the crawler.
67         </p>
68         <ul>
69           <li>The crawler now uses the 'Referer' header field correctly at login.</li>
70           <li>KiSS now uses hidden form fields in their login process which are now also handled correctly by the
71               crawler.</li>
72         </ul>
73       </section>
74     </section>
75     <section id="overview">
76       <title>Overview</title>
77    
78       <p>
79         In 2005,  <a href="site:links/kiss">KiSS</a> introduced the ability
80         to schedule recordings on KiSS hard disk recorder (such as the 
81         DP-558) through a web site on the internet. When a new recording is
82         scheduled through the web site, the KiSS recorder finds out about 
83         this new recording by polling a server on the internet. 
84         This is a really cool feature since it basically allows programming
85         the recorder when away from home. 
86       </p>
87       <p>
88         After using this feature for some time now, I started noticing regular
89         patterns. Often you are looking for the same programs and for certain
90         types of programs. So, wouldn't it be nice to have a program 
91         do this work for you and automatically record programs and notify you
92         of possibly interesting ones?
93       </p>
94       <p>
95         This is where the KiSS crawler comes in. This is a simple crawler which 
96         logs on to the KiSS electronic programme guide web site and gets
97         programme information from there. Then based on that it automatically
98         records programs for you or sends notifications about interesting ones.
99       </p>
100       <p>
101         In its current version, the crawler can be used in two ways:  
102       </p>
103       <ul>
104         <li><strong>standalone program</strong>: A standalone program run as a scheduled task.</li>
105         <li><strong>web application</strong>: A web application running on a java
106           application server. With this type of use, the crawler also features an automatic retry
107           mechanism in case of failures, as well as a simple web interface. </li>
108       </ul>
109     </section>
110     
111     <section>
112       <title>Downloading</title>
113       
114       <p>
115         At this moment, no formal releases have been made and only the latest
116         version can be downloaded. 
117       </p>
118       <p>
119         The easy way to start is the 
120         <a href="installs/crawler/target/wamblee-crawler-0.2-SNAPSHOT-kissbin.zip">standalone program binary version</a>
121         or using the <a href="installs/crawler/kissweb/target/wamblee-crawler-kissweb.war">web
122           application</a>.
123       </p>
124       <p>
125         The latest source can be obtained from subversion with the 
126         URL <code>https://wamblee.org/svn/public/utils</code>. The subversion 
127         repository allows read-only access to anyone. 
128       </p>
129       <p>
130         The application was developed and tested on SuSE linux 9.1 with JBoss 4.0.2 application
131         server (only required for the web application). It requires at least a Java Virtual Machine
132         1.5 or greater to run. 
133       </p>
134     </section>
135     
136     <section>
137       <title>Configuring the crawler</title>
138       
139       <p>
140         The crawler comes with three configuration files:
141       </p>
142       <ul>
143         <li><code>crawler.xml</code>: basic crawler configuration
144           tailored to the KiSS electronic programme guide.</li>
145         <li><code>programs.xml</code>: containing a description of which 
146           programs must be recorded and which programs are interesting.</li>
147         <li><code>org.wamblee.crawler.properties</code>: Containing a configuration  </li>
148       </ul>
149       <p>
150         For the standalone program, all configuration files are in the <code>conf</code> directory.
151         For the web application, the properties files is located in the <code>WEB-INF/classes</code>
152         directory of the web application, and <code>crawler.xml</code> and <code>programs.xml</code>
153         are located outside of the web application at a location configured in the properties file. 
154       </p>
155    
156       
157       <section>
158         <title>Crawler configuration <code>crawler.xml</code></title>
159         
160         <p>
161           First of all, copy the <code>config.xml.example</code> file 
162           to <code>config.xml</code>. After that, edit the first entry of 
163           that file and replace <code>user</code> and <code>passwd</code>
164           with your personal user id and password for the KiSS Electronic
165           Programme Guide. 
166         </p>
167       </section>
168
169         <section>
170           <title>Program configuration</title>
171           <p>
172             Interesting TV shows are described using <code>program</code>
173             elements. Each <code>program</code> element contains 
174             one or more <code>match</code> elements that describe 
175             a condition that the interesting program must match. 
176           </p>
177           <p>
178             Matching can be done on the following properties of a program:
179           </p>
180           <table>
181             <tr><th>Field name</th>
182             <th>Description</th></tr>
183             <tr>
184               <td>name</td>
185               <td>Program name</td>
186             </tr>
187             <tr>
188               <td>description</td>
189               <td>Program description</td>
190             </tr>
191             <tr>
192               <td>channel</td>
193               <td>Channel name</td>
194             </tr>
195             <tr>
196               <td>keywords</td>
197               <td>Keywords/classification of the program.</td>
198             </tr>
199           </table>
200           <p>
201             The field to match is specified using the <code>field</code>
202             attribute of the <code>match</code> element. If no field name 
203             is specified then the program name is matched. Matching is done
204             by converting the field value to lowercase and then doing a 
205             perl-like regular expression match of the provided value. As a
206             result, the content of the match element should be specified in 
207             lower case otherwise the pattern will never match.
208             If multiple <code>match</code> elements are specified for a 
209             given <code>program</code> element, then all matches must 
210             apply for a program to be interesting. 
211           </p>
212           <p>
213             Example patterns:
214           </p>
215           <table>
216             <tr>
217               <th>Pattern</th>
218               <th>Example of matching field values</th>
219             </tr>
220             <tr>
221               <td>the.*x.*files</td>
222               <td>"The X files", "The X-Files: the making of"</td>
223             </tr>
224             <tr>
225               <td>star trek</td>
226               <td>"Star Trek Voyager", "Star Trek: The next generation"</td>
227             </tr>
228           </table>
229           
230           <p>
231             It is possible that different programs cannot be recorded 
232             since they overlap. To deal with such conflicts, it is possible
233             to specify a priority using the <code>priority</code> element. 
234             Higher values of the priority value mean a higher priority. 
235             If two programs have the same priority, then it is (more or less)
236             unspecified which of the two will be recorded, but it will at least
237             record one program. If no priority is specified, then the
238             priority is 1 (one).
239           </p>
240           
241           <p>
242             Since it is not always desirable to try to record every
243             program that matches the criteria, it is also possible to 
244             generate notifications for interesting programs only without
245             recording them. This is done by specifying the 
246             <code>action</code> alement with the content <code>notify</code>.
247             By default, the <code>action</code> is <code>record</code>. 
248             To make the mail reports more readable it is possible to 
249             also assign a category to a program for grouping interesting
250             programs. This can be done using the <code>category</code>
251             element. Note that if the <code>action</code> is 
252             <code>notify</code>. then the <code>priority</code> element
253             is not used. 
254           </p>
255           
256         </section>
257       
258       <section>
259         <title>Notification configuration</title>
260         <p>
261            Edit the configuration file <code>org.wamblee.crawler.properties</code>. 
262           The properties file is self-explanatory. 
263         </p>
264       </section>
265     </section>
266     
267    
268     
269     
270     <section>
271       <title>Installing and running the crawler</title>
272       
273       <section>
274         <title>Standalone application</title>
275         <p>
276           In the binary distribution, execute the 
277           <code>run</code> script for your operating system
278           (<code>run.bat</code> for windows, and 
279           <code>run.sh</code> for unix). 
280         </p>
281       </section>
282       
283       <section>
284         <title>Web application</title>
285         <p>
286           After deploying the web application, navigate to the 
287           application in your browser (e.g. 
288           <code>http://localhost:8080/wamblee-crawler-kissweb</code>).
289           The screen should show an overview of the last time it ran (if
290           it ran before) as well as a button to run the crawler immediately.
291           Also, the result of the last run can be viewed.
292           The crawler will run automatically every morning at 5 AM local time, 
293           and will retry at 1 hour intervals in case of failure to retrieve
294           programme information. 
295         </p>
296       </section>
297       
298       <section>
299         <title>Source distribution</title>
300         <p>
301           With the source code, build everything with 
302           <code>ant dist-lite</code>, then locate the binary
303           distribution in <code>lib/wamblee/crawler/kiss/kiss-crawler-bin.zip</code>.
304           Then proceed as for the binary distribution. 
305         </p>
306       </section>
307       
308       <section>
309         <title>General usage</title>
310         <p>
311           When the crawler runs, it 
312           retrieves the programs for tomorrow. As a result, it is advisable 
313           to run the program at an early point of the day as a scheduled
314           task (e.g. cron on unix). For the web application this is 
315           preconfigured at 5AM. 
316         </p>
317         <note>
318           If you deploy the web application today, it will run automatically
319           on the next (!) day. This even holds if you deploy the application
320           before the normal scheduled time.  
321         </note>
322         
323         <p>
324           Modifying the program to allow it to investigate tomorrow's
325           programs instead is easy as well but not yet implemented. 
326         </p>
327       </section>
328       
329       
330     </section>
331
332     <section id="examples">
333       <title>Examples</title>
334     
335       <p>
336         The best example is in the distribution itself. It is my personal
337         <code>programs.xml</code> file.
338       </p>
339     </section>
340     
341     <section>
342       <title>Contributing</title>
343       
344       <p>
345         You are always welcome to contribute. If you find a problem just 
346         tell me about it and if you have ideas am I always interested to 
347         hear about them. 
348       </p>
349       <p>
350         If you are a programmer and have a fix for a bug, just send me a
351         patch and if you are fanatic enough and have ideas, I can also 
352         give you write access to the repository. 
353       </p>
354     </section>
355     
356     
357   </body>
358 </document>