jmyapi

A Java client query API library for MYA (JLab's EPICS Archiver).

---

• Overview
• Quick Start with Compose
• Install
• API
• Configure
• Build
• Test
• Release
• See Also

---

Overview

The Jeffeson Lab EPICS archiver is named MYA, and was designed with command line and C++ APIs. This library provides a native Java API for querying MYA. If you are looking for a quick and easy way to obtain MYA data see: Public MYA Web Service, which is built using this API plus myquery.

Quick Start with Compose

1. Grab project

git clone https://github.com/JeffersonLab/jmyapi
cd jmyapi

2. Launch Compose

docker compose up

3. Run hello app

gradlew hello

Install

The library requires a Java 8+ JVM and standard library at run time, plus has a dependency on the MariaDB database driver.

You can obtain the jmyapi jar file from the Maven Central repository (or Sonatype Backing Store) directly or from a Maven friendly build tool with the following coordinates (Gradle example shown):

implementation 'org.jlab:jmyapi:<version>'

Check the Release Notes to see what has changed in each version.

API

• Javadocs

Example

jmyapi/src/test/java/org/jlab/mya/HelloWorld.java

Lines 27 to 47 in 36e9f0b

	DataNexus nexus = new OnDemandNexus("docker");
	for (String name : DataNexus.getDeploymentNames()) {
	System.out.println(name);
	}
	String pv = "channel1";
	Instant begin = TimeUtil.toLocalDT("2019-08-12T00:00:00.123456");
	Instant end = TimeUtil.toLocalDT("2019-08-12T00:01:00.123456");
	Metadata<FloatEvent> metadata = nexus.findMetadata(pv, FloatEvent.class);
	try (EventStream<FloatEvent> stream = nexus.openEventStream(metadata, begin, end)) {
	FloatEvent event;
	while ((event = stream.read()) != null) {
	System.out.println(event.toString(6));
	}
	}
	}

Configure

Deployments

A deployments.properties file must be included in the runtime classpath to indicate the host names of MYA servers. A template for the properties can be found here.

Credentials

A credentials.properties file must be included in the runtime classpath to indicate the MariaDB username and password to use. A template for the properties can be found here.

Note: An alternative is to use a JNDI DataSource via the PooledNexus instead of using the OnDemandNexus with a credentials file. A PooledNexus is often used with an application server such as Tomcat. See DataSource Notes.

Proxies

If the environment variable JMYAPI_USE_PROXY=true then the proxy hostnames defined in deployments.properties will be used instead of the normal hostnames. This is specifically used when running jmyapi on a localhost workstation with mya inside a docker bridged network.

Build

This project is built with Java 17 (compiled to Java 8 bytecode), and uses the Gradle 7 build tool to automatically download dependencies and build the project from source:

git clone https://github.com/JeffersonLab/jmyapi
cd jmyapi
gradlew build

Note: If you do not already have Gradle installed, it will be installed automatically by the wrapper script included in the source

Note: Jefferson Lab has an intercepting proxy

Develop

You can use the pre-configured .devcontainer else Install and Build directly on a local workstation.

Test

The unit tests run automatically upon build. Integration tests are separate and require a docker compose environment (MariaDB database).

Localhost Compose env

1. Launch Docker:

docker compose up

2. Run integration tests (on localhost forwarded ports):

gradlew localIntegrationTest

Sibling Dev Container env

gradlew integrationTest

Release

1. Bump the version number in the VERSION file and commit and push to GitHub (using Semantic Versioning).
2. The CD GitHub Action should run automatically invoking:
   • The Create release GitHub Action to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.
   • The Publish artifact GitHub Action to create a deployment artifact on maven central.
   • The Publish docs GitHub Action to create javadocs.

See Also

• Developer Notes
• myquery
• trippy