https://github.com/mbari-org/mxm-java-client
MXM Java Client Library (WIP)
https://github.com/mbari-org/mxm-java-client
Last synced: 10 months ago
JSON representation
MXM Java Client Library (WIP)
- Host: GitHub
- URL: https://github.com/mbari-org/mxm-java-client
- Owner: mbari-org
- Created: 2020-01-08T00:26:08.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2022-08-03T18:36:57.000Z (over 3 years ago)
- Last Synced: 2025-02-04T21:43:19.652Z (11 months ago)
- Language: Java
- Homepage:
- Size: 66.4 KB
- Stars: 0
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
Awesome Lists containing this project
README
# MXM Java Client Library
This project's goal is to build a client library to allow tools and
applications on the JVM to interact with mission execution systems ("providers")
through an MXM service.
**NOTE**: This client library has been put together as needed for demonstration
of integration tools like Neptus.
In the future, a more comprehensive client library will likely be based on
auto-generation from the relevant API spec, GraphQL schema or OpenApi.
What follows are notes from initial development of this project,
plus some more recent edits.
---
**Status**:
- A preliminary version of the library is already available
for initial testing (only informational queries at the moment).
- The MXM service itself, including its API, is also in a prototypical stage
so the API in general is not stable.
## Using the library
The library as well as the javadoc (in a separate JAR) are made available at
https://github.com/mbari-org/mxm-java-client/releases/.
Besides the `mxm-java-client-x.y.z.jar` library, you will also need the
[Apache httpclient](https://search.maven.org/artifact/org.apache.httpcomponents/httpclient)
and the
[Google Gson](https://search.maven.org/artifact/com.google.code.gson/gson)
libraries in your CLASSPATH.
> Under a clone of this repo, and with [`mvn`](https://maven.apache.org/) on your PATH,
> you can run the demo program with `mvn compile exec:java -Dexec.mainClass="MxmClientMain"`.
As indicated in the included [demo program](src/main/java/MxmClientMain.java),
you will construct an instance of the `MxmClient` class providing the URL of the MXM endpoint,
and then make queries and requests as needed:
```java
MxmClient mxm = new MxmClient("http://mxm.shore.mbari.org/mxm-graphql");
// general info about providers:
List providers = mxm.getProviders();
...
// more detailed info about a particular provider:
Optional ox = mxm.getProvider("foo-provider");
...
// detailed info about a mission template:
Optional omt = mxm.getProviderMissionTemplate("foo-provider", "bar-mtempl");
...
// detailed info about a mission:
Optional omt = mxm.getMission("foo-provider", "bar-mtempl", "some-mission");
...
```
Part of the demo program's output is enclosed below.
## General information
The GUI of the current MXM service prototype is at http://mxm.shore.mbari.org/mxm/.
The corresponding MXM API endpoint is `http://mxm.shore.mbari.org/mxm-graphql`.
A [GraphiQL](https://github.com/graphql/graphiql) interface is available
at http://mxm.shore.mbari.org/mxm-graphiql.
This is **highly recommended** as a great tool for general inspection of the
available information, and in particular to then let us know about pieces of
information that should be included and/or that may not yet be visible through
this client library.
## Demo program
The following is part of the output generated by the included demo program
[`MxmClientMain`](src/main/java/MxmClientMain.java) when run
against the API endpoint indicated above:
```
mxm-client library version: 0.1.1
==== all providers response ====
[{
"providerId": "TethysDash",
"description": "TethysDash/LRAUV System",
"httpEndpoint": "http://tethyssim.shore.mbari.org:8080/TethysDash/api/mxm",
"apiType": "REST0",
"canValidate": false,
"usesSched": true,
"usesUnits": true
}]
==== provider providerId='TethysDash' ====
{
"providerId": "TethysDash",
"description": "TethysDash/LRAUV System",
"httpEndpoint": "http://tethyssim.shore.mbari.org:8080/TethysDash/api/mxm",
"apiType": "REST0",
"canValidate": false,
"usesSched": true,
"usesUnits": true,
"missionTemplates": [
{
"missionTplId": "Science/75m_isobath",
"assetClasses": [
{
"assetClassName": "LRAUV"
}
]
},
{
"missionTplId": "Science/chlpeak_sampling_InAboveBelow",
"assetClasses": [
{
"assetClassName": "LRAUV"
}
]
},
{
"missionTplId": "Science/circle_acoustic_contact",
"description": "This mission runs a circle around a specified acoustic contact. The\ntracking behavior periodically queries the DAT for range and direction\nto the contact, and the DAT acoustically interrogates the contact. The\ntracking component then calculates the position of the contact to update\nthe center of the circle. When the vehicle surfaces and updates its own\nposition with GPS, it queries the contact again, then sends the contact\nposition to shore.",
"assetClasses": [
{
"assetClassName": "LRAUV"
}
]
},
```
## Release
Note that automated releases are in place as part of enabled CI.
### manual release
Set `version` in `pom.xml` as needed.
mvn package
generates: `target/mxm-java-client-x.y.z.jar`
---
What follows TO BE UPDATED
cp out/mxm/docJar/dest/out.jar ./mxm-java-client-${MXM_VERSION}-javadoc.jar
Then upload the artifacts to github.
### javadoc
The following is only a dev convenience to update the javadoc in our internal server.
```
mill mxm.docJar
scp out/mxm/docJar/dest/out.jar mxmadmin@mxm.shore.mbari.org:/var/www/html/java-client-doc/javadoc.jar && \
ssh mxmadmin@mxm.shore.mbari.org <<'EOF'
cd /var/www/html/java-client-doc/
unzip -o ./javadoc.jar
EOF
```