From 2c18ea6fe7aa368c8657f04c9bb35958f47242f8 Mon Sep 17 00:00:00 2001 From: Yana Hontyk Date: Fri, 19 Mar 2021 13:24:20 +0100 Subject: [PATCH] Add Java+DB odo documentation --- _topic_map.yml | 2 + ...ng-a-java-application-with-a-database.adoc | 23 ++++ ...-a-java-application-to-mysql-database.adoc | 57 +++++++++ ...-cli-odo-creating-a-database-with-odo.adoc | 62 ++++++++++ ...g-a-java-microservice-jpa-application.adoc | 110 ++++++++++++++++++ 5 files changed, 254 insertions(+) create mode 100644 cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-java-application-with-a-database.adoc create mode 100644 modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc create mode 100644 modules/developer-cli-odo-creating-a-database-with-odo.adoc create mode 100644 modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc diff --git a/_topic_map.yml b/_topic_map.yml index a031577a5c..de193e808d 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -489,6 +489,8 @@ Topics: File: creating-a-multicomponent-application-with-odo - Name: Creating an application with a database File: creating-an-application-with-a-database + - Name: Creating a Java application with a database + File: creating-a-java-application-with-a-database - Name: Using devfiles in odo File: using-devfiles-in-odo - Name: Working with storage diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-java-application-with-a-database.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-java-application-with-a-database.adoc new file mode 100644 index 0000000000..a749ab79b6 --- /dev/null +++ b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-java-application-with-a-database.adoc @@ -0,0 +1,23 @@ +[id=creating-a-java-application-with-a-database] += Creating a Java application with a database +include::modules/developer-cli-odo-attributes.adoc[] +include::modules/common-attributes.adoc[] +:context: creating-a-java-application-with-a-database +toc::[] + +This example describes how to deploy a Java application by using devfile and connect it to a database service. + +.Prerequisites + +* A running cluster. +* `{odo-title}` is installed. +* A Service Binding Operator is installed in your cluster. To learn how to install Operators, contact your cluster administrator or see xref:../../../operators/user/olm-installing-operators-in-namespace.adoc#olm-installing-operators-from-operatorhub_olm-installing-operators-in-namespace[Installing Operators from OperatorHub]. +* A Dev4Devs PostgreSQL Operator Operator is installed in your cluster. To learn how to install Operators, contact your cluster administrator or see xref:../../../operators/user/olm-installing-operators-in-namespace.adoc#olm-installing-operators-from-operatorhub_olm-installing-operators-in-namespace[Installing Operators from OperatorHub]. + +include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+1] + +include::modules/developer-cli-odo-creating-a-database-with-odo.adoc[leveloffset=+1] + +include::modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc[leveloffset=+1] + +include::modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc[leveloffset=+1] diff --git a/modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc b/modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc new file mode 100644 index 0000000000..c1ad5b092b --- /dev/null +++ b/modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * cli_reference/developer_cli_odo/creating-a-java-application-with-a-database + +[id="connecting-a-java-application-to-a-database_{context}"] += Connecting a Java application to a database + +To connect your Java application to the database, use the `odo link` command. + +.Procedure + +. Display the list of services: ++ +[source,terminal] +---- +$ odo service list +---- ++ +.Example output +[source,terminal] +---- +NAME AGE +Database/sampledatabase 6m31s +---- + +. Connect the database to your application: ++ +[source,terminal] +---- +$ odo link Database/sampledatabase +---- + +. Push the changes to your cluster: ++ +[source,terminal] +---- +$ odo push +---- ++ +After the link has been created and pushed, a secret that contains the database connection data is created. + +. Check the component for values injected from the database service: ++ +[source,sh] +---- +$ odo exec -- bash -c 'export | grep DATABASE' +declare -x DATABASE_CLUSTERIP="10.106.182.173" +declare -x DATABASE_DB_NAME="sampledb" +declare -x DATABASE_DB_PASSWORD="samplepwd" +declare -x DATABASE_DB_USER="sampleuser" +---- + +. Open the URL of your Java application and navigate to the `CreatePerson.xhtml` data entry page. Enter a username and age by using the the form. Click *Save*. ++ +Note that now you can see the data in the database by clicking the *View Persons Record List* link. ++ +You can also use a CLI tool such as `psql` to manipulate the database. diff --git a/modules/developer-cli-odo-creating-a-database-with-odo.adoc b/modules/developer-cli-odo-creating-a-database-with-odo.adoc new file mode 100644 index 0000000000..dd1246580c --- /dev/null +++ b/modules/developer-cli-odo-creating-a-database-with-odo.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: + +[id="creating-a-database-with-odo_{context}"] + += Creating a database with `odo` + +To create a database, you must have an access to the database Operator. For this example, Dev4Devs PostgreSQL Operator is used. + +.Procedure + + +. View the list of the services in your project: ++ +[source,terminal] +---- +$ odo catalog list services +---- ++ +.Example output +---- +Operators available in the cluster +NAME CRDs +postgresql-operator.v0.1.1 Backup, Database +---- + +. Store the YAML of the service in a file: ++ +[source,terminal] +---- +$ odo service create postgresql-operator.v0.1.1/Database --dry-run > db.yaml +---- + +. Add the following values under the `metadata:` section in the `db.yaml` file: ++ +[source,yaml] +---- + name: sampledatabase + annotations: + service.binding/db.name: 'path={.spec.databaseName}' + service.binding/db.password: 'path={.spec.databasePassword}' + service.binding/db.user: 'path={.spec.databaseUser}' +---- ++ +This configuration ensures that when a database service is started, appropriate annotations are added to it. Annotations help the Service Binding Operator in injecting the values for `databaseName`, `databasePassword`, and `databaseUser` into the application. + +. Change the following values under the `spec:` section of the YAML file: ++ +[source,yaml] +---- + databaseName: "sampledb" + databasePassword: "samplepwd" + databaseUser: "sampleuser" +---- + +. Create a database from the YAML file: ++ +[source,terminal] +---- +$ odo service create --from-file db.yaml +---- ++ +A database instance is now present in your project. diff --git a/modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc b/modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc new file mode 100644 index 0000000000..5cad1b7e1b --- /dev/null +++ b/modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc @@ -0,0 +1,110 @@ += Creating a Java MicroServices JPA application + +With `odo`, you can create and manage a sample Java MicroServices JPA application. + +.Procedure + +. Clone the sample application: ++ +[source,terminal] +---- +$ git clone https://github.com/redhat-developer/application-stack-samples +---- + +. Navigate to the application directory: ++ +[source,terminal] +---- +$ cd ./application-stack-samples/jpa +---- + +. Initialize the project: ++ +[source,terminal] +---- +$ odo create java-openliberty java-application +---- + +. Push the application to the cluster: ++ +[source,terminal] +---- +$ odo push +---- ++ +The application is now deployed to the cluster. + +. View the status of the cluster by streaming the OpenShift logs to the terminal: ++ +[source,terminal] +---- +$ odo log +---- ++ +Notice the test failures and `UnknownDatabaseHostException` error. This is because your application does not have a database yet: ++ +[source,terminal] +---- +[INFO] [err] java.net.UnknownHostException: ${DATABASE_CLUSTERIP} +[INFO] [err] at java.base/java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:220) +[INFO] [err] at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:403) +[INFO] [err] at java.base/java.net.Socket.connect(Socket.java:609) +[INFO] [err] at org.postgresql.core.PGStream.(PGStream.java:68) +[INFO] [err] at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:144) +[INFO] [err] ... 86 more +[ERROR] Tests run: 2, Failures: 1, Errors: 1, Skipped: 0, Time elapsed: 0.706 s <<< FAILURE! - in org.example.app.it.DatabaseIT +[ERROR] testGetAllPeople Time elapsed: 0.33 s <<< FAILURE! +org.opentest4j.AssertionFailedError: Expected at least 2 people to be registered, but there were only: [] ==> expected: but was: + at org.example.app.it.DatabaseIT.testGetAllPeople(DatabaseIT.java:57) + +[ERROR] testGetPerson Time elapsed: 0.047 s <<< ERROR! +java.lang.NullPointerException + at org.example.app.it.DatabaseIT.testGetPerson(DatabaseIT.java:41) + +[INFO] +[INFO] Results: +[INFO] +[ERROR] Failures: +[ERROR] DatabaseIT.testGetAllPeople:57 Expected at least 2 people to be registered, but there were only: [] ==> expected: but was: +[ERROR] Errors: +[ERROR] DatabaseIT.testGetPerson:41 NullPointer +[INFO] +[ERROR] Tests run: 2, Failures: 1, Errors: 1, Skipped: 0 +[INFO] +[ERROR] Integration tests failed: There are test failures. +---- + +. Create an ingress URL to access the application: ++ +[source,terminal] +---- +$ odo url create --port 8080 +---- + +. Push the changes to your cluster: ++ +[source,terminal] +---- +$ odo push +---- + +. Display the created URL: ++ +[source,terminal] +---- +$ odo url list +---- ++ +.Example output +[source,terminal] +---- +Found the following URLs for component mysboproj +NAME STATE URL PORT SECURE KIND +java-application-8080 Pushed http://java-application-8080.apps-crc.testing 8080 false ingress +---- ++ +The application is now deployed to the cluster and you can access it by using the URL that is created. + +. Use the URL to navigate to the `CreatePerson.xhtml` data entry page and enter a username and age by using the the form. Click *Save*. ++ +Note that you cannot see the data by clicking the *View Persons Record List* link since your application does not have a database connected yet.