The Mapper maps URI identifiers to resources based on content negotiation. It is the place an ID is created and mapped to a resource.
From that point on the mapped URI becomes a permalink that will always resolve.
The mapper manages de-duplication of resources by allowing you to move a mapping from one resource identifier to another. It also manages deletion of resources allowing you to provide a reason for deleting a resource, which is returned with a 410 GONE http response.
You can map a URI to different servers based on the content type requested, e.g. JSON, XML, RDF, HTML.
For info on how it works, data structure and API see: doc/guide.adoc
This software is copyright (c) 2019 Australian National Botanic Gardens
This file is part of National Species List project.
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 http://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.
See: LICENSE.adoc
SDK Man is your friend for installing SDKs including Java, Grails etc.
You need Java 8 installed and on your PATH. Type java -version from the command line to check. You should
get something like:
openjdk version "1.8.0_222" OpenJDK Runtime Environment (build 1.8.0_222-b10) OpenJDK 64-Bit Server VM (build 25.222-b10, mixed mode)
If you need to install one try (YMMV):
sdk install java 8.0.222-adpt
-
Install postgresql
-
Create a super user called "nsl" with the password "nsl":
created user -s nsl -
edit pg_hba.conf so that local interfaces can talk to postgresql with a password:
...
# TYPE DATABASE USER ADDRESS METHOD
...
# IPv4 local connections:
host all all 0.0.0.0/0 md5 #(1)
...-
md5 is a hashed password authentication over TCP and listen on all addresses
|
Tip
|
Open port 5432 on any local firewall if you are using Docker so that the app can connect. |
If you don’t have a mapper schema, you can need to create the schema. Get the test/resource/ddl.sql from the GitHub
repository and run:
dropdb --if-exists nsl && createdb nsl && psql -f ddl.sql nsl
|
Warning
|
Don’t drop the nsl database if it has data you want to keep in it! You could just drop the mapper schema. |
|
Tip
|
You can call your DB something else if you like, just change references to it |
Make a local configuration file called nsl-mapper-config-mn.groovy and put it in a directory like `~/.nsl/ (see the docs/guide.adoc).
This is a basic config that will get you running assuming you have a local database called "nsl" with a user called "nsl" and password "nsl".
import au.org.biodiversity.mapper.Identifier
mapper {
resolverURL = 'http://localhost:8080/nsl-mapper' //(1)
defaultProtocol = 'http'
Closure defaultResolver = { Identifier ident ->
Map serviceHosts = [
apni: 'https://localhost:8090/nsl' //(2)
]
String host = serviceHosts[ident.nameSpace]
if (ident.objectType == 'treeElement') {
return "${host}/services/rest/${ident.objectType}/${ident.versionNumber}/${ident.idNumber}"
}
return "${host}/services/rest/${ident.objectType}/${ident.nameSpace}/${ident.idNumber}"
}
format {
html = defaultResolver
json = defaultResolver
xml = defaultResolver
rdf = {Identifier ident -> return null}
}
auth = [
'TEST-services': [
secret: 'buy-me-a-pony',
application: 'services',
roles : ['admin'],
],
'TEST-editor': [
secret: 'I-am-a-pony',
application: 'editor',
roles : ['admin'],
]
]
}To run the mapper using Docker you need to map the config directory to etc/nsl using -v.
Run the mapper from docker hub:
-
docker run -p 127.0.0.1:7070:8080 -v $HOME/.nsl:/etc/nsl:ro pmcneil/nsl-mapper:2.0
Note your configuration will need to either use a host name or IP address, not localhost, for the database connection.
|
Tip
|
You’ll need to open firewall ports for the database connection and the web connection (e.g. 5432 and 8080) if your OS has a firewall. |
Stop the running container using docker container stop <container ID> where <container ID> is found using
docker container ls.
-
make sure you have a database, java and config
-
clone this repository somewhere
-
cd to project directory
-
execute
./gradlew runfrom the command line -
browse to localhost:8080/ to see mapper page
to stop just press CTRL-C.
|
Note
|
you can change the default port that Micronaut uses by setting the environment variable MICRONAUT_SERVER_PORT=8086.
You can also set it in the resources/application.yml see: https://docs.micronaut.io/latest/guide/index.html#runningSpecificPort
|
|
Tip
|
There is a run-mapper.sh script you can used to run the mapper from a jar. Make sure you edit it and set the appropriate environment variables for your environment.
|
See: doc/guide.adoc
run ./gradlew test after which the test reports will be in build/reports/test
For linux systems that use systemd you can take the example mapper.service file and put it in /etc/systemd/system/
so you can start the mapper as a service. You will need an EnvironmentFile that defines the port, where the jar file is
and mapper config file. By default the EnvironmentFile is /etc/mapper-env.
MICRONAUT_SERVER_PORT=7070
CONFIG_FILE_LOCATION=/home/pmcneil/.nsl/mapper-config-mn.groovy (1)
JAR_FILE=/opt/anbg/mapper-mn.jar-
change to suit where your config file lives.
[Unit]
Description=Mapper Service
[Service]
User=apni (1)
Group=apni (2)
EnvironmentFile=/etc/mapper-env
ExecStart=/usr/bin/java \
-XX:+UnlockExperimentalVMOptions \
-XX:+UseCGroupMemoryLimitForHeap \
-Dcom.sun.management.jmxremote \
-noverify \
-Dmicronaut.config.files=${CONFIG_FILE_LOCATION} \
-jar ${JAR_FILE}
[Install]
WantedBy=multi-user.target-
set the appropriate system user
-
set the appropriate system group