http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/application-resources.adoc ---------------------------------------------------------------------- diff --git a/docs/application-resources.adoc b/docs/application-resources.adoc new file mode 100644 index 0000000..ac85da5 --- /dev/null +++ b/docs/application-resources.adoc @@ -0,0 +1,362 @@ +# Application Resources +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +== Resources + +TomEE provides a simple but powerful way to define resources that can be +injected into managed components inside your application, or looked up +via JNDI. To use a resource, it needs to be defined in the `tomee.xml` +configuration file, a `resources.xml` file within an application, or as +a system property. Defining a resource in `tomee.xml` will make it +available server-wide, whereas defining the resource within a +`resources.xml` file makes it available to a specific application. + +As a simple example, a JMS queue can be defined within `tomee.xml` with +the following configuration. + +.... +<tomee> + <Resource id="MyQueue" type="javax.jms.Queue"/> +</tomee> +.... + +Once the resource has been defined, the server will create an instance +of the resource during startup, and it will be available to be injected +into managed components using the `@Resource` annotation, as shown +below. The `name` attribute on the `@Resource` annotation should match +the `id` attribute on the `Resource` tag. + +.... +public class JmsClient { + + @Resource(name="MyQueue") + private Queue queue; + + public void sendMessage() { + // implementation here... + } + +} +.... + +As an alternative to defining a resource in XML, resources can also be +defined using system properties: + +.... +MyQueue = new://Resource?type=javax.jms.Queue +.... + +Resources, or attributes for resources specified using system properties +will override definitions specified in `tomee.xml`. Server-wide +resources can be looked up in JNDI under the following name: +openejb:Resources/resource id. + +== Defining Resources + +The `<Resource>` tag has a number of attributes, and a resource may also +have a number of fields that can be configured by adding properties to +the body of the `Resource` tag. + +For example, a DataSource resource needs a JDBC driver, URL, username +and password to be able to connect to a database. That would be +configured with the following syntax. Notice the key/value pair syntax +for the properties within the `<Resource>` tag. + +.... +<Resource id="DB" type="DataSource"> + JdbcDriver com.mysql.jdbc.Driver + JdbcUrl jdbc:mysql://localhost/test + UserName test + Password password +</Resource> +.... + +Specifying the key/value pairs specific to a Resource can also be done +when defining the resource via system properties. This is done be +specifying an additional property for each key/value pair, using the +resource ID as a prefix: `<resourceId>.<propertyName>=<value>`. The +system properties equivalent of the resource above is: + +.... +p.setProperty("DB", "new://Resource?type=DataSource"); +p.setProperty("DB.JdbcDriver", "com.mysql.jdbc.Driver"); +p.setProperty("DB,JdbcUrl", "jdbc:mysql://localhost/test"); +p.setProperty("DB.UserName", "test"); +p.setProperty("DB.Password", "password"); +.... + +The `<Resource>` tag has a number of attributes which control the way +that the resource get created. + +* type + +A type that TomEE knows. The type is associated with a provider that +knows how to create that type, and also any default properties that the +resource should have if they are not specified in the resource +definition. See service-jar.xml for an example set of service providers +that come with TomEE. + +* provider + +Explicitly specifies a provider to create the resource, using defaults +for any properties not specified. + +* class-name + +The fully qualified class that creates the resource. This might the +resource class itself, which is created by calling the constructor, or a +factory class that provides a specific factory method to create the +resource. + +* factory-name + +The name of the method to call to create the resource. If this is not +specified, the constructor for the class specified by class-name will be +used. + +* constructor + +Specifies a comma separated list of constructor arguments. These can be +other services, or attributes on the resource itself. + +== Custom resources + +TomEE allows you to define resources using your own Java classes, and +these can also be injected into managed components in the same way as +known resource types are. + +So the following simple resource + +.... +public class Configuration { + + private String url; + private String username; + private int poolSize; + + // getters and setters +} +.... + +Can be defined in `tomee.xml` using the following configuration (note +the `class-name` attribute): + +.... +<Resource id="config" class-name="org.superbiz.Configuration"> + url http://localhost + username tomee + poolSize 20 +</Resource> +.... + +This resource must be available in TomEE's system classpath - i.e. it +must be defined in a .jar within the `lib/` directory. + +== Field and properties + +As shown above, a resource class can define a number of fields, and +TomEE will attempt to apply the values from the resource definition onto +those fields. + +As an alternative to this, you can also add a properties field as shown +below, and this will have any used properties from the resource +configuration set added to it. So as an alternative to the above code, +you could do: + +.... +public class Configuration { + + private Properties properties; + + public Properties getProperties() { + return properties; + } + + public void setProperties(final Properties properties) { + this.properties = properties; + } + +} +.... + +Using the same resource definition: + +.... +<Resource id="config" class-name="org.superbiz.Configuration"> + url http://localhost + username tomee + poolSize 20 +</Resource> +.... + +the url, username and poolSize values will now be available in the +properties field, so for example, the username property could be +accessed via properties.getProperty("username"); + +== Application resources + +Resources can also be defined within an application, and optionally use +classes from the application's classpath. To define resources in a .war +file, include a `WEB-INF/resources.xml`. For an ejb-jar module, use +`META-INF/resources.xml`. + +The format of `resources.xml` uses the same `<Resource>` tag as +`tomee.xml`. One key difference is the root element of the XML is +`<resources>` and not `<tomee>`. + +.... +<resources> + <Resource id="config" class-name="org.superbiz.Configuration"> + url http://localhost + username tomee + poolSize 20 + </Resource> +</resources> +.... + +This mechanism allows you to package your custom resources within your +application, alongside your application code, rather than requiring a +.jar file in the `lib/` directory. + +Application resources are bound in JNDI under +openejb:Resource/appname/resource id. + +== Additional resource properties + +Resources are typically discovered, created, and bound to JNDI very +early on in the deployment process, as other components depend on them. +This may lead to problems where the final classpath for the application +has not yet been determined, and therefore TomEE is unable to load your +custom resource. + +The following properties can be used to change this behavior. + +* Lazy + +This is a boolean value, which when true, creates a proxy that defers +the actual instantiation of the resource until the first time it is +looked up from JNDI. This can be useful if the resource's classpath +until the application is started (see below), or to improve startup time +by not fully initializing resources that might not be used. + +* UseAppClassLoader + +This boolean value forces a lazily instantiated resource to use the +application classloader, instead of the classloader available when the +resources were first processed. + +* InitializeAfterDeployment + +This boolean setting forces a resource created with the Lazy property to +be instantiated once the application has started, as opposed to waiting +for it to be looked up. Use this flag if you require the resource to be +loaded, irrespective of whether it is injected into a managed component +or manually looked up. + +By default, all of these settings are `false`, unless TomEE encounters a +custom application resource that cannot be instantiated until the +application has started. In this case, it will set these three flags to +`true`, unless the `Lazy` flag has been explicitly set. + +== Initializing resources + +=== constructor + +By default, if no factory-name attribute and no constructor attribute is +specified on the `Resource`, TomEE will instantiate the resource using +its no-arg constructor. If you wish to pass constructor arguments, +specify the arguments as a comma separated list: + +.... +<Resource id="config" class-name="org.superbiz.Configuration" constructor="id, poolSize"> + url http://localhost + username tomee + poolSize 20 +</Resource> +.... + +=== factory-name method + +In some circumstances, it may be desirable to add some additional logic +to the creation process, or to use a factory pattern to create +resources. TomEE also provides this facility via the `factory-name` +method. The `factory-name` attribute on the resource can reference any +no argument method that returns an object on the class specified in the +`class-name` attribute. + +For example: + +.... +public class Factory { + + private Properties properties; + + public Object create() { + + MyResource resource = new MyResource(); + // some custom logic here, maybe using this.properties + + return resource; + } + + public Properties getProperties() { + return properties; + } + + public void setProperties(final Properties properties) { + this.properties = properties; + } + +} + +<resources> + <Resource id="MyResource" class-name="org.superbiz.Factory" factory-name="create"> + UserName tomee + </Resource> +</resources> +.... + +=== @PostConstruct / @PreDestroy + +As an alternative to using a factory method or a constructor, you can +use @PostConstruct and @PreDestroy methods within your resource class +(note that you cannot use this within a different factory class) to +manage any additional creation or cleanup activities. TomEE will +automatically call these methods when the application is started and +destroyed. Using @PostConstruct will effectively force a lazily loaded +resource to be instantiated when the application is starting - in the +same way that the `InitializeAfterDeployment` property does. + +.... +public class MyClass { + + private Properties properties; + + public Properties getProperties() { + return properties; + } + + public void setProperties(final Properties properties) { + this.properties = properties; + } + + @PostConstruct + public void postConstruct() throws MBeanRegistrationException { + // some custom initialization + } + } + +} +.... + +== Examples + +The following examples demonstrate including custom resources within +your application: + +* resources-jmx-example +* resources-declared-in-webapp
http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/application-resources.md ---------------------------------------------------------------------- diff --git a/docs/application-resources.md b/docs/application-resources.md deleted file mode 100644 index b3ee1fa..0000000 --- a/docs/application-resources.md +++ /dev/null @@ -1,250 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Application Resources -~~~~~~ -<a name="ApplicationResources"></a> - -# Resources - -TomEE provides a simple but powerful way to define resources that can be injected into managed components inside your application, or looked up via JNDI. To use a resource, it needs to be defined in the `tomee.xml` configuration file, a `resources.xml` file within an application, or as a system property. Defining a resource in `tomee.xml` will make it available server-wide, whereas defining the resource within a `resources.xml` file makes it available to a specific application. - -As a simple example, a JMS queue can be defined within `tomee.xml` with the following configuration. - - <tomee> - <Resource id="MyQueue" type="javax.jms.Queue"/> - </tomee> - -Once the resource has been defined, the server will create an instance of the resource during startup, and it will be available to be injected into managed components using the `@Resource` annotation, as shown below. The `name` attribute on the `@Resource` annotation should match the `id` attribute on the `Resource` tag. - - public class JmsClient { - - @Resource(name="MyQueue") - private Queue queue; - - public void sendMessage() { - // implementation here... - } - - } - -As an alternative to defining a resource in XML, resources can also be defined using system properties: - - MyQueue = new://Resource?type=javax.jms.Queue - -Resources, or attributes for resources specified using system properties will override definitions specified in `tomee.xml`. -Server-wide resources can be looked up in JNDI under the following name: openejb:Resources/resource id. - -# Defining Resources -<a name="DefiningResources"></a> - -The `<Resource>` tag has a number of attributes, and a resource may also have a number of fields that can be configured by adding properties to the body of the `Resource` tag. - -For example, a DataSource resource needs a JDBC driver, URL, username and password to be able to connect to a database. That would be configured with the following syntax. Notice the key/value pair syntax for the properties within the `<Resource>` tag. - - <Resource id="DB" type="DataSource"> - JdbcDriver com.mysql.jdbc.Driver - JdbcUrl jdbc:mysql://localhost/test - UserName test - Password password - </Resource> - -Specifying the key/value pairs specific to a Resource can also be done when defining the resource via system properties. This is done be specifying an additional property for each key/value pair, using the resource ID as a prefix: `<resourceId>.<propertyName>=<value>`. The system properties equivalent of the resource above is: - - p.setProperty("DB", "new://Resource?type=DataSource"); - p.setProperty("DB.JdbcDriver", "com.mysql.jdbc.Driver"); - p.setProperty("DB,JdbcUrl", "jdbc:mysql://localhost/test"); - p.setProperty("DB.UserName", "test"); - p.setProperty("DB.Password", "password"); - -The `<Resource>` tag has a number of attributes which control the way that the resource get created. - -* type - -A type that TomEE knows. The type is associated with a provider that knows how to create that type, and also any default properties that the resource should have if they are not specified in the resource definition. See <a href="https://github.com/apache/tomee/blob/tomee-1.7.x/tomee/tomee-webapp/src/main/resources/META-INF/org.apache.tomee/service-jar.xml";>service-jar.xml</a> for an example set of service providers that come with TomEE. - -* provider - -Explicitly specifies a provider to create the resource, using defaults for any properties not specified. - -* class-name - -The fully qualified class that creates the resource. This might the resource class itself, which is created by calling the constructor, or a factory class that provides a specific factory method to create the resource. - -* factory-name - -The name of the method to call to create the resource. If this is not specified, the constructor for the class specified by class-name will be used. - -* constructor - -Specifies a comma separated list of constructor arguments. These can be other services, or attributes on the resource itself. - -# Custom resources - -TomEE allows you to define resources using your own Java classes, and these can also be injected into managed components in the same way as known resource types are. - -So the following simple resource - - public class Configuration { - - private String url; - private String username; - private int poolSize; - - // getters and setters - } - -Can be defined in `tomee.xml` using the following configuration (note the `class-name` attribute): - - <Resource id="config" class-name="org.superbiz.Configuration"> - url http://localhost - username tomee - poolSize 20 - </Resource> - -This resource must be available in TomEE's system classpath - i.e. it must be defined in a .jar within the `lib/` directory. - -# Field and properties - -As shown above, a resource class can define a number of fields, and TomEE will attempt to apply the values from the resource definition onto those fields. - -As an alternative to this, you can also add a properties field as shown below, and this will have any used properties from the resource configuration set added to it. So as an alternative to the above code, you could do: - - public class Configuration { - - private Properties properties; - - public Properties getProperties() { - return properties; - } - - public void setProperties(final Properties properties) { - this.properties = properties; - } - - } - -Using the same resource definition: - - <Resource id="config" class-name="org.superbiz.Configuration"> - url http://localhost - username tomee - poolSize 20 - </Resource> - -the url, username and poolSize values will now be available in the properties field, so for example, the username property could be accessed via properties.getProperty("username"); - -# Application resources - -Resources can also be defined within an application, and optionally use classes from the application's classpath. To define resources in a .war file, include a `WEB-INF/resources.xml`. For an ejb-jar module, use `META-INF/resources.xml`. - -The format of `resources.xml` uses the same `<Resource>` tag as `tomee.xml`. One key difference is the root element of the XML is `<resources>` and not `<tomee>`. - - <resources> - <Resource id="config" class-name="org.superbiz.Configuration"> - url http://localhost - username tomee - poolSize 20 - </Resource> - </resources> - -This mechanism allows you to package your custom resources within your application, alongside your application code, rather than requiring a .jar file in the `lib/` directory. - -Application resources are bound in JNDI under openejb:Resource/appname/resource id. - -# Additional resource properties - -Resources are typically discovered, created, and bound to JNDI very early on in the deployment process, as other components depend on them. This may lead to problems where the final classpath for the application has not yet been determined, and therefore TomEE is unable to load your custom resource. - -The following properties can be used to change this behavior. - -* Lazy - -This is a boolean value, which when true, creates a proxy that defers the actual instantiation of the resource until the first time it is looked up from JNDI. This can be useful if the resource's classpath until the application is started (see below), or to improve startup time by not fully initializing resources that might not be used. - -* UseAppClassLoader - -This boolean value forces a lazily instantiated resource to use the application classloader, instead of the classloader available when the resources were first processed. - -* InitializeAfterDeployment - -This boolean setting forces a resource created with the Lazy property to be instantiated once the application has started, as opposed to waiting for it to be looked up. Use this flag if you require the resource to be loaded, irrespective of whether it is injected into a managed component or manually looked up. - -By default, all of these settings are `false`, unless TomEE encounters a custom application resource that cannot be instantiated until the application has started. In this case, it will set these three flags to `true`, unless the `Lazy` flag has been explicitly set. - -# Initializing resources - -## constructor - -By default, if no factory-name attribute and no constructor attribute is specified on the `Resource`, TomEE will instantiate the resource using its no-arg constructor. If you wish to pass constructor arguments, specify the arguments as a comma separated list: - - <Resource id="config" class-name="org.superbiz.Configuration" constructor="id, poolSize"> - url http://localhost - username tomee - poolSize 20 - </Resource> - -## factory-name method - -In some circumstances, it may be desirable to add some additional logic to the creation process, or to use a factory pattern to create resources. TomEE also provides this facility via the `factory-name` method. The `factory-name` attribute on the resource can reference any no argument method that returns an object on the class specified in the `class-name` attribute. - -For example: - - public class Factory { - - private Properties properties; - - public Object create() { - - MyResource resource = new MyResource(); - // some custom logic here, maybe using this.properties - - return resource; - } - - public Properties getProperties() { - return properties; - } - - public void setProperties(final Properties properties) { - this.properties = properties; - } - - } - - <resources> - <Resource id="MyResource" class-name="org.superbiz.Factory" factory-name="create"> - UserName tomee - </Resource> - </resources> - -## @PostConstruct / @PreDestroy - -As an alternative to using a factory method or a constructor, you can use @PostConstruct and @PreDestroy methods within your resource class (note that you cannot use this within a different factory class) to manage any additional creation or cleanup activities. TomEE will automatically call these methods when the application is started and destroyed. Using @PostConstruct will effectively force a lazily loaded resource to be instantiated when the application is starting - in the same way that the `InitializeAfterDeployment` property does. - - public class MyClass { - - private Properties properties; - - public Properties getProperties() { - return properties; - } - - public void setProperties(final Properties properties) { - this.properties = properties; - } - - @PostConstruct - public void postConstruct() throws MBeanRegistrationException { - // some custom initialization - } - } - - } - -# Examples - -The following examples demonstrate including custom resources within your application: - -* resources-jmx-example -* resources-declared-in-webapp http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/arquillian-available-adapters.adoc ---------------------------------------------------------------------- diff --git a/docs/arquillian-available-adapters.adoc b/docs/arquillian-available-adapters.adoc new file mode 100644 index 0000000..dd9c074 --- /dev/null +++ b/docs/arquillian-available-adapters.adoc @@ -0,0 +1,311 @@ +# TomEE and Arquillian +:index-group: Arquillian +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +Check out the link:arquillian-getting-started.html[Getting started] page +if you are not at all familiar with Arquillian. + +All the Arquillian Adapters for TomEE support the following +configuration options in the *src/test/resources/arquillian.xml*: + +.... +<container qualifier="tomee" default="true"> + <configuration> + <property name="httpPort">-1</property> + <property name="stopPort">-1</property> + <!--Optional Container Properties--> + <property name="properties"> + aproperty=something + </property> + <!--Optional Remote Adapter Deployer Properties + <property name="deployerProperties"> + aproperty=something + </property> + --> + </configuration> +</container> +.... + +The above can also be set as system properties rather than via the +*src/test/resources/arquillian.xml* file. + +.... +<build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-surefire-plugin</artifactId> + <configuration> + <systemPropertyVariables> + <tomee.httpPort>-1</tomee.httpPort> + <tomee.stopPort>-1</tomee.stopPort> + </systemPropertyVariables> + </configuration> + </plugin> + </plugins> +</build> +.... + +When a port is set to -1, a random port will be chosen. This is key to +avoiding port conflicts on CI systems or for just plain clean testing. + +The TomEE Arquillian adapters will export the actual port chosen back as +a system property using the same name. The test case can use the +property to retrieve the port and contact the server. + +.... +URL url = new URL("http://localhost:"; + System.getProperty("tomee.httpPort"); +// use the URL to connect to the server +.... + +If that property returns null + +When you are actually using a test on the client side, you can use +instead + +.... +import org.jboss.arquillian.test.api.ArquillianResource; +... +@ArquillianResource private URL url; +.... + +The URL will get injected by Arquillian. Be careful, that injection only +works if your are on the client side (it does not make sense in the +server side). So, if for a specific need to need it, just use the system +property. + +== TomEE Embedded Adapter + +The TomEE Embedded Adapter will boot TomEE right inside the test case +itself resulting in one JVM running both the application and the test +case. This is generally much faster than the TomEE Remote Adapter and +great for development. That said, it is strongly recommended to also run +all tests in a Continuous Integration system using the TomEE Remote +Adapter. + +To use the TomEE Embedded Arquillian Adapter, simply add these Maven +dependencies to your Maven pom.xml: + +.... +<dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>arquillian-tomee-embedded</artifactId> + <version>1.7.1</version> <!--Current version--> +</dependency> +<dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>tomee-embedded</artifactId> + <version>1.7.1</version> +</dependency> +<!--Required for WebServices and RESTful WebServices--> +<dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>tomee-webservices</artifactId> + <version>1.7.1</version> +</dependency> +<dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>tomee-jaxrs</artifactId> + <version>1.7.1</version> +</dependency> +.... + +As mentioned above the Embedded Adapter has the following properties +which can be specified in the *src/test/resources/arquillian.xml* file: + +* `httpPort` +* `stopPort` +* `properties` (System properties for container) + +Or alternatively as System properties, possibly shared with other TomEE +Arquillian Adapters: + +* `tomee.httpPort` +* `tomee.stopPort` + +Or more specifically as a System properties only applicable to the +Embedded Adapter: + +* `tomee.embedded.httpPort` +* `tomee.embedded.stopPort` + +== TomEE Remote Adapter + +The TomEE Remote Adapter will unzip and setup a TomEE or TomEE Plus +distribution. Once setup, the server will execute in a separate process. +This will be slower, but with the added benefit it is 100% match with +the production system environment. + +On a local machine clients can get the remote server port using the +following System property: + +.... +final String port = System.getProperty("server.http.port"); +.... + +The following shows a typical configuration for testing against TomEE +(webprofile version). The same can be done against TomEE+ by changing +`<tomee.classifier>webprofile</tomee.classifier>` to +`<tomee.classifier>plus</tomee.classifier>` + +.... +<properties> + <tomee.version>1.7.1</tomee.version> + <tomee.classifier>webprofile</tomee.classifier> +</properties> +<build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-surefire-plugin</artifactId> + <configuration> + <systemPropertyVariables> + <tomee.classifier>${tomee.classifier}</tomee.classifier> + <tomee.version>${tomee.version}</tomee.version> + </systemPropertyVariables> + </configuration> + </plugin> + </plugins> +</build> +<dependencies> + <dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>arquillian-tomee-remote</artifactId> + <version>${tomee.version}</version> + </dependency> + <dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>apache-tomee</artifactId> + <version>${tomee.version}</version> + <classifier>${tomee.classifier}</classifier> + <type>zip</type> + </dependency> +</dependencies> +.... + +The Remote Adapter has the following properties which can be specified +in the *src/test/resources/arquillian.xml* file: + +* `httpPort` +* `stopPort` +* `version` +* `classifier` (Must be either `webprofile` or `plus`) +* `properties` (System properties for container) +* `deployerProperties` (Sent to Deployer) + +Or alternatively as System properties, possibly shared with other TomEE +Arquillian Adapters: + +* `tomee.httpPort` +* `tomee.stopPort` +* `tomee.version` +* `tomee.classifier` + +Or more specifically as a System properties only applicable to the +Remote Adapter: + +* `tomee.remote.httpPort` +* `tomee.remote.stopPort` +* `tomee.remote.version` +* `tomee.remote.classifier` + +== Maven Profiles + +Setting up both adapters is quite easy via Maven profiles. Here the +default adapter is the Embedded Adapter, the Remote Adapter will run +with `-Ptomee-webprofile-remote` specified as a `mvn` command argument. + +.... +<profiles> + + <profile> + <id>tomee-embedded</id> + <activation> + <activeByDefault>true</activeByDefault> + </activation> + <dependencies> + <dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>arquillian-tomee-embedded</artifactId> + <version>1.0.0</version> + </dependency> + </dependencies> + </profile> + + <profile> + <id>tomee-webprofile-remote</id> + <properties> + <tomee.version>1.0.0</tomee.version> + <tomee.classifier>webprofile</tomee.classifier> + </properties> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-surefire-plugin</artifactId> + <configuration> + <systemPropertyVariables> + <tomee.classifier>${tomee.classifier}</tomee.classifier> + <tomee.version>${tomee.version}</tomee.version> + </systemPropertyVariables> + </configuration> + </plugin> + </plugins> + </build> + <dependencies> + <dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>arquillian-tomee-remote</artifactId> + <version>${tomee.version}</version> + </dependency> + <dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>apache-tomee</artifactId> + <version>${tomee.version}</version> + <classifier>${tomee.classifier}</classifier> + <type>zip</type> + </dependency> + </dependencies> + </profile> + + <profile> + <id>tomee-plus-remote</id> + <properties> + <tomee.version>1.0.0</tomee.version> + <tomee.classifier>plus</tomee.classifier> + </properties> + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-surefire-plugin</artifactId> + <configuration> + <systemPropertyVariables> + <tomee.classifier>${tomee.classifier}</tomee.classifier> + <tomee.version>${tomee.version}</tomee.version> + </systemPropertyVariables> + </configuration> + </plugin> + </plugins> + </build> + <dependencies> + <dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>arquillian-tomee-remote</artifactId> + <version>${tomee.version}</version> + </dependency> + <dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>apache-tomee</artifactId> + <version>${tomee.version}</version> + <classifier>${tomee.classifier}</classifier> + <type>zip</type> + </dependency> + </dependencies> + </profile> + +</profiles> +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/arquillian-available-adapters.md ---------------------------------------------------------------------- diff --git a/docs/arquillian-available-adapters.md b/docs/arquillian-available-adapters.md deleted file mode 100644 index ac9c85e..0000000 --- a/docs/arquillian-available-adapters.md +++ /dev/null @@ -1,264 +0,0 @@ -index-group=Arquillian -type=page -status=published -title=TomEE and Arquillian -~~~~~~ - -Check out the [Getting started](arquillian-getting-started.html) page if you are not at all familiar with Arquillian. - -All the Arquillian Adapters for TomEE support the following configuration options in the **src/test/resources/arquillian.xml**: - - <container qualifier="tomee" default="true"> - <configuration> - <property name="httpPort">-1</property> - <property name="stopPort">-1</property> - <!--Optional Container Properties--> - <property name="properties"> - aproperty=something - </property> - <!--Optional Remote Adapter Deployer Properties - <property name="deployerProperties"> - aproperty=something - </property> - --> - </configuration> - </container> - -The above can also be set as system properties rather than via the **src/test/resources/arquillian.xml** file. - - <build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-surefire-plugin</artifactId> - <configuration> - <systemPropertyVariables> - <tomee.httpPort>-1</tomee.httpPort> - <tomee.stopPort>-1</tomee.stopPort> - </systemPropertyVariables> - </configuration> - </plugin> - </plugins> - </build> - -When a port is set to -1, a random port will be chosen. This is key to avoiding port conflicts on CI systems or for just plain clean testing. - -The TomEE Arquillian adapters will export the actual port chosen back as a system property using the same name. The test case can use the property to retrieve the port and contact the server. - - URL url = new URL("http://localhost:"; + System.getProperty("tomee.httpPort"); - // use the URL to connect to the server - -If that property returns null - -When you are actually using a test on the client side, you can use instead - - import org.jboss.arquillian.test.api.ArquillianResource; - ... - @ArquillianResource private URL url; - -The URL will get injected by Arquillian. Be careful, that injection only works if your are on the client side (it does not make sense in the server side). So, if for a specific need to need it, just use the system property. - -# TomEE Embedded Adapter - -The TomEE Embedded Adapter will boot TomEE right inside the test case itself resulting in one JVM running both the application and the test case. This is generally much faster than the TomEE Remote Adapter and great for development. That said, it is strongly recommended to also run all tests in a Continuous Integration system using the TomEE Remote Adapter. - -To use the TomEE Embedded Arquillian Adapter, simply add these Maven dependencies to your Maven pom.xml: - - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>arquillian-tomee-embedded</artifactId> - <version>1.7.1</version> <!--Current version--> - </dependency> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>tomee-embedded</artifactId> - <version>1.7.1</version> - </dependency> - <!--Required for WebServices and RESTful WebServices--> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>tomee-webservices</artifactId> - <version>1.7.1</version> - </dependency> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>tomee-jaxrs</artifactId> - <version>1.7.1</version> - </dependency> - -As mentioned above the Embedded Adapter has the following properties which can be specified in the **src/test/resources/arquillian.xml** file: - - - `httpPort` - - `stopPort` - - `properties` (System properties for container) - -Or alternatively as System properties, possibly shared with other TomEE Arquillian Adapters: - - - `tomee.httpPort` - - `tomee.stopPort` - -Or more specifically as a System properties only applicable to the Embedded Adapter: - - - `tomee.embedded.httpPort` - - `tomee.embedded.stopPort` - - -# TomEE Remote Adapter - -The TomEE Remote Adapter will unzip and setup a TomEE or TomEE Plus distribution. Once setup, the server will execute in a separate process. This will be slower, but with the added benefit it is 100% match with the production system environment. - -On a local machine clients can get the remote server port using the following System property: - - final String port = System.getProperty("server.http.port"); - -The following shows a typical configuration for testing against TomEE (webprofile version). The same can be done against TomEE+ by changing `<tomee.classifier>webprofile</tomee.classifier>` to `<tomee.classifier>plus</tomee.classifier>` - - <properties> - <tomee.version>1.7.1</tomee.version> - <tomee.classifier>webprofile</tomee.classifier> - </properties> - <build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-surefire-plugin</artifactId> - <configuration> - <systemPropertyVariables> - <tomee.classifier>${tomee.classifier}</tomee.classifier> - <tomee.version>${tomee.version}</tomee.version> - </systemPropertyVariables> - </configuration> - </plugin> - </plugins> - </build> - <dependencies> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>arquillian-tomee-remote</artifactId> - <version>${tomee.version}</version> - </dependency> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>apache-tomee</artifactId> - <version>${tomee.version}</version> - <classifier>${tomee.classifier}</classifier> - <type>zip</type> - </dependency> - </dependencies> - -The Remote Adapter has the following properties which can be specified in the **src/test/resources/arquillian.xml** file: - - - `httpPort` - - `stopPort` - - `version` - - `classifier` (Must be either `webprofile` or `plus`) - - `properties` (System properties for container) - - `deployerProperties` (Sent to Deployer) - -Or alternatively as System properties, possibly shared with other TomEE Arquillian Adapters: - - - `tomee.httpPort` - - `tomee.stopPort` - - `tomee.version` - - `tomee.classifier` - -Or more specifically as a System properties only applicable to the Remote Adapter: - - - `tomee.remote.httpPort` - - `tomee.remote.stopPort` - - `tomee.remote.version` - - `tomee.remote.classifier` - -# Maven Profiles - -Setting up both adapters is quite easy via Maven profiles. Here the default adapter is the Embedded Adapter, the Remote Adapter will run with `-Ptomee-webprofile-remote` specified as a `mvn` command argument. - - <profiles> - - <profile> - <id>tomee-embedded</id> - <activation> - <activeByDefault>true</activeByDefault> - </activation> - <dependencies> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>arquillian-tomee-embedded</artifactId> - <version>1.0.0</version> - </dependency> - </dependencies> - </profile> - - <profile> - <id>tomee-webprofile-remote</id> - <properties> - <tomee.version>1.0.0</tomee.version> - <tomee.classifier>webprofile</tomee.classifier> - </properties> - <build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-surefire-plugin</artifactId> - <configuration> - <systemPropertyVariables> - <tomee.classifier>${tomee.classifier}</tomee.classifier> - <tomee.version>${tomee.version}</tomee.version> - </systemPropertyVariables> - </configuration> - </plugin> - </plugins> - </build> - <dependencies> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>arquillian-tomee-remote</artifactId> - <version>${tomee.version}</version> - </dependency> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>apache-tomee</artifactId> - <version>${tomee.version}</version> - <classifier>${tomee.classifier}</classifier> - <type>zip</type> - </dependency> - </dependencies> - </profile> - - <profile> - <id>tomee-plus-remote</id> - <properties> - <tomee.version>1.0.0</tomee.version> - <tomee.classifier>plus</tomee.classifier> - </properties> - <build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-surefire-plugin</artifactId> - <configuration> - <systemPropertyVariables> - <tomee.classifier>${tomee.classifier}</tomee.classifier> - <tomee.version>${tomee.version}</tomee.version> - </systemPropertyVariables> - </configuration> - </plugin> - </plugins> - </build> - <dependencies> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>arquillian-tomee-remote</artifactId> - <version>${tomee.version}</version> - </dependency> - <dependency> - <groupId>org.apache.openejb</groupId> - <artifactId>apache-tomee</artifactId> - <version>${tomee.version}</version> - <classifier>${tomee.classifier}</classifier> - <type>zip</type> - </dependency> - </dependencies> - </profile> - - </profiles> http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/arquillian-getting-started.adoc ---------------------------------------------------------------------- diff --git a/docs/arquillian-getting-started.adoc b/docs/arquillian-getting-started.adoc new file mode 100644 index 0000000..093a19b --- /dev/null +++ b/docs/arquillian-getting-started.adoc @@ -0,0 +1,41 @@ +# Getting started with Arquillian and TomEE +:index-group: Arquillian +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +Arquillian is a testing framework on top of JUnit (or TestNG if you +prefer). It makes it easier to do integration tests in a managed +environment (JEE environment here after). + +We provide an embedded and remote adapter, see +link:arquillian-available-adapters.html[the available adapters] for more +details. + +In a managed environment it is usually quite difficult to perform unit +tests, due to the fact that most of the time you have to mock almost the +entire environment. It is very time consuming and requires complicated +integration tests that must reflect the production environment as best +as possible. Unit tests lose their true value. + +JEE always got seen as an heavy technology, impossible to test and to +use in development. OpenEJB always fight against that idea and proved +that it's really possible. + +As David Blevins said: > "Do not blame EJBs (ie. Java EE) because your +server is not testable." + +With latest Java EE specifications (5 and especially 6), it becomes a +reality. Arquillian typically addresses that area. It is basically a +framework that aims at helping/managing the server/container in an +agnostic way. Arquillian is responsible for the lifecycle of the +container (start, deploy, undeploy, stop, etc). + +TomEE community heavily invested on that framework to prove it's really +useful and can really help testing Java EE application. That's also an +opportunity to get the most out of TomEE (lightweight, fast, +feature-rich, etc). + +\{info See http://arquillian.org[Arquillian.org] for a great quick-start +tutorial on Arquillian itself. } http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/arquillian-getting-started.md ---------------------------------------------------------------------- diff --git a/docs/arquillian-getting-started.md b/docs/arquillian-getting-started.md deleted file mode 100644 index 78d635f..0000000 --- a/docs/arquillian-getting-started.md +++ /dev/null @@ -1,24 +0,0 @@ -index-group=Arquillian -type=page -status=published -title=Getting started with Arquillian and TomEE -~~~~~~ - -Arquillian is a testing framework on top of JUnit (or TestNG if you prefer). It makes it easier to do integration tests in a managed environment (JEE environment here after). - -We provide an embedded and remote adapter, see [the available adapters](arquillian-available-adapters.html) for more details. - -In a managed environment it is usually quite difficult to perform unit tests, due to the fact that most of the time you have to mock almost the entire environment. It is very time consuming and requires complicated integration tests that must reflect the production environment as best as possible. Unit tests lose their true value. - -JEE always got seen as an heavy technology, impossible to test and to use in development. OpenEJB always fight against that idea and proved that it's really possible. - -As David Blevins said: -> "Do not blame EJBs (ie. Java EE) because your server is not testable." - -With latest Java EE specifications (5 and especially 6), it becomes a reality. Arquillian typically addresses that area. It is basically a framework that aims at helping/managing the server/container in an agnostic way. Arquillian is responsible for the lifecycle of the container (start, deploy, undeploy, stop, etc). - -TomEE community heavily invested on that framework to prove it's really useful and can really help testing Java EE application. That's also an opportunity to get the most out of TomEE (lightweight, fast, feature-rich, etc). - -{info -See [Arquillian.org](http://arquillian.org) for a great quick-start tutorial on Arquillian itself. -}
