You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by rm...@apache.org on 2015/04/10 11:15:34 UTC
svn commit: r1672588 - in /tomee/site/trunk/content: application-composer/
application-composer/advanced.md application-composer/getting-started.md
application-composer/history.md application-composer/index.md
documentation.mdtext
Author: rmannibucau
Date: Fri Apr 10 09:15:33 2015
New Revision: 1672588
URL: http://svn.apache.org/r1672588
Log:
adding few doc about application composer
Added:
tomee/site/trunk/content/application-composer/
tomee/site/trunk/content/application-composer/advanced.md
tomee/site/trunk/content/application-composer/getting-started.md
tomee/site/trunk/content/application-composer/history.md
tomee/site/trunk/content/application-composer/index.md
Modified:
tomee/site/trunk/content/documentation.mdtext
Added: tomee/site/trunk/content/application-composer/advanced.md
URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/application-composer/advanced.md?rev=1672588&view=auto
==============================================================================
--- tomee/site/trunk/content/application-composer/advanced.md (added)
+++ tomee/site/trunk/content/application-composer/advanced.md Fri Apr 10 09:15:33 2015
@@ -0,0 +1,98 @@
+# Application Composer Advanced
+
+[Getting Started](getting-started.html) page gives you already a lot of inputs but you caneven go further.
+
+## @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:
+
+```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`:
+
+```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`):
+
+```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):
+
+```java
+@Module
+@Classes(cdi = true, value = { C1.class, C2.class, E1.class })
+@Jars("deltaspike-")
+public WebApp app() {
+ return new WebApp();
+}
+`Ì`
+
+## @Default
+
+`@Default` 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.
+
Added: tomee/site/trunk/content/application-composer/getting-started.md
URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/application-composer/getting-started.md?rev=1672588&view=auto
==============================================================================
--- tomee/site/trunk/content/application-composer/getting-started.md (added)
+++ tomee/site/trunk/content/application-composer/getting-started.md Fri Apr 10 09:15:33 2015
@@ -0,0 +1,207 @@
+# Application Composer Getting Started
+
+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`:
+
+```xml
+<dependency>
+ <groupId>org.apache.openejb</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`:
+
+```xml
+<dependency>
+ <groupId>org.apache.openejb</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`:
+
+```xml
+<dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-cxf</artifactId>
+ <version>${openejb.version></version>
+</dependency>
+```
+
+etc...
+
+## 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 2.x: you can only write method(s) decorated with `@Module`
+* since TomEE 2.x: you can skip it and use `@Classes` directly on the ApplicationComposer class as a shortcut for:
+
+```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:
+
+```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:
+
+```java
+@Configuration
+public Properties configuration() {
+ return new PropertiesBuilder()
+ .p("db", "new://Resource?type=DataSource")
+ .p("db.JdbcUrld", "jdbc:hsqldb:mem:test")
+ .build();
+}
+`Ì`
+
+Since TomEE 2.x you can also put properties on ApplicationComposer class using `@ContainerProperties` API:
+
+```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:
+
+```java
+@Component
+public SecurityService mockSecurity() {
+ return new MySecurityService();
+}
+`Ì`
+
+## How to run it?
+
+### JUnit
+
+If you use JUnit you have mainly 2 solutions to run you "model" using the ApplicationComposer:
+
+* using `ApplicationComposer` runner:
+
+```java
+@RunWith(ApplicationComposer.class)
+public class MyTest {
+ // ...
+}
+`Ì`
+
+* using `ApplicationComposerRule` rule:
+
+```java
+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 2.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 2.x you can also use `ApplicationComposers` to directly run you ApplicationComposer model
+as a standalone application:
+
+```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
+
+```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
+ }
+}
+`ÌÌ
Added: tomee/site/trunk/content/application-composer/history.md
URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/application-composer/history.md?rev=1672588&view=auto
==============================================================================
--- tomee/site/trunk/content/application-composer/history.md (added)
+++ tomee/site/trunk/content/application-composer/history.md Fri Apr 10 09:15:33 2015
@@ -0,0 +1,38 @@
+# Application Composer History
+
+ApplicationComposer can look like a long story but following it you'll realize it is finally quite natural.
+
+## Internal tool
+
+TomEE (former OpenEJB) is an Application Server. One of the most important task writing an Application Server
+is to ensure the implemented features do what is expected. However it is hard to write N test applications, in N modules
+to ensure it works smoothly. In particular when you want to test a small part of the whole server.
+
+So you immediately think to mocking what is not needed. It works but has a big pitfall: test is often a noop or hide
+a lot of issues.
+
+So the idea came to be able to shortcut the part we don't care much about runtime: the application packaging.
+
+Here what is the ApplicationComposer: an (originally test) API to create a EE application programmatically.
+
+## Designs
+
+ApplicationComposer design was aligned on this simple need. An ApplicationComposer "test" (browsing other pages you'll see
+it is much more than test today) is composed of mainly 2 parts:
+
+* modules: methods describing a module of an application. It can be a persistence.xml, an ejb-jar.xml, a web.xml...but all programmatically.
+* configuration: container configuration allowing to interact with container (creating resources for instance)
+
+## Test but not only
+
+ApplicationComposer was originally a JUnit only runner but was pretty quickly extended to TestNG too and
+today you can even use it to write `main(String[])` - even in a shade!
+
+API was greatly simplified and it allows you pretty easily to deploy with a simple shade a JAXRS/JAXWS/JMS service!
+
+## Going further
+
+If you want to go further you can browse:
+
+* [Getting Started](getting-started.html)
+* [Advanced](advanced.html)
Added: tomee/site/trunk/content/application-composer/index.md
URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/application-composer/index.md?rev=1672588&view=auto
==============================================================================
--- tomee/site/trunk/content/application-composer/index.md (added)
+++ tomee/site/trunk/content/application-composer/index.md Fri Apr 10 09:15:33 2015
@@ -0,0 +1,18 @@
+# Application Composer
+
+Here is the subdomain dedicated to the Application Composer.
+
+If you don't know at all what ApplicationComposer means, [History](history.html) page
+will explain you where does it come from and what it can be used to today.
+
+If you are already familiar with ApplicationComposer concept and are just looking for a sample,
+[Getting Started](getting-started.html) is designed for you.
+
+Finally if you already use ApplicationComposer and just desire to go further, [Advanced](advanced.html)
+page is the one you need to look!
+
+Children:
+
+* [History](history.html)
+* [Getting Started](getting-started.html)
+* [Advanced](advanced.html)
Modified: tomee/site/trunk/content/documentation.mdtext
URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/documentation.mdtext?rev=1672588&r1=1672587&r2=1672588&view=diff
==============================================================================
--- tomee/site/trunk/content/documentation.mdtext (original)
+++ tomee/site/trunk/content/documentation.mdtext Fri Apr 10 09:15:33 2015
@@ -20,6 +20,7 @@ You can also find us on IRC freenode.org
[The 'tomee' webapp](tomee-webapp.html)
[Install TomEE using the drop-in WAR](installation-drop-in-war.html)
[TomEE Reference Card](refcard/refcard.html)
+[ApplicationComposer](application-composer/index.html)
}
{span-one-third
###Configuration