Package org.wikidata.wdtk.wikibaseapi

Class WikibaseDataFetcher

java.lang.Object

org.wikidata.wdtk.wikibaseapi.WikibaseDataFetcher

public class WikibaseDataFetcher
extends Object

Simple class to fetch data from Wikibase via the online API.

Author:

Markus Kroetzsch, Michael Guenther

Constructor Summary

Constructors

Constructor	Description
WikibaseDataFetcher(ApiConnection connection, String siteUri)	Creates an object to fetch data from API with the given ApiConnection object.

Method Summary

Modifier and Type	Method	Description
EntityDocument	getEntityDocument(String entityId)	Fetches the documents for the entity of the given string IDs.
EntityDocument	getEntityDocumentByTitle(String siteKey, String title)	Fetches the document for the entity that has a page of the given title on the given site.
Map<String,EntityDocument>	getEntityDocuments(String... entityIds)	Fetches the documents for the entities of the given string IDs.
Map<String,EntityDocument>	getEntityDocuments(List<String> entityIds)	Fetches the documents for the entities of the given string IDs.
Map<String,EntityDocument>	getEntityDocumentsByTitle(String siteKey, String... titles)	Fetches the documents for the entities that have pages of the given titles on the given site.
Map<String,EntityDocument>	getEntityDocumentsByTitle(String siteKey, List<String> titles)	Fetches the documents for the entities that have pages of the given titles on the given site.
DocumentDataFilter	getFilter()	Returns the DocumentDataFilter object that is used to filter API requests.
MediaInfoIdValue	getMediaInfoIdByFileName(String fileName)	Fetches the MediaInfoId of a file with the given name.
Map<String,MediaInfoIdValue>	getMediaInfoIdsByFileName(String... fileNames)	Fetches the MediaInfoIds of files with the given names.
Map<String,MediaInfoIdValue>	getMediaInfoIdsByFileName(List<String> fileNames)	Fetches the MediaInfoIds of files with the given names.
static WikibaseDataFetcher	getWikidataDataFetcher()	Creates an object to fetch data from wikidata.org.
static WikibaseDataFetcher	getWikimediaCommonsDataFetcher()	Creates an object to fetch data from commons.wikimedia.org.
List<WbSearchEntitiesResult>	searchEntities(String search)
List<WbSearchEntitiesResult>	searchEntities(String search, Long limit)
List<WbSearchEntitiesResult>	searchEntities(String search, String language)
List<WbSearchEntitiesResult>	searchEntities(String search, String language, Long limit)
List<WbSearchEntitiesResult>	searchEntities(WbGetEntitiesSearchData properties)

Methods inherited from class java.lang.Object

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

Constructor Details

WikibaseDataFetcher

public WikibaseDataFetcher(ApiConnection connection,
 String siteUri)

Creates an object to fetch data from API with the given ApiConnection object. The site URI is necessary since it is not contained in the data retrieved from the URI.

Parameters:

connection - ApiConnection

siteUri - the URI identifying the site that is accessed (usually the prefix of entity URIs), e.g., "http://www.wikidata.org/entity/"

Method Details

getWikidataDataFetcher

public static WikibaseDataFetcher getWikidataDataFetcher()

Creates an object to fetch data from wikidata.org. This convenience method creates a default ApiConnection that is not logged in. To use an existing connection, the constructor WikibaseDataFetcher(ApiConnection, String) should be called, using Datamodel.SITE_WIKIDATA as a site URI.

getWikimediaCommonsDataFetcher

public static WikibaseDataFetcher getWikimediaCommonsDataFetcher()

Creates an object to fetch data from commons.wikimedia.org. This convenience method creates a default ApiConnection that is not logged in. To use an existing connection, the constructor WikibaseDataFetcher(ApiConnection, String) should be called, using Datamodel.SITE_WIKIMEDIA_COMMONS as a site URI.

getFilter

public DocumentDataFilter getFilter()

Returns the DocumentDataFilter object that is used to filter API requests. Settings made in this object will affect the API request, and often lead to reduced network traffic and better performance.

Note: Filtering individual properties is currently not supported (such filters will be ignored). However, filtering all properties is possible; in this case all statements are excluded.

Returns:

the filter used by this object

getEntityDocument

public EntityDocument getEntityDocument(String entityId)
                                 throws MediaWikiApiErrorException,
IOException

Fetches the documents for the entity of the given string IDs. The result is an EntityDocument or null if the data could not be fetched.

Parameters:

entityId - string IDs (e.g., "P31" or "Q42") of requested entity

Returns:

retrieved entity document or null

Throws:

MediaWikiApiErrorException

IOException

getEntityDocuments

public Map<String,EntityDocument> getEntityDocuments(String... entityIds)
                                              throws MediaWikiApiErrorException,
IOException

Fetches the documents for the entities of the given string IDs. The result is a map from entity IDs to EntityDocument objects. It is possible that a requested ID could not be found: then this key is not set in the map.

Parameters:

entityIds - string IDs (e.g., "P31", "Q42") of requested entities

Returns:

map from IDs for which data could be found to the documents that were retrieved

Throws:

MediaWikiApiErrorException

IOException

getEntityDocuments

public Map<String,EntityDocument> getEntityDocuments(List<String> entityIds)
                                              throws MediaWikiApiErrorException,
IOException

Fetches the documents for the entities of the given string IDs. The result is a map from entity IDs to EntityDocument objects. It is possible that a requested ID could not be found: then this key is not set in the map.

Parameters:

entityIds - list of string IDs (e.g., "P31", "Q42") of requested entities

Returns:

map from IDs for which data could be found to the documents that were retrieved

Throws:

MediaWikiApiErrorException

IOException

getEntityDocumentByTitle

public EntityDocument getEntityDocumentByTitle(String siteKey,
 String title)
                                        throws MediaWikiApiErrorException,
IOException

Fetches the document for the entity that has a page of the given title on the given site. Site keys should be some site identifier known to the Wikibase site that is queried, such as "enwiki" for Wikidata.org. It could also be used to retrieve Wikimedia Commons MediaInfo entities using the siteKey "commonswiki" and the file title (with the File: prefix) for title.

Note: This method will not work properly if a filter is set for sites that excludes the requested site.

Parameters:

siteKey - wiki site id, e.g., "enwiki"

title - string titles (e.g. "Douglas Adams") of requested entities

Returns:

document for the entity with this title, or null if no such document exists

Throws:

MediaWikiApiErrorException

IOException

getEntityDocumentsByTitle

public Map<String,EntityDocument> getEntityDocumentsByTitle(String siteKey,
 String... titles)
                                                     throws MediaWikiApiErrorException,
IOException

Fetches the documents for the entities that have pages of the given titles on the given site. Site keys should be some site identifier known to the Wikibase site that is queried, such as "enwiki" for Wikidata.org.

Note: This method will not work properly if a filter is set for sites that excludes the requested site.

Parameters:

siteKey - wiki site id, e.g. "enwiki"

titles - list of string titles (e.g. "Douglas Adams") of requested entities

Returns:

map from titles for which data could be found to the documents that were retrieved

Throws:

MediaWikiApiErrorException

IOException

getEntityDocumentsByTitle

public Map<String,EntityDocument> getEntityDocumentsByTitle(String siteKey,
 List<String> titles)
                                                     throws MediaWikiApiErrorException,
IOException

Fetches the documents for the entities that have pages of the given titles on the given site. Site keys should be some site identifier known to the Wikibase site that is queried, such as "enwiki" for Wikidata.org.

Note: This method will not work properly if a filter is set for sites that excludes the requested site.

Parameters:

siteKey - wiki site id, e.g. "enwiki"

titles - list of string titles (e.g. "Douglas Adams") of requested entities

Returns:

map from titles for which data could be found to the documents that were retrieved

Throws:

MediaWikiApiErrorException

IOException

getMediaInfoIdByFileName

public MediaInfoIdValue getMediaInfoIdByFileName(String fileName)
                                          throws IOException,
MediaWikiApiErrorException

Fetches the MediaInfoId of a file with the given name. This method only works with file name (e.g. "File:Albert Einstein Head.jpg"). The "File:" prefix can be omitted, in this case, it will be automatically added during processing. For example, "Albert Einstein Head.jpg" will be processed as "File:Albert Einstein Head.jpg". Notice that pages other than file pages will also be fitted with the "File:" prefix. For example, "Main Page" will be processed as "File:Main Page", which doesn't exist. So always make sure you are dealing with file name. Use this method for speeding up if you only need the id information, i.e. you don't need other information like labels, descriptions, statements, etc. Otherwise, you may need to use getEntityDocumentByTitle(String siteKey, String title)

Parameters:

fileName - file name (e.g. "File:Albert Einstein Head.jpg" or "Albert Einstein Head.jpg") of the requested MediaInfoId, the "File:" prefix can be omitted

Returns:

the corresponding MediaInfoId for the file name, or null if not found

Throws:

IOException

MediaWikiApiErrorException

getMediaInfoIdsByFileName

public Map<String,MediaInfoIdValue> getMediaInfoIdsByFileName(String... fileNames)
                                                       throws IOException,
MediaWikiApiErrorException

Fetches the MediaInfoIds of files with the given names. This method only works with file name (e.g. "File:Albert Einstein Head.jpg"). The "File:" prefix can be omitted, in this case, it will be automatically added during processing. For example, "Albert Einstein Head.jpg" will be processed as "File:Albert Einstein Head.jpg". Notice that pages other than file pages will also be fitted with the "File:" prefix. For example, "Main Page" will be processed as "File:Main Page", which doesn't exist. So always make sure you are dealing with file name. Use this method for speeding up if you only need the id information, i.e. you don't need other information like labels, descriptions, statements, etc. Otherwise, you may need to use getEntityDocumentsByTitle(String siteKey, String...titles)

Parameters:

fileNames - list of file names of the requested MediaInfoIds

Returns:

map from file names for which data could be found to the MediaInfoIds that were retrieved

Throws:

IOException

MediaWikiApiErrorException

getMediaInfoIdsByFileName

public Map<String,MediaInfoIdValue> getMediaInfoIdsByFileName(List<String> fileNames)
                                                       throws IOException,
MediaWikiApiErrorException

Fetches the MediaInfoIds of files with the given names. This method only works with file name (e.g. "File:Albert Einstein Head.jpg"). The "File:" prefix can be omitted, in this case, it will be automatically added during processing. For example, "Albert Einstein Head.jpg" will be processed as "File:Albert Einstein Head.jpg". Notice that pages other than file pages will also be fitted with the "File:" prefix. For example, "Main Page" will be processed as "File:Main Page", which doesn't exist. So always make sure you are dealing with file name. Use this method for speeding up if you only need the id information, i.e. you don't need other information like labels, descriptions, statements, etc. Otherwise, you may need to use getEntityDocumentsByTitle(String siteKey, List titles)

Parameters:

fileNames - list of file names of the requested MediaInfoIds

Returns:

map from file names for which data could be found to the MediaInfoIds that were retrieved

Throws:

IOException

MediaWikiApiErrorException

searchEntities

public List<WbSearchEntitiesResult> searchEntities(String search)
                                            throws MediaWikiApiErrorException,
IOException

Throws:

MediaWikiApiErrorException

IOException

searchEntities

public List<WbSearchEntitiesResult> searchEntities(String search,
 String language)
                                            throws MediaWikiApiErrorException,
IOException

Throws:

MediaWikiApiErrorException

IOException

searchEntities

public List<WbSearchEntitiesResult> searchEntities(String search,
 Long limit)
                                            throws MediaWikiApiErrorException,
IOException

Throws:

MediaWikiApiErrorException

IOException

searchEntities

public List<WbSearchEntitiesResult> searchEntities(String search,
 String language,
 Long limit)
                                            throws MediaWikiApiErrorException,
IOException

Throws:

MediaWikiApiErrorException

IOException

searchEntities

public List<WbSearchEntitiesResult> searchEntities(WbGetEntitiesSearchData properties)
                                            throws MediaWikiApiErrorException,
IOException

Throws:

MediaWikiApiErrorException

IOException