This is an automated email from the ASF dual-hosted git repository. dblevins pushed a commit to branch markdown-to-asciidoc in repository https://gitbox.apache.org/repos/asf/tomee-site-generator.git
commit 87ddfaa8a76c8dc975c86c29242022df01e35796 Author: David Jencks <[email protected]> AuthorDate: Thu Mar 5 08:30:14 2020 -0800 xref fixes --- tomee/modules/ROOT/pages/contribute.adoc | 5 +- .../ROOT/pages/dev/writing-validation-tests.adoc | 56 ++++++++++++++-------- tomee/modules/ROOT/pages/security/tomee.adoc | 6 +-- 3 files changed, 41 insertions(+), 26 deletions(-) diff --git a/tomee/modules/ROOT/pages/contribute.adoc b/tomee/modules/ROOT/pages/contribute.adoc index 9ccf65d..711dbd8 100644 --- a/tomee/modules/ROOT/pages/contribute.adoc +++ b/tomee/modules/ROOT/pages/contribute.adoc @@ -5,7 +5,10 @@ Some great links for getting involved * xref:dev/source-code.adoc[Source Code] * xref:dev/contribution-tips.adoc[Contribution Tips] -* xref:developer/index.adoc[Developer Documentation] + +NOTE: The next (broken) link on the current site points to an apparently generated list of pages in dev. + +* xref:dev/index.adoc[Developer Documentation] == Contributing doesn't always mean code. diff --git a/tomee/modules/ROOT/pages/dev/writing-validation-tests.adoc b/tomee/modules/ROOT/pages/dev/writing-validation-tests.adoc index e8c909e..d1c60ea 100644 --- a/tomee/modules/ROOT/pages/dev/writing-validation-tests.adoc +++ b/tomee/modules/ROOT/pages/dev/writing-validation-tests.adoc @@ -16,23 +16,25 @@ One of the implementations in the chain is `org.apache.openejb.config.ValidateMo `ValidateModules` is conditionally added to the _chain_ if the property `openejb.validation.skip=true|false`. If this property is false, then `ValidateModules` is used to kick off the Validation Framework -https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/ConfigurationFactory.java[Configuration Factory] +link:https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/ConfigurationFactory.java[Configuration Factory] -. Internally ValidateModules uses the https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/ValidateModules.java[_AppValidator.validate()_ method] +[start=2] +. Internally ValidateModules uses the link:https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/ValidateModules.java[_AppValidator.validate()_ method] . This method then performs validation using a number of rules. -_A validation rule/s is represented by a class implementing ValidationRule. -In fact, all the classes checking the validation rules , extend ValidationBase, which further implements ValidationRule. -+ -image::../images/ClassDiagram.png[] +A validation rule/s is represented by a class implementing ValidationRule. +In fact, all the classes checking the validation rules, extend ValidationBase, which further implements ValidationRule. -The _list of rules_ being executed can actually be found in the following method of https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/AppValidator.java[AppValidator] +image::ClassDiagram.png[] +The _list of rules_ being executed can actually be found in the following method of link:https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/AppValidator.java[AppValidator] + +[start=4] . The above rules are then executed one by one -. Each module has an attached ValidationContext , which maintains a list of failures, warnings and errors. +. Each module has an attached ValidationContext, which maintains a list of failures, warnings and errors. As the above rules are being invoked, the failure/errors/warnings for a module are being added to its ValidationContext. Every Validation failure has an associated message which can be found in `org/apache/openejb/config/rules/messages.properties`. A message has three levels as explained below: -+ + Format for the different levels follows this spirit: .. Should be short and fixed such that someone could search/grep for it without having to know/use regular expressions. @@ -47,6 +49,8 @@ Use several lines if needed. Here is an _example validation message_ +[source,console] +---- # 0 - method name # 1 - full method # 2 - remote|home @@ -55,13 +59,16 @@ Here is an _example validation message_ 1.no.busines.method No such business method 2.no.busines.method Business method {0} not implemented. 3.no.busines.method Business method {1} not implemented. The method was declared in the {2} interface {3}, but not implemented in the ejb class {4} +---- +[start=6] . The validation framework does not stop processing on the first validation failure, but keeps going and checking for other validation errors and reports them all to the user. This allows the user to fix all errors in one go and re-attempt deploying the application. == The Validation Test Framework -. The test framework is specifically written with the following goals in mind: +The test framework is specifically written with the following goals in mind: + . It should be easy to write the test, and the framework should do the boiler-plate work, the test author just needs to provide the relevant info . It should report the test coverage i.e. the framework should generate a report regarding which keys in messages.properties have tests written for them and what is the corresponding Test class/es which test for the validation rule associated with that key @@ -84,29 +91,36 @@ A @Key can be of type FAILURE or WARNING or ERROR. Default value is FAILURE. As seen in the example above, the test() method is expecting two warnings for the key injectionTarget.nameContainsSet. If count is not equal to 2 or some other Validation Failure/Warning/Error was also thrown from the method, then the test fails. -*** Be Careful The test must cause a Validation Failure otherwise the test framework does not get invoked. + +NOTE: Be Careful The test must cause a Validation Failure otherwise the test framework does not get invoked. For example, in the above code, a Key of type WARNING is being tested, however the test is purposely being failed by putting an `@AroundInvoke` around the method with zero arguments + +[start=5] . Once you have written the test and successfully run it, you now need to generate the report. Simply invoke the following maven command -+ + +[source,console] +---- mvn test -Dtest=ValidationKeysAuditorTest -DconfluenceUsername=YourConfluenceUsername -DconfluencePassword=YourConfluencePassword +---- -The above command will create a complete test coverage report and post it to this location xref:validation-keys-audit-report.adoc[Validation Keys Audit Report] +The above command will create a complete test coverage report and post it to this location xref:dev/validation-keys-audit-report.adoc[Validation Keys Audit Report] === Quick facts about ValidationRunner and things to keep in mind while writing tests This class is created specifically to write tests which test OpenEjb validation code. Specifically, it is used to check the usage of keys defined in `org.apache.openejb.config.rules.Messages.properties`. To use this runner, simply annotate your test case with `@RunWith(ValidationRunner.class`). -Here are some things to keep in mind when writing tests: + 1. -A test method needs to be annotated with + `org.apache.openejb.config.rules.Keys` instead of the `org.junit.Test` + 2. -Any usage of the @Test annotation will be ignored + 3. -If the @Keys and @Test annotation are used together on a test method, then the TestCase will error out + 4. -Every test method should create a EjbJar or EjbModule or AppModule and return it from the method. -It should list the keys being tested in the @Keys annotation +Here are some things to keep in mind when writing tests: -. The runner will invoke the test method and use the Assembler and ConfigurationFactory to create the application 1.This will kick off validation and this Runner will catch ValidationFailureException and make sure that all the keys specified in the @Keys annotation show up in the ValidationFailureException +. A test method needs to be annotated with `org.apache.openejb.config.rules.Keys` instead of the `org.junit.Test` +. Any usage of the @Test annotation will be ignored. +. If the @Keys and @Test annotation are used together on a test method, then the TestCase will error out. +. Every test method should create a EjbJar or EjbModule or AppModule and return it from the method. +It should list the keys being tested in the @Keys annotation +. The runner will invoke the test method and use the Assembler and ConfigurationFactory to create the application. +. This will kick off validation and this Runner will catch ValidationFailureException and make sure that all the keys specified in the @Keys annotation show up in the ValidationFailureException. . If the keys listed in the @Keys annotation match the keys found in the ValidationFailureException, the test passes, else the test fails. . This Runner also validates that the keys specified in the @Keys annotation are also available in the org.apache.openejb.config.rules.Messages.properties file. If the key is not found, then the Runner throws and exception resulting in your test case not being allowed to run. -. Sometimes you want to write a test where you do not want any ValidationFailureException to be thrown, in those scenarios, simply annotate your test with @Keys and do not specify any @Key in it +. Sometimes you want to write a test where you do not want any ValidationFailureException to be thrown, in those scenarios, simply annotate your test with @Keys and do not specify any @Key in it. diff --git a/tomee/modules/ROOT/pages/security/tomee.adoc b/tomee/modules/ROOT/pages/security/tomee.adoc index 54f3178..62b19fa 100644 --- a/tomee/modules/ROOT/pages/security/tomee.adoc +++ b/tomee/modules/ROOT/pages/security/tomee.adoc @@ -1,6 +1,4 @@ -Title: Apache TomEE - -== Apache TomEE vulnerabilities += Apache TomEE Security Vulnerabilities This page lists all security vulnerabilities fixed in maintenance releases or interim builds of Apache TomEE 1.x. Each vulnerability is given a security impact rating by either the Apache TomEE team or by the dependent project supplying the fix - please note that this rating is not uniform and will vary from project to project. @@ -10,7 +8,7 @@ NOTE: Vulnerabilities that are not TomEE vulnerabilities but have either been in Please note that binary patches are never provided. If you need to apply a source code patch, use the building instructions for the Apache TomEE version that you are using. -For TomEE 1.x those are xref:/dev/building-tomee-from-source.adoc[Building TomEE from source]. +For TomEE 1.x those are xref:/dev/building-from-source.adoc[Building TomEE from source]. If you need help on building or configuring TomEE or other help on following the instructions to mitigate the known vulnerabilities listed here, please send your questions to the public xref:../support.adoc[Users mailing list]
