diamondlightsource / gda-ispyb-api Goto Github PK

Library for writing acquisition metadata into an ISPyB database

License: Apache License 2.0

Java 99.54% Shell 0.46%

gda-ispyb-api's Introduction

GDA ISPyB API

This is a Java library for accessing a Diamond-flavour ISPyB database. It's designed for server-side-only usage, utilising stored procedures to access the database tables. A key benefit of this approach is the ability to modify the behaviour of the library methods without downtime and without building and deploying a new version of the library itself. A simple change to a stored procedure is very quick and runs in a transaction without disrupting access to the database.

The stored procedures are maintained in a separate repository: ispyb-database.

Build requirements

MariaDB 10.3 or later
JDK 1.8 (also appears to work with 11) JRE and development packages (e.g. on Fedora: java-1.8.0-openjdk java-1.8.0-openjdk-devel)
Maven

Documentation

The javadocs are currently hosted at https://alfred.diamond.ac.uk/documentation/javadocs/gda-ispyb-api/.

Examples

For example usage, see the integration tests, e.g. PlateIntegrationTest.

Tests

To create the database user, run e.g. these SQL commands:

CREATE USER maven@localhost IDENTIFIED BY 'password_here';

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, EXECUTE, CREATE VIEW, SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, EVENT, TRIGGER ON `maven\_%`.* TO 'maven'@'localhost';

To build and test the JARs:

mvn -Dispyb.url={jdbc_url} -Dispyb.user={user} -Dispyb.pw={password} -Dispyb.host={host} -Dispyb.port={port} package

Example:

mvn -Dispyb.url='jdbc:mariadb://localhost:3306' -Dispyb.user=maven -Dispyb.pw='password_here' -Dispyb.host=localhost -Dispyb.port=3306 package

To run a particular test class:

mvn -Dispyb.url={jdbc_url} -Dispyb.user={user} -Dispyb.pw={password} -Dispyb.host={host} -Dispyb.port={port} -Dtest={TestClassName} test

To generate javadocs:

mvn -Dispyb.url={jdbc_url} -Dispyb.user={user} -Dispyb.pw={password} -Dispyb.host={host} -Dispyb.port={port} install

The javadocs will then appear in a folder called target/apidocs/.

Release

To release, use the script release.sh with the argument major, minor, or bugfix. This script will handle updating the version. The result will be added to GitHub as a release by Azure Pipelines.

gda-ispyb-api's People

Contributors

Stargazers

Watchers

Forkers

gerring mtwharmby jamesmudd callumforrester jlmuir tpoliaw keeble collang

gda-ispyb-api's Issues

Consider IspybApi tag interface

I note that grouping stored procedure access by interface has commenced with IspybPlateApi and IspybPdfInterface.

rather than eliminating the IspybApi interface class, consider using it as a tag interface (no methods) that any new API group extends. For example:
IspybPlateApi extends IspybApi.

This may assist maintaining references to a collection of implementations when sophisticated clients need access to more than one.

Replace plugin dependency with package import

The 2 plugins uk.ac.diamond.ispyb.api and uk.ac.diamond.ispyb.jdbc have dependencies on specific bundles to supply spring framework (org.apache.servicemix.bundles.spring-*).

Unfortunately this is problematic when those plugins are consumed by another project that has its own idea of what should supply the spring framework (eg GDA uses uk.ac.diamond.org.springframework). Currently, GDA ends up with multiple bundles that supply the same version of the same packages, with attendant build failures.

One option is to change the bundles in this project to have package dependencies only, which could be satisfied in this project's build by the apache servicemix bundles, and in the GDA build by their own bundling. An equivalent change could in theory be made on the GDA side, but for various reasons that's harder to do.

Note: you will also need to remove the bundle dependency from uk.ac.diamond.ispyb.feature

Add plugin dependencies into uk.ac.diamond.ispyb.feature

Please add to uk.ac.diamond.ispyb.feature the following plugin dependencies.

org.apache.commons.lang3
org.mariadb.jdbc

They are already plugin (not package) dependencies of uk.ac.diamond.ispyb.api, and should be in the feature as well.

Consider enum or tag identifier for each IspybApi grouping interface

There currently exist two interface classes providing access to distinct sets of stored procedures. it is foreseeable that there will be more, and that some clients may need to use more than one. (eg a read_only set of methods, and a finite set of create methods).

Consider using an enum (or a String identifier) for each. This will assist a client identifying which API sets of methods it has access to.

This could also simplify your Dao Factories by using the identifier as a parameter to a single multi-purpose factory, removing the need to add another factory method to the interface every time a new implementation group is created. The single factory method can still delegate to an extension for that type.

Change API parameters and return types from primitives to appropriate class types

Parameters and return types on the API may potentially be nullable.
Easiest to avoid any related problems if all API parameters and return types avoided primitives in their signatures.

Done for v1.0.9 but newer API extensions waver from this practice.

Retrieving a row containing datetime fields == null gives ConversionException

(The below test is currently on the SCI-8216 branch only.)

If I remove the setStarttime and setEndtime lines in the testRetrieveDataCollectionGroup test, I get an error like below. However, it should be possible to retrieve rows where a datetime field is null, so this is a bug that needs fixing.

[ERROR] testRetrieveDataCollectionGroup(uk.ac.diamond.ispyb.test.DataCollectionIntegrationTest) Time elapsed: 0.037 s <<< ERROR!
org.apache.commons.beanutils.ConversionException: No value specified for 'java.sql.Timestamp'
at uk.ac.diamond.ispyb.test.DataCollectionIntegrationTest.lambda$testRetrieveDataCollectionGroup$9(DataCollectionIntegrationTest.java:155)
at uk.ac.diamond.ispyb.test.DataCollectionIntegrationTest.testRetrieveDataCollectionGroup(DataCollectionIntegrationTest.java:155)

Use Long integers for primary key fields

Where primary keys are returned or used as parameters, our drivers use Long integer types.
Casting exceptions are thrown where this is not specified.

Done in v1.0.9 but not consistent on master branch.