From commits-return-44143-archive-asf-public=cust-asf.ponee.io@tomee.apache.org Sun Dec 2 01:13:00 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 9A1491807C2 for ; Sun, 2 Dec 2018 01:12:55 +0100 (CET) Received: (qmail 2391 invoked by uid 500); 2 Dec 2018 00:12:54 -0000 Mailing-List: contact commits-help@tomee.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tomee.apache.org Delivered-To: mailing list commits@tomee.apache.org Received: (qmail 1846 invoked by uid 99); 2 Dec 2018 00:12:54 -0000 Received: from Unknown (HELO svn01-us-west.apache.org) (209.188.14.144) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 02 Dec 2018 00:12:54 +0000 Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id A3C873A2775 for ; Sun, 2 Dec 2018 00:12:52 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1847931 [18/22] - in /tomee/site/trunk/content: latest/docs/admin/cluster/ latest/docs/admin/configuration/ latest/docs/advanced/applicationcomposer/ latest/docs/advanced/client/ latest/docs/advanced/jms/ latest/docs/advanced/setup/ latest... Date: Sun, 02 Dec 2018 00:12:51 -0000 To: commits@tomee.apache.org From: dblevins@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20181202001252.A3C873A2775@svn01-us-west.apache.org> Added: tomee/site/trunk/content/tomee-8.0/docs/advanced/setup/index.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/advanced/setup/index.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/advanced/setup/index.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/advanced/setup/index.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,327 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +

How to Setup TomEE in production

+
+
+
+
+ +
+
+
+
+

You can use TomEE as described on Directory Structure page but in production it is better to +split TomEE and application binaries and configuration.

+
+
+

Idea is to have this kind of layout (the root is the one you prefer):

+
+
+

[{ + label: '/some/path', + description: 'any location on your file system', + children: [ + { + label: 'tomee', + description: 'all tomee binaries will be there, note: you often do the same for the JVM versions you have', + children: [ + { + label: 'tomee-1.7.1', + description: 'a particular tomee version (just unzip it there)', + children: [ + { label: 'bin', description: 'the startup binaries/scripts' }, + { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' }, + { label: 'lib', description: 'the binaries' } + ] + }, + { + label: 'tomee-1.7.2', + description: 'a particular tomee version (just unzip it there)', + children: [ + { label: 'bin', description: 'the startup binaries/scripts' }, + { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' }, + { label: 'lib', description: 'the binaries' } + ] + }, + { + label: 'tomee-7.0.0-M3', + description: 'a particular tomee version (just unzip it there)', + children: [ + { label: 'bin', description: 'the startup binaries/scripts' }, + { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' }, + { label: 'lib', description: 'the binaries' } + ] + } + ] + }, + { + label: 'applications', + description: 'all applications', + children: [ + { + label: 'application1', + description: 'any application instance (ie configuration + binaries)', + children: [ + { label: 'bin', description: 'provide scripts for this instance (see under that file layout)' }, + { label: 'conf', description: 'the instance configuration, typically what is in tomee/conf when used in standalone' }, + { label: 'lib', description: 'some additional binaries like JDBC drivers' }, + { label: 'logs', description: 'instances logs location' }, + { label: 'work', description: 'dedicated work directory' }, + { label: 'temp', description: 'instance temporary folder' }, + { label: 'webapps', description: 'instance webapp folder' } + ] + }, + { + label: 'application2', + description: 'any application instance (ie configuration + binaries)', + children: [ + { label: 'bin', description: 'provide scripts for this instance (see under that file layout)' }, + { label: 'conf', description: 'the instance configuration, typically what is in tomee/conf when used in standalone' }, + { label: 'lib', description: 'some additional binaries like JDBC drivers' }, + { label: 'logs', description: 'instances logs location' }, + { label: 'work', description: 'dedicated work directory' }, + { label: 'temp', description: 'instance temporary folder' }, + { label: 'webapps', description: 'instance webapp folder' } + ] + } + ] + } + ] +}]

+
+
+

Click on a tree node or open a folder to see the detail there.

+
+
+

 

+
+
+
+
+

Instance scripts

+
+

The idea for instances (applications) scripts is to simply delegate to tomcat ones but customizing the JVM and TomEE versions.

+
+
+

Customizing the version (and locations) is done in bin/setenv.sh of instances.

+
+
+

Here are an example for the common scripts (of course you can write helper version like restart etc).

+
+
+

setenv.sh

+
+
+
#! /bin/sh
+
+# which java
+export JAVA_HOME="/some/path/java/jdk-8u60"
+# which tomee
+export CATALINA_HOME="/some/path/tomee/tomee-7.0.0-M3"
+# where is the application - to let tomcat/tomee finds the configuration
+export CATALINA_BASE="/some/path/application1/"
+# to let tomee be able to kill the instance if shutdown doesn't work (see shutdown script)
+export CATALINA_PID="/some/path/application1/work/tomee.pid"
+
+
+
+
+

startup

+
+
+
#! /bin/bash
+
+proc_script_base="`cd $(dirname $0) && cd .. && pwd`"
+source "$proc_script_base/bin/setenv.sh"
+nohup "$CATALINA_HOME/bin/startup.sh" "$@" > $proc_script_base/logs/nohup.log &
+
+
+
+
+

shutdown

+
+
+
#! /bin/bash
+
+proc_script_base="`cd $(dirname $0) && cd .. && pwd`"
+source "$proc_script_base/bin/setenv.sh"
+# we support parameters like timeout and force, typically we would call it this way: ./shutdown 1200 -force
+"$CATALINA_HOME/bin/shutdown.sh" "$@"
+
+
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/advanced/setup/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/tomee-8.0/docs/advanced/shading/index.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/advanced/shading/index.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/advanced/shading/index.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/advanced/shading/index.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,511 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

Fat / Uber jars - Using the Shade Plugin

+
+
+
+
+ +
+
+
+
+

Shading the container and the application has some challenges like merging correctly resources (META-INF/services/ typically).

+
+
+

Here is a maven shade plugin configuration working for most cases:

+
+
+
+
<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-shade-plugin</artifactId>
+  <version>2.3</version>
+  <executions>
+    <execution>
+      <phase>package</phase>
+      <goals>
+        <goal>shade</goal>
+      </goals>
+      <configuration>
+        <dependencyReducedPomLocation>${project.build.directory}/reduced-pom.xml</dependencyReducedPomLocation>
+        <transformers>
+          <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+            <mainClass>org.apache.tomee.embedded.FatApp</mainClass>
+          </transformer>
+          <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
+            <resource>META-INF/cxf/bus-extensions.txt</resource>
+          </transformer>
+          <transformer implementation="org.apache.openwebbeans.maven.shade.OpenWebBeansPropertiesTransformer" />
+        </transformers>
+        <filters>
+          <filter> <!-- we don't want JSF to be activated -->
+            <artifact>*:*</artifact>
+            <excludes>
+              <exclude>META-INF/faces-config.xml</exclude>
+            </excludes>
+          </filter>
+        </filters>
+      </configuration>
+    </execution>
+  </executions>
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.openwebbeans</groupId>
+      <artifactId>openwebbeans-maven</artifactId>
+      <version>1.7.0/version>
+    </dependency>
+  </dependencies>
+</plugin>
+
+
+
+ + + + + +
+ + +see TomEE Embedded page for more information about tomee embedded options. +
+
+
+ + + + + +
+ + +this shade uses TomEE Embedded but you can do the same with an Application Composer application. +
+
+
+ + + + + +
+ + +if you have META-INF/web-fragment.xml in your application you will need to merge them in a single one in the shade. Note that tomcat provides one +which can be skipped in this operation since it is there only as a marker for jasper detection. +
+
+
+

Then just build the jar:

+
+
+
+
mvn clean package
+
+
+
+

And you can run it:

+
+
+
+
java -jar myapp-1.0-SNAPSHOT.jar
+
+
+
+
+
+

Fat Jars with Gradle

+
+
+

With gradle you can rely on either jar plugin, fatjar plugin or shadowjar plugin. Last one is likely the closer to maven shade plugin +so that’s the one used for next sample:

+
+
+
+
// run $ gradle clean shadowJar
+import org.apache.openwebbeans.gradle.shadow.OpenWebBeansPropertiesTransformer
+
+buildscript {
+    repositories {
+        mavenLocal()
+        jcenter()
+    }
+    dependencies {
+        classpath 'com.github.jengelman.gradle.plugins:shadow:1.2.3'
+        classpath 'org.apache.openwebbeans:openwebbeans-gradle:1.7.0'
+    }
+}
+
+apply plugin: 'com.github.johnrengelman.shadow'
+
+group 'org.apache.tomee.demo.gradle'
+version '1.0-SNAPSHOT'
+
+apply plugin: 'idea'
+apply plugin: 'java'
+
+sourceCompatibility = 1.8
+
+repositories {
+    mavenLocal()
+    mavenCentral()
+}
+
+dependencies {
+    compileOnly 'org.projectlombok:lombok:1.16.10'
+    compile 'org.apache.tomee:tomee-embedded:7.0.2-SNAPSHOT'
+}
+
+// customize exclusions depending your app
+
+// first the not used dependencies like JSF, JAXWS, JMS ones
+def excludedDependenciesGroups = [
+        // gradle is buggy with poms, scope provided and optional I think
+        'com.google.code.findbugs',
+        'com.google.guava',
+        'javax.annotation',
+        'javax.ws.rs',
+        'net.sf.ehcache',
+        'org.apache.httpcomponents',
+        'org.ow2.asm',
+        // tomee jaxws, jms, etc...
+        'commons-codec',
+        'com.sun.xml.messaging.saaj',
+        'joda-time',
+        'junit',
+        'net.shibboleth.utilities',
+        'org.apache.activemq',
+        'org.apache.activemq.protobuf',
+        'org.apache.myfaces.core',
+        'org.apache.neethi',
+        'org.apache.santuario',
+        'org.apache.ws.xmlschema',
+        'org.apache.wss4j',
+        'org.bouncycastle',
+        'org.cryptacular',
+        'org.fusesource.hawtbuf',
+        'org.jasypt',
+        'org.jvnet.mimepull',
+        'org.opensaml',
+        'wsdl4j',
+        'xml-resolver'
+]
+
+// then cxf+tomee specific dependencies so we need to be more precise than the group
+// to not exclude everything
+def excludedDependenciesArtifacts = [
+        'cxf-rt-bindings-soap',
+        'cxf-rt-bindings-xml',
+        'cxf-rt-databinding-jaxb',
+        'cxf-rt-frontend-jaxws',
+        'cxf-rt-frontend-simple',
+        'cxf-rt-security-saml',
+        'cxf-rt-ws-addr',
+        'cxf-rt-wsdl',
+        'cxf-rt-ws-policy',
+        'cxf-rt-ws-security',
+        'openejb-cxf',
+        'openejb-webservices',
+        'tomee-webservices',
+        'geronimo-connector',
+        'geronimo-javamail_1.4_mail'
+]
+shadowJar {
+    classifier = 'bundle'
+
+    // merge SPI descriptors
+    mergeServiceFiles()
+    append 'META-INF/cxf/bus-extensions.txt'
+    transform(OpenWebBeansPropertiesTransformer.class)
+
+    // switch off JSF + JMS + JAXWS
+    exclude 'META-INF/faces-config.xml'
+    dependencies {
+        exclude(dependency {
+            excludedDependenciesGroups.contains(it.moduleGroup) ||
+                    excludedDependenciesArtifacts.contains(it.moduleName)
+        })
+    }
+
+    // ensure we define the expected Main (if you wrap tomee main use your own class)
+    manifest {
+        attributes 'Main-Class': 'org.apache.tomee.embedded.FatApp'
+    }
+}
+
+
+
+

Then run:

+
+
+
+
gradle clean build shadowJar
+
+
+
+

and you’ll get build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar ready to run with:

+
+
+
+
java -jar build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar --as-war --simple-log=true
+
+
+
+
+
+

Fat Wars

+
+
+

Fat Wars are executable wars. Note they can be fancy for demos but they have the drawback to put the server in web resources +at packaging time (to ensure the war is actually an executable jar) so adding a filter preventing these files to be read +can be needed if you don’t already use a web technology doing it (a servlet bound to /*).

+
+
+

Here how to do a fat war:

+
+
+
+
<properties>
+  <!-- can be uber (for all), jaxrs, jaxws for lighter ones -->
+  <tomee.flavor>uber</tomee.flavor>
+</properties>
+
+<dependencies>
+  <!-- ...your dependencies as usual... -->
+  <dependency>
+    <groupId>org.apache.tomee</groupId>
+    <artifactId>tomee-embedded</artifactId>
+    <classifier>${tomee.flavor}</classifier>
+    <version>7.0.0</version>
+    <scope>provided</scope>
+  </dependency>
+</dependencies>
+
+<build>
+  <plugins>
+    <plugin>
+      <groupId>org.apache.maven.plugins</groupId>
+      <artifactId>maven-war-plugin</artifactId>
+      <version>2.6</version>
+      <configuration>
+        <failOnMissingWebXml>false</failOnMissingWebXml>
+        <archive>
+          <manifest>
+            <mainClass>org.apache.tomee.embedded.Main</mainClass>
+          </manifest>
+        </archive>
+        <dependentWarExcludes />
+        <overlays>
+          <overlay>
+            <groupId>org.apache.tomee</groupId>
+            <artifactId>tomee-embedded</artifactId>
+            <classifier>${tomee.flavor}</classifier>
+            <type>jar</type>
+            <excludes />
+          </overlay>
+        </overlays>
+      </configuration>
+    </plugin>
+  </plugins>
+</build>
+
+
+
+

Then just build the war:

+
+
+
+
mvn clean package
+
+
+
+

And you can run it:

+
+
+
+
java -jar myapp-1.0-SNAPSHOT.war
+
+
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/advanced/shading/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/tomee-8.0/docs/advanced/tomee-embedded/index.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/advanced/tomee-embedded/index.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/advanced/tomee-embedded/index.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/advanced/tomee-embedded/index.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,788 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

TomEE Embedded

+
+
+
+
+ +
+
+
+
+

TomEE Embedded is based on Tomcat embedded and starts a real TomEE in the launching JVM. It is also +able to deploy the classpath as a webapp and to use either META-INF/resources or a folder as web resources.

+
+
+

Here is a basic programmatic usage based on org.apache.tomee.embedded.Container class:

+
+
+
+
try (final Container container = new Container(new Configuration()).deployClasspathAsWebApp()) {
+    System.out.println("Started on http://localhost:" + container.getConfiguration().getHttpPort());
+
+    // do something or wait until the end of the application
+}
+
+
+
+

All EE features are then accessible directly in the same JVM.

+
+
+
+
+

TomEE Embedded Configuration

+
+
+

The default configuration allows to start tomee without issue but you can desire to customize some of them.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDefaultDescription

httpPort

8080

http port

stopPort

8005

shutdown port

host

localhost

host

dir

-

where to create a file hierarchy for tomee (conf, temp, …​)

serverXml

-

which server.xml to use

keepServerXmlAsThis

false

don’t adjust ports/host from the configuration and keep the ones in server.xml

properties

-

container properties

quickSession

true

use Random instead of SecureRandom (for dev)

skipHttp

false

don’t use the http connector

httpsPort

8443

https potr

ssl

false

activate https

withEjbRemote

false

use EJBd

keystoreFile

-

https keystore location

keystorePass

-

https keystore password

keystoreType

JKS

https keystore type

clientAuth

-

https client auth

keyAlias

-

https alias

sslProtocol

-

SSL protocol for https connector

webXml

-

default web.xml to use

loginConfig

-

which LoginConfig to use, relies on org.apache.tomee.embedded.LoginConfigBuilder to create it

securityConstraints

-

add some security constraints, use org.apache.tomee.embedded.SecurityConstaintBuilder to build them

realm

-

which realm to use (useful to switch to JAASRealm for instance) without modifying the application

deployOpenEjbApp

false

should internal openejb application be delpoyed

users

-

a map of user/password

roles

-

a map of role/users

tempDir

${java.io.tmpdir}/tomee-embedded_${timestamp}

tomcat needs a docBase, in case you don’t provide one one will be created there

webResourceCached

true

should web resources be cached by tomcat (set false in frontend dev)

configuration-location

-

location (classpath or file) to a .properties to configure the server +[pre-task

-

Runnable or org.apache.tomee.embedded.LifecycleTask implementations to execute before the container starts

classes-filter

-

implementation of a custom xbean Filter to ignore not desired classes during scanning

basic

+
+

Note: passing to Container constructor a Configuration it will start the container automatically but using setup(Configuration) +to initialize the configuration you will need to call start().

+
+
+

You can also pass through the properties connector.xxx and connector.attributes.xxx to customize connector(s) +configuration directly.

+
+
+
+
+

Standalone applications or TomEE Embedded provided main(String[])

+
+
+

Deploying an application in a server is very nice cause the application is generally small and it allows to update the +container without touching the application (typically insanely important in case of security issues for instance).

+
+
+

However sometimes you don’t have the choice so TomEE Embedded provides a built-in main(String[]). Here are its options:

+
+
+ + + + + +
+ + +this is still a TomEE so all system properties work (for instance to create a resource). +
+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDefaultDescription

--path

-

location of application(s) to deploy

--context

-

Context name for applications (same order than paths)

-p or --port

8080

http port

-s or --shutdown

8005

shutdown port

-d or --directory

./.apache-tomee

tomee work directory

-c or --as-war

-

deploy classpath as a war

-b or --doc-base

-

where web resources are for classpath deployment

--renaming

-

for fat war only, is renaming of the context supported

--serverxml

-

the server.xml location

--tomeexml

-

the server.xml location

--property

-

a list of container properties (values follow the format x=y)

+
+

Note that since 7.0.0 TomEE provides 3 flavors (qualifier) of tomee-embedded as fat jars:

+
+
+
    +
  • +

    uber (where we put all request features by users, this is likely the most complete and the biggest)

    +
    • +
  • +

    jaxrs: webprofile minus JSF

    +
    • +
  • +

    jaxws: webprofile plus JAX-WS

    +
    • +
+
+
+

These different uber jars are interesting in mainly 2 cases:

+
+
+
    +
  • +

    you do a war shade (it avoids to list a bunch of dependencies but still get a customized version)

    +
    • +
  • +

    you run your application using --path option

    +
    • +
+
+
+ + + + + +
+ + +if you already do a custom shade/fatjar this is not really impacting since you can depend on tomee-embedded and exclude/include what you want. +
+
+
+
+
+

FatApp a shortcut main

+
+
+

FatApp main (same package as tomee embedded Main) just wraps the default main ensuring:

+
+
+
    +
  • +

    ̀`--as-war` is used

    +
    • +
  • +

    ̀`--single-classloader` is used

    +
    • +
  • +

    --configuration-location=tomee-embedded.properties is set if tomee-embedded.properties is found in the classpath

    +
    • +
+
+
+
+
+

configuration-location

+
+
+

--configuration-location option allows to simplify the configuration of tomee embedded through properties.

+
+
+

Here are the recognized entries (they match the configuration, see org.apache.tomee.embedded.Configuration for the detail):

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name

http

https

stop

host

dir

serverXml

keepServerXmlAsThis

quickSession

skipHttp

ssl

http2

webResourceCached

withEjbRemote

deployOpenEjbApp

keystoreFile

keystorePass

keystoreType

clientAuth

keyAlias

sslProtocol

webXml

tempDir

classesFilter

conf

properties.x (set container properties x with the associated value)

users.x (for default in memory realm add the user x with its password - the value)

roles.x (for default in memory realm add the role x with its comma separated users - the value)

connector.x (set the property x on the connector)

realm=fullyqualifiedname,realm.prop=xxx (define a custom realm with its configuration)

login=,login.prop=xxx (define a org.apache.tomee.embedded.LoginConfigBuilder == define a LoginConfig)

securityConstraint=,securityConstraint.prop=xxx (define a org.apache.tomee.embedded.SecurityConstaintBuilder == define webapp security)

configurationCustomizer.alias=,configurationCustomizer.alias.class=class,configurationCustomizer.alias.prop=xxx (define a ConfigurationCustomizer)

+
+

Here is a sample to add BASIC security on /api/*:

+
+
+
+
# security configuration
+securityConstraint =
+securityConstraint.authConstraint = true
+securityConstraint.authRole = **
+securityConstraint.collection = api:/api/*
+
+login =
+login.realmName = app
+login.authMethod = BASIC
+
+realm = org.apache.catalina.realm.JAASRealm
+realm.appName = app
+
+properties.java.security.auth.login.config = configuration/login.jaas
+
+
+
+

And here a configuration to exclude jackson packages from scanning and use log4j2 as main logger (needs it as dependency):

+
+
+
+
properties.openejb.log.factory = log4j2
+properties.openejb.container.additional.include = com.fasterxml.jackson,org.apache.logging.log4j
+
+
+
+
+
+

Application Runner

+
+
+

SInce TomEE 7.0.2, TomEE provide a light ApplicationComposer integration for TomEE Embedded (all features are not yet supported but the main ones are): +org.apache.tomee.embedded.TomEEEmbeddedApplicationRunner. It relies on the definition of an @Application:

+
+
+
+
@Application
+@Classes(context = "app")
+@ContainerProperties(@ContainerProperties.Property(name = "t", value = "set"))
+@TomEEEmbeddedApplicationRunner.LifecycleTasks(MyTask.class) // can start a ftp/sftp/elasticsearch/mongo/... server before tomee
+@TomEEEmbeddedApplicationRunner.Configurers(SetMyProperty.class)
+public class TheApp {
+    @RandomPort("http")
+    private int port;
+
+    @RandomPort("http")
+    private URL base;
+
+    @org.apache.openejb.testing.Configuration
+    public Properties add() {
+        return new PropertiesBuilder().p("programmatic", "property").build();
+    }
+
+    @PostConstruct
+    public void appStarted() {
+        // ...
+    }
+}
+
+
+
+

Then just start it with:

+
+
+
+
TomEEEmbeddedApplicationRunner.run(TheApp.class, "some arg1", "other arg");
+
+
+
+ + + + + +
+ + +@Classes(values) and @Jars are supported too which can avoid a huge scanning if you run with a lot of not CDI dependencies which would boost the startup of your application. +
+
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/advanced/tomee-embedded/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/tomee-8.0/docs/contrib/debug/debug-intellij.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/contrib/debug/debug-intellij.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/contrib/debug/debug-intellij.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/contrib/debug/debug-intellij.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,266 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +

null

+
+
+
+
+ +
+ +

Debugging an Apache TomEE App in Intellij IDEA

+

Stepping through the TomEE source code is a must-to-follow step if you want to understand how TomEE works and later contribute. This is a guide to quickly start your debugging session with TomEE as a TomEE developer.

+

This guide assumes that:

+
    +
  • Linux is the OS
    • +
  • IntelliJ IDEA 13.1.3 is the IDE
    • +
  • Maven 3.0.5 or better is installed
    • +
+

Download the Source Code

+

For beginners it is recommended not to start with the trunk, because it is common to have some blockers or non-stable functionality which could bring your learning to a halt. So first start with the latest stable released source code. Move to trunk once you are ready to do some code modification on TomEE.

+

Click here to download TomEE 1.7.1 Source code

+

Build the Source Code

+

First extract the zip file named openejb-4.7.1-source-release.zip to any location. Lets assume it is your home folder.

+
+

unzip openejb-4.7.1-source-release -d ~

+
+

The above command will create the openejb-4.7.1 directory in your home directory.

+

Even though you can do a full build, We will run the following command to do a quick build so that you can have your meal before your hunger kills you.

+
+

mvn -Pquick -Dsurefire.useFile=false -DdisableXmlReport=true -DuniqueVersion=false -ff -Dassemble -DskipTests -DfailIfNoTests=false clean install

+
+

More details about building the product from the source can be found here.

+

Deploy TomEE

+

The TomEE build builds several distributions (zip & war files) to cater the different needs of different users. Here we discuss about the tomee plus distribution & TomEE war distribution only. TomEE+ is the full feature packed distribution from TomEE.

+

TomEE+ zip location:

+
+

~/openejb-4.7.1/tomee/apache-tomee/target/apache-tomee-plus-1.7.1.zip

+
+

Unzip the zip into your home directory (or any other location)

+
+

unzip ~/openejb-4.7.1/tomee/apache-tomee/target/apache-tomee-plus-1.7.1.zip -d ~

+
+

You will find the directory apache-tomee-plus-1.7.1 in your home folder. Lets run the TomEE.

+
+

cd ~/apache-tomee-plus-1.7.1/bin

./catalina.sh run

+
+

"INFO: Server startup in xxxx ms" is the Green light!

+

Prepare your IDE

+

Lets prepare our IntelliJ IDEA for the debugging session.

+

Start IntelliJ IDEA and Click the Import Project link

+

+

Select the ~/openejb-4.7.1 directory and press OK

+

Select import project from external model & Maven as the external model.

+

+

Press Next on this screen.

+

+

Select the main profile.

+

+

Select the org.apache.openejb:openejb:4.7.1

+

+

Select the JDK you want to use with.

+

+

Give the project a name and press Finish.

+

+

Now your IDE will load the project.

+

First Breakpoint

+

Next step is to put a breakpoint at the place where the code is triggered. Lets understand how the code is triggered.

+

TomEE+ is created on top of Tomcat. TomEE registers a Tomcat Lifecycle Listener "org.apache.tomee.catalina.ServerListener" on server.xml file.

+

All the Tomcat lifecycle events i.e. before_init, after_init, start, before_stop etc... are received by the lifecycleEvent method of the ServerListener.

+

The execution of TomEE code starts in this lifecycleEvent method. So the first breakpoint should be on the lifecycleEvent method.

+

Run TomEE+ in debug mode

+

If you simply run catalina.sh jpda run in the bin folder of tomee deployment, the server starts in the debug mode but it will quckly pass your breakpoint before you attach your IDE to the server process.

+

So we set** JPDA_SUSPEND="y"** before we start our debugging. This will tell the server "Do not proceed until the Debugger tool is attached to the process"

+

The convenient way of doing this is adding this line to catalina.sh file right after the #!/bin/sh line.

+
+

#!/bin/sh
JPDA_SUSPEND="y"

+

Now to time to run TomEE+ on debug mode.

+

~/apache-tomee-plus-1.7.1/bin/catalina.sh jpda run

+
+

The terminal should hang with the message "Listening for transport dt_socket at address: 8000"

+

Attach IntelliJ IDEA debugger

+
    +
  • Menu Bar > Run > Edit Configurations
    • +
  • Press the "**+**" button on the top left corner to get the Add new configuration menu
    • +
  • Select "Remote" from the Add new configuration menu
    • +
  • Give a name (I gave "TomEE DEBUG") to this new configuration and set the Port to 8000
    • +
  • Click OK.
    • +
+

+

To start debugging your TomEE+

+

Main Menu > Run > Debug TomEE DEBUG

+

Congratulations! You hit the break point you put at the startup of the TomEE code. Carry on with your debugging session to learn more.

+
+ +
+ + + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/contrib/debug/debug-intellij.html ------------------------------------------------------------------------------ svn:eol-style = native