13.10.1 Oggetti ContentHandler

Gli utenti si aspettano che la sotto classe ContentHandler supporti le loro applicazioni. I seguenti metodi vengono chiamati dal parser sugli appropriati eventi nei documenti in input:

setDocumentLocator( locator)

Chiamato dal parser per dare all'applicazione un indicatore di posizione per localizzare l'origine degli eventi del documento.

I parser SAX vengono fortemente richiesti (anche se non assolutamente richiesti) per sostituire un indicatore di posizione. Se un parser si comporta così, allora deve fornire un indicatore di posizione invocando questo metodo prima di invocare altri metodi nell'interfaccia del DocumentHandler.

L'indicatore di posizione permette all'applicazione di determinare la posizione finale di ogni evento relativo ad un documento, se il parser non riporta un errore. Tipicamente, le applicazioni useranno questa informazione per riportare i propri errori (come i caratteri che non corrispondono con le regole di applicazioni business). L'informazione restituita dall'indicatore di posizione probabilmente non è sufficiente per essere usata con un motore di ricerca.

Notare che l'indicatore di posizione restituirà le informazioni soltanto durante l'invocazione di eventi su questa interfaccia. L'applicazione non tenterà di usarlo un'altra volta.

startDocument( ): Riceve la notifica dell'inizio di un documento.
Il parser SAX invocherà questo metodo una volta sola, prima di ogni altro metodo in questa interfaccia o nel DTDHandler (con un'eccezione rappresentata da setDocumentLocator()).

endDocument( ): Riceve la notifica della fine di un documento.
Il parser SAX invocherà questo metodo una volta sola e sarà l'ultimo metodo invocato durante l'analisi. Il parser non invocherà questo metodo prima di avere finito di analizzare (per un errore irrecuperabile) o per aver raggiunto la fine dell'input.

startPrefixMapping( prefix, uri)

Inizia il campo d'azione di un prefisso URI della mappatura dello spazio dei nomi.

L'informazione da questo evento non è necessaria per la normale elaborazione dello spazio dei nomi: il lettore SAX XML rimpiazzerà automaticamente i prefissi per i nomi degli elementi e degli attributi quando la caratteristica feature_namespaces viene abilitata (predefinito).

Ci sono casi, comunque, quando le applicazioni hanno la necessità dell'uso di prefissi in dati carattere o nel valore degli attributi, dove non possono essere espansi automaticamente in modo sicuro; gli eventi startPrefixMapping() e endPrefixMapping() forniscono le informazioni per l'applicazione per espandere i prefissi in quegli stessi contesti, se necessario.

Notare che gli eventi startPrefixMapping() e endPrefixMapping() non vengono garantiti perché siano annidati in relazione agli altri: tutti gli eventi startPrefixMapping() e tutti gli eventi endPrefixMapping() avverranno dopo l'evento corrispondente endElement(), ma il loro ordine non è garantito.

endPrefixMapping( prefix): Termina il campo d'azione della mappatura del prefisso URI.
Vedere startPrefixMapping() per i dettagli. Questo evento avviene sempre dopo l'evento corrispondente endElement(), ma l'ordine degli eventi endPrefixMapping() non viene altrettanto garantito.

startElement( name, attrs): Segnali che indicano l'avvio di un elemento in una modalità che non tiene conto dello spazio dei nomi.
Il parametro name contiene il nome del tipo di elemento grezzo XML 1.0 come fosse una stringa e il parametro attrs mantiene un oggetto dell'interfaccia Attributes contenente gli attributi dell'elemento. L'oggetto passato come attrs può essere riusato dal parser; mantenere un riferimento ad esso non è un modo certo per mantenere una copia degli attributi. Per mantenere una copia degli attributi, usare il metodo copy() dell'oggetto attrs.

endElement( name): Segnali che indicano l'avvio di un elemento in una modalità che non tiene conto dello spazio dei nomi.
Il parametro name contiene il nome del tipo dell'elemento, come con l'evento startElement().

startElementNS( name, qname, attrs)

Segnali che indicano l'avvio di un elemento in una modalità che non tiene conto dello spazio dei nomi.

Il parametro name contiene il nome del tipo dell'elemento come se fosse una tupla (uri, nomelocale), il parametro qname contiene il nome grezzo XML 1.0 usato nel sorgente del documento ed il parametro attrs mantiene un'istanza dell'interfaccia AttributesNS che contiene gli attributi dell'elemento. Se nessuno spazio dei nomi viene associato con l'elemento, il componente uri del nome avrà il valore None. L'oggetto passato come attrs può essere riusato dal parser; mantenere un riferimento ad esso non è un modo certo per mantenere una copia degli attributi. Per mantenere una copia degli attributi, usate il metodo copy() dell'oggetto attrs.

I parser possono impostare il parametro qname a None, a meno che la funzionalità feature_namespace_prefixes sia attivata.

endElementNS( name, qname): Segnali che indicano l'avvio di un elemento in una modalità che non tiene conto dello spazio dei nomi.
Il parametro name contiene il nome del tipo dell'elemento, come con il metodo startElementNS(), alla stregua del parametro qname.

characters( content)

Riceve una notifica di dati carattere.

Il parser chiamerà questo metodo per riportare ogni spezzone di dati carattere. Il parser SAX può restituire tutti i dati carattere contigui in un singolo spezzone, o possono essere suddivisi in più pezzi; tuttavia, tutti i caratteri in ogni singolo evento devono provenire dalla medesima entità esterna, in questo modo il Locator fornisce informazioni utili.

content può essere una stringa Unicode o una stringa composta da byte; il modulo lettore expat produce sempre stringhe Unicode.

Note: La prima interfaccia SAX 1 fornita dal Python XML Special Interest Group usava, per questo metodo, molte interfacce simili a quelle di Java. Poiché la maggior parte dei parser usati da Python non traggono vantaggi dalla vecchia interfaccia, è stata scelta una forma più semplice per sostituirla. Per convertire il vecchio codice alla nuova interfaccia, usare content invece di affettare il contenuto con i vecchi parametri offset e length.

ignorableWhitespace( whitespace)

Riceve una notifica di uno spazio vuoto, ignorabile nell'elemento content.

I parser convalidanti devono usare questo metodo per riportare ogni spezzone di spazi vuoti ignorabili (vedere la raccomandazione W3C XML 1.0 sezione 2.10 ): anche i parser non convalidanti possono usare questo metodo se sono capaci di analizzare ed usano i modelli di contenuto.

Il parser SAX può restituire tutti i dati carattere contigui in un singolo spezzone, o possono essere suddivisi in più pezzi; tuttavia, tutti i caratteri in ogni singolo evento devono provenire dalla medesima entità esterna, in questo modo il Locator fornisce informazioni utili.

processingInstruction( target, data)

Riceve notifica di un'istruzione elaborata.

Il parser invocherà questo metodo una volta per tutte le istruzioni trovate: notare che queste istruzioni di elaborazione possono trovarsi prima o dopo l'elemento del documento principale.

Un parser SAX non dovrebbe mai riportare una dichiarazione XML (XML 1.0, sezione 2.8) o una dichiarazione di testo (XML 1.0, sezione 4.3.1) usando questo metodo.

skippedEntity( name): Riceve notifica di un'entità saltata.
Il Parser chiamerà questo metodo per ogni entità saltata. Processori che non validano possono saltare entità se non hanno visto le dichiarazioni (perché, per esempio, l'entità è stata dichiarata in un sotto insieme DTD esterno). Tutti i processori possono saltare delle entità in base al valore delle proprietà feature_external_ges e feature_external_pes.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.