+ This page offers some general information about the appserver control + features of the J2EE plug-in. Specific details about + related targets and + their properties can be found elsewhere. +
++ When developing a web application (or website for that matter), each developer + working on the project needs to have an environment to run and test their + application. Rather than store a complete application server install in source + control, it is much more feasible to have a centralized install of that + application server. Then, using only the minimum configuration files the + developer can control a separate isolated instance of the application server + on their machine. +
++ The Maven J2EE plug-in appserver features use this technique to install and control + application server instances for your project needs. The appserver + features are not for + deploying webapps or war files into application servers. +
++ The following table shows the various appserver versions that are + supported by the appserver control features of the Maven J2EE plug-in + and what propety values are required to be set in order for the + maven:appserver-* targets to work with those versions. +
+| Server | +${maven.appserver.name} | +${maven.appserver.version} | +${maven.j2ee.version} | +
|---|---|---|---|
| Tomcat 4.x | +tomcat |
+ 40 |
+ 12 or 13 |
+
The following application servers are expected to be supported soon:
+ ++ To make life even easier when using the appserver targets, the Maven J2EE + plug-in includes a proxy build file. This means a file similar to the one + below is copied to the directory specified by + ${maven.appserver.dir}. +
+| ${maven.appserver.dir}/build.xml |
|---|
Using this build file, you can run the appserver related targets quickly + from within your ${maven.appserver.dir} directory. Typing simply
+can stop, re-install, and re-start a started server instance.
++ Having a common directory layout would allow for users familiar + with one Maven project to immediately feel at home in another + Maven project. The advantages are analogous to adopting a + site-wide look-and-feel. Common Maven procedures strengthen the + Maven brand. +
++ The next two sections document the directory layout expected by + Maven and the directory layout created by Maven. Please try to + conform to this structure as much as possible; however, if you + must these settings can be overridden via properties as + documented in the Integration document. +
+| Directory or file name | +Content | +Comment | +
|---|---|---|
| src/webapp | +The base directory under which web applications can be found. | ++ This directory contains the web application to + be built. The web application name is passed to maven as the + property ${maven.j2ee.war.name} + | +
| Directory name | +Content | +Comment | +
|---|---|---|
| target/ | +Contains compiled WARs and EARs. | ++ This directory is used by the J2EE Plug-in as the destination of the + built war and ear files + | +
+ The following is a list of things that are being contemplated + for the Maven J2EE Plug-in. +
++ This document describes the supplied + goals + that are available when using the J2EE Plug-in with Maven. +
++ Please refer to the + Integration document for + more information on how to integrate these goals into + your project. +
++ The build file utilizes various properties for default and + user-configurable settings. All J2EE Plug-in properties are described + in the Properties document. + + The rest of this document assumes your project follows the standard + Directory Layout; however, it is + possible to override many of these defaults. +
+| Goal | Description |
|---|---|
| j2ee:validate-war | +Validate a WAR file. |
+
| j2ee:ejb | +Creates an EJBjar file. |
+
| j2ee:ear | +Creates an EAR file. |
+
| j2ee:appserver-install | +Installs an Application Server instance | +
| j2ee:appserver-start | +Starts an Application Server instance | +
| j2ee:appserver-stop | +Stops an Application Server instance | +
| j2ee:appserver-clean | +Safely deletes the Application Server instance installation directory
+ specified by the ${maven.appserver.dir}
+ property. |
+
+ The j2ee:validate-war target validates the newly
+ produced war file.
+
+ The validator checks the folowing: +
<servlet> tag are loadable
+ from the war file and not the classpath<servlet> tag exist in the war
+ <taglib> have a
+ <taglib-location> that exists in the war<location> nested
+ within an <error-page> element must exist in the
+ war file<form-login-config
+ > element must exist in the war file
+ The j2ee:ejb target generates the ejb jar file
+ for the project. Optionally it can also create jars containing the local
+ and remote interfaces. The files are produced in the
+ ${maven.build.dir}/ejb
+ directory and have a name based on the
+ ${maven.j2ee.ejb.name}
+ property.
+
The files generated are: +
${maven.j2ee.ejb.name}.jar${maven.j2ee.ejb.name}-remote.jar ${maven.j2ee.ejb.name}-local.jar + Maven also includes the license file, LICENSE.txt, if it exists, in + the META-INF directory. +
++ The contents of the ejb file include: +
+| Item | Description |
|---|---|
| ejb-jar.xml | +
+ A J2EE enterprise bean deployment descriptor, which
+ is placed in the root of the resulting ear file.
+ The
+ ${maven.j2ee.ejb.conf.dir} and associated includes and
+ excludes properties defines the location of this file.
+ |
+
| Classes | +
+ The files in the ${maven.build.dest}
+ directory to be included is specified using the
+ ${maven.j2ee.ejb.includes}
+ and ${maven.j2ee.ejb.excludes}
+ properties.
+ |
+
| Meta-Inf | +
+ Files to be included the META-INF directory of the ejb
+ jar file may be specified using the
+
+ ${maven.j2ee.ejb.conf.dir},
+
+ ${maven.j2ee.ejb.conf.includes} and
+
+ ${maven.j2ee.ejb.conf.excludes} properties.
+ |
+
+ The j2ee:ear target generates an ear file for the
+ project. The ear file is produced in the
+ ${maven.build.dir}
+ directory and has a name defined by the
+ ${maven.j2ee.ear.name}
+ property.
+
+ Maven also includes the license file, LICENSE.txt, if it exists, under + the directory META-INF. +
++ The contents of the ear file include: +
+| Item | Description |
|---|---|
| application.xml | +
+ A J2EE enterprise application deployment descriptor, which
+ is placed in the META-INF of the resulting ear file.
+ The ${maven.j2ee.ear.appxml}
+ property defines the location of this file. It defaults to
+ src/application.xml
+ |
+
| Other Content | +
+ Any dependencies specified in your project.xml
+ may be included by adding the ear.bundle.jar property to the
+ properties, e.g.
+ |
+
+ The j2ee:appserver-install target installs the minimum
+ directory and file structure necessary for an individual application
+ server instance. Once the structure is created inside the
+ directory specified by ${maven.appserver.dir}
+ , configuration files are installed using the copy task and the filter
+ mechanism built into Ant.
+ The exact work done by this target is specific to the
+ name and version of the application server you specify using
+ ${maven.appserver.name}
+ and ${maven.appserver.version}
+ properties.
+
+ Optionally, you can invoke the install target of the
+ Ant build.xml file copied to ${maven.appserver.dir} instead. See the
+ appserver proxy build file for more
+ information.
+
+ During the configuration process, all + maven.appserver.* properties + are used as filter tokens while files in + ${maven.conf.dir}/${maven.appserver.name}${maven.appserver.version} are + copied to ${maven.appserver.dir}. By default, certain files are + excluded from copying to ${maven.appserver.dir}. Files excluded are: +
++ This allows you to keep you webapp specific conf files in the same + directory and not have them installed with this target needlessly. +
++ Your configuration files may require additional processing ( using additional + filter tokens for example). In that case you can use the + maven-post-appserver-install + callback target to re-configure files. +
++ This target has different behavior + depending on the current status of the application server. The + behavior is defined by the following rules: +
+| Server Status | Behavior |
|---|---|
| Not Installed | ++ Install and configure the application server. + | +
| Installed and stopped | ++ Re-install/re-configure the application server. + | +
| Installed and started | ++ Stop, re-install/re-configure, re-start the application server. + | +
Note: In all situations, the j2ee:appserver-install
+ target will overwrite existing appserver configuration files already
+ installed. Maven does this because it cannot know if the you have changed
+ your maven.appserver.* related properties,
+ so it always re-configures the configuration files. Since this
+ operation has low overhead, it is considered a feature that allows dynamic
+ updates to your appserver related property values.
+ The j2ee:appserver-start target
+ attempts to start the application server instance you have specified
+ via properties.
+
Optionally, you can invoke the start target of the
+ Ant build.xml file copied to ${maven.appserver.dir} instead. See the
+ appserver proxy build file for more
+ information.
+
+ This target will cause two processes to run. One process will + represent the running of the Ant build file for the Maven target. + The other will be the forked JVM that actually starts the application + server instance. +
++ If you don't want the processes to block your current terminal, + you can execute the call to this target in the background using the + traditional '&' directive on unix-like systems. +
+For example, to run the server in the background, go to your + ${maven.appserver.dir} directory and type:
++ This target has different behavior + depending on the current status of the application server. The + behavior is defined by the following rules: +
+| Server Status | Behavior |
|---|---|
| Not Installed | ++ Install/configure, then start the application server. + | +
| Installed and stopped | ++ Start the application server. + | +
| Installed and started | ++ Stop and then re-start the application server. This is useful for + application servers that are not set to auto-reload resources. + | +
+ The j2ee:appserver-stop target
+ attempts to stop the application server instance you have specified
+ via the maven.appserver.* properties.
+
Optionally, you can invoke the stop target of the
+ Ant build.xml file copied to ${maven.appserver.dir} instead. See the
+ appserver proxy build file for more
+ information.
+
+ This target only has relevance if the application server instance + is actually started. All other situations do nothing. +
+
+ The j2ee:appserver-clean target
+ attempts to safely delete the directory specified by
+ ${maven.appserver.dir}.
+
+ This target has different behavior + depending on the current status of the application server. The + behavior is defined by the following rules: +
+| Server Status | Behavior |
|---|---|
| Installed and stopped | ++ Deletes the directory specified by ${maven.appserver.dir}. + | +
| Installed and started | ++ Stop the application server instance and then delete the directory + specified by ${maven.appserver.dir}. + | +
+ This document provides an overview of the reference section + for the Maven J2EE Plug-in. + The documents presented here are references, if you are looking + for more verbose usage material, please refer to the Getting Started section. +
+ +| Document | Description |
|---|---|
| Goals | ++ This document provides detailed information on the various + goals that are available as part of the Maven J2EE Plug-in. + | +
| Properties | ++ The behavior of the Maven J2EE Plug-in can be altered via numerous + properties. This document describes each property + available as the default used. + | +
| Directory Layout | ++ The preferred directory layout structure is documented + here. This is a useful document if you are trying to + determine what a particular component of your directory + hierarchy is used for. + | +
| Appserver Notes | +
+ + This page contains additional reference material regarding the application server ( + appserver ) control features of the Maven J2EE plugin. + ++ For additional help in understanding what the appserver features of the + Maven J2EE plugin are, look at the + J2EE plug-in properties + and J2EE build file + documents. + + |
+
| Futures | ++ These are the current thoughts on additional items + that could or should be added to the plug-in. + They may or may not make it to an actual task list of a + developer. + | +
+ The following is an overview of the various properties (and + default values) used by the Maven J2EE Plug-in goals. These properties + control various aspects of the J2EE build. Most of these + properties are optional and have defaults; however, there are + mandatory properties that must be set as described in this document. +
++ These properties can be overridden to change the default behavior of + the Maven J2EE Plug-in. If you need to override any of these properties, + please refer to the + Integration + document for the preferred method of setting properties in your project. +
+| Section | Description |
|---|---|
| General Settings | ++ These properties specify various settings that may be used in any + J2EE Plug-in target. + | +
| War | ++ These properties specify various settings that control the build + of a war file by the J2EE Plug-in. + | +
| EJB | ++ These properties specify various settings that control the build + of a ejb jar by the J2EE Plug-in. + | +
| Ear | ++ These properties specify various settings that control the build + of an ear file by the J2EE Plug-in. + | +
| Appserver | ++ These properties detail what application server instance you would + like to install and control for your project and how to configure + it. + | +
| Property | Optional? | Description |
|---|---|---|
| maven.j2ee.version | ++ No for the "appserver:install" goal. + Otherwise, Yes. + | +
+ Specifies the version of J2EE you are trying to use. Valid values are:
+
|
+
| Property | Optional? | Description |
|---|---|---|
| maven.j2ee.war.name | +No | ++ Specifies the name of the web application to be built. + | +
| maven.j2ee.war.src | +Yes | +
+ Specifies the directory in the local file system that is
+ used as the base directory for finding web applications. It defaults
+ to ${maven.src.dir}/webapps
+ |
+
| maven.j2ee.war.content | +Yes | ++ Specifies the directory in the local file system that holds + web content to be placed in the war file. It defaults + to ${maven.j2ee.war.src}/${maven.j2ee.war.name} + | +
| maven.j2ee.war.classes.includes | +Yes | +
+ Specifies the pattern of files in the directory specified by
+ ${maven.build.dest}
+ to be included in the /WEB-INF/classes of the resulting
+ war file. It defaults to **, that is, all files.
+ |
+
| maven.j2ee.war.classes.excludes | +Yes | +
+ Specifies the pattern of files in the directory specified by
+ ${maven.build.dest}
+ that are not to be included in the
+ /WEB-INF/classes of the resulting war file.
+ It defaults to **/package.html.
+ |
+
| maven.j2ee.war.lib.includes | +Yes | +
+ WARNING: This property is temporarily unused. + Specifies the pattern of files in the + project dependencies + to be included in the/WEB-INF/lib of the resulting
+ war file. It defaults to *.jar, that is, all dependencies.
+ |
+
| maven.j2ee.war.lib.excludes | +Yes | +
+ WARNING: This property is temporarily unused. + Specifies the pattern of files in the + project dependencies + not to be included in the/WEB-INF/lib of the resulting
+ war file. It defaults to blank, that is, no dependencies are excluded.
+ |
+
| maven.j2ee.war.webxml | +Yes | +
+ Specifies the deployment descriptor to be used when building the war
+ file. It will be placed in /WEB-INF/web.xml of the resulting
+ war file. It defaults to ${maven.conf.dir}/${maven.j2ee.war.name}-web.xml
+ |
+
| Property | Optional? | Description |
|---|---|---|
| maven.j2ee.ejb.name | +No | ++ Specifies the name of the ejb jar to be built. + | +
| maven.j2ee.ejb.conf.dir | +No | +
+ Specifies the directory to be used to find the deployment descriptor
+ and other files to be placed in META-INF directory of
+ the resulting ejb jar. It defaults to
+ ${maven.conf.dir}/${maven.j2ee.ejb.name}
+ |
+
| + maven.j2ee.ejb.conf.includes + + | +Yes | +
+ Specifies the a pattern of files to be included in the
+ META-INF directory of the resulting ejb jar, relative
+ to the ${maven.j2ee.ejb.conf.dir}. It defaults to
+ ejb-jar.xml.
+ |
+
| + maven.j2ee.ejb.conf.excludes + + | +Yes | +
+ Specifies the a pattern of files to be excluded from the
+ META-INF directory of the resulting ejb jar, relative
+ to the ${maven.j2ee.ejb.conf.dir}. It defaults to
+ blank.
+ |
+
| maven.j2ee.ejb.includes | +Yes | +
+ Specifies the pattern of files in the
+ ${maven.build.dest}
+ directory to be included in the generated ejb jar. Defaults to **/*.
+ |
+
| maven.j2ee.ejb.excludes | +Yes | +
+ Specifies the pattern of compiled class files to be excluded
+ from the generated ejb jar. Defaults to **/package.html.
+ |
+
| maven.j2ee.ejb.local.includes | +Yes | +
+ If this property exists then a jar file with the name
+ ${maven.j2ee.ejb.name}-local.jar
+ containing the matching files will be generated in
+ ${maven.build.dir}/ejb.
+ |
+
| maven.j2ee.ejb.local.excludes | +Yes | +
+ Files to be excluded from the
+ ${maven.j2ee.ejb.name}-local.jar
+ |
+
| maven.j2ee.ejb.remote.includes | +Yes | +
+ If this property exists then a jar file with the name
+ ${maven.j2ee.ejb.name}-remote.jar
+ containing the matching files will be generated in
+ ${maven.build.dir}/ejb.
+ |
+
| maven.j2ee.ejb.remote.excludes | +Yes | +
+ Files to be excluded from the
+ ${maven.j2ee.ejb.name}-remote.jar
+ |
+
| Property | Optional? | Description |
|---|---|---|
| maven.j2ee.ear.name | +No | ++ Specifies the name of the enterprise application to be built. + | +
| maven.j2ee.ear.includes | +Yes | +
+ Specifies the pattern of files in the
+ ${maven.build.dir}
+ directory to be included in the resulting ear file. It defaults to
+ *.jar, *.war, that is, all jar and war files.
+ |
+
| maven.j2ee.ear.excludes | +Yes | +
+ Specifies the pattern of files in the
+ ${maven.build.dir}
+ directory that are not to be included in the resulting ear file.
+ It defaults to blank, that is, nothing is excluded.
+ |
+
| maven.j2ee.ear.appxml | +Yes | +
+ Specifies the deployment descriptor to be used when building the ear
+ file. It will be placed in /application.xml of the resulting
+ ear file. It defaults to ${maven.conf.dir}/${maven.j2ee.ear.name}-application.xml
+ |
+
Although application server ( appserver ) instance control is part + of the J2EE plugin, all appserver related properties begin with + the "maven.appserver" prefix. This is indicative of the large scope of + functionality within the appserver targets. +
+| Property | Optional? | Description |
|---|---|---|
| maven.appserver.name | +No | ++ Specifies the name of the application server to install and control + for your project. + + Please refer to the supported servers + table for a current list of supported appservers and the ${maven.appserver.name} + value they use use. + | +
| maven.appserver.version | +No | ++ Specifies the version of the appserver to install and control + for your project. Please refer to the + supported servers + table for a current list of supported appservers and the + ${maven.appserver.version} value they use. + | +
| maven.appserver.home | +No | ++ Specifies the directory where the shared installation of the appserver + resides. This should be the home of the appserver specified by + ${maven.appserver.name} + and ${maven.appserver.version}. + | +
| maven.appserver.dir | +No | ++ Specifies the directory where the appserver instance is installed + during the "appserver:install" goal. + Defaults to be ${basedir}/server . + | +
| maven.appserver.host | +No | ++ Specifies the default host to use to access the started server + instance. Defaults to 'localhost'. + | +
| maven.appserver.port.http | +No | ++ Specifies the HTTP port number to use to access the started server + instance. Defaults to 8080. + | +
| maven.appserver.url | +No | ++ The URL that is used to test if your appserver instance is running. + This URL must point to a target that will return a response code < 400 + when your appserver instance is started. Default value is + http://${maven.appserver.host}:${maven.appserver.port.http}/index.html + | +
| maven.appserver.port.https | +Yes | ++ Specifies the HTTPS port number to use to access the started server + instance using SSL. Defaults to 444. + | +
| maven.appserver.port.one | +Yes | ++ Optional additional port you can specify when configuring appserver files during + install. + | +
| maven.appserver.port.two | +Yes | ++ Optional additional port you can specify when configuring appserver files during + install. + | +
| maven.appserver.port.three | +Yes | ++ Optional additional port you can specify when configuring appserver files during + install. + | +
| maven.appserver.classpath | +Yes | +
+ A path-like
+ value that can specify resources to make available as
+ part of the classpath of the JVM used when controlling your appserver instance.
+ For example, you may have several webapps running in the same container
+ that require a JDBC driver be available. Adding a reference to that
+ jar here will put it in the classpath of the JVM used to start
+ your appserver.
+
+ An example of a valid value might be:
+
+ /jars/database.jar;/jars/foobar.jar
+
+ Path seperators are automatically converted to their system correct values.
+ By default, there are no additional paths. Jars required to control an appserver
+ are automatically built-in and do not need to be added here.
+ |
+