de.geeksfactory.opacclient.apis

Interface OpacApi

All Known Implementing Classes:

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

public interface OpacApi

Generic interface for accessing online library catalogues.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	OpacApi.CancelResult The result of a cancel(String, Account, int, String) call
static class	OpacApi.MultiStepResult The result of a multi-step-supporting method call.
static class	OpacApi.OpacErrorException A general exception containing a human-readable error message
static class	OpacApi.ProlongAllResult The result of a prolongAll(Account, int, String) call
static class	OpacApi.ProlongResult The result of a prolong(String, Account, int, String) call
static class	OpacApi.ReservationResult The result of a reservation(DetailledItem, Account, int, String) call

Field Summary

Fields

Modifier and Type	Field and Description
static int	SUPPORT_FLAG_ACCOUNT_PROLONG_ALL Availability of the "prolong all lent items" feature Flag to be present in the result of getSupportFlags().
static int	SUPPORT_FLAG_CHANGE_ACCOUNT Allow account change on reservation click.
static int	SUPPORT_FLAG_ENDLESS_SCROLLING When the results are shown as an endless scrolling list, will reload the page the selected result is located on if this flag is not present.
static int	SUPPORT_FLAG_QUICKLINKS Availability of the "quicklinks" feature Flag to be present in the result of getSupportFlags().
static int	SUPPORT_FLAG_WARN_PROLONG_FEES Asks the user responsibly about prolong fees
static int	SUPPORT_FLAG_WARN_RESERVATION_FEES Asks the user responsibly about reservation fees Flag to be present in the result of getSupportFlags().

Method Summary

Modifier and Type	Method and Description
AccountData	account(Account account) Load account view (borrowed and reserved items, see AccountData) This function is always called from a background thread, you can use blocking network operations in it.
OpacApi.CancelResult	cancel(java.lang.String media, Account account, int useraction, java.lang.String selection) Cancel a media reservation/order identified by the given String (see AccountData documentation) (see AccountData) This function is always called from a background thread, you can use blocking network operations in it.
void	checkAccountData(Account account) Check the validity of given account data.
SearchRequestResult	filterResults(Filter filter, Filter.Option option) If your search(List) implementation puts something different from null into SearchRequestResult.setFilters(List), this will be called to apply a filter to the last search request.
DetailledItem	getResult(int position) Get details for the item at position from last search(java.util.List<de.geeksfactory.opacclient.searchfields.SearchQuery>) or searchGetPage(int) call.
DetailledItem	getResultById(java.lang.String id, java.lang.String homebranch) Get details for the item with unique ID id.
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	getShareUrl(java.lang.String id, java.lang.String title) Some library systems allow us to share search results.
java.util.Set<java.lang.String>	getSupportedLanguages() Get all languages supported by this library.
int	getSupportFlags() Return which optional features your API implementation supports.
void	init(Library library, HttpClientFactory httpClientFactory) Is called whenever a new API object is created.
OpacApi.ProlongResult	prolong(java.lang.String media, Account account, int useraction, java.lang.String selection) Extend the lending period of the item identified by the given String (see AccountData) This function is always called from a background thread, you can use blocking network operations in it.
OpacApi.ProlongAllResult	prolongAll(Account account, int useraction, java.lang.String selection) Extend the lending period of all lent items.
OpacApi.ReservationResult	reservation(DetailledItem item, Account account, int useraction, java.lang.String selection) Perform a reservation on the item last fetched with getResultById or getResult for Account acc.
SearchRequestResult	search(java.util.List<SearchQuery> query) Performs a catalogue search.
SearchRequestResult	searchGetPage(int page) Get result page page of the search performed last with search(java.util.List<de.geeksfactory.opacclient.searchfields.SearchQuery>).
void	setLanguage(java.lang.String language) Set the language to use.
void	setStringProvider(StringProvider stringProvider) Sets the StringProvider to use for error messages etc.
void	start() May be called on application startup and you are free to call it in our 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.

Field Detail

SUPPORT_FLAG_ACCOUNT_PROLONG_ALL

static final int SUPPORT_FLAG_ACCOUNT_PROLONG_ALL

Availability of the "prolong all lent items" feature Flag to be present in the result of getSupportFlags().

See Also:

Constant Field Values

SUPPORT_FLAG_QUICKLINKS

static final int SUPPORT_FLAG_QUICKLINKS

Availability of the "quicklinks" feature Flag to be present in the result of getSupportFlags().

See Also:

Constant Field Values

SUPPORT_FLAG_ENDLESS_SCROLLING

static final int SUPPORT_FLAG_ENDLESS_SCROLLING

When the results are shown as an endless scrolling list, will reload the page the selected result is located on if this flag is not present. Flag to be present in the result of getSupportFlags().

See Also:

Constant Field Values

SUPPORT_FLAG_CHANGE_ACCOUNT

static final int SUPPORT_FLAG_CHANGE_ACCOUNT

Allow account change on reservation click. Flag to be present in the result of getSupportFlags().

See Also:

Constant Field Values

SUPPORT_FLAG_WARN_RESERVATION_FEES

static final int SUPPORT_FLAG_WARN_RESERVATION_FEES

Asks the user responsibly about reservation fees Flag to be present in the result of getSupportFlags().

See Also:

Constant Field Values

SUPPORT_FLAG_WARN_PROLONG_FEES

static final int SUPPORT_FLAG_WARN_PROLONG_FEES

Asks the user responsibly about prolong fees

See Also:

Constant Field Values

Method Detail

start

void start()
    throws java.io.IOException

May be called on application startup and you are free to call it in our 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.

Throws:

java.io.IOException - if network connection failed

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

init

void init(Library library,
          HttpClientFactory httpClientFactory)

Is called whenever a new API object is created. The difference to start is that you can rely on it but must not use blocking network functions in it. I use it to initialize my DefaultHTTPClient and to store the metadata and library objects.

Parameters:

library - The library the Api is initialized for

httpClientFactory - 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.

search

SearchRequestResult search(java.util.List<SearchQuery> query)
                    throws java.io.IOException,
                           OpacApi.OpacErrorException,
                           org.json.JSONException

Performs a catalogue search. The given List<SearchQuery> contains the search criteria. See documentation on SearchResult for details. This function is always called from a background thread, you can use blocking network operations in it. See documentation on DetailledItem for details.

Parameters:

query - see above

Returns:

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

Throws:

org.json.JSONException

java.io.IOException

OpacApi.OpacErrorException

See Also:

SearchResult

volumeSearch

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

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.

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

filterResults

SearchRequestResult filterResults(Filter filter,
                                  Filter.Option option)
                           throws java.io.IOException,
                                  OpacApi.OpacErrorException

If your search(List) implementation puts something different from null into SearchRequestResult.setFilters(List), this will be called to apply a filter to the last search request. If your search(List) implementation does not set SearchRequestResult.setFilters(List), this wil never be called. Just return null. This function is always called from a background thread, you can use blocking network operations in it. See documentation on DetailledItem for details.

Parameters:

filter - The filter to be applied.

option - The filters option to be applied. If the option.isApplied() returns true, the filter is to be removed!

Returns:

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

Throws:

java.io.IOException

OpacApi.OpacErrorException

Since:

2.0.6

See Also:

SearchResult, Filter

searchGetPage

SearchRequestResult searchGetPage(int page)
                           throws java.io.IOException,
                                  OpacApi.OpacErrorException,
                                  org.json.JSONException

Get result page page of the search performed last with search(java.util.List<de.geeksfactory.opacclient.searchfields.SearchQuery>). This function is always called from a background thread, you can use blocking network operations in it. See documentation on DetailledItem for details.

Parameters:

page - page number to fetch

Returns:

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

Throws:

java.io.IOException

OpacApi.OpacErrorException

org.json.JSONException

See Also:

search(List), SearchResult

getResultById

DetailledItem getResultById(java.lang.String id,
                            java.lang.String homebranch)
                     throws java.io.IOException,
                            OpacApi.OpacErrorException

Get details for the item with unique ID id. This function is always called from a background thread, you can use blocking network operations in it.

Parameters:

id - id of object to fetch

homebranch - The users "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, set to null.

Returns:

Media details

Throws:

java.io.IOException

OpacApi.OpacErrorException

See Also:

DetailledItem

getResult

DetailledItem getResult(int position)
                 throws java.io.IOException,
                        OpacApi.OpacErrorException

Get details for the item at position from last search(java.util.List<de.geeksfactory.opacclient.searchfields.SearchQuery>) or searchGetPage(int) call. We generally prefer getResultById(String, String), so if you implement getResultById AND every search result of your driver has an id set, you can omit this method (respectively, return null). This function is always called from a background thread, you can use blocking network operations in it.

Parameters:

position - position of object in last search

Returns:

Media details

Throws:

java.io.IOException

OpacApi.OpacErrorException

See Also:

DetailledItem

reservation

OpacApi.ReservationResult reservation(DetailledItem item,
                                      Account account,
                                      int useraction,
                                      java.lang.String selection)
                               throws java.io.IOException

Perform a reservation on the item last fetched with getResultById or getResult for Account acc. (if applicable) This function is always called from a background thread, you can use blocking network operations in it.

Parameters:

item - The item to place a reservation for.

account - Account to be used

useraction - Identifier for the selection made by the user in selection, if a selection was made (see OpacApi.MultiStepResult.getActionIdentifier()) or 0, if no selection was required. If your last method call returned CONFIRMATION_NEEDED, this is set to ACTION_CONFIRMATION if the user positively confirmed the action.

selection - When the method is called for the first time or if useraction is ACTION_CONFIRMATION, this parameter is null. If you return SELECTION in your OpacApi.MultiStepResult.getStatus(), this method will be called again with the user's selection present in selection.

Returns:

A ReservationResult object which has to have the status set.

Throws:

java.io.IOException

prolong

OpacApi.ProlongResult prolong(java.lang.String media,
                              Account account,
                              int useraction,
                              java.lang.String selection)
                       throws java.io.IOException

Extend the lending period of the item identified by the given String (see AccountData) This function is always called from a background thread, you can use blocking network operations in it.

Parameters:

media - Media identification

account - Account to be used

useraction - Identifier for the selection made by the user in selection, if a selection was made (see OpacApi.MultiStepResult.getActionIdentifier()) or 0, if no selection was required. If your last method call returned CONFIRMATION_NEEDED, this is set to ACTION_CONFIRMATION if the user positively confirmed the action.

selection - When the method is called for the first time or if useraction is ACTION_CONFIRMATION, this parameter is null. If you return SELECTION in your OpacApi.MultiStepResult.getStatus(), this method will be called again with the user's selection present in selection.

Returns:

A ProlongResult object which has to have the status set.

Throws:

java.io.IOException

prolongAll

OpacApi.ProlongAllResult prolongAll(Account account,
                                    int useraction,
                                    java.lang.String selection)
                             throws java.io.IOException

Extend the lending period of all lent items. Will only be called if your getSupportFlags() implementation's return value contains the SUPPORT_FLAG_ACCOUNT_PROLONG_ALL flag. If you don't support the feature, just implement a stub method, like return false; This function is always called from a background thread, you can use blocking network operations in it.

Returns:

A ProlongAllResult object which has to have the status set.

Throws:

java.io.IOException

See Also:

prolong(String, Account, int, String), AccountData

cancel

OpacApi.CancelResult cancel(java.lang.String media,
                            Account account,
                            int useraction,
                            java.lang.String selection)
                     throws java.io.IOException,
                            OpacApi.OpacErrorException

Cancel a media reservation/order identified by the given String (see AccountData documentation) (see AccountData) This function is always called from a background thread, you can use blocking network operations in it.

Parameters:

media - Media identification

account - Account to be used

useraction - Identifier for the selection made by the user in selection, if a selection was made (see OpacApi.MultiStepResult.getActionIdentifier()) or 0, if no selection was required. If your last method call returned CONFIRMATION_NEEDED, this is set to ACTION_CONFIRMATION if the user positively confirmed the action.

selection - When the method is called for the first time or if useraction is ACTION_CONFIRMATION, this parameter is null. If you return SELECTION in your OpacApi.MultiStepResult.getStatus(), this method will be called again with the user's selection present in selection.

Returns:

A CancelResult object which has to have the status set.

Throws:

java.io.IOException

OpacApi.OpacErrorException

account

AccountData account(Account account)
             throws java.io.IOException,
                    org.json.JSONException,
                    OpacApi.OpacErrorException

Load account view (borrowed and reserved items, see AccountData) This function is always called from a background thread, you can use blocking network operations in it.

Parameters:

account - The account to display

Returns:

Account details

Throws:

java.io.IOException

org.json.JSONException

OpacApi.OpacErrorException

See Also:

AccountData

checkAccountData

void checkAccountData(Account account)
               throws java.io.IOException,
                      org.json.JSONException,
                      OpacApi.OpacErrorException

Check the validity of given account data. This is separate from the account(Account) function because just checking the login can be much faster than retrieving all the account data. This function is always called from a background thread, you can use blocking network operations in it.

Parameters:

account - The account to check

Throws:

OpacApi.OpacErrorException - when the login data is invalid or there's another error message from the OPAC system

java.io.IOException

org.json.JSONException

getSearchFields

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

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.

Returns:

List of allowed fields

Throws:

OpacApi.OpacErrorException

org.json.JSONException

java.io.IOException

See Also:

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

getShareUrl

java.lang.String getShareUrl(java.lang.String id,
                             java.lang.String title)

Some library systems allow us to share search results. If your library system allows this natively (to link directly on search results), you can return the corresponding URL with this function. If your library does not support this at all, return null. If you library only accepts direkt links when a session is open, get in touch with me (mail@raphaelmichel.de) to get it integrated in the opacapp.de proxy.

Parameters:

id - Media id of the item to be shared

title - Title of the item to be shared

Returns:

An URL or null.

getSupportFlags

int getSupportFlags()

Return which optional features your API implementation supports.

Returns:

combination (bitwise OR) of SUPPORT_FLAG_* constants

setStringProvider

void setStringProvider(StringProvider stringProvider)

Sets the StringProvider to use for error messages etc.

Parameters:

stringProvider - the StringProvider to use

getSupportedLanguages

java.util.Set<java.lang.String> getSupportedLanguages()
                                               throws java.io.IOException

Get all languages supported by this library. This will be a Set of language codes defined in ISO-639-1 (two-letter codes in lower case, see this list). We don't need to use this function in the app because the API will automatically fall back if the language set is not supported, but it is used in the MeaningDetector tool to get search fields for all supported languages. This function may use blocking network operations and may return null if the API doesn't support different languages.

Throws:

java.io.IOException

setLanguage

void setLanguage(java.lang.String language)

Set the language to use. This should be one of the language codes defined in ISO-639-1 (two-letter codes in lower case, see this list). The API should use the default language of the library if this is not called and should fall back first to English and then to the library's default language if the requested language is not available.

Parameters:

language - the language to use