Configurare IFile

Questa è la parte più importante per l’utilizzo corretto della libreria. Una configurazione errata potrebbe provocarvi problemi nel processo di indicizzazione. Pertanto questo è il capito più importante e andrebbe letto con molta attenzione.

La configurazione di IFile viene fatta mediante l’utilizzo di un file XML IFileConfig.xml presente nella cartella /config  validato da un XSD IFileConfig.xsd che si trova nella stessa cartella.

Il file XML è così strutturato:

<ifile>
    <root-application>...</root-application>
    <table-name collation="…">...</table-name>
    <timelimit>...</timelimit>
    <memorylimit>...</memorylimit>
    <duplicate>...</duplicate>
    <encoding>...</encoding>
    <doctotxt encoding="…" type="…" />
    <server bit="..." />
	<xpdf>
		<opw>...</opw>
		<pdftotext>
			<executable>...</executable>
			<xpdfrc>...</xpdfrc>
		</pdftotext>				
		<pdfinfo>
			<executable>...</executable>
			<xpdfrc>...</xpdfrc>
		</pdfinfo>				
	</xpdf>    
	<zend-document> 
          <fields> 
              <field name="…" type="…" encoding="…" />
              ... 
          </fields> 
    </zend-document>
    <analyzer>
         <type>
             <default>...</default>
             <custom-default class=”...”>...</custom-default>        
         </type>
         <filters>
             <stop-words>...</stop-words>
             <short-words>...</short-words>
             <custom-filters>
                <filter>...</filter>
                <filter>...</filter>
                ...
             </custom-filters>
         </filters>
    </analyzer>
</ifile>


Di seguito verranno descritti tutti gli elementi del file di configurazione. Ogni elemento viene definito con la seguente sintassi:

<nomeTag> [obbligatorio|facoltativo] {occorrenze}

Ifile [obbligatorio] {1}

Il tag <ifile> è il  tag di root  del file XML il quale all’interno presenta sei sezioni:

 

root-application [obbligatorio] {1}

Il tag <root-application>  definisce il path della root dell’applicazione. Questo è molto utile da utilizzare in caso si debba spostare l'applicazione in ambienti diversi, permettendo così di avere path relativi dei file indicizzati.  
Il sistema verifica che il path inserito esista e sia corretto nell’ambiente in cui si sta eseguendo il processo di indicizzazione,  altrimenti viene invoca una eccezione di root inesistente.
Va ricordato che non va inserito l’ultimo separatore di delimitazione.

Esempio 1:
<root-application>/var/www/html/app</root-application>

Se si è configurata la root con il path sopra indicato ed il file si trova nella directory /var/www/html/app/filePdf/mypdf.pdf, IFile indicizzerà i seguenti field (per maggiori dettagli vedi capitolo:Fields e custom fields):
Esempio 2:
<root-application>/var/www/html/newapp</root-application>

Se si è configurata la root con il path sopra indicato (diverso dal path in cui realmente si trova l’applicazione) ed il file si trova nella directory /var/www/html/app/filePdf/mypdf.pdf, IFile indicizzerà i seguenti field:
In questo caso il percorso del file (field:path) viene salvato come path assoluto e non relativo al path dell’applicazione.

table-name [opzionale] {1}

Il tag <table-name>  definisce il nome della tebella se viene utilizzata l’interfaccia di Mysqli per l’indicizzazione dei documenti.

Utilizzando l’interfaccia MYSQL non e’ necessario configurare il TAG dato che la gestione e configurazione del processo di indicizzazione andrà effettuata direttamente su MySql.

Il sistema verifica l’esistenza della tabella, e se questa non esiste viene creata automaticamente on le caratteristiche di charset del Data Base. 

Esempio:
<table-name>myTableInDB</table-name>

Il tag presenta l’attributo “collation” per la definizione della collation della Tabella.
La collation definita, deve far parte della lista delle collation installate sul server MySql (SHOW COLLATION) e appartenente al charsert utilizzato, vedi tag <encoding>.

timelimit [opzionale] {1}

Il tag <tilmelimit>  definisce il tempo massimo di esecuzione del processo di  indicizzazione  del singolo documento.
Il tag accetta solo valori interi positivi.
Se non valorizzato, il time-limit è quello configurato nel php.ini.
Il valore minimo inseribile è di 180 secondi.

Esempio:
<timelimit>360</timelimit>

memorylimit [opzionale] {1}

Il tag <memorylimit>  definisce  la memoria massima che lo script può allocare durante l’esecuzione del processo di indicizzazione del singolo documento.
Il tag accetta solo valori interi positivi.
Se non valorizzato, il memory-limit è quello configurato nel php.ini.

Esempio:
<memorylimit>128</memorylimit>

duplicate [opzionale] {1}

Il tag <duplicate> definisce la possibilità di avere documenti duplicati all'interno dell'indice.
Se settato a zero (0) o non presente, il sistema verifica che il contenuto del documento da indicizzare non sia già presente nell'indice. Se presente invoca una eccezione.
Altrimenti se settato a uno (1) il sistema non verifica l'esistenza del documento all'interno dell'indice.
La verifica viene fatta sul contenuto del documento.
Parametri permessi:


Esempio:
<duplicate>1</duplicate>

encoding  [opzionale] {1}

Il tag <encoding> definisce il tipo di "charset encoding" in cui è stato scritto il documento.  Di fatto la combinazione di questo tag con il tipo di Analyzer (descritto più avanti)definiscono il processo di conversione dei dati per una corretta indicizzazione. Ad oggi il “charset encoding” definito in fase di configurazione viene utilizzato non solo per l’indicizzazione del contenuto del documento ma per tutti  i campi da indicizzare.
Se non valorizzato il sistema cerca di recuperare autonomamente il tipo di encoding di ogni campo.
I tipi di charset configurabili sono:


Il tipo di encoding è mappatto nel seguente modo per l’interfaccia MySqli:

ascii: ASCII
latin1: ISO-8859-1 ISO-8859-15 Windows-1252
latin2: ISO-8859-2
latin7: ISO-8859-7
cp1256: CP1256
utf8: UTF-8

E' possibile estendere i charset andando a definire nel file XSD altri tipi.

Un tipo di encoding errato potrebbe provocare una indicizzazione incompleta o non corretta dei campi da indicizzare.

Va fatta molta attenzione al tipo di encoding che viene settato in funzione del tipo di Analyzer utilizzato.
Per le esperienze avute, in caso non si abbia una vera conoscenza del tipo di encoding del documento (ovvero nella maggior parte dei casi), conviene non configurare il tag.
Di fatto nel caso si utilizzi un Analyzer di tipo UTF-8 e si hanno file codificati in UTF-8 non andrebbe configurato l’encoding dato che le librerie di Zend Lucene tenterebbero di forzare  la codifica e pertanto si potrebbe avere, soprattutto per caratteri speciali (con un numero di byte maggiore di uno), una alterazione dei caratteri.

In altri casi il processo di tokenizzazione dei termini potrebbe non andare a buon fine e ritornare un insieme vuoto, pertanto se il sistema presenta una eccezione che il contenuto del documento non è stato tokenizzato verificate anche l’encoding utilizzato.

La chiamata alla funzione "iconv" per la trasformazione del testo nel corretto encoding, da parte degli analyzer della libreria ZEND, potrebbe provocare un NOTICE di carattere illegale. Questo tronca il contenuto al carattere illegale e pertanto il documento viene indicizzato in modo parzile.

Esempio:
<encoding>UTF-8</encoding>

doctotxt [opzionale] {1}

Il tag <doctotxt> è un tag vuoto e definisce il tipo, e l’encoding per il recupero del contenuto da file Microsoft Word.
Se non valorizzato il sistema definisce automaticamente dei parametri di default:
type = PHP
encoding = ""

Attributo Descrizione Necessità
type Tipo di parser:
  • ANTIWORD
  • COM
  • PHP
Non è possibile definire altri tipi.
Obbligatorio
encoding Il tipo di encoding da utilizzare per il contenuto del documento è utilizzato solo per il type “ANTIWORD” ed equivale al nome senza estensione dei file .txt presenti nella cartella:

adapter/helpers/binaries/resources/
Opzionale

Esempio:
<doctotxt encoding="ANTIWORD" type="UTF-8" />


server [opzionale] {1}

Il tag <server> è un tag vuoto e definisce il tipo di server su cui gira IFile.
Se non valorizzato il sistema definisce automaticamente dei parametri di default.


zend-document [opzionale] {1}

Il tag <zend-document> è il tag permete una configurazione manuale della Zend_Search_Lucene_Document .
Se non valorizzato il sistema definisce automaticamente dei parametri di default.

Il tag contiene due sezioni:


fields [opzionale] {1}

Il tag <fields> è il contenitore per la configurazione dei Field (campi) utilizzati da IFile, per l’indicizzazione (vedi capitolo: Fields e custom fields).

Il tag contiene una sezione:

field [obbligatorio] {n}

Il tag <field> è un tag vuoto e definisce il tipo, il nome e l’encoding del field.

Attributo Descrizione Necessità
name Nome del field (campo):
  • name
  • extensionfile
  • path
  • filename
  • introtext
  • body
  • title
  • subject
  • description
  • creator
  • keywords
  • created
  • modified
Non è possibile definire altri nomi.
Obbligatorio
type Definizione del tipo di indicizzazione :
  • Keyword
  • UnIndexed
  • Binary
  • Text
  • UnStored
Obbligatorio
encoding Il tipo di encoding da utilizzare per il contenuto del field :
  • UTF-8
  • ASCII
  • ISO8859-1
  • ISO8859-15
  • CP1256
  • Windows-1252
Obbligatorio

Per maggiori dettagli sui tipi di indicizazione si demanda al sito della Zend Framework:

http://framework.zend.com/manual/en/zend.search.lucene.overview.html

analyzer  [opzionale] {1}

Il tag <analyzer> è il tag per la gestione del tipo di analizzatore del testo da indicizzare.

Il tipo di analyzer serve per la gestione dei documenti sia in fase di indicizzazione che in fase di ricerca solo se viene utilizzata l’interfaccia LUCENE. Il TAG risulta inutile se si utilizza una interfaccia diversa per l’indicizzaione, peranto si può anche non configurarlo. Se si configura un tipo di analyzer per indicizzare un documento e se ne configura un altro per la ricerca, i risultati potrebbero essere diversi da quelli attesi. Di fatto un analyzer dovrebbe essere sempre lo stesso per l’indice.

Se non valorizzato il sistema definisce automaticamente come analyzer:
Utf8_CaseInsensitive (vedi tag type/default)
Il tag contiene due sezioni:


type  [opzionale] {1}

Il tag <type> definisce il tipo di analizzatore del testo da indicizzare.  
Se non valorizzato il sistema definisce automaticamente come analyzer:
Utf8_CaseInsensitive (vedi tag default)
Il tag contiene due sezioni:


Le due sezioni sono alternative ed esclusive, ovvero una esclude l’altra.

default [a scelta] {1}

Il tag <default> definisce il tipo di analizzatore del testo da indicizzare gestiti dalla libreria Zend_Search_lucene.  

I tipi di analizzatori sono:


Per maggiori dettagli sul tipo di analyzer più appropriato alle proprie esigenze si demanda al sito della Zend Framework:

http://framework.zend.com/manual/en/zend.search.lucene.extending.html
Il tag è alternativo con il tag custom-default.
Esempio:
<default>Utf8Num</default>

custom-default [a scelta] {1}

Il tag <custom-default> definisce un tipo di analizzatore del testo personalizzato.
Ovvero è possibile definire delle proprie classi per analizzare e tokenizzare  il testo . Il tag necessita del path assoluto ove risiede lo script PHP contenente la classe definita nell’attributo "class".

Attributo Descrizione Necessità
Class Nome della classe da richiamare che estende la Zend_Search_Lucene_Analysis_Analyzer Obbligatorio

Il tag è alternativo con il tag default.
Un esempio di analizzatore personalizzato è presente al sito:
http://code.google.com/p/lucene-silverstripe-plugin/

Esempio:
<custom-default
class="StandardAnalyzer_Analyzer_Standard_English"> /var/www/html/app/analyzer/StandardAnalyzer/Analyzer/Standard/English.php 
</custom-default>

filters  [opzionale] {1}
Il tag <filters> è il tag per la gestione del processo di tokenizzazione definendo i filtri sui termini tokenizzati. 

I filtri servono per la gestione dei documenti sia in fase di indicizzazione che in fase di ricerca. Se si configurano dei filtri per indicizzare un documento e se ne configurano altri per la ricerca, i risultati potrebbero essere diversi da quelli attesi. Di fatto i filtri dovrebbero essere sempre gli stessi per l’indice.

E’ possibile non definire nessun tipo di filtro.
Il tag contiene tre sezioni:

stop-words [opzionale] {1}

Il tag <stop-words> definisce il file per l’eliminazione delle parole (termini tokenizzati) all’interno del testo da indicizzare.
Il tag richiede il path assoluto del file delle stop-words.
Il file deve contenere tutte le parole separate da un ritorno a capo.

Esempio:
<stop-words>/var/www/html/app/mystopwords.txt</stop-words>

short-words [opzionale] {1}

Il tag <short-words> definisce il limite minimo di caratteri del singolo termine. Pertanto settando un limite minimo di 3 caratteri per termine, il sistema non indicizzerà e non considererà nei processi di ricerca tutte quelle parole di due caratteri (come ad esempio: io, tu, li, il, …).
Il sistema permette di definire un limite minimo che va da 2 (due)  a 4 (quattro) caratteri.

E' possibile estendere il limite andando a definire nuovi limiti minimi nel file XSD.

Esempio:
<short-words>3</short-words>

custom-fields [opzionale] {1}
Il tag <custom-filter> definisce la gestione di eventuali filtri personalizzati.
E' permesso integrare più di un filtro.

Il tag contiene una sezione:

filter [opzionale] {n}

Il tag <filter> permette di configurare eventuali filtri sui termini.

Ovvero è possibile definire delle proprie classi per tokenizzare  il testo . Il tag necessita del path assoluto ove risiede lo script PHP contenente la classe definita nell’attributo "class".


Attributo Descrizione Necessità
Class Nome della classe da richiamare che estende la Zend_Search_Lucene_Analysis_TokenFilter Obbligatorio

Un esempio di analizzatore personalizzato è presente al sito:
http://code.google.com/p/lucene-silverstripe-plugin/

Esempio:
<filter class="StandardAnalyzer_Analysis_TokenFilter_EnglishStemmer">/var/www/html/app/analyzer/StandardAnalyzer/Analyzer/TokenFilter/EnglishStemmer.php</custom-default>