TOMEE-2316 Convert Markdown files to Asciidoc in the docs folder - 13
Project: http://git-wip-us.apache.org/repos/asf/tomee/repo Commit: http://git-wip-us.apache.org/repos/asf/tomee/commit/aef8367d Tree: http://git-wip-us.apache.org/repos/asf/tomee/tree/aef8367d Diff: http://git-wip-us.apache.org/repos/asf/tomee/diff/aef8367d Branch: refs/heads/master Commit: aef8367d3b001ccf908b941d1c48d5e68285a95f Parents: 388460f Author: Carlos Chacin <[email protected]> Authored: Wed Dec 5 22:07:29 2018 -0800 Committer: Carlos Chacin <[email protected]> Committed: Wed Dec 5 22:07:29 2018 -0800 ---------------------------------------------------------------------- docs/topic-config.adoc | 48 +++++ docs/topic-config.md | 36 ---- docs/transaction-annotations.adoc | 226 ++++++++++++++++++++++ docs/transaction-annotations.md | 219 --------------------- docs/transactionmanager-config.adoc | 181 +++++++++++++++++ docs/transactionmanager-config.md | 166 ---------------- docs/understanding-callbacks.adoc | 95 +++++++++ docs/understanding-callbacks.md | 92 --------- docs/understanding-the-directory-layout.adoc | 73 +++++++ docs/understanding-the-directory-layout.md | 72 ------- docs/unix-daemon.adoc | 147 ++++++++++++++ docs/unix-daemon.md | 108 ----------- docs/validation-tool.adoc | 142 ++++++++++++++ docs/validation-tool.md | 141 -------------- docs/version-checker.adoc | 13 ++ docs/version-checker.md | 12 -- 16 files changed, 925 insertions(+), 846 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/topic-config.adoc ---------------------------------------------------------------------- diff --git a/docs/topic-config.adoc b/docs/topic-config.adoc new file mode 100644 index 0000000..de270aa --- /dev/null +++ b/docs/topic-config.adoc @@ -0,0 +1,48 @@ +# Topic Configuration +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +A Topic can be declared via xml in the `<tomee-home>/conf/tomee.xml` +file or in a `WEB-INF/resources.xml` file using a declaration like the +following. All properties in the element body are optional. + +.... +<Resource id="myTopic" type="javax.jms.Topic"> + destination = +</Resource> +.... + +Alternatively, a Topic can be declared via properties in the +`<tomee-home>/conf/system.properties` file or via Java VirtualMachine +`-D` properties. The properties can also be used when embedding TomEE +via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext` + +.... +myTopic = new://Resource?type=javax.jms.Topic +myTopic.destination = +.... + +Properties and xml can be mixed. Properties will override the xml +allowing for easy configuration change without the need for $\{} style +variable substitution. Properties are not case sensitive. If a property +is specified that is not supported by the declared Topic a warning will +be logged. If a Topic is needed by the application and one is not +declared, TomEE will create one dynamically using default settings. +Multiple Topic declarations are allowed. # Supported Properties + +Property + +Type + +Default + +Description + +destination + +String + +Specifies the name of the topic http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/topic-config.md ---------------------------------------------------------------------- diff --git a/docs/topic-config.md b/docs/topic-config.md deleted file mode 100644 index 92b24da..0000000 --- a/docs/topic-config.md +++ /dev/null @@ -1,36 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Topic Configuration -~~~~~~ - - -A Topic can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional. - - <Resource id="myTopic" type="javax.jms.Topic"> - destination = - </Resource> - -Alternatively, a Topic can be declared via properties in the `<tomee-home>/conf/system.properties` file or via Java VirtualMachine `-D` properties. The properties can also be used when embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext` - - myTopic = new://Resource?type=javax.jms.Topic - myTopic.destination = - -Properties and xml can be mixed. Properties will override the xml allowing for easy configuration change without the need for ${} style variable substitution. Properties are not case sensitive. If a property is specified that is not supported by the declared Topic a warning will be logged. If a Topic is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple Topic declarations are allowed. -# Supported Properties -<table class="mdtable"> -<tr> -<th>Property</th> -<th>Type</th> -<th>Default</th> -<th>Description</th> -</tr> -<tr> - <td>destination</td> - <td>String</td> - <td></td> - <td> -Specifies the name of the topic -</td> -</tr> -</table> http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/transaction-annotations.adoc ---------------------------------------------------------------------- diff --git a/docs/transaction-annotations.adoc b/docs/transaction-annotations.adoc new file mode 100644 index 0000000..ac4704b --- /dev/null +++ b/docs/transaction-annotations.adoc @@ -0,0 +1,226 @@ +# Transaction Annotations +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +_Also see link:testing-transactions-example.html[Testing Transactions] +for an example of how to use and test EJB transaction attributes_ + +The _javax.ejb.TransactionAttribute_ annotation (@TransactionAttribute) +can be applied to a bean class or it's methods. + +Usage of the @TransactionAttribute requires you to specify one of six +different transaction attribute types defined via the +javax.ejb.TransactionAttributeType enum. + +* TransactionAttributeType._MANDATORY_ +* TransactionAttributeType._REQUIRED_ +* TransactionAttributeType._REQUIRES_NEW_ +* TransactionAttributeType._SUPPORTS_ +* TransactionAttributeType._NOT_SUPPORTED_ +* TransactionAttributeType._NEVER_ + +Per EJB 3.0 the default transaction attribute for all EJB 3.0 +applications is _REQUIRED_. The default transaction attribute for EJB +2.1, 2.0 and 1.1 applications is vendor specific. In OpenEJB EJB 2.1, +2.0 and 1.1 applications also use _REQUIRED_ as the default. + +== Attribute Types summary + +A simplistic way to visualize the transaction attributes is as follows. + +Failing + +Correcting + +No Change + +Transacted + +MANDATORY + +REQUIRED, REQUIRES_NEW + +SUPPORTS + +Not Transacted + +NEVER + +NOT_SUPPORTED + +SUPPORTS + +The "_Transacted_" and "_Not Transacted_" categories represent the +container guarantee, i.e. if the bean method will or will not be invoked +in a transaction. The "_Failing_", "_Correcting_", and "_No Change_" +categories represent the action take by the container to achieve that +guarantee. + +For example, _Never_ and _Mandatory_ are categorized as "_Failing_" and +will cause the container to throw an exception to the caller if there is +(Tx Never) or is not (Tx Mandatory) a transaction in progress when the +method is called. The attributes _Required_, _RequiresNew_, and +_NotSupported_ are categorized as "_Correcting_" as they will cause the +container to adjust the transactional state automatically as needed to +match the desired state, rather than blocking the invocation by throwing +an exception. + +=== Detailed description of each Attribute + +==== MANDATORY + +A _MANDATORY_ method is guaranteed to always be executed in a +transaction. However, it's the caller's job to take care of suppling the +transaction. If the caller attempts to invoke the method _outside_ of a +transaction, then the container will block the call and throw them an +_exception_. + +==== REQUIRED + +A _REQUIRED_ method is guaranteed to always be executed in a +transaction. If the caller attempts to invoke the method _outside_ of a +transaction, the container will _start_ a transaction, execute the +method, then _commit_ the transaction. + +==== REQUIRES_NEW + +A _REQUIRES_NEW_ method is guaranteed to always be executed in a +transaction. If the caller attempts to invoke the method _inside or +outside_ of a transaction, the container will still _start_ a +transaction, execute the method, then _commit_ the transaction. Any +transaction the caller may have in progress will be _suspended_ before +the method execution then _resumed_ afterward. + +==== NEVER + +A _NEVER_ method is guaranteed to never be executed in a transaction. +However, it's the caller's job to ensure there is no transaction. If the +caller attempts to invoke the method _inside_ of a transaction, then the +container will block the call and throw them an _exception_. + +==== NOT_SUPPORTED + +A _NOT_SUPPORTED_ method is guaranteed to never be executed in a +transaction. If the caller attempts to invoke the method _inside_ of a +transaction, the container will _suspend_ the caller's transaction, +execute the method, then _resume_ the caller's transaction. + +==== SUPPORTS + +A _SUPPORTS_ method is guaranteed to adopt the exact transactional state +of the caller. These methods can be invoked by caller's _inside or +outside_ of a transaction. The container will do nothing to change that +state. + +== On Methods + +.... +@Stateless +public static class MyBean implements MyBusinessInterface { + + @TransactionAttribute(TransactionAttributeType.MANDATORY) + public String codeRed(String s) { + return s; + } + + public String codeBlue(String s) { + return s; + } +} +.... + +* _codeRed_ will be invoked with the attribute of _MANDATORY_ +* _codeBlue_ will be invoked with the default attribute of _REQUIRED_ + +== On Classes + +.... +@Stateless +@TransactionAttribute(TransactionAttributeType.MANDATORY) +public static class MyBean implements MyBusinessInterface { + + public String codeRed(String s) { + return s; + } + + public String codeBlue(String s) { + return s; + } +} +.... + +* _codeRed_ and _codeBlue_ will be invoked with the attribute of +_MANDATORY_ + +== Mixed on classes and methods + +.... +@Stateless +@TransactionAttribute(TransactionAttributeType.SUPPORTS) +public static class MyBean implements MyBusinessInterface { + + @TransactionAttribute(TransactionAttributeType.NEVER) + public String codeRed(String s) { + return s; + } + + public String codeBlue(String s) { + return s; + } + + @TransactionAttribute(TransactionAttributeType.REQUIRED) + public String codeGreen(String s) { + return s; + } +} +.... + +* _codeRed_ will be invoked with the attribute of _NEVER_ +* _codeBlue_ will be invoked with the attribute of _SUPPORTS_ +* _codeGreen_ will be invoked with the attribute of _REQUIRED_ + +# Illegal Usage + +Generally, transaction annotationss cannot be made on AroundInvoke +methods and most callbacks. + +The following usages of @TransactionAttribute have no effect. + +.... +@Stateful +public class MyStatefulBean implements MyBusinessInterface { + + @PostConstruct + @TransactionAttribute(TransactionAttributeType.NEVER) + public void constructed(){ + + } + + @PreDestroy + @TransactionAttribute(TransactionAttributeType.NEVER) + public void destroy(){ + + } + + @AroundInvoke + @TransactionAttribute(TransactionAttributeType.NEVER) + public Object invoke(InvocationContext invocationContext) throws Exception { + return invocationContext.proceed(); + } + + @PostActivate + @TransactionAttribute(TransactionAttributeType.NEVER) + public void activated(){ + + } + + @PrePassivate + @TransactionAttribute(TransactionAttributeType.NEVER) + public void passivate(){ + + } +} +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/transaction-annotations.md ---------------------------------------------------------------------- diff --git a/docs/transaction-annotations.md b/docs/transaction-annotations.md deleted file mode 100644 index 403ae91..0000000 --- a/docs/transaction-annotations.md +++ /dev/null @@ -1,219 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Transaction Annotations -~~~~~~ - -_Also see [Testing Transactions](testing-transactions-example.html) - for an example of how to use and test EJB transaction attributes_ - -The *javax.ejb.TransactionAttribute* annotation (@TransactionAttribute) can -be applied to a bean class or it's methods. - -Usage of the @TransactionAttribute requires you to specify one of six -different transaction attribute types defined via the -javax.ejb.TransactionAttributeType enum. - - - TransactionAttributeType.*MANDATORY* - - TransactionAttributeType.*REQUIRED* - - TransactionAttributeType.*REQUIRES_NEW* - - TransactionAttributeType.*SUPPORTS* - - TransactionAttributeType.*NOT_SUPPORTED* - - TransactionAttributeType.*NEVER* - -Per EJB 3.0 the default transaction attribute for all EJB 3.0 applications -is *REQUIRED*. The default transaction attribute for EJB 2.1, 2.0 and 1.1 -applications is vendor specific. In OpenEJB EJB 2.1, 2.0 and 1.1 -applications also use *REQUIRED* as the default. - -<a name="TransactionAnnotations-AttributeTypessummary"></a> -## Attribute Types summary - -A simplistic way to visualize the transaction attributes is as follows. - -<table class="mdtable"> -<tr><td> </th><th> Failing </th><th> Correcting </th><th> No Change </th></tr> -<tr><th> Transacted </td><td> MANDATORY </td><td> REQUIRED, REQUIRES_NEW </td><td> SUPPORTS </td></tr> -<tr><th> Not Transacted </td><td> NEVER </td><td> NOT_SUPPORTED </td><td> SUPPORTS </td></tr> -</table> - -The "*Transacted*" and "*Not Transacted*" categories represent the -container guarantee, i.e. if the bean method will or will not be invoked in -a transaction. The "*Failing*", "*Correcting*", and "*No Change*" -categories represent the action take by the container to achieve that -guarantee. - -For example, *Never* and *Mandatory* are categorized as "*Failing*" and -will cause the container to throw an exception to the caller if there is -(Tx Never) or is not (Tx Mandatory) a transaction in progress when the -method is called. The attributes *Required*, *RequiresNew*, and -*NotSupported* are categorized as "*Correcting*" as they will cause the -container to adjust the transactional state automatically as needed to -match the desired state, rather than blocking the invocation by throwing an -exception. - -<a name="TransactionAnnotations-DetaileddescriptionofeachAttribute"></a> -### Detailed description of each Attribute - -<a name="TransactionAnnotations-MANDATORY"></a> -#### MANDATORY - -A _MANDATORY_ method is guaranteed to always be executed in a transaction. -However, it's the caller's job to take care of suppling the transaction. -If the caller attempts to invoke the method *outside* of a transaction, -then the container will block the call and throw them an *exception*. - -<a name="TransactionAnnotations-REQUIRED"></a> -#### REQUIRED - -A _REQUIRED_ method is guaranteed to always be executed in a transaction. -If the caller attempts to invoke the method *outside* of a transaction, the -container will *start* a transaction, execute the method, then *commit* the -transaction. - -<a name="TransactionAnnotations-REQUIRES_NEW"></a> -#### REQUIRES_NEW - -A _REQUIRES_NEW_ method is guaranteed to always be executed in a -transaction. If the caller attempts to invoke the method *inside or -outside* of a transaction, the container will still *start* a transaction, -execute the method, then *commit* the transaction. Any transaction the -caller may have in progress will be *suspended* before the method execution -then *resumed* afterward. - -<a name="TransactionAnnotations-NEVER"></a> -#### NEVER - -A _NEVER_ method is guaranteed to never be executed in a transaction. -However, it's the caller's job to ensure there is no transaction. If the -caller attempts to invoke the method *inside* of a transaction, then the -container will block the call and throw them an *exception*. - -<a name="TransactionAnnotations-NOT_SUPPORTED"></a> -#### NOT_SUPPORTED - -A _NOT_SUPPORTED_ method is guaranteed to never be executed in a -transaction. If the caller attempts to invoke the method *inside* of a -transaction, the container will *suspend* the caller's transaction, execute -the method, then *resume* the caller's transaction. - -<a name="TransactionAnnotations-SUPPORTS"></a> -#### SUPPORTS - -A _SUPPORTS_ method is guaranteed to adopt the exact transactional state of -the caller. These methods can be invoked by caller's *inside or outside* -of a transaction. The container will do nothing to change that state. - - -<a name="TransactionAnnotations-OnMethods"></a> -## On Methods - - - @Stateless - public static class MyBean implements MyBusinessInterface { - - @TransactionAttribute(TransactionAttributeType.MANDATORY) - public String codeRed(String s) { - return s; - } - - public String codeBlue(String s) { - return s; - } - } - - -- _codeRed_ will be invoked with the attribute of _MANDATORY_ -- _codeBlue_ will be invoked with the default attribute of _REQUIRED_ - -<a name="TransactionAnnotations-OnClasses"></a> -## On Classes - - - @Stateless - @TransactionAttribute(TransactionAttributeType.MANDATORY) - public static class MyBean implements MyBusinessInterface { - - public String codeRed(String s) { - return s; - } - - public String codeBlue(String s) { - return s; - } - } - - -- _codeRed_ and _codeBlue_ will be invoked with the attribute of -_MANDATORY_ - -<a name="TransactionAnnotations-Mixedonclassesandmethods"></a> -## Mixed on classes and methods - - - @Stateless - @TransactionAttribute(TransactionAttributeType.SUPPORTS) - public static class MyBean implements MyBusinessInterface { - - @TransactionAttribute(TransactionAttributeType.NEVER) - public String codeRed(String s) { - return s; - } - - public String codeBlue(String s) { - return s; - } - - @TransactionAttribute(TransactionAttributeType.REQUIRED) - public String codeGreen(String s) { - return s; - } - } - - -- _codeRed_ will be invoked with the attribute of _NEVER_ -- _codeBlue_ will be invoked with the attribute of _SUPPORTS_ -- _codeGreen_ will be invoked with the attribute of _REQUIRED_ - -<a name="TransactionAnnotations-IllegalUsage"></a> -# Illegal Usage - -Generally, transaction annotationss cannot be made on AroundInvoke methods -and most callbacks. - -The following usages of @TransactionAttribute have no effect. - - - @Stateful - public class MyStatefulBean implements MyBusinessInterface { - - @PostConstruct - @TransactionAttribute(TransactionAttributeType.NEVER) - public void constructed(){ - - } - - @PreDestroy - @TransactionAttribute(TransactionAttributeType.NEVER) - public void destroy(){ - - } - - @AroundInvoke - @TransactionAttribute(TransactionAttributeType.NEVER) - public Object invoke(InvocationContext invocationContext) throws Exception { - return invocationContext.proceed(); - } - - @PostActivate - @TransactionAttribute(TransactionAttributeType.NEVER) - public void activated(){ - - } - - @PrePassivate - @TransactionAttribute(TransactionAttributeType.NEVER) - public void passivate(){ - - } - } http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/transactionmanager-config.adoc ---------------------------------------------------------------------- diff --git a/docs/transactionmanager-config.adoc b/docs/transactionmanager-config.adoc new file mode 100644 index 0000000..a69194d --- /dev/null +++ b/docs/transactionmanager-config.adoc @@ -0,0 +1,181 @@ +# TransactionManager Configuration +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +A TransactionManager can be declared via xml in the +`<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file +using a declaration like the following. All properties in the element +body are optional. + +.... +<TransactionManager id="myTransactionManager" type="TransactionManager"> + adler32Checksum = true + bufferSizeKb = 32 + checksumEnabled = true + defaultTransactionTimeout = 10 minutes + flushSleepTime = 50 Milliseconds + logFileDir = txlog + logFileExt = log + logFileName = howl + maxBlocksPerFile = -1 + maxBuffers = 0 + maxLogFiles = 2 + minBuffers = 4 + threadsWaitingForceThreshold = -1 + txRecovery = false +</TransactionManager> +.... + +Alternatively, a TransactionManager can be declared via properties in +the `<tomee-home>/conf/system.properties` file or via Java +VirtualMachine `-D` properties. The properties can also be used when +embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or +`InitialContext` + +.... +myTransactionManager = new://TransactionManager?type=TransactionManager +myTransactionManager.adler32Checksum = true +myTransactionManager.bufferSizeKb = 32 +myTransactionManager.checksumEnabled = true +myTransactionManager.defaultTransactionTimeout = 10 minutes +myTransactionManager.flushSleepTime = 50 Milliseconds +myTransactionManager.logFileDir = txlog +myTransactionManager.logFileExt = log +myTransactionManager.logFileName = howl +myTransactionManager.maxBlocksPerFile = -1 +myTransactionManager.maxBuffers = 0 +myTransactionManager.maxLogFiles = 2 +myTransactionManager.minBuffers = 4 +myTransactionManager.threadsWaitingForceThreshold = -1 +myTransactionManager.txRecovery = false +.... + +Properties and xml can be mixed. Properties will override the xml +allowing for easy configuration change without the need for $\{} style +variable substitution. Properties are not case sensitive. If a property +is specified that is not supported by the declared TransactionManager a +warning will be logged. If a TransactionManager is needed by the +application and one is not declared, TomEE will create one dynamically +using default settings. Multiple TransactionManager declarations are +allowed. # Supported Properties + +Property + +Type + +Default + +Description + +adler32Checksum + +boolean + +true + +Requires TxRecovery + +bufferSizeKb + +int + +32 + +Requires TxRecovery + +checksumEnabled + +boolean + +true + +Requires TxRecovery + +defaultTransactionTimeout + +time + +10Â minutes + +flushSleepTime + +time + +50Â Milliseconds + +Requires TxRecovery + +logFileDir + +String + +txlog + +Requires TxRecovery + +logFileExt + +String + +log + +Requires TxRecovery + +logFileName + +String + +howl + +Requires TxRecovery + +maxBlocksPerFile + +int + +-1 + +Requires TxRecovery + +maxBuffers + +int + +0 + +Requires TxRecovery + +maxLogFiles + +int + +2 + +Requires TxRecovery + +minBuffers + +int + +4 + +Requires TxRecovery + +threadsWaitingForceThreshold + +int + +-1 + +Requires TxRecovery + +txRecovery + +boolean + +false + +When set to true, Howl logging is enabled http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/transactionmanager-config.md ---------------------------------------------------------------------- diff --git a/docs/transactionmanager-config.md b/docs/transactionmanager-config.md deleted file mode 100644 index 6faf550..0000000 --- a/docs/transactionmanager-config.md +++ /dev/null @@ -1,166 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=TransactionManager Configuration -~~~~~~ - - -A TransactionManager can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional. - - <TransactionManager id="myTransactionManager" type="TransactionManager"> - adler32Checksum = true - bufferSizeKb = 32 - checksumEnabled = true - defaultTransactionTimeout = 10 minutes - flushSleepTime = 50 Milliseconds - logFileDir = txlog - logFileExt = log - logFileName = howl - maxBlocksPerFile = -1 - maxBuffers = 0 - maxLogFiles = 2 - minBuffers = 4 - threadsWaitingForceThreshold = -1 - txRecovery = false - </TransactionManager> - -Alternatively, a TransactionManager can be declared via properties in the `<tomee-home>/conf/system.properties` file or via Java VirtualMachine `-D` properties. The properties can also be used when embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext` - - myTransactionManager = new://TransactionManager?type=TransactionManager - myTransactionManager.adler32Checksum = true - myTransactionManager.bufferSizeKb = 32 - myTransactionManager.checksumEnabled = true - myTransactionManager.defaultTransactionTimeout = 10 minutes - myTransactionManager.flushSleepTime = 50 Milliseconds - myTransactionManager.logFileDir = txlog - myTransactionManager.logFileExt = log - myTransactionManager.logFileName = howl - myTransactionManager.maxBlocksPerFile = -1 - myTransactionManager.maxBuffers = 0 - myTransactionManager.maxLogFiles = 2 - myTransactionManager.minBuffers = 4 - myTransactionManager.threadsWaitingForceThreshold = -1 - myTransactionManager.txRecovery = false - -Properties and xml can be mixed. Properties will override the xml allowing for easy configuration change without the need for ${} style variable substitution. Properties are not case sensitive. If a property is specified that is not supported by the declared TransactionManager a warning will be logged. If a TransactionManager is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple TransactionManager declarations are allowed. -# Supported Properties -<table class="mdtable"> -<tr> -<th>Property</th> -<th>Type</th> -<th>Default</th> -<th>Description</th> -</tr> -<tr> - <td>adler32Checksum</td> - <td>boolean</td> - <td>true</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>bufferSizeKb</td> - <td>int</td> - <td>32</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>checksumEnabled</td> - <td>boolean</td> - <td>true</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>defaultTransactionTimeout</td> - <td><a href="configuring-durations.html">time</a></td> - <td>10 minutes</td> - <td> - -</td> -</tr> -<tr> - <td>flushSleepTime</td> - <td><a href="configuring-durations.html">time</a></td> - <td>50 Milliseconds</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>logFileDir</td> - <td>String</td> - <td>txlog</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>logFileExt</td> - <td>String</td> - <td>log</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>logFileName</td> - <td>String</td> - <td>howl</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>maxBlocksPerFile</td> - <td>int</td> - <td>-1</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>maxBuffers</td> - <td>int</td> - <td>0</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>maxLogFiles</td> - <td>int</td> - <td>2</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>minBuffers</td> - <td>int</td> - <td>4</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>threadsWaitingForceThreshold</td> - <td>int</td> - <td>-1</td> - <td> -Requires TxRecovery -</td> -</tr> -<tr> - <td>txRecovery</td> - <td>boolean</td> - <td>false</td> - <td> -When set to true, Howl logging is enabled -</td> -</tr> -</table> http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/understanding-callbacks.adoc ---------------------------------------------------------------------- diff --git a/docs/understanding-callbacks.adoc b/docs/understanding-callbacks.adoc new file mode 100644 index 0000000..b5b9919 --- /dev/null +++ b/docs/understanding-callbacks.adoc @@ -0,0 +1,95 @@ +# Understanding Callbacks +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +The rules here are pretty hard to follow without +examples. + +When they say one AroundInvoke per class they mean that in the most +literal sense as in one individual java class definition, not including +it's parent class or classes, may exactly one AroundInvoke method. The +bean or interceptor class may have an AroundInvoke method, its parent +class may have an AroundInvoke method, the parent's parent class may +have an AroundInvoke method and so on. + +So the following is legal. + +.... +public class Plant { + @AroundInvoke + public Object a(InvocationContext ctx) throws Exception { + return ctx.proceed(); + } +} + +public class Fruit extends Plant { + @AroundInvoke + public Object b(InvocationContext ctx) throws Exception { + return ctx.proceed(); + } +} + +@Stateless +public class Apple extends Fruit implements AppleLocal { + @AroundInvoke + public Object c(InvocationContext ctx) throws Exception { + return ctx.proceed(); + } + + public String grow(){ + return "ready to pick"; + } +} + +public interface AppleLocal { + public String grow(); +} +.... + +The result is that when the "grow" method on AppleLocal (and +consequently on Apple) is invoked, the container will first invoke the +following AroundInvoke methods in this order; a, b, c. + +What the ejb spec doesn't do such a good job at stating is that there +are ways to effectively shut off the callbacks, including AroundInvoke, +of a parent class by simply overriding the method. We can shut off the +"a" around invoke with a slightly different version of Apple as follows: + +.... +@Stateless +public class Apple extends Fruit implements AppleLocal { + + // This will now never be called. + public Object a(InvocationContext ctx) throws Exception { + return null; + } + + @AroundInvoke + public Object c(InvocationContext ctx) throws Exception { + return ctx.proceed(); + } + + public String grow(){ + return "ready to pick"; + } +} +.... + +The result of this is that when the "grow" method on AppleLocal is +invoked, the container will first invoke the AroundInvoke methods "b" +then "c" skipping "a" completely. + +When they say that an AroundInvoke method cannot be a business method, +they mean that they cannot be exposed to clients through a local or +remote interface. The following would be illegal. + +.... +public interface AppleLocal { + public String grow(); + + // This is an AroundInvoke method in the bean class, not a legal business method! + public Object c(InvocationContext ctx) throws Exception; +} +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/understanding-callbacks.md ---------------------------------------------------------------------- diff --git a/docs/understanding-callbacks.md b/docs/understanding-callbacks.md deleted file mode 100644 index 49eb893..0000000 --- a/docs/understanding-callbacks.md +++ /dev/null @@ -1,92 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Understanding Callbacks -~~~~~~ -The rules here are pretty hard to follow without examples. - -When they say one AroundInvoke per class they mean that in the most literal -sense as in one individual java class definition, not including it's parent -class or classes, may exactly one AroundInvoke method. The bean or -interceptor class may have an AroundInvoke method, its parent class may -have an AroundInvoke method, the parent's parent class may have an -AroundInvoke method and so on. - -So the following is legal. - - - public class Plant { - @AroundInvoke - public Object a(InvocationContext ctx) throws Exception { - return ctx.proceed(); - } - } - - public class Fruit extends Plant { - @AroundInvoke - public Object b(InvocationContext ctx) throws Exception { - return ctx.proceed(); - } - } - - @Stateless - public class Apple extends Fruit implements AppleLocal { - @AroundInvoke - public Object c(InvocationContext ctx) throws Exception { - return ctx.proceed(); - } - - public String grow(){ - return "ready to pick"; - } - } - - public interface AppleLocal { - public String grow(); - } - - -The result is that when the "grow" method on AppleLocal (and consequently -on Apple) is invoked, the container will first invoke the following -AroundInvoke methods in this order; a, b, c. - -What the ejb spec doesn't do such a good job at stating is that there are -ways to effectively shut off the callbacks, including AroundInvoke, of a -parent class by simply overriding the method. We can shut off the "a" -around invoke with a slightly different version of Apple as follows: - - - @Stateless - public class Apple extends Fruit implements AppleLocal { - - // This will now never be called. - public Object a(InvocationContext ctx) throws Exception { - return null; - } - - @AroundInvoke - public Object c(InvocationContext ctx) throws Exception { - return ctx.proceed(); - } - - public String grow(){ - return "ready to pick"; - } - } - - -The result of this is that when the "grow" method on AppleLocal is invoked, -the container will first invoke the AroundInvoke methods "b" then "c" -skipping "a" completely. - -When they say that an AroundInvoke method cannot be a business method, they -mean that they cannot be exposed to clients through a local or remote -interface. The following would be illegal. - - - public interface AppleLocal { - public String grow(); - - // This is an AroundInvoke method in the bean class, not a legal business method! - public Object c(InvocationContext ctx) throws Exception; - } http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/understanding-the-directory-layout.adoc ---------------------------------------------------------------------- diff --git a/docs/understanding-the-directory-layout.adoc b/docs/understanding-the-directory-layout.adoc new file mode 100644 index 0000000..51d957d --- /dev/null +++ b/docs/understanding-the-directory-layout.adoc @@ -0,0 +1,73 @@ +:index-group: OpenEJB +Standalone Server +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published +:jbake-title: Understanding the Directory Layout + + +Unpacking the standalone OpenEJB will result in the following directory +layout: + +.... +apache-openejb-[version]\apps +apache-openejb-[version]\bin +apache-openejb-[version]\conf +apache-openejb-[version]\data +apache-openejb-[version]\lib +apache-openejb-[version]\logs +apache-openejb-[version]\LICENSE +apache-openejb-[version]\NOTICE +apache-openejb-[version]\README.txt +.... + +# Directories + +== bin/ + +Contains commands to start/stop the server (You can also do a lot of +other stuff like deploy/undeploy, but we will just talk about things +needed to get you started) + +== lib/ + +Contains several jar files (you only need of few of these jars in your +classpath to do EJB development) + +== apps/ + +Once you create your EJB's and jar them up, you can place your jar file +in this directory and start the server. The server will automatically +deploy all the EJB's contained in this JAR. + +== logs/ + +Contains log files. + +== conf/ + +This directory contains nothing but a README.txt file at the time +OpenEJB is unpacked. The first time OpenEJB is started however, these +files will be created: + +.... + conf/ + openejb.xml (main config file) + logging.properties (log levels and files) + login.config (jaas config file) + users.properties (users that can log in) + groups.properties (groups in which users belong) + + conf.d/ + + admin.properties (network socket for administration) + ejbd.properties (network socket for ejb invocations) + hsql.properties (network socket for hsql client access) + httpejbd.properties (network socket for ejb invocations over http) + telnet.properties (network socket for telnet "server") +.... + +These files can be edited as desired. If at any time you are unhappy +with your changes or simply wish to start over, you can delete or move +any of the files above and a new one containing the default values will +be automatically created. http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/understanding-the-directory-layout.md ---------------------------------------------------------------------- diff --git a/docs/understanding-the-directory-layout.md b/docs/understanding-the-directory-layout.md deleted file mode 100644 index 1c22183..0000000 --- a/docs/understanding-the-directory-layout.md +++ /dev/null @@ -1,72 +0,0 @@ -index-group=OpenEJB Standalone Server -type=page -status=published -title=Understanding the Directory Layout -~~~~~~ - -Unpacking the standalone OpenEJB will result in the following directory layout: - - apache-openejb-[version]\apps - apache-openejb-[version]\bin - apache-openejb-[version]\conf - apache-openejb-[version]\data - apache-openejb-[version]\lib - apache-openejb-[version]\logs - apache-openejb-[version]\LICENSE - apache-openejb-[version]\NOTICE - apache-openejb-[version]\README.txt - -<a name="UnderstandingtheDirectoryLayout-Directories"></a> -# Directories - -<a name="UnderstandingtheDirectoryLayout-bin/"></a> -## bin/ - -Contains commands to start/stop the server (You can also do a lot of other -stuff like deploy/undeploy, but we will just talk about things needed to -get you started) - -<a name="UnderstandingtheDirectoryLayout-lib/"></a> -## lib/ - -Contains several jar files (you only need of few of these jars in your -classpath to do EJB development) - -<a name="UnderstandingtheDirectoryLayout-apps/"></a> -## apps/ - -Once you create your EJB's and jar them up, you can place your jar file in -this directory and start the server. The server will automatically deploy -all the EJB's contained in this JAR. - -<a name="UnderstandingtheDirectoryLayout-logs/"></a> -## logs/ - -Contains log files. - -<a name="UnderstandingtheDirectoryLayout-conf/"></a> -## conf/ - -This directory contains nothing but a README.txt file at the time OpenEJB -is unpacked. The first time OpenEJB is started however, these files will -be created: - - conf/ - openejb.xml (main config file) - logging.properties (log levels and files) - login.config (jaas config file) - users.properties (users that can log in) - groups.properties (groups in which users belong) - - conf.d/ - - admin.properties (network socket for administration) - ejbd.properties (network socket for ejb invocations) - hsql.properties (network socket for hsql client access) - httpejbd.properties (network socket for ejb invocations over http) - telnet.properties (network socket for telnet "server") - -These files can be edited as desired. If at any time you are unhappy with -your changes or simply wish to start over, you can delete or move any of -the files above and a new one containing the default values will be -automatically created. http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/unix-daemon.adoc ---------------------------------------------------------------------- diff --git a/docs/unix-daemon.adoc b/docs/unix-daemon.adoc new file mode 100644 index 0000000..b5aa326 --- /dev/null +++ b/docs/unix-daemon.adoc @@ -0,0 +1,147 @@ +# Unix Daemon +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +Apache TomEE can be run as a daemon using the +http://commons.apache.org/daemon/jsvc.html[jsvc] tool from the +http://commons.apache.org/daemon[Apache Commons Daemon] project. + +Source tarballs for `jsvc` are included with Tomcat and therefore can be +found in TomEE as well. These need to be compiled before jsvc can be +used. + +== Building jsvc + +First, we'll need to locate and unpack the +`commons-daemon-native.tar.gz` + +.... +cd $TOMEE_HOME/bin +tar xzvf commons-daemon-native.tar.gz +cd commons-daemon-1.0.7-native-src/unix/ +.... + +Note that the `commons-daemon-1.0.7-native-src` directory may have a +slightly different version number. + +Second, we'll need to build the `jsvc` binary. Under a UNIX operating +system you will need: + +* An ANSI-C compliant compiler (GCC is good) +* GNU Make +* A Java Platform 2 compliant SDK + +You have to specify the `JAVA_HOME` of the SDK either with the +`--with-java=<dir>` parameter or set the `JAVA_HOME` environment to +point to your SDK installation. For example: + +.... +./configure --with-java=/usr/java +.... + +or + +.... +export JAVA_HOME +./configure +.... + +If your operating system is supported, configure will go through +cleanly, otherwise it will report an error (please send us the details +of your OS/JDK, or a patch against the sources). To build the binaries +and libraries simply do: + +.... +make +.... + +This will generate the executable file `jsvc`. + +Finally, we'll want to set the execution bits and move the `jsvc` binary + +.... +chmod 755 jsvc +mv jsvc $TOMEE_HOME/bin +.... + +Done! + +As one script, the above might look like: + +.... +cd $TOMEE_HOME/bin +tar xzvf commons-daemon-native.tar.gz +cd commons-daemon-1.0.7-native-src/unix/ +./configure +make +chmod 755 jsvc +mv jsvc ../.. +.... + +== Starting (unix) + +.... +sudo "$TOMEE_HOME/bin/jsvc" -cp "$TOMEE_HOME/bin/bootstrap.jar:$TOMEE_HOME/bin/tomcat-juli.jar" \ + "-javaagent:$TOMEE_HOME/lib/openejb-javaagent.jar" -outfile "$TOMEE_HOME/logs/catalina.out" \ + -errfile "$TOMEE_HOME/logs/catalina.err" org.apache.catalina.startup.Bootstrap +.... + +== Starting (osx) + +For a 64-bit JVM such as OSX Lion + +.... +sudo arch -arch x86_64 "$TOMEE_HOME/bin/jsvc" -jvm server -cp "$TOMEE_HOME/bin/bootstrap.jar:$TOMEE_HOME/bin/tomcat-juli.jar" \ + "-javaagent:$TOMEE_HOME/lib/openejb-javaagent.jar" -outfile "$TOMEE_HOME/logs/catalina.out" \ + -errfile "$TOMEE_HOME/logs/catalina.err" org.apache.catalina.startup.Bootstrap +.... + +For a 32-bit JVM + +.... +sudo arch -arch i386 "$TOMEE_HOME/bin/jsvc" -jvm server -cp "$TOMEE_HOME/bin/bootstrap.jar:$TOMEE_HOME/bin/tomcat-juli.jar" \ + "-javaagent:$TOMEE_HOME/lib/openejb-javaagent.jar" -outfile "$TOMEE_HOME/logs/catalina.out" \ + -errfile "$TOMEE_HOME/logs/catalina.err" org.apache.catalina.startup.Bootstrap +.... + +=== Note on formatting + +Note that `\` at the end of each line is unix syntax to keep everything +effectively as one line and one command. The command is simply too long +to show as one line on a fixed width html page. The `\` can be removed +as long as the resulting command is one long line. + +== Common Issues + +Ensure your `$TOME_HOME` and `$JAVA_HOME` variables are set correctly. +You should see similar output with the following two commands + +.... +mingus:~ 01:51:37 +$ ls $TOMEE_HOME +LICENSE RELEASE-NOTES bin endorsed logs webapps +NOTICE RUNNING.txt conf lib temp work + +mingus:~ 01:51:46 +$ ls $JAVA_HOME +bin bundle lib man +.... + +The `jsvc -debug` option can also show useful information for +troubleshooting: + +.... +$TOMEE_HOME/bin/jsvc -debug +.... + +Note on OSX, `$JAVA_HOME` should be set to +`/System/Library/Frameworks/JavaVM.framework/Home` + +== Further documentation + +See also the full Apache Commons Daemon documentation for jsvc. + +* http://commons.apache.org/daemon/jsvc.html http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/unix-daemon.md ---------------------------------------------------------------------- diff --git a/docs/unix-daemon.md b/docs/unix-daemon.md deleted file mode 100644 index 12ebd38..0000000 --- a/docs/unix-daemon.md +++ /dev/null @@ -1,108 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Unix Daemon -~~~~~~ - -Apache TomEE can be run as a daemon using the [jsvc](http://commons.apache.org/daemon/jsvc.html) tool from the [Apache Commons Daemon](http://commons.apache.org/daemon) project. - -Source tarballs for `jsvc` are included with Tomcat and therefore can be found in TomEE as well. These need to be compiled before jsvc can be used. - -# Building jsvc - -First, we'll need to locate and unpack the `commons-daemon-native.tar.gz` - - cd $TOMEE_HOME/bin - tar xzvf commons-daemon-native.tar.gz - cd commons-daemon-1.0.7-native-src/unix/ - -Note that the `commons-daemon-1.0.7-native-src` directory may have a slightly different version number. - -Second, we'll need to build the `jsvc` binary. Under a UNIX operating system you will need: - - - An ANSI-C compliant compiler (GCC is good) - - GNU Make - - A Java Platform 2 compliant SDK - -You have to specify the `JAVA_HOME` of the SDK either with the `--with-java=<dir>` parameter or set the `JAVA_HOME` environment to -point to your SDK installation. For example: - - ./configure --with-java=/usr/java - -or - - export JAVA_HOME - ./configure - -If your operating system is supported, configure will go through cleanly, otherwise it will report an error (please send us the details of your -OS/JDK, or a patch against the sources). To build the binaries and libraries simply do: - - make - -This will generate the executable file `jsvc`. - -Finally, we'll want to set the execution bits and move the `jsvc` binary - - chmod 755 jsvc - mv jsvc $TOMEE_HOME/bin - -Done! - -As one script, the above might look like: - - cd $TOMEE_HOME/bin - tar xzvf commons-daemon-native.tar.gz - cd commons-daemon-1.0.7-native-src/unix/ - ./configure - make - chmod 755 jsvc - mv jsvc ../.. - -# Starting (unix) - - sudo "$TOMEE_HOME/bin/jsvc" -cp "$TOMEE_HOME/bin/bootstrap.jar:$TOMEE_HOME/bin/tomcat-juli.jar" \ - "-javaagent:$TOMEE_HOME/lib/openejb-javaagent.jar" -outfile "$TOMEE_HOME/logs/catalina.out" \ - -errfile "$TOMEE_HOME/logs/catalina.err" org.apache.catalina.startup.Bootstrap - -# Starting (osx) - -For a 64-bit JVM such as OSX Lion - - sudo arch -arch x86_64 "$TOMEE_HOME/bin/jsvc" -jvm server -cp "$TOMEE_HOME/bin/bootstrap.jar:$TOMEE_HOME/bin/tomcat-juli.jar" \ - "-javaagent:$TOMEE_HOME/lib/openejb-javaagent.jar" -outfile "$TOMEE_HOME/logs/catalina.out" \ - -errfile "$TOMEE_HOME/logs/catalina.err" org.apache.catalina.startup.Bootstrap - -For a 32-bit JVM - - sudo arch -arch i386 "$TOMEE_HOME/bin/jsvc" -jvm server -cp "$TOMEE_HOME/bin/bootstrap.jar:$TOMEE_HOME/bin/tomcat-juli.jar" \ - "-javaagent:$TOMEE_HOME/lib/openejb-javaagent.jar" -outfile "$TOMEE_HOME/logs/catalina.out" \ - -errfile "$TOMEE_HOME/logs/catalina.err" org.apache.catalina.startup.Bootstrap - -## Note on formatting - -Note that `\` at the end of each line is unix syntax to keep everything effectively as one line and one command. The command is simply too long to show as one line on a fixed width html page. The `\` can be removed as long as the resulting command is one long line. - -# Common Issues - -Ensure your `$TOME_HOME` and `$JAVA_HOME` variables are set correctly. You should see similar output with the following two commands - - mingus:~ 01:51:37 - $ ls $TOMEE_HOME - LICENSE RELEASE-NOTES bin endorsed logs webapps - NOTICE RUNNING.txt conf lib temp work - - mingus:~ 01:51:46 - $ ls $JAVA_HOME - bin bundle lib man - -The `jsvc -debug` option can also show useful information for troubleshooting: - - $TOMEE_HOME/bin/jsvc -debug - -Note on OSX, `$JAVA_HOME` should be set to `/System/Library/Frameworks/JavaVM.framework/Home` - -# Further documentation - -See also the full Apache Commons Daemon documentation for jsvc. - - - [http://commons.apache.org/daemon/jsvc.html](http://commons.apache.org/daemon/jsvc.html) http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/validation-tool.adoc ---------------------------------------------------------------------- diff --git a/docs/validation-tool.adoc b/docs/validation-tool.adoc new file mode 100644 index 0000000..de714e3 --- /dev/null +++ b/docs/validation-tool.adoc @@ -0,0 +1,142 @@ +# Validation Tool +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +# NAME + +openejb validate - OpenEJB Validation Tool + +# SYNOPSIS + +openejb validate link:options.html[options] jarfiles + +# NOTE + +The OpenEJB Validation tool must be executed from the OPENEJB_HOME +directory. This is the directory where OpenEJB was installed or +unpacked. For for the remainder of this document we will assume you +unpacked OpenEJB into the directory C:. + +In Windows, the validation tool can be executed as follows: + +_C:> openejb validate -help_ + +\{warning} There is a bug in the openejb.bat script of OpenEJB 0.9.0 +that doesn't allow you to execute the validate command as above. For +that release, Windows users can execute the following command: _C:> +bin.bat -help_ + +\{warning} + +In UNIX, Linux, or Mac OS X, the deploy tool can be executed as follows: + +`[user@host openejb]([email protected]) # ./openejb.sh validate -help` + +Depending on your OpenEJB version, you may need to change execution bits +to make the scripts executable. You can do this with the following +command. + +`[user@host openejb]([email protected]) # chmod 755 openejb.sh bin/*.sh` + +From here on out, it will be assumed that you know how to execute the +right openejb script for your operating system and commands will appear +in shorthand as show below. + +_openejb validate -help_ + +# DESCRIPTION + +The validation tool currently checks for the following things: * Does +the Jar have all the ejb-class class files * Does the Jar have all the +home class files * Does the Jar have all the remote class files * Is the +ejb-class a sub-interface of SessionBean or EntityBean * Is the home a +sub-interface of EJBHome * Is the remote a sub-interface of EJBObject * +Are all the methods in the remote interface implemented in the ejb-class +* Are there create methods in the home interface * Are the create +methods in the home interface implemented in the ejb-class * Are the +required post create methods in the ejb-class of EntityBeans * Are there +any create methods in the ejb-class, but not in the home interface + +More checks will be added in the future. + +# OPTIONS + +-v + +Sets the output level to 1. This will output just the minumum details on +each failure. + +-vv + +Default. Sets the output level to 2. Outputs one line summaries of each +failure. This is the default output level. + +-vvv + +Sets the output level to 3. Outputs verbose details on each failure, +usually with details on how to correct the failures. + +-xml + +Outputs information in well-formed XML. + +-nowarn + +Suppresses warnings. + +-version + +Print the version. + +-help + +Print this help message. + +-examples + +Show examples of how to use the options. + +# COMMON ISSUES + +== Misslocated class or NoClassDefFoundError + +The short explanation is that the parent doesn't have all the classes it +needs as some of them are only in the child classloader, where the +parent can't see them. + +This would occur, for example, if a class was loaded by the parent +classloader, but that class' superclass wasn't visible to the parent +classloader, perhaps because it is only in the child classloader. + +Here is a more concrete example: + +.... +public interface Person extends EJBObject { +} + +public interface Employee extends Person { +} +.... + +Ok, so when we build our ejb jar, we put both the Person and Employee +interfaces in the jar, so everything should be good (so we think). But +now let's say that for some reason the Employee interface is also in +another jar and that jar was loaded into the system classpath. + +When a new classloader is create for my ejb-jar at runtime and the +system attempts to load the Employee interface, the call goes right +through that classloader and down to the system classloader. The +Employee interface is found, because it was accidentally added to that +extra jar in the system classpath. So now the system classloader goes +looking for Employee's superinterface, Person, where it immediatly blows +up and throws a NoClassDefFoundError: Person. + +Most people will look at their ejb-jar and think, "But all my classes +are there!?", which is true. It really doesn't matter though, because +one of those classes is also in the parent classloader. The first call +to load that class will bypass your classloader completely and go to the +parent. Once there, it is the parent's job to find _all_ the dependent +classes. If it can't ... NoClassDefFoundError. http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/validation-tool.md ---------------------------------------------------------------------- diff --git a/docs/validation-tool.md b/docs/validation-tool.md deleted file mode 100644 index c9c6510..0000000 --- a/docs/validation-tool.md +++ /dev/null @@ -1,141 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Validation Tool -~~~~~~ - -<a name="ValidationTool-NAME"></a> -# NAME - -openejb validate - OpenEJB Validation Tool - -<a name="ValidationTool-SYNOPSIS"></a> -# SYNOPSIS - - -openejb validate [options](options.html) - jarfiles - -<a name="ValidationTool-NOTE"></a> -# NOTE - - -The OpenEJB Validation tool must be executed from the OPENEJB_HOME -directory. This is the directory where OpenEJB was installed or unpacked. -For for the remainder of this document we will assume you unpacked OpenEJB -into the directory C:\openejb. - -In Windows, the validation tool can be executed as follows: - -*C:\openejb> openejb validate -help* - - -{warning} -There is a bug in the openejb.bat script of OpenEJB 0.9.0 that doesn't -allow you to execute the validate command as above. For that release, -Windows users can execute the following command: -*C:\openejb> bin\validate.bat -help* - -{warning} - - -In UNIX, Linux, or Mac OS X, the deploy tool can be executed as follows: - -`[user@host openejb]([email protected]) -# ./openejb.sh validate -help` - - -Depending on your OpenEJB version, you may need to change execution bits to -make the scripts executable. You can do this with the following command. - -`[user@host openejb]([email protected]) -# chmod 755 openejb.sh bin/*.sh` - - -From here on out, it will be assumed that you know how to execute the right -openejb script for your operating system and commands will appear in -shorthand as show below. - -*openejb validate -help* - - -<a name="ValidationTool-DESCRIPTION"></a> -# DESCRIPTION - - -The validation tool currently checks for the following things: -* Does the Jar have all the ejb-class class files -* Does the Jar have all the home class files -* Does the Jar have all the remote class files -* Is the ejb-class a sub-interface of SessionBean or EntityBean -* Is the home a sub-interface of EJBHome -* Is the remote a sub-interface of EJBObject -* Are all the methods in the remote interface implemented in the ejb-class -* Are there create methods in the home interface -* Are the create methods in the home interface implemented in the ejb-class -* Are the required post create methods in the ejb-class of EntityBeans -* Are there any create methods in the ejb-class, but not in the home -interface - -More checks will be added in the future. - -<a name="ValidationTool-OPTIONS"></a> -# OPTIONS - - -<table class="mdtable"> -<tr><td>-v</td><td>Sets the output level to 1. This will output just the minumum details -on each failure.</td></tr> -<tr><td>-vv</td><td>Default. Sets the output level to 2. Outputs one line summaries of -each failure. This is the default output level.</td></tr> -<tr><td>-vvv</td><td>Sets the output level to 3. Outputs verbose details on each failure, -usually with details on how to correct the failures.</td></tr> -<tr><td>-xml</td><td>Outputs information in well-formed XML.</td></tr> -<tr><td>-nowarn</td><td>Suppresses warnings.</td></tr> -<tr><td>-version</td><td>Print the version.</td></tr> -<tr><td>-help</td><td>Print this help message.</td></tr> -<tr><td>-examples</td><td>Show examples of how to use the options.</td></tr> -</table> - -<a name="ValidationTool-COMMONISSUES"></a> -# COMMON ISSUES - -<a name="ValidationTool-MisslocatedclassorNoClassDefFoundError"></a> -## Misslocated class or NoClassDefFoundError - -The short explanation is that the parent doesn't have all the classes it -needs as some of them are only in the child classloader, where the parent -can't see them. - -This would occur, for example, if a class was loaded by the parent -classloader, but that class' superclass wasn't visible to the parent -classloader, perhaps because it is only in the child classloader. - -Here is a more concrete example: - - public interface Person extends EJBObject { - } - - public interface Employee extends Person { - } - - -Ok, so when we build our ejb jar, we put both the Person and Employee -interfaces in the jar, so everything should be good (so we think). But now -let's say that for some reason the Employee interface is also in another -jar and that jar was loaded into the system classpath. - -When a new classloader is create for my ejb-jar at runtime and the system -attempts to load the Employee interface, the call goes right through that -classloader and down to the system classloader. The Employee interface is -found, because it was accidentally added to that extra jar in the system -classpath. So now the system classloader goes looking for Employee's -superinterface, Person, where it immediatly blows up and throws a -NoClassDefFoundError: Person. - -Most people will look at their ejb-jar and think, "But all my classes are -there!?", which is true. It really doesn't matter though, because one of -those classes is also in the parent classloader. The first call to load -that class will bypass your classloader completely and go to the parent. -Once there, it is the parent's job to find *all* the dependent classes. If -it can't ... NoClassDefFoundError. http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/version-checker.adoc ---------------------------------------------------------------------- diff --git a/docs/version-checker.adoc b/docs/version-checker.adoc new file mode 100644 index 0000000..c282a4b --- /dev/null +++ b/docs/version-checker.adoc @@ -0,0 +1,13 @@ +# Checking Your OpenEJB Version +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +== Update checker + +To check your OpenEJB version each time OpenEJB/TomEE starts simple add +the system property openejb.version.check=true. + +Note: it can be done through system.properties files. http://git-wip-us.apache.org/repos/asf/tomee/blob/aef8367d/docs/version-checker.md ---------------------------------------------------------------------- diff --git a/docs/version-checker.md b/docs/version-checker.md deleted file mode 100644 index fcc4000..0000000 --- a/docs/version-checker.md +++ /dev/null @@ -1,12 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Checking Your OpenEJB Version -~~~~~~ - -# Update checker - -To check your OpenEJB version each time OpenEJB/TomEE starts simple add the system property -openejb.version.check=true. - -Note: it can be done through system.properties files.
