de.geeksfactory.opacclient.apis

Class BaseApi

java.lang.Object

de.geeksfactory.opacclient.apis.BaseApi

All Implemented Interfaces:

OpacApi

Direct Known Subclasses:

Adis, BiBer1992, Bibliotheca, Heidi, IOpac, Open, Pica, Primo, SearchOnlyApi, SISIS, SRU, TestApi, TouchPoint, VuFind, WebOpacNet, WinBiap, Zones

public abstract class BaseApi
extends java.lang.Object
implements OpacApi

Abstract Base class for OpacApi implementations providing some helper methods for HTTP

Nested Class Summary

Nested classes/interfaces inherited from interface de.geeksfactory.opacclient.apis.OpacApi

OpacApi.CancelResult, OpacApi.MultiStepResult, OpacApi.OpacErrorException, OpacApi.ProlongAllResult, OpacApi.ProlongResult, OpacApi.ReservationResult

Field Summary

Fields

Modifier and Type	Field and Description
protected org.apache.http.client.HttpClient	http_client
protected boolean	httpLoggingEnabled
protected boolean	initialised
protected static java.lang.String	KEY_SEARCH_QUERY_AUDIENCE Some libraries support a special "audience" field with specified values.
protected static java.lang.String	KEY_SEARCH_QUERY_AUTHOR Author name to search for.
protected static java.lang.String	KEY_SEARCH_QUERY_AVAILABLE Restrict search to available media.
protected static java.lang.String	KEY_SEARCH_QUERY_BARCODE Unique item identifier.
protected static java.lang.String	KEY_SEARCH_QUERY_BRANCH Library branch to search in.
protected static java.lang.String	KEY_SEARCH_QUERY_CATEGORY Item category (like "book" or "CD").
protected static java.lang.String	KEY_SEARCH_QUERY_DIGITAL Restrict search to digital media.
protected static java.lang.String	KEY_SEARCH_QUERY_FREE Keywords to do a free search.
protected static java.lang.String	KEY_SEARCH_QUERY_HOME_BRANCH "Home" library branch.
protected static java.lang.String	KEY_SEARCH_QUERY_ISBN An ISBN / EAN code to search for.
protected static java.lang.String	KEY_SEARCH_QUERY_KEYWORDA "Keyword A".
protected static java.lang.String	KEY_SEARCH_QUERY_KEYWORDB "Keyword B".
protected static java.lang.String	KEY_SEARCH_QUERY_LOCATION Item location in library.
protected static java.lang.String	KEY_SEARCH_QUERY_ORDER Sort search results in a specific order This is only used internally to construct search fields.
protected static java.lang.String	KEY_SEARCH_QUERY_PUBLISHER The "publisher" search field This is only used internally to construct search fields.
protected static java.lang.String	KEY_SEARCH_QUERY_SYSTEM Systematic identification, used in some libraries.
protected static java.lang.String	KEY_SEARCH_QUERY_TITLE Item title to search for.
protected static java.lang.String	KEY_SEARCH_QUERY_YEAR Year of publication.
protected static java.lang.String	KEY_SEARCH_QUERY_YEAR_RANGE_END Start of range, if year of publication can be specified as a range.
protected static java.lang.String	KEY_SEARCH_QUERY_YEAR_RANGE_START End of range, if year of publication can be specified as a range.
protected Library	library
protected StringProvider	stringProvider
protected java.util.Set<java.lang.String>	supportedLanguages

Fields inherited from interface de.geeksfactory.opacclient.apis.OpacApi

SUPPORT_FLAG_ACCOUNT_PROLONG_ALL, SUPPORT_FLAG_CHANGE_ACCOUNT, SUPPORT_FLAG_ENDLESS_SCROLLING, SUPPORT_FLAG_QUICKLINKS, SUPPORT_FLAG_WARN_PROLONG_FEES, SUPPORT_FLAG_WARN_RESERVATION_FEES

Constructor Summary

Constructors

Constructor and Description
BaseApi()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	buildHttpGetParams(java.util.List<org.apache.http.NameValuePair> params)
static java.lang.String	cleanUrl(java.lang.String myURL) Cleans the parameters of a URL by parsing it manually and reformatting it using URLEncodedUtils.format(java.util.List, String)
protected static java.lang.String	convertStreamToString(java.io.InputStream is) Reads content from an InputStream into a string, using the default ISO-8859-1 encoding
protected static java.lang.String	convertStreamToString(java.io.InputStream is, java.lang.String encoding) Reads content from an InputStream into a string
void	downloadCover(CoverHolder item) Downloads a cover to a CoverHolder.
protected java.lang.String	getDefaultEncoding()
static java.util.Map<java.lang.String,java.util.List<java.lang.String>>	getQueryParams(java.lang.String url)
static java.util.Map<java.lang.String,java.lang.String>	getQueryParamsFirst(java.lang.String url)
java.util.List<SearchField>	getSearchFields() Returns a list of search criteria which are supported by this OPAC and should be visible in the search activity.
java.lang.String	httpGet(java.lang.String url) Deprecated.
java.lang.String	httpGet(java.lang.String url, java.lang.String encoding)
java.lang.String	httpGet(java.lang.String url, java.lang.String encoding, boolean ignore_errors)
java.lang.String	httpGet(java.lang.String url, java.lang.String encoding, boolean ignore_errors, org.apache.http.client.CookieStore cookieStore) Perform a HTTP GET request to a given URL
java.lang.String	httpPost(java.lang.String url, org.apache.http.HttpEntity data) Deprecated.
java.lang.String	httpPost(java.lang.String url, org.apache.http.HttpEntity data, java.lang.String encoding)
java.lang.String	httpPost(java.lang.String url, org.apache.http.HttpEntity data, java.lang.String encoding, boolean ignore_errors)
java.lang.String	httpPost(java.lang.String url, org.apache.http.HttpEntity data, java.lang.String encoding, boolean ignore_errors, org.apache.http.client.CookieStore cookieStore) Perform a HTTP POST request to a given URL
void	init(Library library, HttpClientFactory http_client_factory) Initializes HTTP client and String Provider
protected void	logHttpError(java.lang.Throwable e)
abstract java.util.List<SearchField>	parseSearchFields()
protected static java.util.Map<java.lang.String,java.lang.String>	searchQueryListToMap(java.util.List<SearchQuery> queryList) Converts a List of SearchQuerys to Map of their keys and values.
void	setHttpLoggingEnabled(boolean httpLoggingEnabled)
void	setStringProvider(StringProvider stringProvider) Sets the StringProvider to use for error messages etc.
protected boolean	shouldUseMeaningDetector()
void	start() May be called on application startup and you are free to call it in our OpacApi.search(java.util.List<de.geeksfactory.opacclient.searchfields.SearchQuery>) implementation or similar positions.
SearchRequestResult	volumeSearch(java.util.Map<java.lang.String,java.lang.String> query) Performs a catalogue search for volumes of an item.

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.geeksfactory.opacclient.apis.OpacApi

account, cancel, checkAccountData, filterResults, getResult, getResultById, getShareUrl, getSupportedLanguages, getSupportFlags, prolong, prolongAll, reservation, search, searchGetPage, setLanguage

Field Detail

http_client

protected org.apache.http.client.HttpClient http_client

library

protected Library library

stringProvider

protected StringProvider stringProvider

supportedLanguages

protected java.util.Set<java.lang.String> supportedLanguages

initialised

protected boolean initialised

httpLoggingEnabled

protected boolean httpLoggingEnabled

KEY_SEARCH_QUERY_FREE

protected static final java.lang.String KEY_SEARCH_QUERY_FREE

Keywords to do a free search. Some APIs do support this, some don't. If supported, it must at least search in title and author field, but should also search abstract and other things. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_TITLE

protected static final java.lang.String KEY_SEARCH_QUERY_TITLE

Item title to search for. Doesn't have to be the full title, can also be a substring to be searched. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_AUTHOR

protected static final java.lang.String KEY_SEARCH_QUERY_AUTHOR

Author name to search for. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_KEYWORDA

protected static final java.lang.String KEY_SEARCH_QUERY_KEYWORDA

"Keyword A". Most libraries require very special input in this field. May be only shown if "advanced fields" is set in user preferences. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_KEYWORDB

protected static final java.lang.String KEY_SEARCH_QUERY_KEYWORDB

"Keyword B". Most libraries require very special input in this field. May be only shown if "advanced fields" is set in user preferences. Can only be set, if KEY_SEARCH_QUERY_KEYWORDA is set as well. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_BRANCH

protected static final java.lang.String KEY_SEARCH_QUERY_BRANCH

Library branch to search in. The user is able to select from multiple options, generated from the MetaData you store in the MetaDataSource you get in init(Library, HttpClientFactory). This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_HOME_BRANCH

protected static final java.lang.String KEY_SEARCH_QUERY_HOME_BRANCH

"Home" library branch. Some library systems require this information at search request time to determine where book reservations should be placed. If in doubt, don't use. Behaves similar to KEY_SEARCH_QUERY_BRANCH . This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_ISBN

protected static final java.lang.String KEY_SEARCH_QUERY_ISBN

An ISBN / EAN code to search for. We cannot promise whether it comes with spaces or hyphens in between but it most likely won't. If it makes a difference to you, eliminate everything except numbers and X. We also cannot say whether a ISBN10 or a ISBN13 is supplied - if relevant, check in your OpacApi.search(List) implementation. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_YEAR

protected static final java.lang.String KEY_SEARCH_QUERY_YEAR

Year of publication. Your API can either support this or both the KEY_SEARCH_QUERY_YEAR_RANGE_* fields (or none of them). This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_YEAR_RANGE_START

protected static final java.lang.String KEY_SEARCH_QUERY_YEAR_RANGE_START

End of range, if year of publication can be specified as a range. Can not be combined with KEY_SEARCH_QUERY_YEAR but has to be combined with KEY_SEARCH_QUERY_YEAR_RANGE_END. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_YEAR_RANGE_END

protected static final java.lang.String KEY_SEARCH_QUERY_YEAR_RANGE_END

Start of range, if year of publication can be specified as a range. Can not be combined with KEY_SEARCH_QUERY_YEAR but has to be combined with KEY_SEARCH_QUERY_YEAR_RANGE_START. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_SYSTEM

protected static final java.lang.String KEY_SEARCH_QUERY_SYSTEM

Systematic identification, used in some libraries. Rarely in use. May be only shown if "advanced fields" is set in user preferences. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_AUDIENCE

protected static final java.lang.String KEY_SEARCH_QUERY_AUDIENCE

Some libraries support a special "audience" field with specified values. Rarely in use. May be only shown if "advanced fields" is set in user preferences. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_PUBLISHER

protected static final java.lang.String KEY_SEARCH_QUERY_PUBLISHER

The "publisher" search field This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_CATEGORY

protected static final java.lang.String KEY_SEARCH_QUERY_CATEGORY

Item category (like "book" or "CD"). The user is able to select from multiple options, generated from the MetaData you store in the MetaDataSource you get in init(Library, HttpClientFactory). This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_BARCODE

protected static final java.lang.String KEY_SEARCH_QUERY_BARCODE

Unique item identifier. In most libraries, every single book has a unique number, most of the time printed on the in form of a barcode, sometimes encoded in a NFC chip. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_LOCATION

protected static final java.lang.String KEY_SEARCH_QUERY_LOCATION

Item location in library. Currently not in use. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_DIGITAL

protected static final java.lang.String KEY_SEARCH_QUERY_DIGITAL

Restrict search to digital media. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_AVAILABLE

protected static final java.lang.String KEY_SEARCH_QUERY_AVAILABLE

Restrict search to available media. This is only used internally to construct search fields.

See Also:

Constant Field Values

KEY_SEARCH_QUERY_ORDER

protected static final java.lang.String KEY_SEARCH_QUERY_ORDER

Sort search results in a specific order This is only used internally to construct search fields.

See Also:

Constant Field Values

Constructor Detail

BaseApi

public BaseApi()

Method Detail

cleanUrl

public static java.lang.String cleanUrl(java.lang.String myURL)

Cleans the parameters of a URL by parsing it manually and reformatting it using URLEncodedUtils.format(java.util.List, String)

Parameters:

myURL - the URL to clean

Returns:

cleaned URL

convertStreamToString

protected static java.lang.String convertStreamToString(java.io.InputStream is,
                                                        java.lang.String encoding)
                                                 throws java.io.IOException

Reads content from an InputStream into a string

Parameters:

is - InputStream to read from

encoding - the encoding to use

Returns:

String content of the InputStream

Throws:

java.io.IOException

convertStreamToString

protected static java.lang.String convertStreamToString(java.io.InputStream is)
                                                 throws java.io.IOException

Reads content from an InputStream into a string, using the default ISO-8859-1 encoding

Parameters:

is - InputStream to read from

Returns:

String content of the InputStream

Throws:

java.io.IOException

searchQueryListToMap

protected static java.util.Map<java.lang.String,java.lang.String> searchQueryListToMap(java.util.List<SearchQuery> queryList)

Converts a List of SearchQuerys to Map of their keys and values. Can be used to convert old implementations using search(Map<String, String>) to the new SearchField API

Parameters:

queryList - List of search queries

Returns:

Map of their keys and values

getQueryParams

public static java.util.Map<java.lang.String,java.util.List<java.lang.String>> getQueryParams(java.lang.String url)

getQueryParamsFirst

public static java.util.Map<java.lang.String,java.lang.String> getQueryParamsFirst(java.lang.String url)

init

public void init(Library library,
                 HttpClientFactory http_client_factory)

Initializes HTTP client and String Provider

Specified by:

init in interface OpacApi

Parameters:

library - The library the Api is initialized for

http_client_factory - A HttpClientFactory instance that will be used for instantiating HTTP clients. This factory is pluggable because we want to use platform-specific code on Android.

start

public void start()
           throws java.io.IOException

Description copied from interface: OpacApi

May be called on application startup and you are free to call it in our OpacApi.search(java.util.List<de.geeksfactory.opacclient.searchfields.SearchQuery>) implementation or similar positions. It is commonly used to initialize a session. You MUST NOT rely on it being called and should check by yourself, whether it was already called (if your following calls require it to be called before). You SHOULD use this function to populate the MetaDataSource e.g. with information on your library's branches. This function is always called from a background thread, you can use blocking network operations in it.

Specified by:

start in interface OpacApi

Throws:

java.io.IOException - if network connection failed

NotReachableException - may throw this if the library couldn't be reached

httpGet

public java.lang.String httpGet(java.lang.String url,
                                java.lang.String encoding,
                                boolean ignore_errors,
                                org.apache.http.client.CookieStore cookieStore)
                         throws java.io.IOException

Perform a HTTP GET request to a given URL

Parameters:

url - URL to fetch

encoding - Expected encoding of the response body

ignore_errors - If true, status codes above 400 do not raise an exception

cookieStore - If set, the given cookieStore is used instead of the built-in one.

Returns:

Answer content

Throws:

NotReachableException - Thrown when server returns a HTTP status code greater or equal than 400.

java.io.IOException

httpGet

public java.lang.String httpGet(java.lang.String url,
                                java.lang.String encoding,
                                boolean ignore_errors)
                         throws java.io.IOException

Throws:

java.io.IOException

httpGet

public java.lang.String httpGet(java.lang.String url,
                                java.lang.String encoding)
                         throws java.io.IOException

Throws:

java.io.IOException

httpGet

@Deprecated
public java.lang.String httpGet(java.lang.String url)
                                     throws java.io.IOException

Deprecated.

Throws:

java.io.IOException

downloadCover

public void downloadCover(CoverHolder item)

Downloads a cover to a CoverHolder. You only need to use this if the covers are only available with e.g. Session cookies. Otherwise, it is sufficient to specify the URL of the cover.

Parameters:

item - CoverHolder to download the cover for

httpPost

public java.lang.String httpPost(java.lang.String url,
                                 org.apache.http.HttpEntity data,
                                 java.lang.String encoding,
                                 boolean ignore_errors,
                                 org.apache.http.client.CookieStore cookieStore)
                          throws java.io.IOException

Perform a HTTP POST request to a given URL

Parameters:

url - URL to fetch

data - POST data to send

encoding - Expected encoding of the response body

ignore_errors - If true, status codes above 400 do not raise an exception

cookieStore - If set, the given cookieStore is used instead of the built-in one.

Returns:

Answer content

Throws:

NotReachableException - Thrown when server returns a HTTP status code greater or equal than 400.

java.io.IOException

logHttpError

protected void logHttpError(java.lang.Throwable e)

httpPost

public java.lang.String httpPost(java.lang.String url,
                                 org.apache.http.HttpEntity data,
                                 java.lang.String encoding,
                                 boolean ignore_errors)
                          throws java.io.IOException

Throws:

java.io.IOException

httpPost

public java.lang.String httpPost(java.lang.String url,
                                 org.apache.http.HttpEntity data,
                                 java.lang.String encoding)
                          throws java.io.IOException

Throws:

java.io.IOException

httpPost

@Deprecated
public java.lang.String httpPost(java.lang.String url,
                                             org.apache.http.HttpEntity data)
                                      throws java.io.IOException

Deprecated.

Throws:

java.io.IOException

getDefaultEncoding

protected java.lang.String getDefaultEncoding()

shouldUseMeaningDetector

protected boolean shouldUseMeaningDetector()

volumeSearch

public SearchRequestResult volumeSearch(java.util.Map<java.lang.String,java.lang.String> query)
                                 throws java.io.IOException,
                                        OpacApi.OpacErrorException

Description copied from interface: OpacApi

Performs a catalogue search for volumes of an item. The query is given to it from DetailledItem.getVolumesearch(). This function is always called from a background thread, you can use blocking network operations in it. See documentation on DetailledItem for details.

Specified by:

volumeSearch in interface OpacApi

Parameters:

query - see above

Returns:

List of results and additional information, or result object with the error flag set to true.

Throws:

java.io.IOException

OpacApi.OpacErrorException

See Also:

SearchResult

setStringProvider

public void setStringProvider(StringProvider stringProvider)

Description copied from interface: OpacApi

Sets the StringProvider to use for error messages etc.

Specified by:

setStringProvider in interface OpacApi

Parameters:

stringProvider - the StringProvider to use

getSearchFields

public java.util.List<SearchField> getSearchFields()
                                            throws org.json.JSONException,
                                                   OpacApi.OpacErrorException,
                                                   java.io.IOException

Description copied from interface: OpacApi

Returns a list of search criteria which are supported by this OPAC and should be visible in the search activity. Values should be instances of subclasses of the abstract SearchField class. This is called asynchronously, so you can load webpages to get the search fields, but you should save them to the metadata afterwards to make it faster.

Specified by:

getSearchFields in interface OpacApi

Returns:

List of allowed fields

Throws:

org.json.JSONException

OpacApi.OpacErrorException

java.io.IOException

See Also:

OpacApi.search(java.util.List<de.geeksfactory.opacclient.searchfields.SearchQuery>)

parseSearchFields

public abstract java.util.List<SearchField> parseSearchFields()
                                                       throws java.io.IOException,
                                                              OpacApi.OpacErrorException,
                                                              org.json.JSONException

Throws:

java.io.IOException

OpacApi.OpacErrorException

org.json.JSONException

buildHttpGetParams

public static java.lang.String buildHttpGetParams(java.util.List<org.apache.http.NameValuePair> params)
                                           throws java.io.UnsupportedEncodingException

Throws:

java.io.UnsupportedEncodingException

setHttpLoggingEnabled

public void setHttpLoggingEnabled(boolean httpLoggingEnabled)