From commits-return-44128-archive-asf-public=cust-asf.ponee.io@tomee.apache.org Sun Dec 2 01:12:56 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 31B0818077A for ; Sun, 2 Dec 2018 01:12:54 +0100 (CET) Received: (qmail 974 invoked by uid 500); 2 Dec 2018 00:12:53 -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 882 invoked by uid 99); 2 Dec 2018 00:12:53 -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:53 +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 493243A0F1A for ; Sun, 2 Dec 2018 00:12:52 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1847931 [3/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.493243A0F1A@svn01-us-west.apache.org> Added: tomee/site/trunk/content/latest/docs/admin/configuration/server.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/latest/docs/admin/configuration/server.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/latest/docs/admin/configuration/server.html (added) +++ tomee/site/trunk/content/latest/docs/admin/configuration/server.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,557 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

Container Configuration

+
+
+
+
+ +
+
+

Server

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameValueDescription

openejb.embedded.remotable

bool

activate or not the remote services when available

.bind, <service prefix>.port, <service prefix>.disabled, <service prefix>.threads

host or IP, port, bool

override the host. Available for ejbd and httpejbd services (used by jaxws and jaxrs), number of thread to manage requests

openejb.embedded.initialcontext.close

LOGOUT or DESTROY

configure the hook called when closing the initial context. Useful when starting OpenEJB from a new InitialContext([properties]) instantiation. By default it simply logs out the logged user if it exists. DESTROY means clean the container.

javax.persistence.provider

string

override the JPA provider value

javax.persistence.transactionType

string

override the transaction type for persistence contexts

javax.persistence.jtaDataSource

string

override the JTA datasource value for persistence contexts

javax.persistence.nonJtaDataSource

string

override the non JTA datasource value for persistence contexts

openejb.descriptors.output

bool

dump memory deployment descriptors. Can be used to set complete metadata to true and avoid scanning when starting the container or to check the used configuration.

openejb.deployments.classpath.require.descriptor

CLIENT or EJB

can allow to filter what you want to scan (client modules or ejb modules)

openejb.descriptors.output.folder

path

where to dump deployement descriptors if activated.

openejb.strict.interface.declaration

bool

add some validations on session beans (spec validations in particular). false by default.

openejb.conf.file or openejb.configuration

string

OpenEJB configuration file path

openejb.debuggable-vm-hackery

bool

remove JMS informations from deployment

openejb.validation.skip

bool

skip the validations done when OpenEJB deploys beans

openejb.deployments.classpath.ear

bool

deploy the classpath as an ear

openejb.webservices.enabled

bool

activate or not webservices

openejb.validation.output.level

TERSE or MEDIUM or VERBOSE

level of the logs used to report validation errors

openejb.user.mbeans.list * or a list of classes separated by ,

list of mbeans to deploy automatically

openejb.deploymentId.format composition (+string) of {ejbName} {ejbType} {ejbClass} and {ejbClass.simpleName} default {ejbName}. The format to use to deploy ejbs.

openejb.deployments.classpath

bool

whether or not deploy from classpath

openejb.deployments.classpath.include and openejb.deployments.classpath.exclude

regex

regex to filter the scanned classpath (when you are in this case)

openejb.deployments.package.include and openejb.deployments.package.exclude

regex

regex to filter scanned packages

openejb.autocreate.jta-datasource-from-non-jta-one

bool

whether or not auto create the jta datasource if it doesn’t exist but a non jta datasource exists. Useful when using hibernate to be able to get a real non jta datasource.

openejb.altdd.prefix

string

prefix use for altDD (example test to use a test.ejb-jar.xml).

org.apache.openejb.default.system.interceptors

class names

list of interceptor (qualified names) separated by a comma or a space add these interceptor on all beans

openejb.jndiname.strategy.class

class name

an implementation of org.apache.openejb.assembler.classic.JndiBuilder.JndiNameStrategy

openejb.jndiname.failoncollision

bool

if a NameAlreadyBoundException is thrown or not when 2 EJBs have the same name

openejb.jndiname.format

string

composition of these properties: ejbType, ejbClass, ejbClass.simpleName, ejbClass.packageName, ejbName, deploymentId, interfaceType, interfaceType.annotationName, interfaceType.annotationNameLC, interfaceType.xmlName, interfaceType.xmlNameCc, interfaceType.openejbLegacyName, interfaceClass, interfaceClass.simpleName, interfaceClass.packageName default {deploymentId}{interfaceType.annotationName}. Change the name used for the ejb.

openejb.org.quartz.threadPool.class

class

qualified name which implements org.quartz.spi.ThreadPool the thread pool used by quartz (used to manage ejb timers)

openejb.localcopy

bool

default true. whether or not copy EJB arguments[/method/interface] for remote invocations.

openejb.cxf.jax-rs.providers

string

the list of the qualified name of the JAX-RS providers separated by comma or space. Note: to specify a provider for a specific service suffix its class qualified name by ".providers", the value follow the same rules. Note 2: default is a shortcut for jaxb and json providers.

openejb.wsAddress.format

string

composition of {ejbJarId}, ejbDeploymentId, ejbType, ejbClass, ejbClass.simpleName, ejbName, portComponentName, wsdlPort, wsdlService default /{ejbDeploymentId}. The WS name format.

org.apache.openejb.server.webservices.saaj.provider

axis2, sun or null

specified the saaj configuration

[<uppercase service name>.]<service id>.<name> or [<uppercase service name>.]<service id>

whatever is supported (generally string, int …​)

set this value to the corresponding service. example: [EnterpriseBean.]<ejb-name>.activation.<property>, [PERSISTENCEUNIT.]<persistence unit name>.<property>, [RESOURCE.]<name>

log4j.category.OpenEJB.options

DEBUG, INFO, …​

active one OpenEJB log level. need log4j in the classpath

openejb.jmx.active

bool

activate (by default) or not the OpenEJB JMX MBeans

openejb.nobanner

bool

activate or not the OpenEJB banner (activated by default)

openejb.check.classloader

bool

if true print some information about duplicated classes

openejb.check.classloader.verbose

bool

if true print classes intersections

openejb.additional.exclude

string separated by comma

list of prefixes you want to exclude and are not in the default list of exclusion

openejb.additional.include

string separated by comma

list of prefixes you want to remove from thedefault list of exclusion

openejb.offline

bool

if true can create datasources and containers automatically

openejb.exclude-include.order

include-exclude or exclude-include

if the inclusion/exclusion should win on conflicts (intersection)

openejb.log.color

bool

activate or not the color in the console in embedded mode

openejb.log.color.<level in lowercase>

color in uppercase

set a color for a particular level. Color are BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, DEFAULT.

tomee.serialization.class.blacklist

string

default list of packages/classnames excluded for EJBd deserialization (needs to be set on server and client sides). Please see the description of Ejbd Transport for details.

tomee.serialization.class.whitelist

string

default list of packages/classnames allowed for EJBd deserialization (blacklist wins over whitelist, needs to be set on server and client sides). Please see the description of Ejbd Transport for details.

tomee.remote.support

boolean

if true /tomee webapp is auto-deployed and EJBd is active (true by default for 1.x, false for 7.x excepted for tomee maven plugin and arquillian)

openejb.crosscontext

bool

set the cross context property on tomcat context (can be done in the traditionnal way if the deployment is don through the webapp discovery and not the OpenEJB Deployer EJB)

openejb.jsessionid-support

bool

remove URL from session tracking modes for this context (see javax.servlet.SessionTrackingMode)

openejb.myfaces.disable-default-values

bool

by default TomEE will initialize myfaces with some its default values to avoid useless logging

openejb.web.xml.major

int

major version of web.xml. Can be useful to force tomcat to scan servlet 3 annotatino when deploying with a servlet 2.x web.xml

tomee.jaxws.subcontext

string

sub context used to bind jaxws web services, default is webservices

openejb.servicemanager.enabled

bool

run all services detected or only known available services (WS and RS

tomee.jaxws.oldsubcontext

bool

wether or not activate old way to bind jaxws webservices directly on root context

openejb.modulename.useHash

bool

add a hash after the module name of the webmodule if it is generated from the webmodule location, it avoids conflicts between multiple deployment (through ear) of the same webapp. Note: it disactivated by default since names are less nice this way.

openejb.session.manager

qualified name (string)

configure a session managaer to use for all contexts

tomee.tomcat.resource.wrap

bool

wrap tomcat resources (context.xml) as tomee resources if possible (true by default)

tomee.tomcat.datasource.wrap

bool

same as tomee.tomcat.resource.wrap for datasource (false by default). Note that setting it to true will create tomee datasources but can have the side effect to create twice singleton resources

openejb.environment.default

bool

should default JMS resources be created or not, default to false to ensure no port is bound or multiple resources are created and completely uncontrolled (doesn’t apply to datasources etc for compatibility). For tests only!

+
+
+

Client

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameValueDescription

openejb.client.identityResolver

implementation of org.apache.openejb.client.IdentityResolver

default org.apache.openejb.client.JaasIdentityResolver. The class to get the client identity.

openejb.client.connection.pool.timeout or openejb.client.connectionpool.timeout

int (ms)

the timeout of the client

openejb.client.connection.pool.size or openejb.client.connectionpool.size

int

size of the socket pool

openejb.client.keepalive

int (ms)

the keepalive duration

openejb.client.protocol.version

string

Optional legacy server protocol compatibility level. Allows 4.6.x clients to potentially communicate with older servers. OpenEJB 4.5.2 and older use version "3.1", and 4.6.x currently uses version "4.6" (Default). This does not allow old clients to communicate with new servers prior to 4.6.0

tomee.serialization.class.blacklist

string

default list of packages/classnames excluded for EJBd deserialization (needs to be set on server and client sides). Please see the description of Ejbd Transport for details.

tomee.serialization.class.whitelist

string

default list of packages/classnames allowed for EJBd deserialization (blacklist wins over whitelist, needs to be set on server and client sides). Please see the description of Ejbd Transport for details.

+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/latest/docs/admin/configuration/server.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/latest/docs/advanced/applicationcomposer/index.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/latest/docs/advanced/applicationcomposer/index.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/latest/docs/advanced/applicationcomposer/index.html (added) +++ tomee/site/trunk/content/latest/docs/advanced/applicationcomposer/index.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,272 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

ApplicationComposer with JBatch

+
+
+
+
+ +
+
+

ApplicationComposer can be a way to run a JBatch not needing any HTTP connector.

+
+
+

Here is an example making batch integration easy - note you can extract the generic part in a library very easily:

+
+
+ + + + + +
+ + +if you didn’t check yet BatchEE provides some standalone utilities for JBatch but the idea of this page can be reused for a lot of applications. +
+
+
+
+
// helper class reusable for any batch
+abstract class BatchApplication {
+    private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("YYYYMMddHHmmss");
+
+    protected Report runBatch(final String batchName, final Properties config) {
+        final JobOperator operator = BatchRuntime.getJobOperator();
+        final long id = operator.start(batchName, config);
+        Batches.waitForEnd(operator, id);
+        return new Report(operator.getJobExecution(id), operator.getParameters(id));
+    }
+
+    @Module // we enforce BatchEE to be initialized as an EJB context to get JNDI for JTA init, needed for TomEE 1
+    public EjbModule ensureBatchEESetupIsDoneInTheRightContext() {
+        final EjbJar ejbJar = new EjbJar().enterpriseBean(new SingletonBean(BatchEEBeanManagerInitializer.class));
+
+        final Beans beans = new Beans();
+        beans.addManagedClass(BatchEEBeanManagerInitializer.Init.class);
+
+        final EjbModule ejbModule = new EjbModule(ejbJar);
+        ejbModule.setModuleId("batchee-shared-components");
+        ejbModule.setBeans(beans);
+        return ejbModule;
+    }
+
+    public static class Report {
+        private final JobExecution execution;
+        private final Properties properties;
+
+        public Report(final JobExecution execution, final Properties properties) {
+            this.execution = execution;
+            this.properties = properties;
+        }
+
+        public JobExecution getExecution() {
+            return execution;
+        }
+
+        public Properties getProperties() {
+            return properties;
+        }
+    }
+}
+
+@Classes(cdi = true, value = { MyFilter.class, MoveFile.class, InputFile.class, MyReader.class, LoggingListener.class })
+public class MyBatch extends BatchApplication {
+    private final Properties config;
+
+    public Mybatch(final String[] args) { // main args
+        this.config = new Properties() {{ // create the batch config
+            setProperty("input-directory", args[0]);
+        }};
+    }
+
+    public Report execute(final String inputDirectory) {
+        return runBatch("sunstone", config);
+    }
+
+    public static void main(final String[] args) throws Exception {
+        ApplicationComposers.run(MyBatch.class, args);
+    }
+}
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/latest/docs/advanced/applicationcomposer/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/latest/docs/advanced/client/jndi.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/latest/docs/advanced/client/jndi.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/latest/docs/advanced/client/jndi.html (added) +++ tomee/site/trunk/content/latest/docs/advanced/client/jndi.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,365 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +

Java Naming and Directory Interface (JNDI)

+
+
+
+
+ +
+
+

TomEE has several JNDI client intended for multiple usages.

+
+
+

Default one

+
+
+

In a standalone instance you generally don’t need (or want) to specify anything +to do a lookup. Doing so you will inherit from the contextual environment:

+
+
+
+
final Context ctx = new InitialContext();
+ctx.lookup("java:....");
+
+
+
+
+
+

LocalInitialContextFactory

+
+
+

This is the legacy context factory used by OpenEJB. It is still useful to fallback +on the "default" one in embedded mode where sometimes classloaders or libraries can mess +up the automatic conextual context.

+
+
+

Usage:

+
+
+
+
Properties properties = new Properties();
+properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.LocalInitialContextFactory");
+final Context ctx = new InitialContext(properties);
+ctx.lookup("java:....");
+
+
+
+

This context factory supports few more options when you boot the container creating a context:

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

Name

Description

openejb.embedded.remotable

true/false: starts embedded services

Context.SECURITY_PRINCIPAL/Context.SECURITY_CREDENTIALS

the global security identity for the whole container

+
+ + + + + +
+ + +Context.SECURITY_* shouldn’t be used for runtime lookups with LocalInitialContextFactory, it would leak a security identity and make the runtime no more thread safe. +This factory was deprecated starting with 7.0.2 in favor of org.apache.openejb.core.OpenEJBInitialContextFactory. +
+
+
+
+
+

OpenEJBInitialContextFactory

+
+
+

This factory allows you to access local EJB and container resources.

+
+
+
+
Properties properties = new Properties();
+properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.OpenEJBInitialContextFactory");
+final Context ctx = new InitialContext(properties);
+ctx.lookup("java:....");
+
+
+
+
+
+

RemoteInitialContextFactory

+
+
+

Intended to be used to contact a remote server, the org.apache.openejb.client.RemoteInitialContextFactory relies on the provider url +to contact a tomee instance:

+
+
+
+
Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory");
+p.put(Context.PROVIDER_URL, "failover:ejbd://192.168.1.20:4201,ejbd://192.168.1.30:4201");
+
+final InitialContext remoteContext = new InitialContext(p);
+ctx.lookup("java:....");
+
+
+
+

Contrarly to local one, the remote factory supports Context.SECURITY_* options in a thread safe manner and you can do lookups at runtime using them.

+
+
+

See Cluster page for more details on the options.

+
+
+

Security

+
+

The context configuration can take additional configuration to handle EJB security:

+
+
+
+
p.put("openejb.authentication.realmName", "my-realm"); // optional
+p.put(Context.SECURITY_PRINCIPAL, "alfred");
+p.put(Context.SECURITY_CREDENTIALS, "bat");
+
+
+
+

The realm will be used by JAAS to get the right LoginModules and principal/credentials to +do the actual authentication.

+
+
+

HTTP case

+
+

Often HTTP layer is secured and in this case you need to authenticate before the EJBd (remote EJB TomEE protocol) layer. +Thanks to TomEE/Tomcat integration login there will propagate to the EJBd context.

+
+
+

This can be done passing the token you need to set as Authorization header in the PROVIDER_URL:

+
+
+
+
// tomee/openejb principal/credentials
+p.put(Context.PROVIDER_URL, "http://localhost:8080/tomee/ejb?authorization=Basic%20dG9tZWU6b3BlbmVqYg==");
+
+
+
+

The token passed as authorization query parameter is the header value URL encoded. It can +be any token like a basic one, a custom one, an OAuth2 one (in this case you need to renew it programmatically +and change your client instance when renewing) etc…​

+
+
+ + + + + +
+ + +basic being very common there is a shortcut with two alternate query parameter replacing authorization one: basic.password and basic.username. +
+
+
+

Finally if you don’t use Authorization header you can change the used header setting authorizationHeader query parameter.

+
+
+ + + + + +
+ + +authorization, authorizationHeader, basic.username, and basic.password are removed +from the URL before opening the connection and therefore not logged in the remote server access log since version 7.0.3. +
+
+
+
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/latest/docs/advanced/client/jndi.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/latest/docs/advanced/jms/jms-configuration.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/latest/docs/advanced/jms/jms-configuration.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/latest/docs/advanced/jms/jms-configuration.html (added) +++ tomee/site/trunk/content/latest/docs/advanced/jms/jms-configuration.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,276 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

Why is my ActiveMQ/JMS MDB not scaling as expected?

+
+
+
+
+ +
+
+

Why my ActiveMQ/JMS MDB is not scaling as expected?

+
+

There are multiple configurations points to ensure you scale as much as you want.

+
+
+

Here some common configuration to validate (note that when possible the sample value is the default):

+
+
+
    +
  • +

    The resource adapter thread pool ("worker threads" or WorkManager) limits the number of max work threads:

    +
    • +
+
+
+
+
<Resource id="my resource adapter" ....>
+  # using -1 will make the server using cached threads (unbounded)
+  # min recommanded: maxSessions + 1 (for connect())
+  threadPoolSize = 30
+</Resource>
+
+
+
+
    +
  • +

    Then the MDB container itself has a upper bound through InstanceLimit which controls the max MDB instance count:

    +
    • +
+
+
+
+
<Container id="my mdb container" type="MESSAGE">
+    # -1 will disable it
+    # min recommanded = maxSessions
+    InstanceLimit = 10
+</Container>
+
+
+
+
    +
  • +

    ActiveMQ maxSessions controls how many sessions a MDB can use:

    +
    • +
+
+
+
+
@MessageDriven(activationConfig = {
+        @javax.ejb.ActivationConfigProperty(propertyName = "maxSessions", propertyValue = "1"),
+        @javax.ejb.ActivationConfigProperty(propertyName = "destination", propertyValue = "target-queue")
+})
+public static class MyMdb implements MessageListener {
+    @Override
+    public void onMessage(final Message message) {
+        // ...
+    }
+}
+
+
+
+
    +
  • +

    The ConnectionFactory has also an instance pool through geronimo-connector logic, configuration +can make the behavior changing but this is controlled through pool related variables (the pool and resource properties are merged in the definition):

    +
    • +
+
+
+
+
<Resource id="my connection factory" type="ConnectionFactory">
+    # recommanded to be aligned on maxSessions
+    PoolMaxSize = 10
+    # for 100% MDB (no client) you can evaluate to turn it off/false, for client it can still be useful depending what you do
+    Pooling = true
+</Resource>
+
+
+
+
+

Slow Message Consumption

+
+

If you find you have a slow consumption of messages there are several options to have a look (activemq website explains it very well) +but one very impacting option can be the prefetch size.

+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/latest/docs/advanced/jms/jms-configuration.html ------------------------------------------------------------------------------ svn:eol-style = native