42. URLchecker

Auteur Marc Jeurissen
Oud BVV nr 2125

42.1. Abstract

In een aantal Brocade-applicaties worden URL’s genoteerd, zo bevat de catalografische module eind 2006 een 30.000-tal links. Dit stelt een groot probleem naar onderhoud. Het is immers niet mogelijk de URL’s op regelmatige tijdstippen manueel te controleren op geldigheid. Dit document beschrijft de opzet en de werking van een URLchecker-software. Het hart van deze software is een toolcat-applicatie urlchecker die 3 onderscheiden acties kan uitvoeren:

  • verzamelen
  • checken
  • rapporteren

De URLchecker kan, zoals alle toolcat-applicaties, vanaf de commandolijn uitgevoerd worden, maar kan ook gestuurd worden vanuit de Brocade-interface via Brocade ‣ Catalografie - Beheersfuncties ‣ URL checker [link]. Alle software staat in het qtech-project /urlchecker/application.

42.2. Meta-informatie - Brocade interface

Het opstarten van de toolcat-applicatie URLchecker via de Brocade-interface, gebeurt door zogenaamde URLjobs. Elke URLjob omvat een eenmalige verzameling van URL’s, een eenmalige check van deze URL’s en een eenmalige rapportering. Een URLjob behoort tot een bepaalde URLset, die op haar beurt behoort tot een bepaalde URLcollectie.

42.2.1. URLcollectie

De URLcollectie omschrijft de collector (M-expressie) die moet uitgevoerd worden om een bepaalde groep van URL’s te verzamelen, evenals de namen en de verklaring van de variabelen die door deze collector moeten gekend zijn om deelverzamelingen (URLsets) van die URL’s te bekomen. Deze collector moet apart ontwikkeld worden. Op dit moment (december 2006) bestaat een collector voor URL’s in de catalografie).

Het commando urlchecker -collect spreekt de collector-motor %Collect^bucscoll aan, die op haar beurt de specifieke collector aanspreekt. Deze collector moet als generator telkens 1 waarde teruggeven, vertrekkend van de vorige waarde in variabele RDcolpos (initieel=””). De terug te geven waarde moet in variabele RDcolval geplaatst worden en moet bestaan uit volgende delen, gescheiden door ^:

  • op correcte manier geëncodeerde url
  • de context van de url (vb. c-loi)
  • eventueel het url-type waarvan de url afkomstig is

De collector-motor fungeert op haar beurt als generator voor urlchecker -collect en geeft lijnen terug zoals verder gespecificeerd.

42.2.2. URLset

Een URLset is een concrete invulling van een URLcollectie, met name de parameters voor de collector krijgen concrete waarden toebedeeld waarmee de collector een bepaalde deelverzameling van URL’s zal opleveren. Bovendien kunnen volgende meta-gegevens nog ingevuld worden:

maximum aantal URL’s
Het maximum aantal URL’s dat de collector mag opleveren.
aantal URL’s per set
In hoeveel sets moeten de URL’s onderverdeeld worden?
sleuteltest
Als deze optie is aangevinkt en de te verzamelen URL’s zijn opgebouwd vanuit url-types, dan kan bij de meta-informatie van het url-type gekeken worden of er een sleutelwaarde met sleuteltrefwoorden is ingevuld. In dat geval voegt de collector een extra URL toe met als context keytest urltype en als te checken inhoud de gevonden sleuteltrefwoorden. Bovendien kan aangegeven worden of bij een mislukking van de sleuteltest, volgende URL’s van dit urltype nog moeten gecheckt worden.
te negeren urltypes
Opsomming van urltypes die niet gecheckt en dus niet verzameld moeten worden.
te negeren domeinen
Opsomming van domeinnamen die niet gecheckt en dus niet verzameld moeten worden.

Het scherm bevat tevens een opsomming van de URLjobs die voor deze URLset werden uitgevoerd. De URLjobs kunnen van hieruit ook geschrapt worden.

42.2.3. URLjob

Een URLjob is een concrete, eenmalige, uitvoering van een URLset, met name de verzameling van URL’s, gevolgd door een eenmalige check en een rapportering. Een URLjob kan gekopieerd en geschrapt worden. De docman-paths in een URLjob worden 30 dagen bewaard.

Verzamelen

De URLjob neemt in eerste instantie de gegevens van de gekoppelde URLset over, maar deze kunnen nog aangepast worden.

Start verzameling URL’s start een Brocade-batch-job op die het commando urlchecker -collect URLjob-identifier activeert. De working directory voor deze job is registry.urlchecker_process_dir. Op het einde van die Brocade-job wordt de docman-path naar de xml-file met de verzamelde URL’s in de URLjob genoteerd. Van zodra een verzameljob is opgestart kan voor deze specifieke URLjob geen nieuwe verzameljob meer gestart worden. De status van de URLjob evolueert van Verzamelen URL’s is bezig naar URL’s zijn verzameld.

Checken

Deze actie kan enkel uitgevoerd worden indien er een docman-path naar een verzamelfile in de URLjob genoteerd staat. Het aantal te checken sets en een opsomming van de reeds gecheckte sets staan genoteerd in het check-blok.

Start URL check op server start een Brocade-batch-job op die het commando urlchecker -check URLjob-identifier set=n,n,.. activeert. Er kan gespecificeerd worden voor welke sets de job moet gestart worden (opsomming n,n,.. en/of range n-nn). Een blanco set-specificatie betekent dat alle sets moeten gecheckt worden. De working directory voor deze job is registry.urlchecker_process_dir. Op het einde van die Brocade-job wordt de docman-path naar de xml-file met de verzamelde URL’s in de URLjob genoteerd. Als een checkjob is afgelopen en nog niet alle sets zijn gecheckt, kan een nieuwe job gestart worden. Als de check compleet is, is een nieuwe checkjob niet meer mogelijk. De status van de URLjob evolueert van Checken URL’s op server nog niet volledig naar Niet alle sets zijn gecheckt of Alle sets zijn gecheckt.

Een tweede mogelijkheid is de URLcheck op een PC uitvoeren. In dat geval moet de verzamelfile van de URLjob via de docman-link naar de PC overgeheveld worden. Na uitvoering van de check kan de file met de resultaten via een manuele upload in de URLjob genoteerd worden. Het aantal gecheckte sets en de status van de URLjob worden automatisch uit de opgeladen file afgeleid. Zodra de file is opgeladen komt de status van de URLjob op Niet alle sets zijn gecheckt of Alle sets zijn gecheckt.

Rapporteren
Start rapportering start een Brocade-batch-job op die het commando urlchecker -report URLjob-identifier <URLcheck activeert. De working directory voor deze job is registry.urlchecker_process_dir. Een reportjob kan opgestart worden zolang niet alle sets gecheckt en gerapporteerd zijn. De status van de URLjob evolueert van Aanmaak rapport is bezig naar Rapporten zijn aangemaakt maar check nog niet compleet of Alle rapporten zijn aangemaakt, job is afgewerkt.

42.3. Toolcat-applicatie urlchecker

42.3.1. URL’s verzamelen

  • Commando

    urlchecker -collect tekstfile | brocade URLset-identifier | brocade URLjob-identifier [xmlfile=path resultfile] [user=user]
    
  • Verklaring

    Het eerste en enige argument beschrijft de bron van de te verzamelen URL’s. Dit kan zijn:

    • een tekstfile met een lijn per lijn opsomming van te checken URL’s. Dit is de enige mogelijkheid om URL’s te verzamelen op een server of werkstation die geen Brocade-databank aan boord heeft.
    • een identifier van een URLset. Kan enkel op een server waarop een Brocade-databank draait. In dit geval wordt automatisch een bij de URLset horende URLjob gemaakt in Brocade.
    • een identifier van een URLjob. Kan enkel op een server waarop een Brocade-databank draait. In dit geval worden de gegevens van die URLjob in Brocade opgevraagd.

    Mogelijke modifiers zijn:

    xmlfile

    Dit is de path van de targetfile, een xml-file met de verzamelde URL’s. Deze modifier is verplicht indien de bron een tekstfile is. In de andere gevallen wordt de targetfile default weggeschreven in registry.urlchecker_process_dir/URLjob-identifier.xml.

    user

    Enkel van toepassing indien de bron een URLset-identifier is. Zoals al vermeld wordt dan een nieuwe URLjob aangemaakt met deze user als aanmaker. Default is usystem de aanmaker.

  • Werking

    De aangesproken bron moet lijnen teruggeven met volgende delen, gescheiden door ^:

    • op correcte manier geëncodeerde url
    • de context van de url (vb. c-loi)
    • 1 | 0 = moet body overgehaald worden of enkel headers. Default = 1
    • trefwoorden, gescheiden door ;, die moeten voorkomen in de body van deze url
    • trefwoorden, gescheiden door ;, die niet mogen voorkomen in de body van deze url
    • het url-type waarvan de url afkomstig is

    Deze gegevens worden samengevoegd in een xml-structuur volgens de urlchecker-dtd. Indien de bron een tekstfile is worden alle URL’s in 1 set geplaatst, anders worden sets gemaakt zoals opgegeven in de URLset of URLjob. Indien de bron een URLset of URLjob is wordt de aangemaakte xml-file extra gestockeerd in docman en de docman-path wordt in Brocade bij de URLjob weggeschreven. De path van de nieuwe xml-file wordt uitgeprint op stdout.

    Voorbeelden:

    urlchecker -collect 1234
    urlchecker -collect catua user=mjeuris
    urlchecker -collect /library/tmp/urls.txt xmlfile=/library/tmp/urls.xml
    

42.3.2. URL’s checken

  • Commando

    urlchecker -check xmlfile | brocade URLjob-identifier [set=setnr,setnr,..] [reset=y|n] [status=y|n] [proxy=proxy-server[:][port][:user:password]]
    
  • Verklaring

    Het eerste en enige argument beschrijft de bron van de te checken URL’s. Dit kan zijn:

    • een URLjob-identifier waarvan fase 1, het verzamelen van de URL’s, is afgelopen. Kan enkel op een server waarop een Brocade-databank draait.
    • een path naar een xml-file die het resultaat is van urlchecker -collect.
.. _URLcheckmodifier: Mogelijke modifiers zijn: set een opsomming, gescheiden door ``,``, van de sets die moeten gecheckt worden. Indien niet gespecificeerd worden alle nog niet gecheckte sets verwerkt. ``urlchecker -check`` houdt een statusfile bij met daarin o.a. de reeds afgewerkte sets. reset 1|0 = schrap de statusfile, m.a.w. alle sets worden opnieuw gemarkeerd als nog niet gecheckt status 1|0 = toon enkel statusinformatie, voer geen check uit proxy indien het http-verkeer via een proxy-server verloopt, dan moeten de gegevens hiervan in deze modifier gespecificeerd worden op de volgende manier:: proxy-server[:][port][:user:password]. Voorbeeld urlchecker -check 678 proxy=dummyserver::dummyuser:dummypw
  • Werking

    urlchecker -check werkt op de door urlchecker -collect afgeleverde xml-file. Indien dit laatste bestand werd aangemaakt op de server en men verkiest de checking uit te voeren op een PC, dan moet deze file vanzelfsprekend eerst naar een passende directory op de PC overgeheveld worden.

    De xml-file wordt overlopen en elke url wordt gecheckt volgens zijn opgegeven specificaties, dit is

    • al of niet body overhalen,
    • al of niet body controleren op keywords,
    • al of niet een bepaalde useragent imiteren.

    De checking gebeurt via pycurl, een python-layer op libcurl.

    Aan het resultaat van een urlcheck wordt een status toegekend afhankelijk van de HTTP Status Code:

    success

    een HTTP status code in de 200 reeks of 307 (Temporary Redirect) of 302 (Found)

    warning

    een HTTP status code in de 300 reeks, anders dan 307 of 302

    error

    een HTTP status code in de 400 reeks

    servererror

    een HTTP status code in de 500 reeks

    contenterror

    de check op zich was succesvol maar de inhoud bevat ofwel niet alle gevraagde trefwoorden ofwel staan er verboden trefwoorden in

    De resultaten worden samengevoegd in een xml-structuur volgens de urlreporter-dtd. Sets die via afzonderlijke commando’s gecheckt worden (via modifier set=) komen toch in dezelfde xml-structuur terecht; deze wordt met andere woorden aangevuld tot de check compleet is. Een statusfile houdt een en ander bij. De xml-structuur zelf komt terecht in een xml-file in dezelfde directory als de xml-sourcefile (default registry.urlchecker_process_dir). De naam van deze file is xml-sourcefile-basename[_incomplete]_report.xml.

    Indien de bron een URLjob is, wordt de aangemaakte xml-file extra gestockeerd in docman en de docman-path wordt in Brocade bij de URLjob weggeschreven. Indien de checking is uitgevoerd op een PC, dan kan de xml-file manueel in een URLjob ge-upload worden via de Brocade-interface. De path van de nieuwe xml-file wordt uitgeprint op stdout.

  • Uitvoering op PC

    Hiervoor dient op de PC in kwestie het pakket urlchecker uit het software-archief geïnstalleerd te worden. Dit is een self-extracting archive die zich standaard expandeert in c:\tmp\urlchecker, maar dit kan overschreven worden. 1 van de geëxpandeerde files is urlchecker.exe, dit is de volwaardige toolcat-applicatie urlchecker.

    Waarschuwing

    Indien het http-verkeer via een proxy-server verloopt, dan moet dit gespecificeerd worden in de proxy-modifier.

  • Voorbeelden:

    urlchecker -check 1234
    urlchecker -check 1234 status=y
    urlchecker -check /library/tmp/urls.xml
    urlchecker -check /library/tmp/urls.xml set=1,3
    

42.3.3. Rapporteren

  • Commando

    urlchecker -report xmlfile | brocade URLjob-identifier [keepfiles=y|n]
    
  • Verklaring

    Het eerste en enige argument beschrijft de bron van de te rapporteren URL’s. Dit kan zijn:

    • een URLjob-identifier waarvan (een deel van) fase 2, het checken van de URL’s, is afgelopen. Kan enkel op een server waarop een Brocade-databank draait.
    • een path naar een xml-file die het resultaat is van urlchecker -check

    Mogelijke modifiers zijn:

    keepfiles

    1|0 = indien alle sets gerapporteerd zijn en de bron een URLjob is wordt de resultaatfile opgeslagen in docman en worden default alle files in de werkdirectory geschrapt, tenzij keepfiles=1.

  • Werking

    Het resultaat van urlchecker -check is een xml-file die nu door urlchecker -report wordt omgezet in 1 of meerdere html-rapporten.

    Een html-rapport is onderverdeeld in maximaal 5 tabellen (1 per statuscode) met daarin per url statusinformatie, context en eventueel een url die eigenlijk in de plaats van de oorspronkelijke moet gebruikt worden. De tabellen zijn sorteerbaar per kolom.

    Er wordt 1 html-rapport gemaakt per gecontroleerde set, dit om de overzichtelijkheid te behouden. De rapporten komen terecht in dezelfde directory als de xml-sourcefile (default registry.urlchecker_process_dir). De naam van deze rapporten is xml-sourcefile-basename_report_set_setnr.html.

    Indien de bron een URLjob is, worden de aangemaakte html-files extra gestockeerd in docman en de docman-paths worden in Brocade bij de URLjob weggeschreven.

    De paths van de nieuwe html-files worden uitgeprint op stdout.

  • Voorbeelden:

    urlchecker -report 1234
    urlchecker -report 1235 keepfiles=y
    urlchecker -report /library/tmp/url_report.xml
    

42.4. Catalografie: Meta-informatie url type

URL checker maakt gebruik van meta-informatie ingegeven bij het URL type:

Urltype-test
Geef in het veld testwaarde een waarde op. Brocade neemt deze waarde en voegt die aan het URL-frame toe. Vervolgens test Brocade deze waarde en vergelijkt de uitkomst met de specifieke woorden of zinsdalen ingegeven in het veld Test op. Indien de test negatief is dan wordt voor dit URL type een content error gegeven. Deze test wordt uitgevoerd voor elk URL-type.
Url-test
Geef woorden of zinsdelen op die NIET op een pagina van dit urltype mogen voorkomen (bv. Record not found). Indien de woorden toch voorkomen, dan geeft de URLchecker een content error. Deze URL-test wordt uitgevoerd bij elke gevonden instance van het URL-type.

42.5. Samenvatting werkwijze

  • Het aanmaken van een URLcollectie is een taak voor de software-ontwikkelaars. Er moet immers een routine gemaakt worden die de gewenste URL’s verzamelt.

  • Een URLset kan ingevuld worden door iemand met kennis van bepaalde parameters die meestal in Brocade in meta-informatie zijn vastgelegd, bvb. lidmaatschappen, toegangssleutels enz.

  • Voor het uitvoeren van een URLjob is in principe geen kennis van de parameters vereist vermits ze overgenomen worden van de URLset. Ze kunnen evenwel nog overschreven worden.

    • Het verzamelen wordt opgestart op de server. De job loopt in de achtergrond. Door het scherm te refreshen of terug op te roepen kan men de status van de job opvolgen. Na afloop verschijnt de docman-url naar de file met de verzamelde URL’s.

    • Het checken kan gebeuren

      • op de server op dezelfde manier als het verzamelen
      • op een PC. Hiervoor moet de toolcat-applicatie urlchecker vanuit het software-archief op de pc geïnstalleerd zijn. De file met verzamelde URL’s moet via de docman-link op de pc geplaatst worden. Vervolgens wordt urlchecker -check uitgevoerd.
  • Het rapporteren gebeurt best op de server. Indien het checken op de pc gebeurd is moet de file met de resultaten opgeladen worden in de URLjob. De rapportering gebeurt in de achtergrond en kan gevolgd worden zoals beschreven bij het verzamelen. Na afloop verschijnen de docman-urls van de rapporten (1 per set).