calendarium-romanum-remote
Extends calendarium-romanum with a new class
CalendariumRomanum::Remote::Calendar
.
It is (only exception being the constructor) API-compatible
with CalendariumRomanum::Calendar
, but obtains the data
from a remote calendar API instead of computing them.
What it is good for
There are cases when you can't - or don't want to - setup a
CalendariumRomanum::Calendar
yourself.
Maybe you don't have all the necessary data, but there is a calendar
API instance which has them.
Maybe you always want to have the most accurate and up-to-date data,
but you don't want to watch for fixes and updates
to calendarium-romanum
, and there is a regularly updated instance
of calendar API out there.
In all these cases it is convenient to use calendarium-romanum-remote
instead of building a regular Calendar
in your application.
Usage
Load by
require 'calendarium-romanum'
require 'calendarium-romanum/remote'
or by a shortcut
require 'calendarium-romanum-remote'
CR = CalendariumRomanum
# create by specifying a year and remote calendar URI
calendar = CR::Remote::Calendar.new(2016, 'http://calapi.inadiutorium.cz/api/v0/en/calendars/general-la/')
# use the same way as the normal Calendar, get the same return values
day = calendar.day Date.new(2016, 12, 24)
As most abstractions, also the one of Remote::Calendar
is
leaky:
a whole bunch of errors specific to the network communication
taking place in the background can occur.
CR = CalendariumRomanum
calendar = CR::Remote::Calendar.new(2016, 'http://calapi.inadiutorium.cz/api/v0/en/calendars/general-la/')
begin
day = calendar.day Date.new(2016, 12, 24)
rescue CR::Remote::UnexpectedResponseError
# the server responded with some "unhappy" HTTP status code
rescue CR::Remote::InvalidDataError => err
# data returned by the server were not understood
rescue HTTPI::Error
# parent class of lower-level network errors raised by HTTPI -
# see its documentation or source for the specific exception
# classes
end
Important implementation details
Under the hood HTTPi is used to issue HTTP requests
and multi_json for JSON deserialization.
Both gems provide uniform public interfaces while allowing
you to choose among several implementations.
calendarium-romanum-remote
deliberately does not make any
choice concerning the implementations and leaves this up to you.
There are sensible defaults working out of the box,
but it's advisable to check both gems' documentation to see
what options you have and how to make use of them.
The following example configures curb
to be used internally
as HTTP client and oj
as JSON deserializer.
require 'curb'
require 'oj'
require 'calendarium-romanum-remote'
HTTPI.adapter = :curb
MultiJson.adapter = :oj
License
freely choose between GNU/LGPL 3 and MIT