content/application-composer/getting-started.md

# 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`:

    <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`:

    <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`:

    <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:

    @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:
 
    @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:

    @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:

    @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:

    @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:

    @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 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:

    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

    @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
        }
    }

## Going further

If you want to learn more about ApplicationComposer see [Advanced](advanced.html) page.