You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@turbine.apache.org by gk...@apache.org on 2021/07/27 15:42:34 UTC
[turbine-archetypes] 05/06: all info in docs folder,
github will find README.md automatically, more explicit schema.xml
This is an automated email from the ASF dual-hosted git repository.
gk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/turbine-archetypes.git
commit 5e3b21d39178bf2095ce8b37e771ac8d94f5f26e
Author: gemkall <ge...@fu-berlin.de>
AuthorDate: Tue Jul 27 17:37:39 2021 +0200
all info in docs folder, github will find README.md automatically, more explicit schema.xml
---
src/main/resources/archetype-resources/README.md | 132 ---------------------
.../archetype-resources/docs/DOCKER-README.md | 70 +++++------
.../resources/archetype-resources/docs/README.md | 111 +++++++++--------
.../main/torque-schema/torque-security-schema.xml | 10 +-
4 files changed, 85 insertions(+), 238 deletions(-)
diff --git a/src/main/resources/archetype-resources/README.md b/src/main/resources/archetype-resources/README.md
deleted file mode 100644
index a960e28..0000000
--- a/src/main/resources/archetype-resources/README.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# Quick Guide to using the new Turbine 5.1 maven archetype for skeleton application generation
-
-## About this archetype
-
-Turbine Version: Turbine 5.1.
-
-You may skip Docker and Local Database Setup and read it later.
-
-### Docker Setup
-
-- If docker is available you could use the Docker build setup. Follow instructions here: [DOCKER README] (docs/DOCKER-README.md).
-
-#### Local Database Setup
-
-First, you should have a local database installed and configured prior to
-beginning the application setup below.
-
-- Find more information about Logs and application structur here: [README] (docs/README.md).
-
-
-### Maven archetype
-
-Next, you can invoke the Maven archetype for turbine-webapp-5.0 from
-the command line as shown below - please update values starting
-with 'groupId' as appropriate.
-
-```sh
-mvn archetype:generate \
- -DarchetypeGroupId=org.apache.turbine \
- -DarchetypeArtifactId=turbine-webapp-5.1 \
- -DarchetypeVersion=2.0.0-SNAPSHOT \
- -DgroupId=com.mycompany.webapp \
- -DartifactId=myhelloworld \
- -Dversion=1.0 \
- -Dturbine_app_name=HelloWorld \
- -Dturbine_database_adapter=mysql \
- -Dturbine_database_user=db_username \
- -Dturbine_database_password=db_password \
- -Dturbine_database_name=helloworld \
- -Dturbine_database_timezone=UTC \
- -Dturbine_database_url=jdbc:mysql://localhost:3306/ \
- -Dgoals=generate-sources,integration-test
-```
-
-#### Docker integration
-
-N.B. Set docker variable to true to enable Docker setup in building the artifact:
-
- -Ddocker=true
-
-to immediately enable docker setup, when generating the archetype.
-
-Currently only port 3306 is supported, if you do not want ot change the port seetings for the db container in docker-compose.yml
-
-### Development
-
-You may use
-
-```sh
-mvn archetype:generate -DarchetypeCatalog=local
-```
-
-to avoid declaring the *archetype* variables.
-
-This requires you provide a local catalog in $HOME\.m2\archetype-catalog.xml. Find further information here: https://maven.apache.org/archetype/archetype-models/archetype-catalog/archetype-catalog.html.
-
-##### Example
-<archetype-catalog ...>
- <archetype>
- <groupId>org.apache.turbine</groupId>
- <artifactId>turbine-webapp-5.1</artifactId>
- <version>2.0.0-SNAPSHOT</version>
- <description>This archetype sets up a web application project based on Apache Turbine 5.0</description>
- </archetype>
- </archetypes>
-</archetype-catalog>
-
-### Notes (local Database Setup only)
-
-When invoking archetype:generate like above, you already have set Turbine goals generate-sources,integration-test
-and you can then skip them later.
-
-Be aware, when you set both mvn commands goals (which are maven phases actually), i.e with
-
--Dgoals=generate-sources, integration-test
-
-you have to create the database (see above) before finishing the (interactive) archetype commands.
-Otherwise you could catch up doing this later and after that is done calling the phases afterwards as mentioned below.
-
-#### turbine_database_url
-
-Note that the database URL (turbine_database_url)
-will be appended with your database name
-in the final pom.xml, so you do not need to specify that in
-the configuration. Be sure that it ends with a slash ('/')!
-
-## Project Start and Usage
-
-Next, change into the newly generated project folder, in our case
-
-```sh
-cd myhelloworld
-```
-
-Skip next two steps, if the build was successfull.
-
-```sh
-mvn generate-sources
-```
-This will generate the OM layer and SQL code for creating the corresponding database tables.
-
-
-```sh
-mvn integration-test
-```
-This executes the SQL code to create the application schema defined in src/main/torque-schema.
-
-You should now check the database tables and if some data is missing
-insert the sample data file in sample-mysql-data (Torque 4.0 has disabled the datasql task).
-
-```sh
-mvn clean install
-```
-
-If you get an error like *"The driver has not received any packets"* probably the database is not up and running or the port may be another one.
-
-Last step on the command line is run the server by invoking
-mvn -Pjetty
-
-- Now you can launch your new Turbine application by default [http://localhost:8081/app] (check port in pom.xml, if needed).
-
-- Find more information about Logs and application structur here: [README] (docs/README.md).
diff --git a/src/main/resources/archetype-resources/docs/DOCKER-README.md b/src/main/resources/archetype-resources/docs/DOCKER-README.md
index 219c3a9..c6eea76 100644
--- a/src/main/resources/archetype-resources/docs/DOCKER-README.md
+++ b/src/main/resources/archetype-resources/docs/DOCKER-README.md
@@ -22,34 +22,23 @@ To run the build with maven do this outside of the container using following mvn
mvn install -Pdocker
-
-- Then check in directory target/docker-resources the file docker-compose.yml e.g. with
-
- docker compose config
-
-## Optional Integration Test (not tested)
-
- mvn integration-test
-
-N.B.: This builds the integrationtest project in target/test-classes/projects/first/project/integrationtest with docker enabled configuration.
-Running the build inside the container is not required and may be problematic, unless you use only public available dependencies.
-
-
# Installation (running the app)
+
+- Change into directory target/docker-resources andf check the file docker-compose.yml, e.g. with
-- Change into the projects target/docker resource folder
-
-```sh
-cd target/docker-resources
-```
+ cd <project>/target/docker-resources
-## Check Docker Compose file (optional)
+ docker compose config
+
+- Build and start the services
-- Check services in docker-compose.yml (volumes)
-```
-docker-compose config
-```
+ docker compose build --no-cache
+ docker compose up
+
+First time building might take a couple of minutes.
+ - Now you can launch in another termina your new Turbine application by default [http://localhost:8081/app]
+
N.B. You may use the command *docker compose* or *docker-compose*, but will slightly different results.
- Check database service call in ** target/<projectname>/WEB-INF/jetty-env.xml**. It should reference the service name (db), not localhost - as it is also set in maven docker profile.
@@ -116,10 +105,7 @@ If previously build, you may want to delete all volumes (this will delete all ta
- Build it
-
-```sh
docker-compose build --no-cache
-```
.. optionally build it separately
docker-compose build --no-cache --build-arg DB_CONTEXT=./docker-resources/db db
@@ -135,14 +121,13 @@ It is a dependency for the service app (see app/Dockerfile).
### Starting Services
Start both services in one step
-```
-docker-compose up
-```
+
+ docker-compose up
+
.. or doing it in background, requires second start command
-```
-docker-compose -d up
-docker-compose start
-```
+
+ docker-compose -d up
+ docker-compose start
This will start first the db service, then the app service. Jetty is run exposing the webapp to **http://localhost:8081/app**.
By default remote debugging is activated (port 9000), which could be removed/commented in docker-compose.yml.
@@ -160,9 +145,8 @@ docker-compose run --rm db /bin/sh
```
Extract data in db service
-```sh
- mysql -u root -h db -P 3306 -p
-```
+ mysql -u root -h db -P 3306 -p
+
.. or
docker-compose exec db mysql -u root --password=... -e "show databases;" --build-arg DB_CONTEXT=./docker-resources/db
@@ -171,13 +155,13 @@ Extract data in db service
### App Service
This will start app and db (as it depends on app):
-```sh
-docker-compose run --rm app /bin/sh
-```
+
+ docker-compose run --rm app /bin/sh
+
In the container, check:
-```sh
-ls -la /myapp // should list pom.xml ...
-```
+
+ ls -la /myapp // should list pom.xml ...
+
# System Specific Informations
@@ -219,7 +203,7 @@ Error starting userland proxy: mkdir /port/tcp:0.0.0.0:13306:tcp:...:3306: input
### Still more docker commands ...
- docker ps
+ docker volume inspect <containerid>
// delete intermediate images, volumes
docker rmi $(docker images --filter "dangling=true" -q)
diff --git a/src/main/resources/archetype-resources/docs/README.md b/src/main/resources/archetype-resources/docs/README.md
index b26b963..a1855da 100644
--- a/src/main/resources/archetype-resources/docs/README.md
+++ b/src/main/resources/archetype-resources/docs/README.md
@@ -1,36 +1,39 @@
-#*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you 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.
-*#
-
-
# Quick Guide to using the new Turbine 5.1 maven archetype for skeleton application generation
+Maven Archetype to generate a webapp utilizing Turbine 5.x
+
+## Getting Started
+
+These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
+
+### Prerequisites
+
+* Java 8 JDK or later
+* [MySQL](https://www.mysql.com/) - Database Server or [Docker] (https://docs.docker.com/get-docker/)
+* [Maven](https://maven.apache.org/) - Dependency Management
+
+You should have Java 8 or later installed. The archetype sets up a new application using MySQL as the default database store. However, you can adjust this to use any database supported by Apache Torque 5.x. If not using Docker, you should therefore be at least have a database instance where you have access rights to create a new database schema and populate it with the tables the application generates. Finally, this is a maven archetype, so of course you should install a local version [...]
## About this archetype
-Turbine Version: Turbine 5.1.
+Turbine Version: Turbine 5.1 Turbine-webapp-5.x
-Follow either Local database Setup or Docker Setup
+### Integration Test (if you checked out this Archetype Generate Repository)
-### Local database Setup
+ mvn integration-test
+
+N.B.: This builds an integrationtest project in target/test-classes/projects/first/project/integrationtest (if you provide -Ddocker=true with docker enabled configuration, otherwise you need a hosted mysql database). You could start testing this archetype here..
+
+- Follow either Local database Setup or Docker Setup
+
+### Docker Setup
+
+- If docker is available you could use the Docker build setup. Follow instructions here: [DOCKER README] (DOCKER-README.md).
+
+### Local Database Setup
First, you should have a local database installed and configured prior to
-beginning the application setup.
+beginning the application setup below.
As we are using MySQL by default you need to create the database in MySQL (server version should be at least 5.5, because of new sql driver), e.g. with
@@ -40,46 +43,39 @@ mysql> \q
or other tools. The database should have been started and the database user granted enough rights.
+### Maven archetype
+
+Next, you can invoke the Maven archetype for turbine-webapp-5.0 from
+the command line as shown below - please update values starting
+with 'groupId' as appropriate.
-### Docker integration (short intro)
+```sh
+mvn archetype:generate \
+ -DarchetypeGroupId=org.apache.turbine \
+ -DarchetypeArtifactId=turbine-webapp-5.1 \
+ -DarchetypeVersion=2.0.0-SNAPSHOT \
+ -DgroupId=com.mycompany.webapp \
+ -DartifactId=myhelloworld \
+ -Dversion=1.0 \
+ -Dturbine_app_name=HelloWorld \
+ -Dturbine_database_adapter=mysql \
+ -Dturbine_database_user=db_username \
+ -Dturbine_database_password=db_password \
+ -Dturbine_database_name=helloworld \
+ -Dturbine_database_timezone=UTC \
+ -Dturbine_database_url=jdbc:mysql://localhost:3306/ \
+ -Dgoals=generate-sources,integration-test
+```
-Run this command
+#### Docker integration
- mvn clean install -Pdocker
+N.B. Set docker variable to true to enable Docker setup in building the artifact:
+ -Ddocker=true
to immediately enable docker setup, when generating the archetype.
Currently only port 3306 is supported, if you do not want ot change the port seetings for the db container in docker-compose.yml
-
-You then should change to the generated docker resources:
-
- cd <project>/target/docker-resources
-
-and follow the instructions in [DOCKER README] (docs/DOCKER-README.md). In short you may do the following (you may have to start docker desktop on windows):
-
- docker compose configurable
- docker compose build --no-cache
- docker compose up
-
- - First time Building might take a couple of minutes.
-
- - Now you can launch your new Turbine application by default [http://localhost:8081/app]
-
-
-- Read [DOCKER README] (DOCKER-README.md).
-
-You then need not to follow the following chapters, but could immediately go to
-
- cd <project>/target/docker-resources
-
-and then follow the instructions in DOCKER-README.md. In short you may do the following:
-
- docker compose configurable
- docker compose build --no-cache
- docker compose up
-
- - Now you can launch your new Turbine application by default [http://localhost:8081/app]
## Project Start and Usage
@@ -145,8 +141,7 @@ If running from integration test, check/update
- target/test-classes/projects/first/project/integrationtest/src/test/conf/torque/TorqueTest.properties or
META-INF/maven/archetype-metadata.xml
-The security test is by default skipped as it requires a running mysql. It tests many of the Fulcrum Torque Turbine security aspects,
-activate it by calling
+The security test is by default skipped as it requires a running mysql. It tests many of the Fulcrum Torque Turbine security aspects, you may activate it by calling
```sh
mvn test -DskipTests=false
diff --git a/src/main/resources/archetype-resources/src/main/torque-schema/torque-security-schema.xml b/src/main/resources/archetype-resources/src/main/torque-schema/torque-security-schema.xml
index 41d6802..2b26cb2 100644
--- a/src/main/resources/archetype-resources/src/main/torque-schema/torque-security-schema.xml
+++ b/src/main/resources/archetype-resources/src/main/torque-schema/torque-security-schema.xml
@@ -80,8 +80,8 @@
<table name="TURBINE_ROLE_PERMISSION"
interface="org.apache.fulcrum.security.torque.peer.TurbineRolePermissionPeerMapper">
- <column name="ROLE_ID" required="true" primaryKey="true" type="INTEGER"/>
- <column name="PERMISSION_ID" required="true" primaryKey="true" type="INTEGER"/>
+ <column name="ROLE_ID" required="true" primaryKey="true" type="INTEGER" javaType="primitive"/>
+ <column name="PERMISSION_ID" required="true" primaryKey="true" type="INTEGER" javaType="primitive"/>
<!-- Turbine service revokeAll(role) manages removal, but you might want to handle it just with onDelete="cascade" -->
<foreign-key foreignTable="TURBINE_ROLE">
@@ -119,9 +119,9 @@
<table name="TURBINE_USER_GROUP_ROLE"
interface="org.apache.fulcrum.security.torque.peer.TurbineUserGroupRoleModelPeerMapper"
peerInterface="org.apache.fulcrum.security.torque.peer.TorqueTurbineUserGroupRolePeer">
- <column name="USER_ID" required="true" primaryKey="true" type="INTEGER"/>
- <column name="GROUP_ID" required="true" primaryKey="true" type="INTEGER"/>
- <column name="ROLE_ID" required="true" primaryKey="true" type="INTEGER"/>
+ <column name="USER_ID" required="true" primaryKey="true" type="INTEGER" javaType="primitive"/>
+ <column name="GROUP_ID" required="true" primaryKey="true" type="INTEGER" javaType="primitive"/>
+ <column name="ROLE_ID" required="true" primaryKey="true" type="INTEGER" javaType="primitive"/>
<!-- Turbine service revokeAll(user) manages removal, but you might want to handle it just with onDelete="cascade" -->
<foreign-key foreignTable="TURBINE_USER">
<reference local="USER_ID" foreign="USER_ID"/>