Quickstart
Per impiegare il parser di feed4j all'interno del tuo software Java devi, come prima cosa, rendere visibile il file feed4j.jar alla tua applicazione, aggiungendolo al CLASSPATH. Siccome feed4j dipende da librerie di terze parti, i cui jar si trovano nella cartella lib del pacchetto di ditribuzione, anche queste devono essere aggiunte al CLASSPATH.
Il parser dei feed
L'uso del parser dei feed (it.sauronsoftware.feed4j.FeedParser) richiede una sola riga di codice:
Feed feedRepresentation = FeedParser.parse(feedUrl);
Dopo aver recuperato la rappresentazione ad oggetti del feed (it.sauronsoftware.feed4j.bean.Feed) puoi attivarne i metodi per sapere qualsiasi cosa contenuta nell'XML elaborato. La rappresentazione del feed è divisa in due parti principali: una intestazione del feed (header) ed una collezione di notizie (item). L'header fornisce accesso ad informazioni che riguardano il feed nella sua completezza, come il titolo, la descrizione, l'indirizzo di origine e così via. I singoli item rappresentano ciascuno una delle notizie riportate nel feed. Principalmente sono formati da un titolo e da un indirizzo, ma possono anche contenere descrizioni in testo semplice e in HTML, date di pubblicazione e modifica, allegati ed altro ancora.
La rappresentazione ad oggetti di un feed può essere padroneggiata in pochi minuti, basta tenere a portata di mano i relativi javadoc, compresi nel pacchetto di distribuzione di feed4j.
Un esempio veloce e completo:
package it.sauronsoftware.feed4j.example1;
import java.net.URL;
import it.sauronsoftware.feed4j.FeedParser;
import it.sauronsoftware.feed4j.bean.Feed;
import it.sauronsoftware.feed4j.bean.FeedHeader;
import it.sauronsoftware.feed4j.bean.FeedItem;
public class FeedExample {
public static void main(String[] args) throws Exception {
URL url = new URL("http://www.scarletgothica.com/rss_it.php");
Feed feed = FeedParser.parse(url);
System.out.println("** HEADER **");
FeedHeader header = feed.getHeader();
System.out.println("Title: " + header.getTitle());
System.out.println("Link: " + header.getLink());
System.out.println("Description: " + header.getDescription());
System.out.println("Language: " + header.getLanguage());
System.out.println("PubDate: " + header.getPubDate());
System.out.println("** ITEMS **");
int items = feed.getItemCount();
for (int i = 0; i < items; i++) {
FeedItem item = feed.getItem(i);
System.out.println("Title: " + item.getTitle());
System.out.println("Link: " + item.getLink());
System.out.println("Plain text description: " + item.getDescriptionAsText());
System.out.println("HTML description: " + item.getDescriptionAsHTML());
System.out.println("PubDate: " + item.getPubDate());
}
}
}
Un esempio un po' più complesso è nella cartella examples/example2 del pacchetto di distribuzione della libreria.
Intercettare le eccezioni
Il metodo FeedParser.parse() può lanciare diversi tipi di eccezione, in base al problema riscontrato:
- FeedIOException: il feed non può essere recuperato a causa di un problema I/O.
- FeedXMLParseException: il file è stato recuperato, ma il suo contenuto non è un XML valido.
- UnsupportedFeedException: il file è stato recuperato, il suo contenuto è risultato essere un XML valido, ma la struttura al suo interno non rispecchia nessuno dei formati di feed supportati da feed4j.
Poiché queste eccezioni estendono tutte la classe FeedException, puoi decidere se gestirle una per una o tutte insieme con un solo blocco catch:
Feed feed;
try {
feed = FeedParser.parse(feedUrl);
} catch (FeedIOException e) {
// una
} catch (FeedXMLParseException e) {
// per
} catch (UnsupportedFeedException e) {
// una
}
try {
feed = FeedParser.parse(feedUrl);
} catch (FeedException e) {
// tutte insieme
}
Formati di feed supportati
Il parser di feed4j può attualmente interpretare i seguenti formati di feed basati su XML:
- RSS 1.0 con supporto per i tag Dublin Core
- RSS 2.0
- RSS 0.91 e 0.92, poiché un feed RSS 0.91 o 0.92 valido è anche un feed RSS 2.0 valido
- Atom 0.3
- Atom 1.0 (IETF standard)
Gestire i tag personalizzati
I feed basati su XML sono flessibili e possono essere estesi con tag personalizzati o di terze parti. Il parser di feed4j ti aiuta nel gestire questi tag dandoti accesso diretto e non strutturato (raw) al loro contenuto. Ad esempio: se gli item presenti nel tuo feed XML contengono un tag di estensione chiamato "phone-number", il cui namespace è "http://www.mysite.org/myCustomTags", puoi accedere al valore al seguente modo:
String value = feedItem.getElementValue( "http://www.mysite.org/myCustomTags", "phone-number" );
Nel pacchetto it.sauronsoftware.feed4j.bean c'è la classe RawElement, che è un contenitore di informazioni raw. FeedHeader, FeedItem, FeedImage e FeedEnclosure estendono RawElement, cosicché oltre a contenere informazioni strutturate come i titoli, le date, gli indirizzi e le descrizioni, possono anche riportare in modo raw tutte le informazioni non direttamente gestite dal parser. Quindi per ottenere un'informazione standard potrai usare i metodi tipizzati e strutturati come getTitle(), getLink() e getPubDate(), mentre tutti gli elementi di estensione non noti a feed4j possono essere recuperati e gestiti con metodi quali getElement(), getAttribute() e getNode(). Fai riferimento alla documentazione javadoc per una lista dettagliata dei metodi disponibili.