= Java Containerized Webservice Core :toc: preamble
image:https://img.shields.io/badge/jdk-15-blueviolet[JDK Version] image:https://img.shields.io/github/v/tag/VEuPathDB/lib-jaxrs-container-core?label=%20[GitHub tag (latest SemVer)] image:https://img.shields.io/github/workflow/status/veupathdb/lib-jaxrs-container-core/Build[GitHub Workflow Status]
Core functionality for containerized web services based on RAML & JaxRS.
https://veupathdb.github.io/lib-jaxrs-container-core/javadoc/[JavaDocs]
== Usage
TODO
== The Web Server
Creating a web server base for a new web service is done by creating a
entrypoint or "main" class that extends the type
org.veupathdb.lib.container.jaxrs.Server
.
The extending class, as a bare minimum, should instantiate a new instance of
your extending class and call the inherited method start(String[] cliArgs)
.
=== Enable Site Data access
If your service requires access to one or more of the VEuPathDB standard site
databases they must be enabled in your Main class (extending Server
) before
calling server.start
.
If any of the standard databases are enabled, the corresponding CLI args for that database config become required.
public class Main extends Server { public static void main(String[] args) { var server = new Main();
// Enable Account Database
server.enableAccountDB();
// Enable Application Database
server.enableApplicationDB();
// Enable User Database
server.enableUserDB();
server.start(args);
=== Extending the CLI Options
NOTE: CLI args/environment vars are processed using https://picocli.info/[PicoCLI]
If additional CLI flags are required for your service, the type
org.veupathdb.lib.container.jaxrs.config.Options
may be extended to include
additional properties.
Registering your new extended Options
class can be done by overriding the
Server
{apos}s newOptions
method to return your extended type.
public class Main extends Server { public static void main(String[] args) { var server = new Main(); server.start(args); }
=== Endpoints/Resources
==== Registering Endpoints
TODO
==== Enable Authentication
TODO
==== Enable CORS Headers
TODO
== Runtime Configuration
=== Misc Options
Projects based on this library may start with the following base options which may be configured via CLI arguments or environment variables.
==== --auth-secret
|$AUTH_SECRET_KEY
Type: string
Required if the service uses request authentication via the WDK user session.
The value must be the MD5 hash of the salt file used by WDK sites.
==== --server-port
|$SERVER_PORT
Type: int
Used to configure the port the web server to listens to.
Defaults to port 80
if unset.
==== --ldap-server
|$LDAP_SERVER
Type: string
Defines the LDAP server(s) that are used to look up Oracle connection details.
Required if the web service connects to Oracle database(s) using a TNS Name rather than individual connection details.
Individual values must be formatted as <host.addr>:<port>
, for example
ldap.mysite.org:123
.
Multiple servers may be specified using a comma to separate them:
ldap1.mysite.org:123,ldap2.mysite.org:123
==== --oracle-base-dn
|$ORACLE_BASE_DN
Type: string
The base context in which Oracle database TNS Names will be resolved.
Required if the web service connects to Oracle database(s) using a TNS Name rather than individual connection details.
=== Application DB Connection
==== Standard Options
These options apply to both LDAP and non-LDAP connection types.
===== --app-db-user
|$APP_DB_USER
Type: string
Sets the connection username for the application DB that this web service will connect to.
===== --app-db-pass
|$APP_DB_PASS
Type: string
Sets the connection password for the application DB that this web service will
===== --app-db-pool-size
|$APP_DB_POOL_SIZE
Type: int
Sets the connection pool size for the application DB that this web service will connect to.
Defaults to 20
==== Connecting with LDAP
===== --app-db-ora
|$APP_DB_TNS_NAME
Type: string
Sets the TNS Name to use when connecting to an application DB instance.
Using this value forces the platform type ORACLE
.
If this value is used, the following raw connection info CLI args/env vars will be ignored:
--app-db-host
|$APP_DB_HOST
--app-db-name
|$APP_DB_NAME
--app-db-port
|$APP_DB_PORT
--app-db-platform
|$APP_DB_PLATFORM
Additionally, if this value is used, the following CLI args/env vars will be required:
--ldap-server
|$LDAP_SERVER
--oracle-base-dn
|$ORACLE_BASE_DN
==== Connecting with Raw Details
===== --app-db-host
|$APP_DB_HOST
Type: string
Sets the host name for the application DB that this web service will connect to.
===== --app-db-name
|$APP_DB_NAME
Type: string
Sets the net/db name for the application DB that this web service will connect to. For Oracle, this should be the Service Name (not SID).
===== --app-db-port
|$APP_DB_PORT
Type: int
Sets the host port for the application DB that this web service will connect to.
===== --app-db-platform
|$APP_DB_PLATFORM
Type: enum
Values::
ORACLE
POSTGRESQL
Sets whether this web service will connect to an ORACLE
or POSTGRESQL
application database.
Defaults to ORACLE
=== Account DB Connection
==== Standard Options
These options apply to both LDAP and non-LDAP connection types.
===== --acct-db-user
|$ACCT_DB_USER
Type: string
Sets the connection username for the account DB that this web service will connect to.
===== --acct-db-pass
|$ACCT_DB_PASS
Type: string
Sets the connection password for the account DB that this web service will connect to.
===== --acct-db-pool-size
|$ACCT_DB_POOL_SIZE
Type: int
Sets the connection pool size for the account DB that this web service will connect to.
Defaults to 20
==== Connecting with LDAP
===== --acct-db-ora
|$ACCT_DB_TNS_NAME
Type: string
Sets the TNS Name to use when connecting to an account DB instance.
Using this value forces the platform type ORACLE
.
If this value is used, the following raw connection info CLI args/env vars will be ignored:
--acct-db-host
|$ACCT_DB_HOST
--acct-db-name
|$ACCT_DB_NAME
--acct-db-port
|$ACCT_DB_PORT
--acct-db-platform
|$ACCT_DB_PLATFORM
Additionally, if this value is used, the following CLI args/env vars will be required:
--ldap-server
|$LDAP_SERVER
--oracle-base-dn
|$ORACLE_BASE_DN
==== Connecting with Raw Details
===== --acct-db-host
|$ACCT_DB_HOST
Type: string
Sets the host name for the account DB that this web service will connect to.
===== --acct-db-name
|$ACCT_DB_NAME
Type: string
Sets the net/db name for the account DB that this web service will connect to. For Oracle, this should be the Service Name (not SID).
===== --acct-db-port
|$ACCT_DB_PORT
Type: int
Sets the host port for the account DB that this web service will connect to.
===== --acct-db-platform
|$ACCT_DB_PLATFORM
Type: enum
Values::
ORACLE
POSTGRESQL
Sets whether this web service will connect to an ORACLE
or POSTGRESQL
account database.
Defaults to ORACLE
=== User DB Connection
==== Standard Options
These options apply to both LDAP and non-LDAP connection types.
===== --user-db-user
|$USER_DB_USER
Type: string
Sets the connection username for the user DB that this web service will connect to.
===== --user-db-pass
|$USER_DB_PASS
Type: string
Sets the connection password for the user DB that this web service will connect to.
===== --user-db-pool-size
|$USER_DB_POOL_SIZE
Type: int
Sets the connection pool size for the user DB that this web service will connect to.
Defaults to 20
==== Connecting with LDAP
===== --user-db-ora
|$USER_DB_TNS_NAME
Type: string
Sets the TNS Name to use when connecting to an user DB instance.
Using this value forces the platform type ORACLE
.
If this value is used, the following raw connection info CLI args/env vars will be ignored:
--user-db-host
|$USER_DB_HOST
--user-db-name
|$USER_DB_NAME
--user-db-port
|$USER_DB_PORT
--user-db-platform
|$USER_DB_PLATFORM
Additionally, if this value is used, the following CLI args/env vars will be required:
--ldap-server
|$LDAP_SERVER
--oracle-base-dn
|$ORACLE_BASE_DN
==== Connecting with Raw Details
===== --user-db-host
|$USER_DB_HOST
Type: string
Sets the host name for the user DB that this web service will connect to.
===== --user-db-name
|$USER_DB_NAME
Type: string
Sets the net/db name for the user DB that this web service will connect to. For Oracle, this should be the Service Name (not SID).
===== --user-db-port
|$USER_DB_PORT
Type: int
Sets the host port for the user DB that this web service will connect to.
===== --user-db-platform
|$USER_DB_PLATFORM
Type: enum
Values::
ORACLE
POSTGRESQL
Sets whether this web service will connect to an ORACLE
or POSTGRESQL
user database.
Defaults to ORACLE