# General documentation for RAS project

## OVERVIEW

Main parts of the system:

- Handle-Template Service (HTS), BB#1
- Abstract RePEc Database (ARDB), BB#2
- HoPEc Web Interface (HWI)
- Control Daemon (CD)

At least HTS and ARDB have to be well-designed black-boxes, suitable for easy reuse by other software.

Black-Box means that the module has very limited, but logically complete and clear external interface. Often a black-box module can provide some useful functionality.

## GLOSSARY of TERMS

- template
- attribute
- cluster
- handle
- template type
- cluster type
- template hash structure
- full template (unfolded template?)
- relation triple:
  - subject
  - relation type (predicate)
  - object
- source
- ARDB operation: get, put, delete

    my $t = get_template ();

    my $title = $t -> {title}[0];
    my $author = $t -> {author}[0]{name}[0];

## Module HTS [BB#1]:

## Module ARDB [BB#2]:

### Responsibilities:

- store template relations and serve applications with "full templates"
- serve as a framework for customizable template's data storage (for HoPEc-specific tables as an immediate example)

### Relies on:

(HTS), HoPEc-DB

### Main parts:

- Configuration
- Relations Service
- ARDB itself (THE main part)

### Interface:

put template ( $template )
get full template ( $template_handle )
delete template ( $source )
initialize database ()
get database status ()

### ARDB Configuration:

    The configuration purpose is to describe how ARDB should process
    templates.  That includes description of:

      - extracting relations from templates

      - storing data in HoPEc-specific tables

    Configuration would consist from one or more sections.  Sections may be
    of several types.

    Section of type "relations" would define:

      - section's unique id (?)

      - template types and attribute names (in those template types) to which
        section applies [required]

        Attribute name in fact should be something more complex.  It should be
        "attribute specification" in the sense, that it must be able to point
        to attributes in clusters.  May be that would have syntax like:
        "author/name" or similar.

        The section would apply to every attribute matching the attribute
        spec if the template is of one of the given types.

      - forward and reverse relation type name, that will be extracted
        from the template & the attribute.  That will go into "relation"
        block in configuration. ("relation" XML element").

        Whenever there is no reverse relation, forward will serve both.
        Forward relation type name is required.

        undirected will

Sample of how configuration and related processing might look like:

    <?xml version="1.0"?>

    <configuration>

      <section
    	    id='id'
    	    template_types='ReDIF-Person 1.0'
    	    attribute_spec='author-software,author-paper,author-article'
    	    >

        <relation forward='wrote' reverse='written-by' />
      </section>

      <relation retrieve='handle|template|nothing' name='written-by' />

      <relation name='cited-by'>
        <retrieve-as-hash as='title' from='template:title' />

        <retrieve-as-hash as='handle' from='template:handle' />

        <retrieve-as-hash as='author-names' from='template:author/name' />
      </relation>

      <relation retrieve='' name='rejected-authorship' />

      <section relation='written-by' id='#1' />
    </configuration>

      $per_t -> {'author-software'}[0] == 'pap_handle';
      $per_t -> {'handle'}[0]             == 'per_handle';

    put template ( $per_t ):

    relations table:

    subject		relation 	object 		source
    --------------------------------------------------------------------
    per_handle	wrote		pap_handle	per_handle

    get full template( per_handle ):

      $per_ft -> {'wrote'}[0] == $pap_template;

    get full template ( pap_handle ):

      $pap_ft ->{'written-by'}[0] == $per_t;

### RELATIONS TABLE SAMPLE RECORDS:

    subject	      	relation 		object 		source
    --------------------------------------------------------------------------------
    per_handle	affiliated-with		inst_handle	per_handle
    per_handle	wrote			pap_handle	per_handle
    pap_handle	maybe-written-by 	per_handle2	pap_handle
    per_handle	rejected-authorsip	pap_hadle2	per_handle
    wrote		reverse-of		written-by 	relations-config
    written-by	reverse-of		wrote		relations-config
    written-by	ignore-upon-get   	true		relations-config
    pap_handle	cited-by		pap_handle2	citec:pap_handle
    pap_handle	cites			pap_handle3	citec:pap_handle

    get full template ( per_handle ):

      $per_ft ->{'rejected-authorship'}[0] == 'pap_handle2';

### Attribute specifications ideas

#### now:

    "author/name"
    $template->{author}->[0]->{name}->[0];

#### future?:

    "author/name"
    $template->{author}->{name};

    "author"
    $template->{author} = 'scalar';

    "author@"
    $template->{author} = [ 'scalar' ];

    "author@/name"
    $template->{author}->[0]->{name} = [ 'scalar' ];

    "author[]/name@"
    $template->{author}->[0]->{name} ->[0]= 'scalar';

## Plugins

Плагины есть двух условных типов: Input и Output.

Input плагины будут отвечать за поставку данных в систему. HTS будет одним из input плагинов. Input плагины будут привлекаться к обработке операций GET FULL TEMPLATE. Каждый input плагин будет отвечать за определенное пространство имен (идентификаторов) записей. То есть каждый плагин будет заявлять список префиксов. Когда ARDB понадобится извлечь (первичную) запись с определнным идентификатором, она просматривает список префиксов, сравнивая искомый идентификатор с префиксами. Должен найтись один и только один подходящий плагин.

Пример: запрос на запись RePEc:bon:bonsfa:198. Среди input плагинов должен быть HTS, заявивший свою ответственность за "RePEc:". Именно он и получит этот запрос и должен будет его обработать.

Output плагины будут обрабатывать входящие в систему данные, т.е. они будут задействоваться при обработке операции PUT TEMPLATE. Output плагины могут сообщать системе, какого типа записи они могут/должны обрабатывать.

Все плагины - это перл модули в "ARDB::Plugin::" package namespace. Input плагины: в "ARDB::Plugin::Input::", output - соответственно в "ARDB::Plugin::Output::". Плагин имеет имя, и свою собственную директорию в ARDB home dir/Plugins/Input/ или в home/Plugins/Output/. Плагин сам отслеживает свое состояние и все параметры, необходимые ему для работы. И он должен отвечать на запросы ARDB относительно состояния: ready or not. В случае "not ready" плагину предложат провести инициализацию. Плагины могут (для их удобства, но не обязаны) наследовать от класса "ARDB::Plugin", или Уоответственно ::Input или ::Output. В любом случае, что бы работать плагин обязан выполнять общие требования интерфейса. В частности: методы get status, initialize. Для Input: get prefixes, get record ( handle ). Output: get record types, process record ( record ).