http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/dev/writing-validation-tests.mdtext ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/dev/writing-validation-tests.mdtext b/src/main/jbake/content/dev/writing-validation-tests.mdtext new file mode 100644 index 0000000..3c70370 --- /dev/null +++ b/src/main/jbake/content/dev/writing-validation-tests.mdtext @@ -0,0 +1,163 @@ +Title: Writing Validation Tests + +<a name="WritingValidationTests-Summary"></a> +## Summary + +Validation is a critical and integral part of the project. If you are +writing some code which validates some rules, you should definitely write a +test for it. A little validation test framework is available to write tests +specifically for Validation. This page explains the details of writing such +tests using example snippets. + +<a name="WritingValidationTests-TheValidationFramework"></a> +## The Validation Framework + +1. `org.apache.openejb.config.ConfigurationFactory` uses a chain of +`org.apache.openejb.config.DynamicDeployer` implementations. One of the +implementations in the chain is +`org.apache.openejb.config.ValidateModules`. `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 + +[Configuration Factory](https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/ConfigurationFactory.java) + +1. Internally ValidateModules uses the [*AppValidator.validate()* method](https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/ValidateModules.java) + +1. 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. + + <img src="../images/ClassDiagram.png" alt="" align="center"> + +The _list of rules_ being executed can actually be found in the following +method of [AppValidator](https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/main/java/org/apache/openejb/config/AppValidator.java) +1. The above rules are then executed one by one + +1. 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: + + 1. Should be short and fixed such that someone could search/grep for it + without having to know/use regular expressions. These tend to be similar + to the message key. + + 2. Intended to contain the issue expressed in 1 with only the essential + details, should not line wrap if possible. Be terse. + + 3. Teacher's assistant. A much more conversational and possibly more +detailed + explanation of the issue, should tell the user what to do to fix the +problem. + I.e. don't just point out what is wrong, also point out what is right. Use + several lines if needed. + +Here is an *example validation message* + + # 0 - method name + # 1 - full method + # 2 - remote|home + # 3 - interface name + # 4 - EJB Class name + 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} + +1. 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. + +<a name="WritingValidationTests-TheValidationTestFramework"></a> +## The Validation Test Framework + + + +1. The test framework is specifically written with the following goals in +mind: +1. 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 +1. 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 +1. It should ensure that if a test is being written for a specific +message key, then that key should exist in the messages.properties file +1. Lets break down the framework by using an [example](https://github.com/apache/openejb/tree/trunk/openejb/container/openejb-core/src/test/java/org/apache/openejb/config/rules/CheckInjectionTargetsTest.java) + + + 1. The first thing to note is that we are running the test using our +own custom runner i.e. `@RunWith(ValidationRunner.class)`. This runner +ensures that the keys we are testing, actually exist in the +messages.properties file. It does a lot more, as we shall see later + 2. The test method + 3. Can be given any name + 4. Must be annotated with @Keys and CANNOT be annotated with @Test. +The rest of the JUnit annotations can be used + 5. Must return one of EjbJar / EjbModule / AppModule. The returned +EjbJar/EjbModule/AppModule will be specifically created to cause one or +more validation errors/warnings/failures. + 1. Following annotations are provided by the framework + 1. @Keys : is a collection of zero or more @Key + 1. @Key : represents a key for which this test is being written. 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. 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 + + +1. Once you have written the test and successfully run it, you now need to +generate the report. Simply invoke the following maven command + + mvn test -Dtest=ValidationKeysAuditorTest +-DconfluenceUsername=YourConfluenceUsername +-DconfluencePassword=YourConfluencePassword + +The above command will create a complete test coverage report and post it +to this location [OPENEJB:Validation Keys Audit Report](openejb:validation-keys-audit-report.html) + +###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 + +1. 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 +1. If the keys listed in the @Keys annotation match the keys found in the +ValidationFailureException, the test passes, else the test fails. +1. 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. +1. 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
http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/dev/xbean-finder.mdtext ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/dev/xbean-finder.mdtext b/src/main/jbake/content/dev/xbean-finder.mdtext new file mode 100644 index 0000000..98bcc93 --- /dev/null +++ b/src/main/jbake/content/dev/xbean-finder.mdtext @@ -0,0 +1,266 @@ +# xbean-finder + +## AnnotationFinder + +It uses ASM create an index of annotations and classes in a specific archive. Reason for using ASM are: + + - Security: Loading classes involves executing static initializers. Imagine doing this for every class in every jar. + - Speed: Loading all those classes is slow + - Memory: Chews up permgen space quickly and needlessly. Additional note, see above, some static initializers may hook themselves into the system and make the entire classloader (and the thousands of classes loaded) impossible to GC. + +### Usage + +Say you had an `@Plugin` annotation you used, you could do as follows and skip the +whole `META-INF` business: + + AnnotationFinder finder = new AnnotationFinder(new JarArchive(classloader, jarUrl)); + List<Class<?>> plugins = finder.findAnnotatedClasses(Plugin.class); + +That's the basics. + + public class AnnotationFinder { + boolean isAnnotationPresent(Class<? extends Annotation> annotation); + + List<String> getClassesNotLoaded(); + + List<Package> findAnnotatedPackages(Class<? extends Annotation> annotation); + + List<Class<?>> findAnnotatedClasses(Class<? extends Annotation> annotation); + + List<Class<?>> findInheritedAnnotatedClasses(Class<? extends Annotation> annotation); + + List<Method> findAnnotatedMethods(Class<? extends Annotation> annotation); + + List<Constructor> findAnnotatedConstructors(Class<? extends Annotation> annotation); + + List<Field> findAnnotatedFields(Class<? extends Annotation> annotation); + + List<Class<?>> findClassesInPackage(String packageName, boolean recursive); + + <T> List<Class<? extends T>> findSubclasses(Class<T> clazz); + + <T> List<Class<? extends T>> findImplementations(Class<T> clazz); + + List<Annotated<Method>> findMetaAnnotatedMethods(Class<? extends Annotation> annotation); + + List<Annotated<Field>> findMetaAnnotatedFields(Class<? extends Annotation> annotation); + + List<Annotated<Class<?>>> findMetaAnnotatedClasses(Class<? extends Annotation> annotation); + + List<String> getAnnotatedClassNames(); + } + +## Archive + +So what we have now is a composable system. You create your finder and feed it an archive, like so: + + Archive archive = new JarArchive(classloader, jarURL); + AnnotationFinder finder = new AnnotationFinder( archive ); + List<Class<?>> plugins = finder.findAnnotatedClasses(PluginAnnotation.class) + +If you want some filtering, you add that in: + + Archive archive = new JarArchive(classloader, jarURL); + + archive = new FilteredArchive(archive, new Filter { + + @Override + public boolean accept(String name) { + return name.startsWith("org.foo."); + } + }); + + AnnotationFinder finder = new AnnotationFinder( archive ); + List<Class<?>> plugins = finder.findAnnotatedClasses(PluginAnnotation.class) + +Several archives can be composed together via `CompositeArchive` + + Archive archive = new CompositeArchive( + new JarArchive(classloader, jarURL), + new FileArchive(classloader, new File("target/classes/")), + new ClassesArchive(Foo.class, Bar.class) + ); + +Sky is the limit. + +We have the following `Archive` implementations + + - ClassesArchive(Class<?>... classes) + - ClassesArchive(Iterable<Class<?>> classes) + - FileArchive(ClassLoader loader, URL url) + - FileArchive(ClassLoader loader, File dir) + - JarArchive(ClassLoader loader, URL url) + +For creating combinations of the above we have: + + - CompositeArchive(Archive... archives) + - CompositeArchive(Iterable<Archive> archives) + +For filtering classes out of archvies: + + - FilteredArchive(Archive archive, Filter filter) + +And a convenience class to quickly get an Archive from a set of urls + + - ClasspathArchive(ClassLoader loader, URL... urls) + - ClasspathArchive(ClassLoader loader, Iterable<URL> urls) + +The above currently only supports `jar:` and `file:` urls + +## Filters + +Several built in filters exist for convenience + + - ClassFilter(String name) + - ContainsFilter(String token) + - PackageFilter(String packageName) + - PatternFilter(String expression) + - PatternFilter(Pattern pattern) + - PrefixFilter(String prefix) + - SuffixFilter(String suffix) + + +As well as some filter implementations that allow all of the above to be composed together + + - ExcludeIncludeFilter(Filter include, Filter exclude) + - FilterList(Filter... filters) + - FilterList(Iterable<Filter> filters) + - IncludeExcludeFilter(Filter include, Filter exclude) + +And the following convenience class for quickly creating any of the above + + public class Filters { + public static Filter packages(String... packages) { + public static Filter classes(String... classes) { + public static Filter prefixes(String... prefixes) { + public static Filter tokens(String... tokens) { + public static Filter suffixes(String... suffixes) { + public static Filter patterns(String... patterns) { + public static Filter optimize(Filter... filters) { + public static Filter optimize(List<Filter>... filterss) { + public static Filter invert(Filter filter) { + } + + +## ResourceFinder + +Something similar to Java 6 ServiceLoader, except doesn't do the instantiations, but you could add that for yourself very easily. + +Using the same `META-INF` layout and files as you posted, you can do like: + + ResourceFinder finder = new ResourceFinder("META-INF/services/"); + List plugins = finder.findAllImplementations(Plugin.class); + +A little neater if you adjusted your META-INF layout as follows + + META-INF/com.example.plugins.Plugins/red + META-INF/com.example.plugins.Plugins/blue + +...where the "red" file contained the text "com.example.plugins.RedPlugin" and the +"blue" file contained the text "com.example.plugins.BluePlugin", you could then get them +in a map like so: + + Map plugins = finder.mapAvailableImplementations(Plugin.class); + Class red = plugins.get("red"); + Class blue = plugins.get("blue"); + +Now say you want to do something similar, but the "red" and "blue" files are +properties files which contain the name of the implementation class and other +configurable properties for your red and blue plugins. + + ResourceFinder finder = new ResourceFinder("META-INF/services/"); + Map pluginConfigs = finder.mapAllProperties(Plugin.class.getName()); + Properties redConfig = pluginConfigs.get("red"); + Properties blueConfig = pluginConfigs.get("blue"); + +Object instantiation was never written into any of those libraries because we're big fans +of xbean-reflect package, which is a real "don't tell me what to do" library for when +you just want to create a simple object and would like to get real basic +field/setter/constructor injection without choking down a whole "i control everything" +framework. + +You just: + + ObjectRecipe recpie = new ObjectRecipe("com.example.plugins.RedPlugin"); + recpie.setProperty("myDateField","2008-04-17"); recpie.setProperty("myIntField","100"); + recpie.setProperty("myBooleanField","true"); + recpie.setProperty("myUrlField","http://www.theserverside.com";); + Plugin red = (Plugin) recpie.create(); + red.start(); + +Obviously, the above style to object creation couples really well to the `ResourceFinder` method +that gives you Properties objects back. You put the class name and config for your plugin in the +properties files and pass the properties right into the ObjectRecipe and more or less get a +little do-it-yourself IoC plugin system. + +# OpenEJB/TomEE + +Here is a grep of some of the calls made to `AnnotationFinder`. Most of this code is in an OpenEJB class called +`AnnotationDeployer` whose primary job is to merge the @annotation and <xml> metadata into one tree. + + for (Annotated<Class<?>> clazz : finder.findMetaAnnotatedClasses(LocalClient.class)) { + for (Annotated<Class<?>> clazz : finder.findMetaAnnotatedClasses(RemoteClient.class)) { + List<Class<?>> connectorClasses = finder.findAnnotatedClasses(Connector.class); + List<Class<?>> classes = finder.findAnnotatedClasses(ConnectionDefinitions.class); + classes = finder.findAnnotatedClasses(ConnectionDefinition.class); + classes = finder.findAnnotatedClasses(Activation.class); + classes = finder.findAnnotatedClasses(AdministeredObject.class); + classes.addAll(finder.findAnnotatedClasses(WebService.class)); + classes.addAll(finder.findAnnotatedClasses(WebServiceProvider.class)); + for (Annotated<Class<?>> beanClass : finder.findMetaAnnotatedClasses(Singleton.class)) { + for (Annotated<Class<?>> beanClass : finder.findMetaAnnotatedClasses(Stateless.class)) { + for (Annotated<Class<?>> beanClass : finder.findMetaAnnotatedClasses(Stateful.class)) { + for (Annotated<Class<?>> beanClass : finder.findMetaAnnotatedClasses(ManagedBean.class)) { + for (Annotated<Class<?>> beanClass : finder.findMetaAnnotatedClasses(MessageDriven.class)) { + List<Class<?>> appExceptions = finder.findAnnotatedClasses(ApplicationException.class); + List<Class<?>> list = finder.findAnnotatedClasses(annotation); + final List<Annotated<Class<?>>> annotatedClasses = sortClasses(annotationFinder.findMetaAnnotatedClasses(Interceptors.class)); + final List<Annotated<Method>> annotatedMethods = sortMethods(annotationFinder.findMetaAnnotatedMethods(Interceptors.class)); + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(ExcludeDefaultInterceptors.class)) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(ExcludeClassInterceptors.class))) { + if (annotationFinder.isAnnotationPresent(Path.class) || !annotationFinder.findAnnotatedMethods(Path.class).isEmpty()) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(Asynchronous.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(Asynchronous.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(RolesAllowed.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(PermitAll.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(DenyAll.class)) { + scheduleMethods.addAll(annotationFinder.findMetaAnnotatedMethods(javax.ejb.Schedules.class)); + scheduleMethods.addAll(annotationFinder.findMetaAnnotatedMethods(javax.ejb.Schedule.class)); + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(PostConstruct.class))) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(PreDestroy.class))) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(javax.interceptor.AroundInvoke.class))) { + for (Annotated<Method> method : sortMethods((annotationFinder.findMetaAnnotatedMethods(javax.interceptor.AroundTimeout.class)))) { + List<Annotated<Method>> timeoutMethods = sortMethods(annotationFinder.findMetaAnnotatedMethods(javax.ejb.Timeout.class)); + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(AfterBegin.class))) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(BeforeCompletion.class))) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(AfterCompletion.class))) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(PostActivate.class))) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(PrePassivate.class))) { + for (Annotated<Method> method : sortMethods(annotationFinder.findMetaAnnotatedMethods(Init.class))) { + List<Annotated<Method>> removeMethods = sortMethods(annotationFinder.findMetaAnnotatedMethods(Remove.class)); + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(EJBs.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(EJB.class)) { + for (Annotated<Field> field : annotationFinder.findMetaAnnotatedFields(EJB.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(EJB.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(Resources.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(Resource.class)) { + for (Annotated<Field> field : annotationFinder.findMetaAnnotatedFields(Resource.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(Resource.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(WebServiceRefs.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(WebServiceRef.class)) { + for (Annotated<Field> field : annotationFinder.findMetaAnnotatedFields(WebServiceRef.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(WebServiceRef.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(PersistenceUnits.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(PersistenceUnit.class)) { + for (Annotated<Field> field : annotationFinder.findMetaAnnotatedFields(PersistenceUnit.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(PersistenceUnit.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(PersistenceContexts.class)) { + for (Annotated<Class<?>> clazz : annotationFinder.findMetaAnnotatedClasses(PersistenceContext.class)) { + for (Annotated<Field> field : annotationFinder.findMetaAnnotatedFields(PersistenceContext.class)) { + for (Annotated<Method> method : annotationFinder.findMetaAnnotatedMethods(PersistenceContext.class)) { + int ann = annotationFinder.findAnnotatedClasses(handler.getAnnotationClass()).size(); + ann += annotationFinder.findAnnotatedMethods(handler.getAnnotationClass()).size(); + List<Annotated<Class<?>>> types = sortClasses(annotationFinder.findMetaAnnotatedClasses(annotationClass)); + List<Annotated<Method>> methods = annotationFinder.findMetaAnnotatedMethods(annotationClass); + List<Class<?>> annotatedClasses = finder.findAnnotatedClasses(Path.class); + methods.addAll(finder.findAnnotatedMethods(Path.class)); http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/dev/xbean-usage-in-openejb.mdtext ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/dev/xbean-usage-in-openejb.mdtext b/src/main/jbake/content/dev/xbean-usage-in-openejb.mdtext new file mode 100644 index 0000000..9a0b1aa --- /dev/null +++ b/src/main/jbake/content/dev/xbean-usage-in-openejb.mdtext @@ -0,0 +1,149 @@ +Title: Xbean usage in OpenEJB +<a name="XbeanusageinOpenEJB-HowXBeanisusedinOpenEJB"></a> +# How XBean is used in OpenEJB + +Below is an explanation by David Blevins on the usage of xbean in OpenEJB. This text was taken from an email conversation. To view the full conversation, click [here](http://www.nabble.com/How-is-XBean-used-in-OpenEJB-3--tf2148639.html#a5959172) + + +<a name="XbeanusageinOpenEJB-xbean-reflect"></a> +## xbean-reflect + + xbean-reflect is a beefed up reflection library. + +Earlier all pluggable components had an "init(Properties props)" method? + Same concept except now we throw the component class and the +properties into an "ObjectRecipe" and call create(). The recipe will +take the props out, convert them to the right data types, and construct +the object using the right constructor and setters. + +So our Containers and stuff now use constructors and setters. Same with anything in a [service-jar.xml](http://svn.apache.org/viewvc/tomee/tomee/trunk/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml?view=markup) + file. + +<a name="XbeanusageinOpenEJB-Somecoderefs:"></a> +#### Some code refs: + +1. [Assembler.java](http://svn.apache.org/viewvc/tomee/tomee/trunk/container/openejb-core/src/main/java/org/apache/openejb/assembler/classic/Assembler.java?revision=546308&view=markup) +We also use it to construct Stateful and Stateless session bean instances. + +1. [StatefulInstanceManager.java](http://svn.apache.org/viewvc/tomee/tomee/trunk/container/openejb-core/src/main/java/org/apache/openejb/core/stateful/StatefulInstanceManager.java?revision=546308&view=markup) +1. [StatelessInstanceManager.java](http://svn.apache.org/viewvc/tomee/tomee/trunk/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessInstanceManager.java?revision=546308&view=markup) + +<a name="XbeanusageinOpenEJB-xbean-finder"></a> +## xbean-finder + +xbean-finder is the second coolest library ever. It's a beefed +up service finder for grabbing stuff in your classpath. We use +it at a couple of places. + +<a name="XbeanusageinOpenEJB-COMMANDLINETOOL:"></a> +### COMMAND LINE TOOL: + +The available commands are in properties files in +"META-INF/org.openejb.cli/\{name\}", where \{name\} is the name of the +command. See: +1. [openejb cli](http://svn.apache.org/viewvc/tomee/tomee/trunk/container/openejb-core/src/main/resources/META-INF/org.apache.openejb.cli/) +1. [openejb cli for itests](http://svn.apache.org/viewvc/tomee/tomee/trunk/itests/openejb-itests-client/src/main/resources/META-INF/org.openejb.cli/) + +Earlier we had the "test" command hardcoded in a script, but the +person may have uninstalled the itests? Well now, if you have +the itests jar, the "test" command will be available. If you +don't have the itests jar, the "test" +command won't be available. The "test" command itself is in the +itests jar. You can put any command in any jar and it will +automatically become available on the command line. Remove the +jar and the command is gone. + +When someone types "java \-jar openejb.jar start" this guy will look +for "META-INF/org.openejb.cli/start". If he finds it, he'll +create it and execute it. If he doesn't find it, he'll list the +available commands by enumerating over all the files he see's in the +classpath under the "META-INF/org.openejb.cli/" directory. See [MainImpl.java](http://svn.apache.org/viewvc/tomee/tomee/trunk/container/openejb-core/src/main/java/org/apache/openejb/cli/MainImpl.java?revision=546308&view=markup) + +An extra cool thing is that each command has in it's properties a +"description" property. This is localized, so if the VM locale +is "pl" it will look for a "description.pl" property and use its +value when printing command line help. +I'd like to give Jeremy Whitlock a big shout-out for doing such a +bang up job on this. He and I worked out the idea and +white-boarded it in the wiki, then Jeremy went off and coded up the +whole thing\! It was fantastic. + +<a name="XbeanusageinOpenEJB-SERVERSERVICES:"></a> +### SERVER SERVICES: + +We also use the xbean-finder to create our Server Services (aka. +protocols). Our ServerService implementations are in properties +files under "META-INF/org.openejb.server.ServerService/\{protocolName\}. +See: +1. [OpenEJB Server - ServerService](http://svn.apache.org/viewvc/tomee/tomee/trunk/server/openejb-server/src/main/resources/META-INF/org.apache.openejb.server.ServerService/) +1. [OpenEJB ejbd - ServerService](http://svn.apache.org/viewvc/tomee/tomee/trunk/server/openejb-ejbd/src/main/resources/META-INF/org.apache.openejb.server.ServerService/) +1. [OpenEJB Telnet - ServerService](http://svn.apache.org/viewvc/tomee/tomee/trunk/server/openejb-telnet/src/main/resources/META-INF/org.apache.openejb.server.ServerService/) +1. [OpenEJB HTTP - ServerService](http://svn.apache.org/viewvc/tomee/tomee/trunk/server/openejb-http/src/main/resources/META-INF/org.apache.openejb.server.ServerService/) + +The very first time a ServerService is constructed, we squirt the +properties file into the openejb/conf/ directory so the user can edit +it. The properties files for ServerServices are very xinet.d +like. For example, here is the definition of the "admin" server +service: + + server = +org.openejb.server.admin.AdminDaemon + bind = 127.0.0.1 + port = 4200 + disabled = false + threads = 1 + only_from = localhost + +You can reconfigure the "admin" server service, for example, via the +properties file in openejb/conf/admin.properties. Or you can do +it on the command line as such: + +<in-a-shell> +$ ./bin/openejb start \-Dadmin.bind=192.168.42.13 +OPENEJB_HOME=/Users/dblevins/work/openejb1/target/openejb-1.1-SNAPSHOT +OpenEJB 1.1-SNAPSHOT build: 20060420-2356 +[http://www.openejb.org](http://www.openejb.org) +resources 1 +OpenEJB ready. +\[init\](init\.html) + OpenEJB Remote Server + *\* Starting Services \*\* + NAME +IP PORT + webadmin 127.0.0.1 + 4203 + httpejbd 127.0.0.1 + 4204 + telnet +127.0.0.1 4202 + ejbd +127.0.0.1 4201 + admin + 192.168.42.13 4200 +\------\- +Ready\! +</in-a-shell> + +You can override any server service property in the same way. + Here are a bunch more examples: + + Option: \-D<service>.bind=<address> + openejb start \-Dejbd.bind=10.45.67.8 + openejb start \-Dejbd.bind=myhost.foo.com + openejb start \-Dtelnet.bind=myhost.foo.com + + Option: \-D<service>.port=<port> + openejb start \-Dejbd.port=8765 + openejb start \-Dhttpejbd.port=8888 + + Option: \-D<service>.only_from=<addresses> + openejb start \-Dadmin.only_from=192.168.1.12 + openejb start +\-Dadmin.only_from=192.168.1.12,joe.foo.com,robert + + Option: \-D<service>.threads=<max> + openejb start \-Dejbd.threads=200 + + Option: \-D<service>.disabled=<true/false> + openejb start \-Dtelnet.disabled=true + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/classloading/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/classloading/index.adoc b/src/main/jbake/content/developer/classloading/index.adoc deleted file mode 100755 index fb47ef3..0000000 --- a/src/main/jbake/content/developer/classloading/index.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= The TomEE ClassLoader -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -TomEE ClassLoading is directly mapped to Tomcat one. - -ifndef::backend-pdf[] - -[#filetree.col-md-3] -[ - { - label: 'JVM', - description: 'The JVM classloader launching tomcat main(String[])', - children: [ - { - label:'common.loader', - description:'Customizable in conf/catalina.properties, the common loader is the Tomcat classloader', - children: [ - { - label:'shared.loader', - description:'Optional layer where you can add libraries for the web applications not seen by Tomcat. It is generally not used and not encouraged since Tomcat 6', - children: [ - { - label:'webapp1', - description:'loader of one of your wars, it container WEB-INF/classes, WEB-INF/lib/*.jar' - }, - { - label:'webapp2', - description:'loader of another one of your wars, it container WEB-INF/classes, WEB-INF/lib/*.jar' - }, - { - label:'application1', - description:'loader of another application, it can be an ear, it contains lib and ejbmodules of the ear', - children: [ - { - label:'earwebapp1', - description:'loader of one of the wars of the ear' - }, - { - label:'earwebapp2', - description:'loader of the other webapp of the ear' - } - ] - } - ] - } - ] - } - ] - } -] - -[#filetreedetail.col-md-8.bs-callout.bs-callout-primary] -Click on the tree (JVM) on the left to see the detail there. - -endif::[] - http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/configuration/cxf.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/configuration/cxf.adoc b/src/main/jbake/content/developer/configuration/cxf.adoc deleted file mode 100755 index 997fc82..0000000 --- a/src/main/jbake/content/developer/configuration/cxf.adoc +++ /dev/null @@ -1,93 +0,0 @@ -= CXF Configuration - JAX-RS (RESTful Services) and JAX-WS (Web Services) -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -TomEE relies on Apache CXF for JAX-RS (RESTful Services) and JAX-WS (Web Services). It does not provide all CXF modules, but the most common ones for both specifications (JAX-RS is part of all distributions but JAX-WS is only part of plus one). - -== Configuration - -CXF API is reusable but you can also configure the interceptors through `openejb-jar.xml` (located in WEB-INF). - -If you want to configure JAX-RS you will use the prefix `cxf.jaxrs` and if you configure JAX-WS you use `cxf.jaxws` prefix. - -TIP: to configure directly the bus use `org.apache.openejb.cxf.bus.` prefix and configure it in `conf/system.properties`. - -To configure JAX-RS you need to add in `openejb-jar.xml` a `pojo-deployment`: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<openejb-jar> - <pojo-deployment class-name="jaxrs-application"> - <properties> - # here will go the config - </properties> - </pojo-deployment> -</openejb-jar> ----- - -For JAX-WS you will use a `pojo-deployment` matching the webservice class name for POJO webservices -or an `ejb-deployment` instead of a `pojo-deployment` for EJB webservices: - - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<openejb-jar> - <ejb-deployment ejb-name="MyEJBWebService"> - <properties> - # here will go the config - </properties> - </ejb-deployment> -</openejb-jar> ----- - -Then once you selected your prefix and know where to write the config just use the following entries: - -- properties: server factory properties -- features: CXF features -- in-interceptors: CXF in interceptors -- out-interceptors: CXF out interceptors -- in-fault-interceptors: CXF in interceptors for fault handling -- out-fault-interceptors: CXF out interceptors for fault handling -- databinding: server databinding -- providers (only for JAX-RS endpoint): list of JAX-RS providers -- skip-provider-scanning (only for JAX-RS): is provider scanning on or not (default true) - -For features and interceptors the rule is the same: value is a list comma separated. Each value of the list is either a qualified class name or an id of a service in resources.xml. - -Databinding is simply either a qualified name or a service id in resources.xml (located in WEB-INF). - -== Sample for JAX-WS - -To configure WSS4J on the EJB `CalculatorBean` for instance add in openejb-jar.xml: - -[source,xml] ----- -<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> - <ejb-deployment ejb-name="CalculatorBean"> - <properties> - cxf.jaxws.in-interceptors = wss4j - </properties> - </ejb-deployment> -</openejb-jar> ----- - -With associated resources.xml which will define precisely the `wss4j` configuration: - -[source,xml] ----- -<resources> - <Service id="wss4j" class-name="org.apache.openejb.server.cxf.config.WSS4JInInterceptorFactory" factory-name="create"> - action = UsernameToken - passwordType = PasswordText - passwordCallbackClass = org.superbiz.ws.security.PasswordCallbackHandler - </Service> -</resources> ----- - -== Sample for JAX-RS - -link:../json/index.html[JAX-RS JSON] page shows a sample dedicated to JAX-RS. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/ide/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/ide/index.adoc b/src/main/jbake/content/developer/ide/index.adoc deleted file mode 100755 index 9bc3370..0000000 --- a/src/main/jbake/content/developer/ide/index.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= Integrated Development Environments (IDEs) -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -TomEE is supported by the main IDEs in the market: - -- https://eclipse.org/downloads/[Eclipse] -- https://www.jetbrains.com/idea/download/[Intellij Idea] -- https://netbeans.org/downloads/[Netbeans] - -=== Eclipse - -Be the first to write this part! - -=== Idea - -Be the first to write this part! - -=== Netbeans - -Be the first to write this part! - - http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/index.adoc b/src/main/jbake/content/developer/index.adoc deleted file mode 100755 index 5d49d24..0000000 --- a/src/main/jbake/content/developer/index.adoc +++ /dev/null @@ -1,7 +0,0 @@ -= Developer -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -Click link:../docs.html[here] to find documentation for developers. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/json/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/json/index.adoc b/src/main/jbake/content/developer/json/index.adoc deleted file mode 100755 index 9141d88..0000000 --- a/src/main/jbake/content/developer/json/index.adoc +++ /dev/null @@ -1,206 +0,0 @@ -= TomEE and Apache Johnzon - JAX-RS JSON Provider -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -Since TomEE 7.0, TomEE comes with Apache Johnzon. -It means you can use JSON-P out of the box but also Johnzon Mapper -which is the default JAX-RS provider for JSON. - -*IMPORTANT* - this is a breaking change with 1.x which was using jettison. -This last one was relying on JAXB model to generate JSON which often led -to unexpected JSON tree and some unexpected escaping too. - -== Getting started with Johnzon Mapper - -http://johnzon.apache.org/ will get more informations than this quick -getting started but here are the basics of the mapping with Johnzon. - -The mapper uses a direct java to json representation. - -For instance this java bean: - -[source,java] ----- -public class MyModel { - private int id; - private String name; - - // getters/setters -} ----- - -will be mapped to: - -[source,java] ----- -{ - "id": 1234, - "name": "Johnzon doc" -} ----- - -Note that Johnzon supports several customization either directly on the MapperBuilder of through annotations. - -=== @JohnzonIgnore - -@JohnzonIgnore is used to ignore a field. You can optionally say you ignore the field until some version -if the mapper has a version: - -[source,java] ----- -public class MyModel { - @JohnzonIgnore - private String name; - - // getters/setters -} ----- - -Or to support name for version 3, 4, ... but ignore it for 1 and 2: - - -[source,java] ----- -public class MyModel { - @JohnzonIgnore(minVersion = 3) - private String name; - - // getters/setters -} ----- - -=== @JohnzonConverter - -Converters are used for advanced mapping between java and json. - -There are several converter types: - -1. Converter: map java to json and the opposite based on the string representation -2. Adapter: a converter not limited to String -3. ObjectConverter.Reader: to converter from json to java at low level -4. ObjectConverter.Writer: to converter from java to json at low level -4. ObjectConverter.Codec: a Reader and Writer - -The most common is to customize date format but they all take. For that simple case we often use a Converter: - -[source,java] ----- -public class LocalDateConverter implements Converter<LocalDate> { - @Override - public String toString(final LocalDate instance) { - return instance.toString(); - } - - @Override - public LocalDate fromString(final String text) { - return LocalDate.parse(text); - } -} ----- - -If you need a more advanced use case and modify the structure of the json (wrapping the value for instance) -you will likely need Reader/Writer or a Codec. - -Then once your converter developed you can either register globally on the MapperBuilder or simply decorate -the field you want to convert with @JohnzonConverter: - -[source,java] ----- -public class MyModel { - @JohnzonConverter(LocalDateConverter.class) - private LocalDate date; - - // getters/setters -} ----- - -=== @JohnzonProperty - -Sometimes the json name is not java friendly (_foo or foo-bar or even 200 for instance). For that cases -@JohnzonProperty allows to customize the name used: - -[source,java] ----- -public class MyModel { - @JohnzonProperty("__date") - private LocalDate date; - - // getters/setters -} ----- - -=== AccessMode - -On MapperBuilder you have several AccessMode available by default but you can also create your own one. - -The default available names are: - -* field: to use fields model and ignore getters/setters -* method: use getters/setters (means if you have a getter but no setter you will serialize the property but not read it) -* strict-method (default based on Pojo convention): same as method but getters for collections are not used to write - -You can use these names with setAccessModeName(). - -=== Your own mapper - -Since johnzon is in tomee libraries you can use it yourself (if you use maven/gradle set johnzon-mapper as provided): - -[source,java] ----- -final MySuperObject object = createObject(); - -final Mapper mapper = new MapperBuilder().build(); -mapper.writeObject(object, outputStream); - -final MySuperObject otherObject = mapper.readObject(inputStream, MySuperObject.class); ----- - -== Johnzon and JAX-RS - -TomEE uses by default Johnzon as JAX-RS provider for versions 7.x. If you want however to customize it you need to follow this procedure: - -1. Create a WEB-INF/openejb-jar.xml: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<openejb-jar> - <pojo-deployment class-name="jaxrs-application"> - <properties> - # optional but requires to skip scanned providers if set to true - cxf.jaxrs.skip-provider-scanning = true - # list of providers we want - cxf.jaxrs.providers = johnzon,org.apache.openejb.server.cxf.rs.EJBAccessExceptionMapper - </properties> - </pojo-deployment> -</openejb-jar> ----- - -2. Create a WEB-INF/resources.xml to define johnzon service which will be use to instantiate the provider - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<resources> - <Service id="johnzon" class-name="org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider"> - # 1M - maxSize = 1048576 - bufferSize = 1048576 - - # ordered attributes - attributeOrder = $order - - # Additional types to ignore - ignores = org.apache.cxf.jaxrs.ext.multipart.MultipartBody - </Service> - - <Service id="order" class-name="com.company.MyAttributeSorter" /> - -</resources> ----- - -Note: as you can see you mainly just need to define a service with the id johnzon (same as in openejb-jar.xml) -and you can reference other instances using $id for services and @id for resources. - http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc b/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc deleted file mode 100644 index 5bf7153..0000000 --- a/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc +++ /dev/null @@ -1,33 +0,0 @@ -= Migrate from TomEE 1 to TomEE 7 -:jbake-date: 2017-06-17 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -== Breaking changes - -- Artifact coordinates changes - -GroupId changed from `org.apache.openejb` to `org.apache.tomee`. -It includes maven plugins which use now `org.apache.tomee.maven` and the `javaee-api`. - -Versions of openejb and tomee are now aligned on 7.x and you don't need to use -4.x and 1.x (or any variant) for openejb and tomee. - -- JAX-RS 2 specification refined the sorting of providers. It can have side effects for message body -readers/writers which don't define their target mediatype properly like Jackson which uses wildcard instead of -a json related mediatype. To solve it register a custom provider redefining the media type. - -Can be as easy as: - -[source,java] ----- -@Provider -@Consumes("application/json") -@Produces("application/json") -public class MyAppJsonProvider extends JacksonJsonProvider { -} ----- - -- JPA and CDI are linked now, enabling JPA to use CDI for its components but CDI can use JPA too... -to solve issues with hibernate you need to add either as system property or persistence unit `tomee.jpa.factory.lazy = true`. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc b/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc deleted file mode 100755 index 64b5e48..0000000 --- a/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc +++ /dev/null @@ -1,335 +0,0 @@ -= ApplicationComposer: The TomEE Swiss Knife -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -ApplicationComposer API is mainly contained in org.apache.openejb.testing package (historically, today we would have called the package org.apache.tomee.applicationcomposer). - -=== Dependencies - -To start using ApplicationComposer you need to add some dependencies. - -The minimum required one is openejb-core: - -[source,xml] ----- -<dependency> - <groupId>org.apache.tomee</groupId> - <artifactId>openejb-core</artifactId> - <version>${openejb.version></version> -</dependency> ----- - -If you need JAXRS services you'll add (or replace thanks to transitivity of maven) openejb-cxf-rs: - -[source,xml] ----- -<dependency> - <groupId>org.apache.tomee</groupId> - <artifactId>openejb-cxf-rs</artifactId> - <version>${openejb.version></version> -</dependency> ----- - -If you need JAXWS services you'll add (or replace thanks to transitivity of maven) openejb-cxf: - -[source,xml] ----- -<dependency> - <groupId>org.apache.tomee</groupId> - <artifactId>openejb-cxf</artifactId> - <version>${openejb.version></version> -</dependency> ----- - -=== ApplicationComposer Components - -==== @Module -An ApplicationComposer needs at minimum a module (the application you need to deploy). - -To do so you have two cases: - -before TomEE 7.x: you can only write method(s) decorated with @Module -since TomEE 7.x: you can skip it and use @Classes directly on the ApplicationComposer class as a shortcut for: - -[source,java] ----- -@Module public WebApp app() { return new WebApp(); } ----- - -The expected returned type of these methods are in org.apache.openejb.jee package: - -- Application: entry point to create an ear -- WebApp: a web application -- EjbJar: an ejb module -- EnterpriseBean children: a simple EJB -- Persistence: a persistence module with multiple units -- PersistenceUnit: a simple unit (automatically wrapped in a Persistence) -- Connector: a JCA connector module -- Beans: a CDI module, -- Class[] or Class: a set of classes scanned to discover annotations - -Note that for easiness @Classes was added to be able to describe a module and some scanned classes. For instance the following snippet will create a web application with classes C1, C2 as CDI beans and E1 as an EJB automatically: - -[source,java] ----- -@Module -@Classes(cdi = true, value = { C1.class, C2.class, E1.class }) -public WebApp app() { - return new WebApp(); -} ----- - -==== @Configuration -Often you need to customize a bit the container or at least create some resources like test databases. To do so you can create a method returning Properties which will be the container properties. - -Note: to simplify writing properties you can use PropertiesBuilder util class which is just a fluent API to write properties. - -In these properties you can reuse OpenEJB/TomEE property syntax for resources. - -Here is a sample: - -[source,java] ----- -@Configuration -public Properties configuration() { - return new PropertiesBuilder() - .p("db", "new://Resource?type=DataSource") - .p("db.JdbcUrld", "jdbc:hsqldb:mem:test") - .build(); -} ----- - -Since TomEE 7.x you can also put properties on ApplicationComposer class using @ContainerProperties API: - -[source,java] ----- -@ContainerProperties({ - @ContainerProperties.Property(name = "db", value = "new://Resource?type=DataSource"), - @ContainerProperties.Property(name = "db.JdbcUrl", value = "jdbc:hsqldb:mem:test") -}) -public class MyAppComposer() { - // ... -} ----- - -==== @Component -Sometimes you need to customize a container component. The most common use case is the security service to mock a little bit authorization if you don't care in your test. - -To do so just write a method decorated with @Component returning the instance you desire. - -Components in TomEE are stored in a container Map and the key needs to be a Class. This one is deduced from the returned type of the @Component method: - -[source,java] ----- -@Component -public SecurityService mockSecurity() { - return new MySecurityService(); -} ----- - -==== @Descriptors -You can reuse existing file descriptors using @Descriptors. The name is the file name and the path either a classpath path or a file path: - -[source,java] ----- -// runner if needed etc... -@Descriptors(@Descriptor(name = "persistence.xml", path = "META-INF/persistence.xml")) -public class MyTest { - //... -} ----- - -Note: this can be put in a @Module method as well. - -==== Services -If you want to test a JAXRS or JAXWS service you need to activate these services. - -To do so just add the needed dependency and use @EnableServices: - -[source,java] ----- -// runner if needed etc... -@EnableService("jaxrs") // jaxws supported as well -public class MyTest { - //... -} ----- - -==== Random port -Services like JAXRS and JAXWS relies on HTTP. Often it is nice to have a random port to be able to deploy multiple tests/projects on the same CI platform at the same time. - -To shortcut all the needed logic you can use @RandomPort. It is simply an injection giving you either the port (int) or the root context (URL): - -[source,java] ----- -// runner, services if needed etc... -public class MyTest { - @RandomPort("http") - private int port; -} ----- - -Note: you can generate this way multiple ports. The value is the name of the service it will apply on (being said http is an alias for httpejbd which is our embedded http layer). - -==== Nice logs -@SimpleLog annotation allows you to have one liner logs - -==== @JaxrsProvider -@JaxrsProvider allows you to specify on a @Module method the list of JAXRS provider you want to use. - -==== Dependencies without hacky code -@Jars allows you to add dependencies (scanned) to your application automatically (like CDI libraries): - -[source,java] ----- -@Module -@Classes(cdi = true, value = { C1.class, C2.class, E1.class }) -@Jars("deltaspike-") -public WebApp app() { - return new WebApp(); -} ----- - -==== @Default -@Default (openejb one not CDI one) automatically adds in the application target/classes as binaries and src/main/webapp as resources for maven projects. - -==== @CdiExtensions -This annotation allows you to control which extensions are activated during the test. - -==== @AppResource -This annotation allows injection of few particular test resources like: - -the test AppModule (application meta) -the test Context (JNDI) -the test ApplicationComposers (underlying runner) -ContextProvider: allow to mock JAXRS contexts - -==== @MockInjector -Allows to mock EJB injections. It decorates a dedicated method returning an instance (or Class) implementing FallbackPropertyInjector. - -==== @WebResource -Allow for web application to add folders containing web resources. - - -=== How to run it? -==== JUnit -If you use JUnit you have mainly 2 solutions to run you "model" using the ApplicationComposer: - -using ApplicationComposer runner: - -[source,java] ----- -@RunWith(ApplicationComposer.class) public class MyTest { // ... } ----- - -using ApplicationComposerRule rule: -public class MyTest { @Rule // or @ClassRule if you want the container/application lifecycle be bound to the class and not test methods public final ApplicationComposerRule rule = new ApplicationComposerRule(this); } - -Tip: since TomEE 7.x ApplicationComposerRule is decomposed in 2 rules if you need: ContainerRule and DeployApplication. Using JUnit RuleChain you can chain them to get the samebehavior as ApplicationComposerRule or better deploy multiple ApplicationComposer models and controlling their deployment ordering (to mock a remote service for instance). - -Finally just write `@Test` method using test class injections as if the test class was a managed bean! - -==== TestNG -TestNG integration is quite simple today and mainly ApplicationComposerListener class you can configure as a listener to get ApplicationComposer features. - -Finally just write TestNG @Test method using test class injections as if the test class was a managed bean! - -==== Standalone -Since TomEE 7.x you can also use ApplicationComposers to directly run you ApplicationComposer model as a standalone application: - -[source,java] ----- -public class MyApp { - public static void main(String[] args) { - ApplicationComposers.run(MyApp.class, args); - } - - // @Module, @Configuration etc... -} ----- - -Tip: if MyApp has `@PostConstruct` methods they will be respected and if MyApp has a constructor taking an array of String it will be instantiated getting the second parameter as argument (ie you can propagate your main parameter to your model to modify your application depending it!) - -=== JUnit Sample - -[source,java] ----- -@Classes(cdi = true, value = { MyService.class, MyOtherService.class }) -@ContainerProperties(@ContainerProperties.Property(name = "myDb", value = "new://Resource?type=DataSource")) -@RunWith(ApplicationComposer.class) -public class MyTest { - @Resource(name = "myDb") - private DataSource ds; - - @Inject - private MyService service; - - @Test - public void myTest() { - // do test using injections - } -} ----- - -=== Start and Deploy once - -When having a huge suite of test it can be long to start/deploy/undeploy/shutdown he container/application for each method. - -That's why `SingleApplicationComposerRunner` allows to just reuse the same instance accross several test. - -The first test will start and deploy the application and then other tests will reuse this instance until the JVM is destroyed -where the server/application will be undeployed/shutdown. - - -Here a simple usage: - -[source,java] ----- -import org.apache.openejb.testing.SingleApplicationComposerRunner; -// other imports - -@RunWith(SingleApplicationComposerRunner.class) -public class MyTest { - @Inject - private ACdiBean bean; - - @Application - private TheModel model; - - @Test - public void aTest() { - // ... - } -} ----- - -TIP: if you need a real TomEE container then you can have a look to `TomEEEmbeddedSingleRunner` which does deploys the classpath -using tomee-embedded. - -==== Configure what to deploy - -As all tests will reuse the same application the model (the class declaring the application with `@Classes`, `@Module` etc...) needs to be extracted from the test class itself. - -The application lookup uses this strategy (ordered): - -- the fully qualified name is read from the system property `tomee.application-composer.application` -- a *single* class decorated with `@Application` is looked in the jar/folder containing the test class - -If you have several "groups" you can use JUnit `@Category` to differentiate them and write one application class by category. Then -in `surefire` plugin you declare two `executions` enforcing the system property `tomee.application-composer.application` for each of them -and the associated `@Category`. - -==== Available injections - -- If the application model class uses `@RandomPort` then the test classes can get it as well -- CDI injections are supported -- `@Application` on a field allows to get the application model to get injected - -Compared to a standalone usage it misses all other EE injections (`@PersistenceContext`, `@Resource` etc... but you can inject them in the application model -and just expose them or wrap them in your tests thanks to the `@Application` field. - - -=== Going further -If you want to learn more about ApplicationComposer see link:../../../advanced/applicationcomposer/index.html[ApplicationComposer Advanced] page. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/testing/arquillian/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/arquillian/index.adoc b/src/main/jbake/content/developer/testing/arquillian/index.adoc deleted file mode 100755 index 16f0538..0000000 --- a/src/main/jbake/content/developer/testing/arquillian/index.adoc +++ /dev/null @@ -1,421 +0,0 @@ -= TomEE and Arquillian -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -TomEE has several arquillian adapter flavors: - -- openejb-embedded: a plain embedded OpenEJB supporting most of EE features -- tomee-embedded: a full TomEE running in the same JVM -- tomee-remote: a standard TomEE running in its own process as in production -- tomee-webapp (not recommanded): an adapter starting from a Tomcat and installing tomee-webapp - -=== Embedded or Remote? - -Big advantage of embedded adapters is to be able to debug as usual. However it has few drawbacks which can make you -rething this choice: - -- JVM resources are available where it will likely not be the case in war mode (src/main/resources typically) -- You can mix server and client side features when writing a test -- Classloading is a bit different by design and less isolated (test dependencies) so you can get runtime surprises when really deploying - -To summarize: the choice is the trade off you choose between easiness and reality of the simulation. - -TIP: in TomEE build we build the same tests against all tomee adapters in the same build/module, this means you can use embedded adapter in dev -and activate remote tomee too (not only cause then if there is a failure you don't know if you missed it locally or if it is due -to the switch of adapter) on your continuous integration platform. - -NOTE: all configurations have defaults - -=== OpenEJB Embedded - -==== Coordinates - -[source,xml] ----- -<dependency> - <groupId>org.apache.tomee</groupId> - <artifactId>arquillian-openejb-embedded</artifactId> - <version>${tomee7.version} -</dependency> ----- - -==== arquillian.xml - -|=== -|Name|Description -|properties|container properties, as in conf/system.properties (not in xml format) -|preloadClasses|some class to load (ie enforce static block initialization) -|startDefaultScopes|should CDI default scopes be started (includes @RequestScoped) -|singleDeploymentByArchiveName |names of archives (or true for all) to dploy a single time -|=== - -Sample: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8" standalone="yes"?> -<arquillian - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> - <container qualifier="openejb" default="true"> - <configuration> - <property name="properties"> - # used to not have a single DataSource and be able to test the resource resolution - db1 = new://Resource?type=DataSource - db1.JdbcUrl = jdbc:hsqldb:mem:db1 - - # will preload both classes, simple comma separated qualified names work too - openejb.arquillian.predeploy-archives = org.company.openejb.arquillian.openejb.archive.[SimpleArchive|SimpleArchive2] - </property> - </configuration> - </container> -</arquillian> ----- - -=== TomEE Embedded - -==== Coordinates - -[source,xml] ----- -<dependency> - <groupId>org.apache.tomee</groupId> - <artifactId>arquillian-tomee-embedded</artifactId> - <version>${tomee7.version} -</dependency> ----- - -==== Configuration - -|=== -|Name|Description -| exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort) -| httpsPort | the HTTPS port -| httpPort | the HTTP port -| stopPort | the shutdown port -| dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs) -| appWorkingDir | where to dump applications (`@Deployment`) -| host | which host to use -| stopHost | which port to use to shutdown TomEE (port on Server configuration) -| stopCommand | which command to use to shutdown TomEE -| serverXml | where is the provided server.xml -| portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used -| preloadClasses | which classes to initialize during container startup -| quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy) -| unsafeEjbd | should EJB allow all classes -| unpackWars | unpackWARs value in server.xml -| properties | container properties -| webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner -| keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set -| singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key -| singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key -|ssl| should https be activated -|withEjbRemote| should EJBd remote be activated -|keystoreFile | if ssl is set to true the keystore location -|keystorePass | if ssl is set to true the keystore password -|keystoreType | if ssl is set to true the keystore type -|clientAuth |should SSL connector use clientAuth -|keyAlias | if ssl is set to true the key to use -|sslProtocol | if ssl is set to true the protocol to use -|users |a map of users (properties syntax) -|roles |user roles (properties syntax) -|webResourcesCached |should resources be cached or not (`DefaultServlet` caching) -|=== - - -Sample: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<arquillian - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation=" - http://jboss.org/schema/arquillian - http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> - <container qualifier="tomee" default="true"> - <configuration> - <property name="serverXml">conf/server.xml</property> - - <!-- port = -1 means random --> - <property name="httpPort">-1</property> - <property name="stopPort">-1</property> - - <!-- ssl --> - <property name="httpsPort">-1</property> - <property name="ssl">false</property> - <property name="keystoreFile">keystore-path</property> - <property name="keystorePass">changeit</property> - <property name="keystoreType">JKS</property> - <property name="clientAuth">false</property> - <property name="keyAlias">alias</property> - <property name="sslProtocol">protocol</property> - - <!-- where to create TomEE files --> - <property name="dir">target/tomee-embedded</property> - - <!-- where to dump on disk applications to deploy --> - <property name="appWorkingDir">target/working-dir</property> - - <!-- optional - limit the port allowed when random --> - <property name="portRange">20001-30000</property> - - <!-- container config --> - <property name="properties"> - # same as embedded case - </property> - - <!-- Deployer config --> - <property name="deployerProperties"> - # openejb.deployer.binaries.use=true - # openejb.deployer.forced.appId=[name] - # openejb.deployer.save-deployments=false - </property> - </configuration> - </container> -</arquillian> ----- - -=== TomEE Remote - -IMPORTANT: if a server is already started on host:port then it will be used instead of starting the configured TomEE type. - -To use a custom instance with arquillian ensure to have ejbd and tomee webapp activated. A way is to have in `conf/system.properties` these entries: - -[source] ----- -tomee.remote.support=true -openejb.system.apps=true - -# you can customize it depending the security level you need on the instance -tomee.serialization.class.whitelist = -tomee.serialization.class.blacklist = org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process ----- - -For really remote instances (= not on localhost) you need the `deployerProperties` of previous snippet too: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<arquillian - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation=" - http://jboss.org/schema/arquillian - http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> - <container qualifier="tomee" default="true"> - <configuration> - <!-- ... --> - <property name="deployerProperties"> - openejb.deployer.binaries.use=true - openejb.deployer.save-deployments=false - </property> - </configuration> - </container> -</arquillian> ----- - -==== Coordinates - -[source,xml] ----- -<dependency> - <groupId>org.apache.tomee</groupId> - <artifactId>arquillian-tomee-remote</artifactId> - <version>${tomee7.version} -</dependency> ----- - -==== Configuration - -|=== -|Name|Description -| exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort) -| httpsPort | the HTTPS port -| httpPort | the HTTP port -| stopPort | the shutdown port -| dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs) -| appWorkingDir | where to dump applications (`@Deployment`) -| host | which host to use -| stopHost | which port to use to shutdown TomEE (port on Server configuration) -| stopCommand | which command to use to shutdown TomEE -| serverXml | where is the provided server.xml -| portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used -| preloadClasses | which classes to initialize during container startup -| quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy) -| unsafeEjbd | should EJB allow all classes -| unpackWars | unpackWARs value in server.xml -| properties | container properties -| webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner -| keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set -| singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key -| singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key -|groupId|the maven groupId of the TomEE (or not) artifact -|artifactId|the maven artifactId of the TomEE (or not) artifact -|version |the maven version of the TomEE (or not) artifact -|classifier |the maven classifier of the TomEE (or not) artifact -|type |the maven type of the TomEE (or not) artifact (should be zip) -|removeUnusedWebapps |should default webapps (ROOT, manager, ...) be removed -|ajpPort |the ajp port if used -|conf |a folder to synchronize with TomEE conf folder -|bin |a folder to synchronize with TomEE bin folder -|lib |a folder to synchronize with TomEE lib folder -|endorsed |a folder to synchronize with TomEE endorsed folder -|javaagent |a list (flat format) of javaagent to add when launching tomee, can use maven coordinates if prefixed with `mvn:` -|additionalLibs |a list (flat format) of library to add to TomEE libraries, can use paths of maven coordinates when prefixed with `mvn:` -|cleanOnStartUp |should TomEE folder be deleted on startup if exists -|debug |should the container run in debug mode (`-Dopenejb.server.debug=true` activates it without touching the configuration) -|debugPort |if activated which port to use to debug -|catalina_opts |equivalent to `CATALINA_OPTS` environment variable -|simple_log |should logs be inline -|deployerProperties |deployer properties, useful when not deploying on an instance managed by the build (remote instance typically) -|=== - - -Sample: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<arquillian - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation=" - http://jboss.org/schema/arquillian - http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> - <container qualifier="tomee" default="true"> - <configuration> - <property name="serverXml">conf/server.xml</property> - - <!-- tomee zip to use --> - <property name="groupId">org.apache.tomee</property> - <property name="artifactId">apache-tomee</property> - <property name="version">LATEST</property> - <property name="type">zip</property> - - <!-- tomee provided files, ignored by default --> - <property name="bin">src/test/tomee/bin</property> - <property name="conf">src/test/tomee/conf</property> - <property name="lib">src/test/tomee/lib</property> - - <!-- - remote debugging, - -Dopenejb.server.debug can activate it too - --> - <property name="debug">false</property> - <property name="debugPort">5005</property> - - <!-- nice one line logging --> - <property name="simpleLog">true</property> - - <!-- jvm config --> - <property name="catalina_opts">-XX:-UseParallelGC</property> - - <!-- remove if exist --> - <property name="cleanOnStartUp">true</property> - - <!-- remove default webapps --> - <property name="removeunusedWebapps">true</property> - - <!-- port = -1 means random --> - <property name="httpPort">-1</property> - <property name="stopPort">-1</property> - - <!-- where to create TomEE --> - <property name="dir">target/apache-tomee</property> - - <!-- where to dump on disk applications to deploy --> - <property name="appWorkingDir">target/working-dir</property> - - <!-- optional - limit the port allowed when random --> - <property name="portRange">20001-30000</property> - - <!-- container config --> - <property name="properties"> - # same as embedded case - </property> - - <!-- we monitor the test with sirona --> - <property name="javaagent"> - mvn:org.apache.sirona:sirona-javaagent:0.2-incubating:jar:shaded - </property> - - <!-- Deployer config --> - <property name="deployerProperties"> - # openejb.deployer.binaries.use=true - # openejb.deployer.forced.appId=[name] - # openejb.deployer.save-deployments=false - </property> - - </configuration> - </container> -</arquillian> ----- - -=== Multiple instances - -With arquillian you can create cluster or isolated instances. Here is a sample `arquillian.xml`: - -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<arquillian xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation=" - http://jboss.org/schema/arquillian - http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> - <group qualifier="tomee-cluster"> - <container qualifier="tomee-1"> - <configuration> - <property name="httpPort">-1</property> - <property name="stopPort">-1</property> - <property name="ajpPort">-1</property> - <property name="dir">target/tomee1</property> - <property name="appWorkingDir">target/wd1</property> - </configuration> - </container> - <container qualifier="tomee-2"> - <configuration> - <property name="httpPort">-1</property> - <property name="stopPort">-1</property> - <property name="ajpPort">-1</property> - <property name="dir">target/tomee2</property> - <property name="appWorkingDir">target/wd2</property> - </configuration> - </container> - </group> -</arquillian> ----- - -Then in your test just specify the container you are testing against: - -[source,java] ----- -@RunWith(Arquillian.class) -public class MultipleTomEETest { - @Deployment(name = "war1", testable = false) - @TargetsContainer("tomee-1") - public static WebArchive war1() { - return /* ... */; - } - - @Deployment(name = "war2", testable = false) - @TargetsContainer("tomee-2") - public static WebArchive war2() { - return /* ... */; - } - - @Test - @OperateOnDeployment("war1") - public void testRunningInDep1( - @ArquillianResource URL url) { - // test on tomee 1, url is contextual - } - - @Test - @OperateOnDeployment("war2") - public void testRunningInDep1( - @ArquillianResource URL url) { - // test on tomee 1, url is contextual - } -} ----- http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/testing/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/index.adoc b/src/main/jbake/content/developer/testing/index.adoc deleted file mode 100755 index 8b277e6..0000000 --- a/src/main/jbake/content/developer/testing/index.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Unit Testing -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -- link:applicationcomposer/index.html[ApplicationComposer]: Lightweight tests -- link:arquillian/index.html[Arquillian]: The standard for EE tests -- link:other/index.html[Going futher]: OpenEJB JUnit, TomEE Embedded... http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/testing/other/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/other/index.adoc b/src/main/jbake/content/developer/testing/other/index.adoc deleted file mode 100755 index b1d41b1..0000000 --- a/src/main/jbake/content/developer/testing/other/index.adoc +++ /dev/null @@ -1,134 +0,0 @@ -= Other Testing Techniques -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -=== EJBContainer - -The `EJBContainer` API is a JavaEE API enriched by some OpenEJB features to make the testing easier. - -It starts a container (embedded for case we are interested in) scanning the classpath. This operation can be -slow and if you go with this solution maybe think to start it only once for all tests. - -==== Sample - -[source,java] ----- -import org.junit.After; -import org.junit.AfterClass; -import org.junit.Before; -import org.junit.BeforeClass; -import org.junit.Test; - -import javax.ejb.embeddable.EJBContainer; -import javax.inject.Inject; -import javax.naming.NamingException; - -import static org.junit.Assert.assertTrue; - -public class ATest { - @Inject - private MyCDIBean aBean; - - @PersistenceContext - private EntityManager em; - - @Resource - private DataSource ds; - - @BeforeClass - public static void start() throws NamingException { - container = EJBContainer.createEJBContainer(); - } - - @AfterClass - public static void shutdown() { - if (container != null) { - container.close(); - } - } - - @Before - public void inject() throws NamingException { - container.getContext().bind("inject", this); - } - - @After - public void reset() throws NamingException { - container.getContext().unbind("inject"); - } - - @Test - public void aTest() { - // ... - } -} ----- - -It will use `createEJBContainer()` method to start the container and application, and `close()` to shutdown it. - -OpenEJB provides the `bind("inject")` hack to be able to get injection in the test class. - -=== OpenEJB JUnit - -`openejb-junit` is another artifact providing some facilities for testing. - -==== EJBContainer Rule - -[source,java] ----- -@Properties({ - @Property(key = DeploymentFilterable.CLASSPATH_EXCLUDE, value = "jar:.*"), - @Property(key = DeploymentFilterable.CLASSPATH_INCLUDE, value = ".*openejb-junit.*") -}) -public class TestEJBContainerDefaultConfig { - @Rule - public final EJBContainerRule containerRule = new EJBContainerRule(this); - - @org.apache.openejb.junit.jee.resources.TestResource - private Context ctx; - - @org.apache.openejb.junit.jee.resources.TestResource - private java.util.Properties props; - - @org.apache.openejb.junit.jee.resources.TestResource - private EJBContainer container; - - - @Test - public void configIsHere() { - // ... - } -} - ----- - -TIP: there is the equivalent runner: `@RunWith(EJBContainerRunner.class)` - -==== InjectRule: injections for EJBContainerRule - -[source,java] ----- -@Properties({ - @Property(key = DeploymentFilterable.CLASSPATH_EXCLUDE, value = "jar:.*"), - @Property(key = DeploymentFilterable.CLASSPATH_INCLUDE, value = ".*myjar.*") -}) -public class TestEJBContainerRule { - @ClassRule - public static final EJBContainerRule CONTAINER_RULE = new EJBContainerRule(); - - @Rule - public final InjectRule injectRule = new InjectRule(this, CONTAINER_RULE); - - @EJB - private BasicEjbLocal ejb; - - @Test - public void aTest() { - // ... - } -} ----- - -TIP: an alternative in `openejb-core` is to use `org.apache.openejb.Injector.inject(instance)` http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/tools/gradle-plugins.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/gradle-plugins.adoc b/src/main/jbake/content/developer/tools/gradle-plugins.adoc deleted file mode 100755 index fe43434..0000000 --- a/src/main/jbake/content/developer/tools/gradle-plugins.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= TomEE Gradle Plugin -:jbake-date: 2016-05-31 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -TomEE provides a gradle plugin for tomee-embedded "Ã la Jetty". - -[source,java] ----- -buildscript { - repositories { - mavenCentral() - } - - dependencies { - classpath 'org.apache.tomee.gradle:tomee-embedded:7.0.0' - } -} - -apply plugin: 'org.apache.tomee.tomee-embedded' - -// ... ----- - -Then just start tomee with: - -[source] ----- -gradle tomee-embedded -i ----- - -== Configuration - -All the configuration is optional. - -[source,java] ----- -// plugin setup -def tomeeEmbedded = extensions.getByName('tomee-embedded') -tomeeEmbedded.tomeeVersion = 'other version' -tomeeEmbedded.skipDefaultRepository = true // don't use central to retrieve tomee - -// container dependencies -def tomeeEmbeddedDeps = configurations.getByName('tomee-embedded') -// add dependencies you need to this configuration ----- - -tomee-embedded task has several more advanced configuration like tomee properties, modules to deploy etc... -Its configuration is pretty close to link:maven/embedded.html[Embedded Maven Plugin]. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/tools/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/index.adoc b/src/main/jbake/content/developer/tools/index.adoc deleted file mode 100755 index 235f774..0000000 --- a/src/main/jbake/content/developer/tools/index.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= Build Tools and Plugins -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -- link:maven-plugins.html[Maven Plugins] -- link:gradle-plugins.html[Gradle Plugin] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/tools/maven-plugins.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/maven-plugins.adoc b/src/main/jbake/content/developer/tools/maven-plugins.adoc deleted file mode 100755 index 3f335d2..0000000 --- a/src/main/jbake/content/developer/tools/maven-plugins.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= TomEE Maven Plugins -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -TomEE provides several maven plugins: - -- one for a link:maven/tomee.html[standalone TomEE] -- one for link:maven/embedded.html[TomEE embedded] -- one for link:maven/applicationcomposer.html[application composer] based applications -- Note: there is one for `EJBContainer` but this one is easily replaced by one of the previous in general http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/b34e23c0/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc b/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc deleted file mode 100755 index 8694c37..0000000 --- a/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= Application Composer Maven Plugin -:jbake-date: 2016-03-16 -:jbake-type: page -:jbake-status: published -:jbake-tomeepdf: - -This plugin has two goal: - -- `applicationcomposer:run`: to start the application from mvn command line -- `applicationcomposer:zip`: to package a zip with dependencies and start scripts - -IMPORTANT: the dependencies are retrieved with `MavenProject.getArtifacts()` which means you artifacts should be a `war` -- maven doesn't populate it with a `jar` - and the compile phase - at least - should be passed to ensure it is populated. - -=== Run goal configuration - -[source] ----- -mvn process-classes applicationcomposer:run -DskipTests ----- - -[.table.table-bordered,options="header"] -|=== -| Name | Default | Description -| args | - | a list of application arguments -|application|-|application qualified name -|binaries|${project.build.outputDirectory}|where is your module code (target/classes) -|mavenLog|true|force to use maven logging in openejb -|=== - -=== Zip goal configuration - -[source] ----- -mvn process-classes applicationcomposer:zip -DskipTests ----- - -[.table.table-bordered,options="header"] -|=== -| Name | Default | Description -|workDir|${project.build.directory}/${project.build.finalName}-applicationcomposer| where the container can "work" and create temp files -|zip|${project.build.directory}/${project.build.finalName}-applicationcomposer.zip| where to create the zip -|attach|true|attach the created artifact -|classifier|-|artifact classifier if needed -|application|-|application qualified name -|binaries|${project.build.outputDirectory}|where is your module code (target/classes) -|===
