Skip to content

Commit

Permalink
Better documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@QubitPi
QubitPi committed Aug 29, 2023
1 parent c4d7a5d commit 5b7a679
Show file tree
Hide file tree
Showing 4 changed files with 83 additions and 111 deletions.
22 changes: 0 additions & 22 deletions docs/docs/ci-cd.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,6 @@ title: CI/CD

![Error loading ci-cd.png](./img/ci-cd.png)

:::caution

[Never use SonarCloud Caching](https://github.com/paion-data/astraios/pull/9), otherwise the dependency injection will
get screwed up. i.e. The following snippet will never go to GitHub Action script

```xml
- name: Cache SonarCloud packages
uses: actions/cache@v1
with:
path: ~/.sonar/cache
key: ${{ runner.os }}-sonar
restore-keys: ${{ runner.os }}-sonar
- name: Cache Maven packages
uses: actions/cache@v1
with:
path: ~/.m2
key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
restore-keys: ${{ runner.os }}-m2
```

:::

The following [GitHub Secrets][How to set up GitHub Action Secrets] needs to be defined

- [**SONAR_TOKEN**](https://sonarcloud.io/project/overview?id=QubitPi_jersey-ws-template)
Expand Down
53 changes: 4 additions & 49 deletions docs/docs/development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,44 +3,11 @@ sidebar_position: 3
title: Development
---

Running Webservice in Docker Compose
------------------------------------

### Defining Data Models

Jersey WS Template can run in [Docker Compose] for the following purposes

1. Decoupling frontend and backend development
2. Easily integrating application backed by Jersey WS Template testing in CI/CD

![Error Loading docker-compose.png](./img/docker-compose.png)

```bash
git clone https://github.com/QubitPi/jersey-ws-template.git
cd jersey-ws-template
git checkout jpa-elide
mvn clean package
MODEL_PACKAGE_NAME=$JWT_MODEL_PACKAGE_NAME docker compose up --build --force-recreate
```

where `$JWT_MODEL_PACKAGE_NAME` is the package in config JAR that contains all
[elide models](https://elide.io/pages/guide/v7/02-data-model.html). It can be set, for example, at command line with:

```bash
export JWT_MODEL_PACKAGE_NAME=com.mycompany.jwt.models
```

The variable will be [passed](https://stackoverflow.com/a/58900415) into Docker Compose file.

### Troubleshooting

#### Database Does Not Contain Model Packages's Bean Table

_If tests is running in IDE_, make sure the model package JAR it is in IDE's **External Libraries**

Running Tests
-------------

The following commands runs both unit and integration tests

```bash
mvn clean verify
```
Expand All @@ -55,7 +22,7 @@ Packaging
mvn clean package
```

A [**WAR** file](https://en.wikipedia.org/wiki/WAR_(file_format)) named `jersey-ws-template-1.0-SNAPSHOT.war` will
A [WAR file](https://en.wikipedia.org/wiki/WAR_(file_format)) named **jersey-ws-template-1.0-SNAPSHOT.war** will
be generated under _target_ directory for [running in Jetty](#running-in-standalone-jetty)

Running Webservice in Standalone Jetty (Production)
Expand All @@ -64,13 +31,7 @@ Running Webservice in Standalone Jetty (Production)
### Download Jetty

At [download page](https://www.eclipse.org/jetty/download.php), pick up a `.tgz` distribution. **It is very important
to pick up Jetty server version that matches JDK version**. For JDK **17**, it's been tested that Jetty _11.0.15_ works

:::note

During testing, the embedded Jetty version is also 11.0.15

:::
to pick up Jetty server version that matches JDK version**. For JDK **17**, it's been tested that Jetty _11.0.15_ worked

Hence, we will use "11.0.15" release as an example:

Expand Down Expand Up @@ -110,12 +71,6 @@ Lastly, drop the [WAR file](#packaging) into **/path/to/jetty-base/webapps** dir
mv /path/to/war-file /path/to/jetty-base/webapps/ROOT.war
```

### Configuring Webservice

#### Define Model Package

#### Set Application Properties

### Running Webservice

```bash
Expand Down
105 changes: 75 additions & 30 deletions docs/docs/elide.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
---
sidebar_position: 6
title: Elide Middleware
title: JPA through Elide Middleware
---

Template can delegate JPA persistence to [Elide].

Configuring Elide requires 2 [bindings][what is binding]:
[Jersey Webservice Template] (_JWT_) delegates JPA capabilities to [Elide]. JWT configures Elide through 2
required Elide [bindings][what is binding]:

1. **[Elide][Elide instance class]**
2. **[ElideSettings][ElideSettings instance class]** with 2 extra sub-bindings:
Expand All @@ -15,66 +14,110 @@ Configuring Elide requires 2 [bindings][what is binding]:

The binding is referencing [Elide Standalone] in the following way:

:::danger

Although the Jersey binder wraps HK2 binder, we
[must pick the _Jersey binder_ for binding Elide resources](https://github.com/QubitPi/jersey-ws-template/pull/29/files#diff-afa024cc2643aaf681db505cac24b8601c94931290718993392e7726001b1559L39-R40),
otherwise, dependency injection will flaky and not right.

:::

![Error loading resource-binding.png](./img/resource-binding.png)

To inject Elide model package, simply put the models in a separate JAR and include it as a dependency in POM. If the
model package is internal and cannot be visible publicly, either make the webservice project private or public with
env variable masking, for example:
Running Webservice in Docker Compose
------------------------------------

### Step 1: Defining Data Models

To inject [Elide model package](https://github.com/yahoo/elide/tree/master/elide-standalone#create-models), simply put
the models in a separate JAR and include it as a dependency in POM. If the model package is internal and cannot be
visible publicly, either make the webservice project private or public with env variable masking, for example:

```xml
<dependencies>
<dependency>
<groupId>${env.MODEL_PACKAGE_JAR_GROUP_ID}</groupId>
<artifactId>${env.MODEL_PACKAGE_JAR_ARTIFACT_ID}</artifactId>
<version>${env.MODEL_PACKAGE_JAR_VERSION}</version>
</dependency>
</dependencies>
<dependencies>
<dependency>
<groupId>${env.MODEL_PACKAGE_JAR_GROUP_ID}</groupId>
<artifactId>${env.MODEL_PACKAGE_JAR_ARTIFACT_ID}</artifactId>
<version>${env.MODEL_PACKAGE_JAR_VERSION}</version>
</dependency>
</dependencies>

...

<repositories>
<repository>
<id>${env.MODEL_PACKAGE_REPO_ID}</id>
<name>JPA model pacakge JAR repository</name>
<url>${env.MODEL_PACKAGE_REPO_URL}</url>
</repository>
</repositories>
```

```bash
export MODEL_PACKAGE_JAR_GROUP_ID=com.mycompnay
export MODEL_PACKAGE_JAR_ARTIFACT_ID=my-model-package
export MODEL_PACKAGE_JAR_VERSION=1.0.7

export MODEL_PACKAGE_REPO_ID=my-repo-id
export MODEL_PACKAGE_REPO_URL=https://private.mvnrepository.com/artifact/com.company/my-model-package
```

### Step 1: Spinning Up Docker Compose

Jersey WS Template can run in [Docker Compose] for the following purposes

1. Decoupling frontend and backend development
2. Easily integrating application backed by Jersey WS Template testing in CI/CD

:::caution

The jetty-base should be initialized with
Docker Compose designed here is intended for local development and testing purposes ONLY! _It is strongly discouraged
to run this Docker Compose in production!_

:::

![Error Loading docker-compose.png](./img/docker-compose.png)

Simply run:

```bash
java -jar $JETTY_HOME/start.jar --add-module=annotations,server,http,deploy,servlet,webapp,resources,jsp,websocket
git clone https://github.com/QubitPi/jersey-ws-template.git
cd jersey-ws-template
git checkout jpa-elide
mvn clean package
MODEL_PACKAGE_NAME=$JWT_MODEL_PACKAGE_NAME docker compose up --build --force-recreate
```

In addition, before running webservice, the environment variable **MODEL_PACKAGE_NAME** must be set. For example:
where `$JWT_MODEL_PACKAGE_NAME` is the package in config JAR that contains all
[elide models](https://elide.io/pages/guide/v7/02-data-model.html). It can be set, for example, at command line with:

```bash
export MODEL_PACKAGE_NAME=com.mycompnay.models
export JWT_MODEL_PACKAGE_NAME=com.mycompany.jwt.models
```

:::
The variable will be [passed](https://stackoverflow.com/a/58900415) into Docker Compose file.

Example POST via JSON API:
### Troubleshooting

```bash
curl -X POST http://localhost:8080/v1/data/EntityType \
-H "Content-Type: application/vnd.api+json" \
-H "Accept: application/vnd.api+json" \
-d '{"data": {"type": "EntityType", "id": "elide-demo"}}'
```
#### Database Does Not Have My Model Packages's Bean Table

_If tests is running in IntelliJ IDE_, make sure the model package JAR it is in IDE's **External Libraries**

Troubleshooting
---------------
Otherwise, the dependency injection didn't find a bean class under the package specified by
[JWT_MODEL_PACKAGE_NAME](#step-1-defining-data-models)

### Entity Missing Default Constructor

```bash
13:17:52.396 [main] INFO o.h.m.i.EntityInstantiatorPojoStandard - HHH000182: No default (no-argument) constructor for
[main] INFO o.h.m.i.EntityInstantiatorPojoStandard - HHH000182: No default (no-argument) constructor for
class: ... (class must be instantiated by Interceptor)
```

Simply add a no-args constructor to the bean class.

### How to Exclude GraphQL Feature

To optionally disable GraphQL endpoints, simply exclude corresponding dependencies in POM. For example:
To optionally disable GraphQL endpoints, exclude corresponding dependencies in POM. For example:

```xml
<dependency>
Expand All @@ -97,6 +140,8 @@ To optionally disable GraphQL endpoints, simply exclude corresponding dependenci
[Elide Standalone]: https://github.com/yahoo/elide/tree/master/elide-standalone
[ElideSettings instance class]: https://github.com/yahoo/elide/blob/master/elide-core/src/main/java/com/yahoo/elide/ElideSettings.java

[Jersey Webservice Template]: https://qubitpi.github.io/jersey-ws-template/

[ResourceConfig]: https://github.com/QubitPi/jersey-ws-template/blob/jpa-elide/src/main/java/com/qubitpi/ws/jersey/template/application/ResourceConfig.java

[what is binding]: https://qubitpi.github.io/jersey/ioc.html
14 changes: 4 additions & 10 deletions docs/docs/setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ sidebar_position: 2
title: Setup
---

This section discusses the one-time setup in order to develop [Jersey Webservice Template]

Prepare for Local Development
-----------------------------

Expand Down Expand Up @@ -56,7 +58,7 @@ OpenJDK 64-Bit Server VM (build 17.0.10+9, mixed mode)

### Installing Docker Engine

[Jersey Webservice Template][jersey-ws-template] has [Docker-based integration tests][Docker-based integration tests];
[Jersey Webservice Template] has [Docker-based integration tests][Docker-based integration tests];
it also supports [running template webserivce in Docker][jersey-ws-template Dockerfile]. Docker can be installed by
following its [official instructions](https://docs.docker.com/desktop/install/mac-install/)

Expand All @@ -75,14 +77,6 @@ IntelliJ settings. If IntelliJ is used for IDE, we may import these code style s
[Jersey-WS-Template-Project-intellij-code-style.xml][style config] file in the root of the repo. The setting for the
project will appear as a new Scheme named Jersey-WS-Template-Project under IDE's `Editor -> Code Style` section.

Removing Unneeded Classes
-------------------------

[Jersey Webservice Template][jersey-ws-template] comes with common classes many webservices need, such as those
implementing caching feature. _Remove them if not needed_:

- [Caching][Caching] and [its tests][Caching tests]

Modifying Templates
-------------------

Expand All @@ -106,7 +100,7 @@ Modifying Templates

[endpoint package]: https://github.com/QubitPi/jersey-ws-template/blob/master/src/main/java/com/qubitpi/ws/jersey/template/application/ResourceConfig.java

[jersey-ws-template]: https://github.com/QubitPi/jersey-ws-template
[Jersey Webservice Template]: https://qubitpi.github.io/jersey-ws-template/
[jersey-ws-template Dockerfile]: https://github.com/QubitPi/jersey-ws-template/blob/master/Dockerfile

[style config]: https://github.com/QubitPi/jersey-ws-template/blob/master/Jersey-WS-Template-Project-intellij-code-style.xml

0 comments on commit 5b7a679

Please sign in to comment.