From e0c2efd19e1afdec641507c616071f660180f04e Mon Sep 17 00:00:00 2001 From: plynch Date: Sun, 26 Jan 2003 06:53:13 +0000 Subject: [PATCH] o adding appserver documentation -- needs a good once over before the next release of the plugin as it probably contains a bunch of falsehoods git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@112751 13f79535-47bb-0310-9956-ffa450edef68 --- appserver/xdocs/appserver.xml | 119 +++++++++ appserver/xdocs/changes.xml | 23 ++ appserver/xdocs/dirlayout.xml | 64 +++++ appserver/xdocs/futures.xml | 46 ++++ appserver/xdocs/goals.xml | 384 +++++++++++++++++++++++++++ appserver/xdocs/index.xml | 71 +++++ appserver/xdocs/navigation.xml | 18 ++ appserver/xdocs/properties.xml | 468 +++++++++++++++++++++++++++++++++ 8 files changed, 1193 insertions(+) create mode 100644 appserver/xdocs/appserver.xml create mode 100644 appserver/xdocs/changes.xml create mode 100644 appserver/xdocs/dirlayout.xml create mode 100644 appserver/xdocs/futures.xml create mode 100644 appserver/xdocs/goals.xml create mode 100644 appserver/xdocs/index.xml create mode 100644 appserver/xdocs/navigation.xml create mode 100644 appserver/xdocs/properties.xml diff --git a/appserver/xdocs/appserver.xml b/appserver/xdocs/appserver.xml new file mode 100644 index 00000000..dd441dc9 --- /dev/null +++ b/appserver/xdocs/appserver.xml @@ -0,0 +1,119 @@ + + + + + Peter Lynch + Maven J2EE Plug-in: Appserver Notes + + + +
+

+ 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.xtomcat4012 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.

+
+ + diff --git a/appserver/xdocs/changes.xml b/appserver/xdocs/changes.xml new file mode 100644 index 00000000..1f8d761b --- /dev/null +++ b/appserver/xdocs/changes.xml @@ -0,0 +1,23 @@ + + + + Changes + dIon Gillard + + + + + + Updated docs so that they referred to the current release and not + b5 + + + Fix for jars not being included in an EAR file + + + Added the new changes report. + + + + + diff --git a/appserver/xdocs/dirlayout.xml b/appserver/xdocs/dirlayout.xml new file mode 100644 index 00000000..5730154a --- /dev/null +++ b/appserver/xdocs/dirlayout.xml @@ -0,0 +1,64 @@ + + + + + dIon Gillard + Maven J2EE Plug-in Directory Layout + + + + +
+

+ 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 nameContentComment
src/webappThe 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 nameContentComment
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 +
+
+ + diff --git a/appserver/xdocs/futures.xml b/appserver/xdocs/futures.xml new file mode 100644 index 00000000..2daf5c8d --- /dev/null +++ b/appserver/xdocs/futures.xml @@ -0,0 +1,46 @@ + + + + + dIon Gillard + Peter Lynch + Futures for the J2EE Plug-in + + + +
+

+ The following is a list of things that are being contemplated + for the Maven J2EE Plug-in. +

+
    +
  1. + We need to have Class-Path entries in generated J2EE EJB jars and + such. Quite tricky as it doesn't work the same for all application + servers (and across versions of them !). +
    2. +
  2. + Add HTML validation. +
    3. +
  3. + Add EAR validation. +
    4. +
  4. + Add validation of Tag libraries to the validate-war goal. +
    5. +
  5. + Add technology specific validators, e.g. JSP/Turbine/Velocity/Struts + etc +
    6. +
  6. + Allow integration with a 'webserver' plugin so that application server + requests can seamlessly be hooked into the application server. +
    7. +
  7. + Tie where applicable the appserver instance to other Maven plugins that + need an application server instance to do their work. +
    8. +
+
+ + diff --git a/appserver/xdocs/goals.xml b/appserver/xdocs/goals.xml new file mode 100644 index 00000000..0c74647f --- /dev/null +++ b/appserver/xdocs/goals.xml @@ -0,0 +1,384 @@ + + + + + dIon Gillard + Kevin O'Neill + Peter Lynch + Maven J2EE Plug-in Goals + + + +
+

+ 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. +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GoalDescription
j2ee:validate-warValidate a WAR file.
j2ee:ejbCreates an EJBjar file.
j2ee:earCreates an EAR file.
j2ee:appserver-installInstalls an Application Server instance
j2ee:appserver-startStarts an Application Server instance
j2ee:appserver-stopStops an Application Server instance
j2ee:appserver-cleanSafely 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: +

    +
  1. The war file exists
    2. +
  2. It is readable
    3. +
  3. The war file has a web.xml (it's only a warning if it + doesn't exist)
    4. +
  4. Servlets defined by a <servlet> tag are loadable + from the war file and not the classpath
    5. +
  5. JSPs defined by a <servlet> tag exist in the war +
    6. +
  6. Taglibs defined by a <taglib> have a + <taglib-location> that exists in the war
    7. +
  7. Error pages specified by a <location> nested + within an <error-page> element must exist in the + war file
    8. +
  8. Login and error pages specified in the <form-login-config + > element must exist in the war file
    9. +
+

+ + +

+ 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 (optional)
    • +
  • ${maven.j2ee.ejb.name}-local.jar (optional)
    • +
+

+

+ Maven also includes the license file, LICENSE.txt, if it exists, in + the META-INF directory. +

+

+ The contents of the ejb file include: +

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

+ + + + + + + + + + +
ItemDescription
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. + + CustomerEjb + 2.4 + + true + + + ]]> +
+ + + + + +

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

+
    +
  • **/web.xml/**
    • +
+

+ 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 StatusBehavior
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 StatusBehavior
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 StatusBehavior
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}. +
+ +
+ + diff --git a/appserver/xdocs/index.xml b/appserver/xdocs/index.xml new file mode 100644 index 00000000..071a15aa --- /dev/null +++ b/appserver/xdocs/index.xml @@ -0,0 +1,71 @@ + + + + + Maen J2EE Plug-in + dIon Gillard + Peter Lynch + + + +
+

+ 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. +

+ + + + + + + + + + + + + + + + + + + +
DocumentDescription
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. +
+ +
+ + diff --git a/appserver/xdocs/navigation.xml b/appserver/xdocs/navigation.xml new file mode 100644 index 00000000..27681333 --- /dev/null +++ b/appserver/xdocs/navigation.xml @@ -0,0 +1,18 @@ + + + + Maven + + + + + + + + + + + + + + diff --git a/appserver/xdocs/properties.xml b/appserver/xdocs/properties.xml new file mode 100644 index 00000000..37057845 --- /dev/null +++ b/appserver/xdocs/properties.xml @@ -0,0 +1,468 @@ + + + + + dIon Gillard + Kevin O'Neill + Peter Lynch + Maven J2EE Plug-in Properties Documentation + + + +
+

+ 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. +

+ + + + + + + + + + + + + + + + + + + + + + +
SectionDescription
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. +
+
+ + +
+ + + + + + + +
PropertyOptional?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: +
    +
  • 12
    • +
  • 13
    • +
+ The above values represent version 1.2 and 1.3 respectively. + The value of this property is especially important for the + supported servers + used with the appserver control features of this plugin. +
+
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyOptional?Description
maven.j2ee.war.nameNo + Specifies the name of the web application to be built. +
maven.j2ee.war.srcYes + 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.contentYes + 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.includesYes + 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.excludesYes + 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.includesYes +

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.excludesYes +

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.webxmlYes + 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 +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyOptional?Description
maven.j2ee.ejb.nameNo + Specifies the name of the ejb jar to be built. +
maven.j2ee.ejb.conf.dirNo + 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.includesYes + Specifies the pattern of files in the + ${maven.build.dest} + directory to be included in the generated ejb jar. Defaults to **/*. +
maven.j2ee.ejb.excludesYes + Specifies the pattern of compiled class files to be excluded + from the generated ejb jar. Defaults to **/package.html. +
maven.j2ee.ejb.local.includesYes + 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.excludesYes + Files to be excluded from the + ${maven.j2ee.ejb.name}-local.jar +
maven.j2ee.ejb.remote.includesYes + 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.excludesYes + Files to be excluded from the + ${maven.j2ee.ejb.name}-remote.jar +
+
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + +
PropertyOptional?Description
maven.j2ee.ear.nameNo + Specifies the name of the enterprise application to be built. +
maven.j2ee.ear.includesYes + 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.excludesYes + 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.appxmlYes + 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. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyOptional?Description
maven.appserver.nameNo + 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.versionNo + 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.homeNo + 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.dirNo + Specifies the directory where the appserver instance is installed + during the "appserver:install" goal. + Defaults to be ${basedir}/server . +
maven.appserver.hostNo + Specifies the default host to use to access the started server + instance. Defaults to 'localhost'. +
maven.appserver.port.httpNo + Specifies the HTTP port number to use to access the started server + instance. Defaults to 8080. +
maven.appserver.urlNo + 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.httpsYes + Specifies the HTTPS port number to use to access the started server + instance using SSL. Defaults to 444. +
maven.appserver.port.oneYes + Optional additional port you can specify when configuring appserver files during + install. +
maven.appserver.port.twoYes + Optional additional port you can specify when configuring appserver files during + install. +
maven.appserver.port.threeYes + Optional additional port you can specify when configuring appserver files during + install. +
maven.appserver.classpathYes + 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. +

+
+ +