Notification Service

• Authors: Last, First (ORCID); ...
• License: Apache 2
• Package source code on GitHub
• Submit Bugs and feature requests
• Contact us: support@dataone.org
• DataONE discussions

Notification Service provides a notification system for datasets and portals, to notify both portal owners/editors and the community about events such as downloads, views, citations, derived products, new datasets added to a portal, reminders to update a portal, etc.

DataONE in general, and notification-service in particular, are open source, community projects. We welcome contributions in many forms, including code, graphics, documentation, bug reports, testing, etc.

Use the DataONE discussions to discuss these contributions with us.

Documentation

Documentation is a work in progress, and can be found here in the README

API Usage Examples

Example API interactions, using curl:

# BASE_URL: the base URL of the notification service instance you're using
# TOKEN: a valid JWT token from the CN used by the installation under test
#
BASE_URL="https://notifications.test.dataone.org"
TOKEN="your-jwt-token-here"

# Subscribe user authenticated with jwt $TOKEN, to update-notifications for
# the dataset identified by {pid}
#
$ curl --request POST "${BASE_URL}/notifications/datasetChanges/{pid}" \
       --header "Authorization: Bearer $TOKEN"  |  jq

# Get a list of subscriptions for user authenticated with jwt $TOKEN:
#
$ curl --request GET "${BASE_URL}/notifications/datasetChanges" \
       --header "Authorization: Bearer $TOKEN"  |  jq

# Unsubscribe user authenticated with jwt $TOKEN, from notifications for the
# dataset identified by {pid}
#
$ curl --request DELETE "${BASE_URL}/notifications/datasetChanges/{pid}" \
       --header "Authorization: Bearer $TOKEN"  |  jq

Tip

You can get an auth token by logging into a metacat instance that uses the same CN as the installation being tested. For example:

• If it's a Production notification service, it should use https://cn.dataone.org/cn/v2; get a token from any prod metacat, e.g. arcticdata.io
• If it's a test/development notification service, it will likely use https://cn-stage-2.test.dataone.org/cn/v2; get a token from the nceas dev metacat

Getting Started - Running Notification Service Yourself

The simplest way to try out the notification service is to use the Helm chart to deploy in a Kubernetes cluster.

For example, assuming you have installed and started Rancher Desktop and ingress-nginx on your local machine, it's easy to install the latest Helm chart:

helm upgrade --install ns --debug -n notifications --create-namespace \
    -f ./helm/examples/values-dev-cluster-ns-example.yaml \
    oci://ghcr.io/dataoneorg/charts/notifications

Caution

This is a simplified process, for evaluation purposes only, and is not intended for production use, since it uses defaults for the namespace, release name and secret credentials.

For production use, you should set credentials appropriately, and may need to override more of the values.yaml settings.

Developer Guide

This section is for developers who want to build, modify, or test the application, or run it locally on their development machine.

Jakarta EE

Notification Service uses the Jakarta EE framework. Jakarta EE is the latest version of what was formerly Oracle's Java Enterprise Edition (originally J2EE). It has now been moved to the Eclipse Foundation, where it is maintained as open source software.

Here are some useful links for those unfamiliar with Jakarta EE:

• Jakarta EE 10
• Jakarta EE 10 API
• Jakarta EE REST Service Tutorial

Development build

This is a java application, built using the Maven build tool.

Note

Prerequisites: The build and tests require:

1. Java 21. It can be downloaded from Adoptium. You can also set Java 21 as the default for only the current directory, using the simple, lightweight jenv tool. This allows you to set global and local Java versions, and switch between them easily.
2. Maven v3.9+.

$ mvn clean package  [ -DskipTests ]

Running the Tests

The tests and their resources all reside in the src/test/java directory. They fall into three categories, and it is important to distinguish between them and adhere to their respective conventions:

Unit Tests

Unit tests are intended to test individual classes and methods.

Important

Unit tests must have all their dependencies mocked out. They should NEVER require a running instance of the application, or other components like a database.

Unit tests are named *Test.java, and are run using the Maven test goal:

mvn clean test

Integration Tests

Integration tests are intended to test the integration and interactions of multiple classes or modules.

Important

Integration tests should NEVER require a running instance of the application (See Smoke Tests). They may, however, rely on other components (such as a database), which are provided and managed by the test framework. (For example, see TestUtils::getTestDb, which uses TestContainers). This enables the test suite to be self-contained, so it will run in CI/CD pipelines.

Integration tests are named *IT.java, and are run using the Maven verify goal (which also runs the unit tests first):

mvn clean verify

Smoke Tests

Smoke tests are intended to be executed against a running instance of the application (e.g. in production), to verify that it is working as expected, after installation or upgrade.

Smoke tests are named *SmokeIT.java, and are run using the Maven verify goal, with the following additional command-line args:

• -PsmokeTest: this tells Maven to run only the smoke tests.
• -DBASE_URL: the base URL of the notification service instance you're using
• -DTOKEN: a valid JWT token from the CN used by the installation under test (see API Usage Examples for details of how to get a token)

# Can set this as an environment variable, to maintain secrecy:
export TOKEN="your-jwt-token-here"

mvn verify -PsmokeTest -DBASE_URL="https://notifications.test.dataone.org" -DTOKEN="$TOKEN"

Building and Running on a Localhost Web Application Server

Note

Prerequisites: In addition to the Java and maven versions listed above, you will need:

1. Apache TomEE v10+ (or another web application server that is fully compliant with Jakarta EE 10. Tomcat version 10 is NOT yet fully compliant with Jakarta EE 10, so for the time being, it is recommended to use Apache TomEE, which is an Apache-maintained combination of Tomcat and the additional libraries needed to support Jakarta EE.)
2. A running PostgreSQL database. This can easily be started in a container, using the provided script:

./scripts/docker-run-db.sh

Build with maven and copy the war file to your TomEE webapps directory:

$ mvn clean package -DskipTests

$ cp ./target/notification-service-[VERSION].war $TOMEE_HOME/webapps

...and (re)start TomEE. You can then visit the URL: http://localhost:8080/notifications/metrics/ping, which should return {"status":"ok"}. You can also validate that the service is working correctly by running the smoke tests.

License

Copyright [2024] [Regents of the University of California]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Acknowledgements

Work on this package was supported by:

• DataONE Network
• Arctic Data Center: NSF-PLR grant #2042102 to M. B. Jones, A. Budden, M. Schildhauer, and J. Dozier

Additional support was provided for collaboration by the National Center for Ecological Analysis and Synthesis, a Center funded by the University of California, Santa Barbara, and the State of California.