Skip to content

Adding a new library

Johan von Forstner edited this page Jan 9, 2021 · 17 revisions

Thank you for being interested in implementing support for a library on your own :-) Please fork the repository, create a branch, do your magic and open a pull request (so I can merge it into my repository)! If you run into problems, feel free to contact me!

  • Opac systems already implemented: Take a look at Supported library types and try to figure out if your library uses one of the systems listed over there. If this is the case, you only have to do the JSON configuration described below.
    Update: As of 2.0.8, there will be a python script tools/ which can generate those files automatically and will prompt you for input.
    Update 2: As of 2016, the configuration files are not included in this repository anymore, but moved to a separate system to make it possible to update the configuration separately from the app. You can still create new configuration files with the script, but have to submit them as a PR to our opacapp-config-files repo. For more details, see here.
  • New Opac systems: If it is not the case, you have to implement a new Java class, as described in the second section of this page.

The JSON configuration

Every supported library is defined by a JSON file in assets/bibs/ (these files are not included in the repository, but instead downloaded from our server as described here. Those JSON files are structured like this example:

	 "account_supported": true, 
	 "api": "oclc2011", 
	 "city": "Bonn", 
	 "country": "Deutschland", 
	 "data": {
	  "baseurl": "", 
	  "information": "" 
	 "geo": [50.73743, 7.0982068], 
	 "state": "Nordrhein-Westfalen",
	 "title": "Stadtbibliothek",
  • api: identifier of the library system, e.g. bibliotheca, sisis, zones22 or biber1992
  • city: town the library is located in, is used to arrange the libraries alphabetically
  • country and state for the list hierarchy
  • geo: Latitude and Longitude of the town
  • data: Information the OPAC's implementation needs, at least:
  • baseurl: The OPAC's base url, without a trailing slash
  • information: An URL for information like opening hours. May be an absolute URL or a relative one, which (in the latter case) is simply appended to baseurl
  • account_supported: A string describing which parts of the OPAC are supported ("Search only", "Search and Account"), is shown in the list of libraries
  • title: An additional name for the library, which is necessary if it is not the main public library in city (can be null). Shouldn't include the city's name because it normally is shown together with city.

The OpacApi interface

If you have to implement a completely new library system, you have to create a new class in de.geeksfactory.opacclient.apis (located in the libopac module), implementing the interface de.geeksfactory.opacclient.apis.OpacApi. You also have to add your class in de.geeksfactory.opacclient.OpacApiFactory.create(…) to make it known to the JSON parsing methods. You can take inspiration from the existing implementations located in the apis subpackage.

Most of our OpacApi implementations extend the BaseApi classes that provide some convenience functions, amongst others a HTTP client with httpGet and httpPost functions. We have two flavors, the ApacheBaseApi and the OkHttpBaseApi, which are based on the Apache HTTP client and the OkHttp client, respectively. Our goal is to move all APIs to the OkHttpBaseApi some time in the future, so new API implementations should extend the OkHttpBaseApi.

The interface is documented by inline javadoc comments. There is an online copy here but I don't guarantee that this is always up to date, although I try to :-)