Resources-specific Handler

A handler is a python class that is plugged into the generic TimeGate to fit any specific technique a web server has to manage its Original Resources and Mementos. Its role is simple: to retrieve the list of URI-Ms (with their archival dates) given a URI-R. It typically does so by connecting to an API.

Alternatives

  • If no API is present: The list can be retrieved from many different ways. Page scraping, rule-based or even in a static manner. Anything will do.
  • If the history cannot be retrieved entirely: The handler can implement an alternative function that returns one single URI-M and its archival datetime given both URI-R and the datetime the user requested.
  • If the TimeGate’s algorithms that select the best Memento for a requested date do not apply to the system: Implementing the alternative function could also be used to bypass these algorithms. This is particularly useful if there are performance concerns, special cases or access restriction for Mementos.

Requirements

_images/code_architecture.png

A handler require to have the following:

  • It must a python file placed in the core.handler module (which is the core/handler/ folder). And it must be unique. If several classes are needed, or to switch quickly between handlers, consider adding the handler module path manually in the configuration file. (See Configuring the server.)
  • A handler must extend the core.handler_baseclass.Handler base-class.
  • Implement at least one of the following:
    • get_all_mementos(uri_r) class function: This function is called by the TimeGate to retrieve the history an original resource uri_r. The parameter uri_r is a Python string representing the requested URI-R. The return value must be a list of 2-tuples: [(uri_m1, date1), (uri_m2, date2), ...] . Each pair (uri_m, date) contains the URI of an archived version of R uri_m, and the date at which it was archived date.
    • get_memento(uri_r, requested_date) class function (alternative): This function will be called by the TimeGate to retrieve the best Memento for uri_ at the date date. Use it if the API cannot return the entire history for a resource efficiently or to bypass the TimeGate’s best Memento selection. The parameter uri_r is a Python string representing the requested URI-R. The parameter date is a Python datetime.DateTime object. In this case, the return value will contain only one 2-tuple: (uri_m, date) which is the best memento that the handler could provide taking into account the limits of the API.
  • Input parameters:
    • All parameter values uri_r are Python strings representing the user’s requested URI-R.
    • All parameter values requested_dateare datetime.DateTime objects representing the user’s requested datetime.
  • Output return values:
    • All return values uri_m must be strings.
    • All return values date must be strings representing dates. Prefer the ISO 8601 format for the dates.
  • Note that:
    • If both functions are implemented, get_memento(uri_r, requested_date) will always be used for TimeGate requests.
    • If the TimeMap advanced feature (see TimeMaps) is enabled, get_all_mementos(uri_r) must be implemented.

Example

A simple example handler is provided incore/handler/ and can be edited to match your web server’s requirements: - See example.py Which returns static lists.

Other handlers examples are provided for real world APIs in core/handler_examples/ for instance:

Other scraping Handlers examples are provided for real world resources without any API: