= GeoNetwork on a read-only database =

|| '''Date''' || 2013-01-22 ||
|| '''Contact(s)''' || Heikki Doeleman ||
|| '''Status''' || Done ||
|| '''Assigned to release''' || 2.9.x ||
|| '''Resources''' || Available (funding EEA) ||
|| '''Ticket #''' || #1216 ||
|| '''Github dev branch ''' || https://github.com/heikkidoeleman/core-geonetwork/tree/eeareadonly ||

== Overview ==

This proposal aims to improve GeoNetwork's behaviour when it is running on a read-only database. A use case for this is that some users wish to set up their DBMS in a master/slave cluster, where the slave is read-only. When the master fails, the slave is automatically activated but is not automatically no longer read-only. 

Without the changes in this proposal GeoNetwork, in such a scenario, would keep trying to write to the database, both behind the screens (e.g. periodic harvesters) or in response to user interaction (e.g. view a metadata, its popularity is increased). This leads to exceptions that slow the system down and further deteriorate the user experience by returning error responses.


=== Proposal Type ===
 * '''Type''': Back-end change, GUI change
 * '''App''': !GeoNetwork
 * '''Module''': main, web-client

=== Links ===
 * '''Documents''': 

=== Voting History ===
 * Vote proposed on 31-01-2013.
 * +1 (1): Emanuele Tajariol, François Prunayre. Proposal accepted.
 * 0 (0)
 * -1 (0)

== Motivations ==

== Proposal == 

=== read-write services ===

A new abstract class !NotInReadOnlyModeService is introduced, which will be the base class of all services that do CUD (create, update, delete) operations on the DB. This class implements Jeeves' Service as do all services. Its {{{exec()}}} method checks whether GeoNetwork is running in read-only mode and if so, it does nothing. If not, it delegates to {{{serviceSpecificExec()}}}, where the affected services should put their normal (non-read-only) execution code.

=== harvesters ===

When !HarvesterManager is initialized, it takes GN's read-only mode status from the !GeonetContext. If it is in read-only mode, harvester operations {{{run}}} (periodic) and {{{invoke}}} (user-instigated) do nothing.

=== determining read-only status ===

The read-only status of GeoNetwork is determined by a periodic 'DB heartbeat' that attempts to write (and delete) a value in the database. If the situation changes (i.e. GN is not read-only but fails to write, or GN is read-only but succeeds writing) the read-only status of GN is dynamically adapted. The heartbeat's initial and fixed delay in seconds can be set in config.xml and have default values 5 and 60. The heartbeat is disabled by default and can be enabled in config.xml by setting parameter DBHeartBeatEnabled to true.

=== other changes ===

There are cases where the DB-writing part of a service is that small that it is better to restrict these writes at a level below the service, to still allow the service to run also in read-only mode. An example is metadata view: this service write to the DB updating the metadata's popularity. Even so it is not made a !NotInReadOnlyModeService, so also in read-only mode you can still use this service; instead the db-writing part is made conditional on readonly state at a level below the service. (of course this may be seen as a design flaw in the service behaviour and you could argue that there should exist a separate service to update the popularity -- but refactoring is outside the scope of this proposal). 

=== Capabilities ===

When GeoNetwork is in read-only mode, the CSW Publication operations (Transaction and Harvest) are not returned in response to a CSW !GetCapabilities request.

=== GUI ===

It is recommended that the GN GUI does not display any link to a service that is culled in a read-only situation. This proposal includes doing that in the Classic and Ext GUIs. An example of what the admin page looks like when GN is in readonly mode is this:


[[Image(admin.png)]] 


=== Testing ===

In config.xml, set the maxIdle connection parameter to 0 to force the pool to request new connection:
{{{
   <minIdle>0</minIdle>
   <maxIdle>0</maxIdle>
}}}

Change the DB read/write mode using:
{{{
-- For postgres
ALTER DATABASE eea_catalogue SET default_transaction_read_only = true;
}}}

The DBHeartBeat status will change in the log:
{{{

2013-01-25 18:10:21,122 WARN  [jeeves.apphand] - DBHeartBeat SQLException: ERROR: cannot execute INSERT in a read-only transaction
2013-01-25 18:10:21,123 INFO  [jeeves.apphand] - GeoNetwork remains in read-only mode
2013-01-25 18:10:41,123 INFO  [jeeves.apphand] - DBHeartBeat: GN is read-only ? true
2013-01-25 18:10:41,141 WARN  [jeeves.apphand] - GeoNetwork can write to the database, switching to read-write mode

}}}


=== Backwards Compatibility Issues ===

None.

=== New libraries added ===

None.

== Risks ==

Everything involves some element of risk....

== Participants ==
 
 * Heikki Doeleman
 * François Prunayre