com.syncthemall.diffbot.api

Class DiffbotAPI

java.lang.Object

com.syncthemall.diffbot.api.DiffbotAPI

All Implemented Interfaces:

Serializable

public class DiffbotAPI
extends Object
implements Serializable

This is the main class of the SDK and allows to call:

• The Article API to extract informations (title, images, main content etc...) from an article web page.
• The Frontpage API to extract the elements (articles, posts, etc...) from the home page of a website.
• The batch API allowing execute multiple Article or Frontpage requests at once.

This class is thread-safe and should be instantiated only once. If the batch API is used this class has to be instantiated only once as it store the list request to execute in a batch.

The underlying implementations for the HTTP client (Apache, GAE url fetch, JVM default) and the JSON parser (Gson or Jackson) can be chosen during construction DiffbotAPI(HttpTransport, JsonFactory, String).

For example to use Apache and Jackson:

 private static DiffbotAPI api;
 ...
 api = new DiffbotAPI(new ApacheHttpTransport(), new JacksonFactory(), "your dev token");
 

Note: google-http-client-jackson2 has to be in the classpath.

The Article API
Calling the API is as simple as :

 Article article = api
                .article(new ArticleRequest("http://www.cbs.com/shows/how_i_met_your_mother/barneys_blog/1000461/").withTags()
                                .withComments().withSummary());
 

The Frontpage API
Calling the API is as simple as :

 Frontpage frontpage = api.frontpage(new FrontpageRequest("http://theverge.com"));
 

The Batch API
The batch API allows to prepare multiple Article and/or Frontpage request and to send them all at once. The batch API:

• limits the number of API calls and reduces the network load, by avoiding http overhead for every request
• slightly improve the performances if a lot of requests are executed
• limits the usage of the Diffbot quota

To prepare requests to be executed in batch:

 Future<Article> fArticle = api
                .batch(new ArticleRequest("http://www.cbs.com/shows/how_i_met_your_mother/barneys_blog/1000461/").withTags()
                                .withComments().withSummary());
 Future<Frontpage> fFrontpage = api.batch(new FrontpageRequest("http://theverge.com"));
 

Note that this can be done by multiple thread. The DiffbotAPI class is fully thread-safe. At this point no call has been done to Diffbot. To obtain the results:

 Article article = fArticle.get();
 Frontpage frontpage = fFrontpage.get();
 

The first line trigger a batch request that retrieves the results for all the requests added since the last call to Future#get(). The second line doesn't need to do any API call as the result was retrieve during the execution of the fist line.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	API_SERVER
protected static String	ARTICLE_URI
protected static String	BATCH_URI
protected static String	FRONTPAGE_URI

Constructor Summary

Constructors

Constructor and Description
DiffbotAPI(com.google.api.client.http.HttpTransport httpTransport, com.google.api.client.json.JsonFactory jsonFactory, String token) Constructor allowing to set the Diffbot developer token and the underlying implementations for the HTTP client and the JSON parser.

Method Summary

Methods

Modifier and Type	Method and Description
Article	article(ArticleRequest articleRequest) Call the Diffbot Article API.
Future<Article>	batch(ArticleRequest articleRequest) Add an ArticleRequest to the batch list.
Future<Frontpage>	batch(FrontpageRequest frontpageRequest) Add an FrontpageRequest to the batch list.
protected void	executeBatch(Future<? extends Object> initiator)
Frontpage	frontpage(FrontpageRequest frontpageRequest) Call the Diffbot Frontpage API.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BATCH_URI

protected static final String BATCH_URI

See Also:

Constant Field Values

API_SERVER

protected static final String API_SERVER

See Also:

Constant Field Values

ARTICLE_URI

protected static final String ARTICLE_URI

See Also:

Constant Field Values

FRONTPAGE_URI

protected static final String FRONTPAGE_URI

See Also:

Constant Field Values

Constructor Detail

DiffbotAPI

public DiffbotAPI(com.google.api.client.http.HttpTransport httpTransport,
          com.google.api.client.json.JsonFactory jsonFactory,
          String token)
           throws JAXBException

Constructor allowing to set the Diffbot developer token and the underlying implementations for the HTTP client and the JSON parser.

The HTTP implementation can be:

• ApacheHttpTransport: Apache HTTP client.
• NetHttpTransport: Default JVM HTTP client.
• UrlFetchTransport: URL Fetch to use with Google App Engine.

The JSON parser implementation can be:

• GsonFactory: Gson.
• JsonFactory: Jackson 2.

Parameters:

httpTransport - an implementation of HttpTransport

jsonFactory - an implementation of JsonFactory

token - your Diffbot developer token

Throws:

JAXBException - if JAXB is not in the classpath

Method Detail

article

public final Article article(ArticleRequest articleRequest)
                      throws DiffbotUnauthorizedException,
                             DiffbotServerException,
                             DiffbotIOException,
                             DiffbotAPIException

Call the Diffbot Article API.

Parameters:

articleRequest - a ArticleRequest filled with the parameters to call the Article API

Returns:

the Article representing the Diffbot API result

Throws:

DiffbotUnauthorizedException - if the developer token is not recognized or revoked

DiffbotServerException - if a HTTP error occurs on the Diffbot server

DiffbotIOException - if an IO error (usually network related) occur during the API call

DiffbotAPIException - if an API error occur on Diffbot servers while processing the request

frontpage

public final Frontpage frontpage(FrontpageRequest frontpageRequest)
                          throws DiffbotUnauthorizedException,
                                 DiffbotServerException,
                                 DiffbotIOException,
                                 DiffbotAPIException,
                                 DiffbotParseException

Call the Diffbot Frontpage API.

Parameters:

frontpageRequest - a FrontpageRequest filled with the parameters to call the Frontpage API

Returns:

the Frontpage representing the Diffbot API result

Throws:

DiffbotUnauthorizedException - if the developer token is not recognized or revoked

DiffbotServerException - if a HTTP error occurs on the Diffbot server

DiffbotIOException - if an IO error (usually network related) occur during the API call

DiffbotAPIException - if an API error occur on Diffbot servers while processing the request

DiffbotParseException - if the Diffbot response cannot be parsed

batch

public final Future<Frontpage> batch(FrontpageRequest frontpageRequest)

Add an FrontpageRequest to the batch list.

Parameters:

frontpageRequest - the FrontpageRequest to add to the list

Returns:

a Future<Frontpage> that will be filled with an Frontpage on the next batch call

batch

public final Future<Article> batch(ArticleRequest articleRequest)

Add an ArticleRequest to the batch list.

Parameters:

articleRequest - the ArticleRequest to add to the list

Returns:

a Future<Article> that will be filled with an Article on the next batch call

executeBatch

protected final void executeBatch(Future<? extends Object> initiator)
                           throws DiffbotUnauthorizedException,
                                  DiffbotServerException,
                                  DiffbotIOException

Throws:

DiffbotUnauthorizedException

DiffbotServerException

DiffbotIOException